Skip to content

Commit 747ea0d

Browse files
jakemccloskeyjakemccloskey
committed
Public release
0 parents  commit 747ea0d

54 files changed

Lines changed: 25362 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.env.example‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
DOCSEARCH_APP_ID=
2+
DOCSEARCH_API_KEY=
3+
DOCSEARCH_INDEX_NAME=

‎.github/workflows/deploy.yml‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
name: Deploy to GitHub Pages
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
8+
jobs:
9+
build:
10+
name: Build Docusaurus
11+
runs-on: ubuntu-latest
12+
13+
steps:
14+
- uses: actions/checkout@v4
15+
with:
16+
fetch-depth: 0
17+
18+
- uses: actions/setup-node@v4
19+
with:
20+
node-version: 20
21+
cache: npm
22+
23+
- name: Setup Pages
24+
uses: actions/configure-pages@v5
25+
26+
- name: Install dependencies
27+
run: npm ci
28+
29+
- name: Build website
30+
run: npm run build
31+
32+
- name: Upload build artifact
33+
uses: actions/upload-pages-artifact@v3
34+
with:
35+
path: build
36+
37+
deploy:
38+
name: Deploy to GitHub Pages
39+
needs: build
40+
permissions:
41+
pages: write
42+
id-token: write
43+
environment:
44+
name: github-pages
45+
url: ${{ steps.deployment.outputs.page_url }}
46+
runs-on: ubuntu-latest
47+
48+
steps:
49+
- name: Deploy to GitHub Pages
50+
id: deployment
51+
uses: actions/deploy-pages@v4

‎.github/workflows/test-deploy.yml‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
name: Validate website
2+
3+
on:
4+
pull_request:
5+
branches:
6+
- main
7+
8+
jobs:
9+
quality:
10+
name: Typecheck, lint, and build
11+
runs-on: ubuntu-latest
12+
13+
steps:
14+
- uses: actions/checkout@v4
15+
with:
16+
fetch-depth: 0
17+
18+
- uses: actions/setup-node@v4
19+
with:
20+
node-version: 20
21+
cache: npm
22+
23+
- name: Install dependencies
24+
run: npm ci
25+
26+
- name: Typecheck
27+
run: npm run typecheck
28+
29+
- name: Lint docs
30+
run: npm run lint:docs
31+
32+
- name: Spellcheck
33+
run: npm run spellcheck
34+
35+
- name: Build website
36+
run: npm run build
37+
38+
smoke:
39+
name: Browser smoke and accessibility
40+
runs-on: ubuntu-latest
41+
42+
steps:
43+
- uses: actions/checkout@v4
44+
with:
45+
fetch-depth: 0
46+
47+
- uses: actions/setup-node@v4
48+
with:
49+
node-version: 20
50+
cache: npm
51+
52+
- name: Install dependencies
53+
run: npm ci
54+
55+
- name: Install Playwright browser
56+
run: npx playwright install --with-deps chromium
57+
58+
- name: Run smoke and accessibility checks
59+
run: npm run test:smoke

‎.gitignore‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Dependencies
2+
/node_modules
3+
4+
# Production
5+
/build
6+
7+
# Generated files
8+
.docusaurus
9+
.cache-loader
10+
11+
# Misc
12+
.DS_Store
13+
.env.local
14+
.env
15+
.env.development.local
16+
.env.test.local
17+
.env.production.local
18+
19+
npm-debug.log*
20+
yarn-debug.log*
21+
yarn-error.log*
22+
23+
# Test output
24+
/playwright-report
25+
/test-results

‎.markdownlint-cli2.jsonc‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
{
2+
"config": {
3+
"default": true,
4+
"line-length": false,
5+
"first-line-heading": false,
6+
"no-inline-html": false
7+
},
8+
"ignores": [
9+
"node_modules/**",
10+
"build/**",
11+
".docusaurus/**",
12+
"playwright-report/**",
13+
"test-results/**"
14+
]
15+
}

‎README.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# soundscript Website
2+
3+
This repository hosts the public soundscript website with a single Docusaurus stack:
4+
5+
- `/` for the marketing homepage
6+
- `/docs` for developer-facing documentation
7+
- future product surfaces like `/playground` as custom pages in the same site
8+
9+
## Local development
10+
11+
```bash
12+
npm install
13+
npm run dev
14+
```
15+
16+
## Quality checks
17+
18+
```bash
19+
npm run typecheck
20+
npm run build
21+
npm run lint:docs
22+
npm run spellcheck
23+
npm run test:smoke
24+
```
25+
26+
`test:smoke` builds the site, serves the production output locally, and runs Playwright smoke plus
27+
accessibility checks.
28+
29+
## Search
30+
31+
The site is wired for Algolia DocSearch through environment variables:
32+
33+
```bash
34+
cp .env.example .env.local
35+
```
36+
37+
Then set:
38+
39+
- `DOCSEARCH_APP_ID`
40+
- `DOCSEARCH_API_KEY`
41+
- `DOCSEARCH_INDEX_NAME`
42+
43+
If those variables are absent, the site still builds and runs, but the DocSearch UI is not shown.
44+
45+
## Crawlers and LLMs
46+
47+
The published site also ships crawler-friendly files from `static/`:
48+
49+
- `robots.txt`
50+
- `llms.txt`
51+
- `llms-full.txt`
52+
53+
Those files are meant to make indexing and LLM ingestion more predictable without changing the main
54+
docs content model.
55+
56+
## Docs ownership
57+
58+
The website repo owns:
59+
60+
- homepage content
61+
- onboarding and adoption docs
62+
- task-oriented guides
63+
64+
The soundscript repo remains the canonical source for normative language and tooling references such
65+
as annotations, diagnostics, builtin contracts, machine numerics, and macro semantics. The website
66+
mirrors those references with a canonical-source note at the top of each relevant page.
67+
68+
## Versioning
69+
70+
Docs versioning is prepared in the site configuration, but the first frozen version should be cut
71+
only at the real v1 tag:
72+
73+
```bash
74+
npm run docs:version:v1
75+
```
76+
77+
Run that at the actual `1.0.0` release point, then rebuild and deploy the site.

‎cspell.config.yaml‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
version: '0.2'
2+
language: en
3+
dictionaries:
4+
- softwareTerms
5+
- html
6+
- css
7+
ignorePaths:
8+
- node_modules
9+
- build
10+
- .docusaurus
11+
words:
12+
- algolia
13+
- builtin
14+
- builtins
15+
- cspell
16+
- docsearch
17+
- inout
18+
- interop
19+
- macros
20+
- metaprogramming
21+
- newtype
22+
- newtypes
23+
- nullness
24+
- numerics
25+
- overclaimed
26+
- overclaiming
27+
- playwright
28+
- soundscript
29+
- soundness
30+
- stdlib
31+
- stdio
32+
- stringifying
33+
- subclassing
34+
- sublabel
35+
- sublist
36+
- thenables
37+
- tsconfig
38+
- typecheck
39+
- typeclasses
40+
- unlisted
41+
- userland
42+
- wasi
43+
- wordmark
44+
- valueclass
45+
- wasm

‎docs/concepts/runtime-and-builtins.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
---
2+
title: Runtime and Builtins
3+
description: How the current runtime story, compile workflow, and compiler-owned builtin modules fit together.
4+
---
5+
6+
This page explains the runtime story behind the CLI output and the `sts:*` builtin modules.
7+
8+
## The normal workflow
9+
10+
For most application teams, the path is simple:
11+
12+
- author `.sts`
13+
- run `soundscript check`
14+
- use `soundscript compile` to produce deployable output
15+
- keep packaging and deployment close to how JS/TS teams already work
16+
17+
## Compiler-owned builtin modules
18+
19+
soundscript ships a focused builtin module surface under `sts:*`.
20+
21+
These modules are compiler-owned. They are not regular npm packages that happen to share a prefix.
22+
That matters because the checker and compiler can reason about them directly.
23+
24+
```ts
25+
import { normalizeThrown } from "sts:failures";
26+
import { U8, type u8 } from "sts:numerics";
27+
```
28+
29+
## The modules most app teams will notice first
30+
31+
### `sts:prelude`
32+
33+
Owns the small shared surface around core value-level helpers such as `Result` and `Option`.
34+
35+
### `sts:failures`
36+
37+
Owns `Failure`, `ErrorFrame`, and `normalizeThrown(...)` for the cases where code needs an explicit
38+
normalized error value inside the current scope.
39+
40+
### `sts:json`
41+
42+
Owns JSON boundary helpers so parsing and stringifying can live on an explicit soundscript surface
43+
instead of disappearing into unchecked assumptions.
44+
45+
### `sts:numerics`
46+
47+
Owns explicit fixed-width numeric types and helpers for the cases where host `number` semantics are
48+
too implicit.
49+
50+
## Other builtin families
51+
52+
The wider supported builtin surface also includes:
53+
54+
- `sts:compare`
55+
- `sts:hash`
56+
- `sts:decode`
57+
- `sts:encode`
58+
- `sts:codec`
59+
- `sts:derive`
60+
- `sts:async`
61+
- `sts:hkt`
62+
- `sts:typeclasses`
63+
64+
Those are real parts of the surface, but most application teams should not need all of them on day
65+
one.
66+
67+
## Why builtins exist at all
68+
69+
The builtin surface gives soundscript a place to define:
70+
71+
- standard failure boundaries
72+
- standard decoding and encoding contracts
73+
- standard numeric semantics where JS host numerics are not enough
74+
- compiler-known helpers that stay consistent across tooling
75+
76+
This is different from “invent a huge new stdlib.” The builtin surface is intentionally focused.
77+
78+
## Builtins versus ecosystem packages
79+
80+
soundscript does **not** require you to avoid ordinary npm packages.
81+
82+
The model is:
83+
84+
- use `sts:*` when you want a compiler-owned surface
85+
- use normal ecosystem packages when they solve the job
86+
- mark the boundary explicitly when `.sts` depends on regular code
87+
88+
That keeps the language usable in existing JS/TS applications instead of turning every adoption into
89+
an ecosystem fork.
90+
91+
## A note on Wasm-oriented features
92+
93+
Some builtin surfaces, especially fixed-width numerics and `#[value]`, matter more if you are
94+
thinking about Wasm. The main docs path still starts with ordinary app code.
95+
96+
## See also
97+
98+
- [Tooling and Workflow](../guides/tooling-and-js-target.md)
99+
- [Builtin Modules](../reference/builtin-modules.md)
100+
- [Tooling and Workflow](../guides/tooling-and-js-target.md)

0 commit comments

Comments
 (0)