Write the examples in SxfeScript, not JavaScript

A site for a language showed four of its six programs in plain
JavaScript, and the quick start opened on a .js file. The language is
the point, so the examples lead with it now.

server, fetch, files and ffi move from .mjs to .sx, with the
annotations that earn their place. Nothing needed an .mjs extension for
its own sake -- .sx is always a module, so top-level await works
without one. Every one of them was run before it was written down, and
CMake now runs the four offline ones as tests: the docs inline these
files verbatim, so an example that stops working is a broken code block
published to the web.

The quick start is reordered to match: .sx first, then ownership, then
a server, and JavaScript and TypeScript at the end where they belong --
as the compatibility story rather than the headline. The two places
that stay JavaScript are the ones demonstrating exactly that: the
plain-JS section here, and LANGUAGE.md's example of what the
compatibility transformer lowers `unsafe extern` to.

GitHub's renderer has no .sx highlighter and returns an ```sx fence as
flat text, so build-docs.py relabels the fence as TypeScript on the way
in and re-tags mut/safe/unsafe as keywords on the way out. The markdown
keeps saying sx.

The landing page now names the file it is quoting instead of carrying a
copy, the way the examples page already did, and its hero snippets go
through the same renderer. Both were hand-maintained HTML that could
drift from the programs they claimed to show, and neither was
highlighted.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: nanofuxion

CMakeLists.txt

@@ -168,6 +168,14 @@ if(BUILD_TESTING AND SXN_BUILD_TESTS)
   add_test(NAME sxfe-frontend COMMAND sxfe-tests)
   add_test(NAME sxn-help COMMAND sxn --help)
   add_test(NAME sxn-example COMMAND sxn ${CMAKE_CURRENT_SOURCE_DIR}/examples/velocity.sx)
+  # The docs site inlines every one of these programs verbatim, so an example
+  # that stops running is a broken code block published to the web. fetch.sx
+  # is left out on purpose: it is the only one that needs the network.
+  foreach(sxn_example hello server files ffi)
+    add_test(NAME sxn-example-${sxn_example}
+             COMMAND sxn ${CMAKE_CURRENT_SOURCE_DIR}/examples/${sxn_example}.sx)
+    set_tests_properties(sxn-example-${sxn_example} PROPERTIES TIMEOUT 30)
+  endforeach()
   add_test(NAME sxn-memory-report COMMAND sxn --memory-report ${CMAKE_CURRENT_SOURCE_DIR}/examples/velocity.sx)
   add_test(NAME sxn-memory-usage COMMAND sxn ${CMAKE_CURRENT_SOURCE_DIR}/tests/fixtures/memory-usage.sx)
   add_test(NAME sxn-native-safe COMMAND sxn ${CMAKE_CURRENT_SOURCE_DIR}/benchmarks/compute-native-safe.sx)

README.md

@@ -34,16 +34,17 @@ surfaces, native calling, bytecode, and the full performance write-up behind
 the two tables below -- lives in [`spec/`](spec/); see that directory's own
 files for each topic.
 
-Complete programs that run as-is are in [`examples/`](examples/):
+Complete programs that run as-is are in [`examples/`](examples/), all of them
+`.sx`:
 
 | File | What it shows |
 |---|---|
 | [`hello.sx`](examples/hello.sx) | Erasable types, `let mut`, and an `&mut` borrow |
 | [`velocity.sx`](examples/velocity.sx) | A primitive-only interface as a fixed-layout struct |
-| [`server.mjs`](examples/server.mjs) | `Sxn.serve` with `Request`/`Response` routing and a JSON body |
-| [`fetch.mjs`](examples/fetch.mjs) | `fetch`, then the same response read as a stream |
-| [`files.mjs`](examples/files.mjs) | `Sxn.file`/`Sxn.write`, and `node:fs` over the same file |
-| [`ffi.mjs`](examples/ffi.mjs) | Calling a C function through `Sxn.ffi` |
+| [`server.sx`](examples/server.sx) | `Sxn.serve` with `Request`/`Response` routing and a JSON body |
+| [`fetch.sx`](examples/fetch.sx) | `fetch`, then the same response read as a stream |
+| [`files.sx`](examples/files.sx) | `Sxn.file`/`Sxn.write`, and `node:fs` over the same file |
+| [`ffi.sx`](examples/ffi.sx) | Calling a C function through `Sxn.ffi` |
 
 ## Install
 
@@ -121,8 +122,8 @@ already loads native code in its engine core on every platform including
 mobile, and has no Node layer to put an addon loader in.)
 
 A third document, **`spec/BYTECODE.md`**, covers `.sxbc`: `sxn compile
-app.js` produces bytecode for distribution (`--strip` drops the compiling
-machine's own paths from it), `sxn --compile-cache app.js` compiles once and
+app.sx` produces bytecode for distribution (`--strip` drops the compiling
+machine's own paths from it), `sxn --compile-cache app.sx` compiles once and
 reuses the result on later launches, and `sxn app.sxbc` runs either one
 directly. Real, measured gains -- see that document for the numbers -- and
 proportional to how much there is to parse: noticeable on a large file,

docs/_page.html

@@ -97,16 +97,6 @@
   }
   .doc h2:hover .anchor, .doc h3:hover .anchor, .doc .anchor:focus { opacity: 1; }
 
-  /* The renderer emits GitHub's own token classes. Map the handful that
-     actually appear onto this site's palette rather than shipping GitHub's
-     stylesheet for them. */
-  .pl-c { color: var(--ink-soft); font-style: italic; }
-  .pl-k { color: var(--unsafe); }
-  .pl-s, .pl-pds, .pl-sr { color: var(--safe); }
-  .pl-c1, .pl-cce { color: var(--accent); }
-  .pl-en, .pl-e, .pl-ent { color: var(--ink); font-weight: 600; }
-  .pl-s1, .pl-smi, .pl-v { color: var(--ink-mid); }
-
   /* ---- prev/next ---- */
   .doc-nav { display: flex; justify-content: space-between; gap: 14px; margin-top: 46px; flex-wrap: wrap; }
   .doc-nav a {

docs/guide/examples.md

@@ -7,11 +7,16 @@ inlined from those files when this page is built, so it cannot drift out of
 step with them. Clone the repo and run them, or paste one into a file and run
 that.
 
+They are all `.sx`, because that is the language this project is for.
+Everything a `.sx` file can do here, a plain `.js`, `.mjs` or `.ts` file can
+do too — the annotations and the ownership syntax are the only difference, and
+[the quick start](../quickstart/) shows the same program in each.
+
 ## Types and borrows
 
 [`examples/hello.sx`](https://github.com/SxfeScript/sxfescript/blob/main/examples/hello.sx)
 
-<!-- include: examples/hello.sx as ts -->
+<!-- include: examples/hello.sx as sx -->
 
 ```sh
 sxn examples/hello.sx
@@ -31,7 +36,7 @@ describes a struct with declared field order and natural alignment — the same
 layout on every supported target, which is what code crossing into native
 memory needs.
 
-<!-- include: examples/velocity.sx as ts -->
+<!-- include: examples/velocity.sx as sx -->
 
 ```sh
 sxn examples/velocity.sx
@@ -43,16 +48,16 @@ sxn examples/velocity.sx
 
 ## An HTTP server
 
-[`examples/server.mjs`](https://github.com/SxfeScript/sxfescript/blob/main/examples/server.mjs)
+[`examples/server.sx`](https://github.com/SxfeScript/sxfescript/blob/main/examples/server.sx)
 
 The handler receives a `Request` and returns a `Response`. `req.url` is
 absolute, so `new URL(req.url)` gives you the path and query, and
 `await req.json()` reads the body.
 
-<!-- include: examples/server.mjs as js -->
+<!-- include: examples/server.sx as sx -->
 
 ```sh
-sxn examples/server.mjs
+sxn examples/server.sx
 ```
 
 ```
@@ -66,15 +71,15 @@ pick a free one. Pass a real port number to choose it yourself.
 
 ## fetch and streams
 
-[`examples/fetch.mjs`](https://github.com/SxfeScript/sxfescript/blob/main/examples/fetch.mjs)
+[`examples/fetch.sx`](https://github.com/SxfeScript/sxfescript/blob/main/examples/fetch.sx)
 
 A response body is a real `ReadableStream`, so it can be piped and consumed a
 chunk at a time rather than only read whole.
 
-<!-- include: examples/fetch.mjs as js -->
+<!-- include: examples/fetch.sx as sx -->
 
 ```sh
-sxn examples/fetch.mjs
+sxn examples/fetch.sx
 ```
 
 ```
@@ -85,15 +90,16 @@ sxn examples/fetch.mjs
 
 ## Files
 
-[`examples/files.mjs`](https://github.com/SxfeScript/sxfescript/blob/main/examples/files.mjs)
+[`examples/files.sx`](https://github.com/SxfeScript/sxfescript/blob/main/examples/files.sx)
 
-`Sxn.file` and `Sxn.write` are the runtime's own file I/O. `node:fs` works
-too, over the same files, for code that already expects it.
+`Sxn.file` and `Sxn.write` are the runtime's own file I/O. The `node:fs`
+import is the compatibility layer reading the same file back, for code that
+already expects Node.
 
-<!-- include: examples/files.mjs as js -->
+<!-- include: examples/files.sx as sx -->
 
 ```sh
-sxn examples/files.mjs
+sxn examples/files.sx
 ```
 
 ```
@@ -104,15 +110,15 @@ sxn version: 0.0.1
 
 ## Calling a C function
 
-[`examples/ffi.mjs`](https://github.com/SxfeScript/sxfescript/blob/main/examples/ffi.mjs)
+[`examples/ffi.sx`](https://github.com/SxfeScript/sxfescript/blob/main/examples/ffi.sx)
 
 `Sxn.ffi(library, symbol, argumentTypes, returnType)` returns a callable
-JavaScript function, through libffi and `dlopen`.
+function, through libffi and `dlopen`.
 
-<!-- include: examples/ffi.mjs as js -->
+<!-- include: examples/ffi.sx as sx -->
 
 ```sh
-sxn examples/ffi.mjs
+sxn examples/ffi.sx
 ```
 
 ```

docs/guide/quickstart.md

@@ -1,7 +1,8 @@
 # Quick start
 
-`sxn` is a single binary. It runs `.sx`, `.ts`, `.js`, `.mjs` and `.cjs`
-files directly, with no build step and nothing to configure first.
+`sxn` is a single binary. It runs `.sx` — this project's own language — plus
+`.ts`, `.js`, `.mjs` and `.cjs`, all directly, with no build step and nothing
+to configure first.
 
 ## Install
 
@@ -34,68 +35,45 @@ rather unpack one yourself.
 
 ## Your first program
 
-Ordinary JavaScript runs as-is. Put this in `hello.js`:
+Put this in `hello.sx`:
 
-```js
-const runtime = typeof Sxn !== "undefined" ? "sxn " + Sxn.version : "something else";
-console.log(`hello from ${runtime}`);
-```
-
-```sh
-sxn hello.js
-```
-
-```
-hello from sxn 0.0.1
-```
-
-## TypeScript, with no build step
-
-Rename it to `hello.ts` and add annotations. `sxn` parses and strips them
-itself, so there is no `tsc` and no bundler in front of it:
-
-```ts
-interface Runtime {
+```sx
+interface Repo {
   name: string;
-  version: string;
+  stars: i32;
 }
 
-function describe(r: Runtime): string {
-  return `hello from ${r.name} ${r.version}`;
-}
+const describe = (repo: Repo): string =>
+  `${repo.name} has ${repo.stars} star${repo.stars === 1 ? "" : "s"}`;
 
-console.log(describe({ name: "sxn", version: Sxn.version }));
+console.log(describe({ name: "sxfescript", stars: 1 }));
 ```
 
 ```sh
-sxn hello.ts
+sxn hello.sx
 ```
 
 ```
-hello from sxn 0.0.1
+sxfescript has 1 star
 ```
 
-Types that can be erased are accepted: aliases, interfaces, `declare`,
-annotations, optional parameters, generics on functions, `as`/`satisfies`,
-and union types. `enum` and `namespace` are rejected on purpose rather than
-stripped, because both emit a real object at runtime in TypeScript, and
-quietly removing them would turn every use of their members into `undefined`:
-
-```
-SyntaxError: unsupported keyword: enum
-```
+That is an ordinary interface and an ordinary annotation, and there is no
+`tsc` and no bundler in front of it. `sxn` parses the types itself and strips
+them as it goes.
 
-## `.sx`: ownership and borrows
+## Ownership and borrows
 
-A `.sx` file is the same language with mutation and aliasing made explicit.
-`let mut` is a mutable owner, `let` an immutable one, `&` borrows a value
-shared, and `&mut` borrows it exclusively:
+`.sx` is the same language with mutation and aliasing made explicit. `let mut`
+is a mutable owner, `let` an immutable one, `&` borrows a value shared, and
+`&mut` borrows it exclusively:
 
-```ts
+```sx
 interface Counter {
   hits: i32;
 }
 
+// &mut borrows the counter exclusively, so bump can change what it was
+// handed without taking ownership of it.
 function bump(c: &mut Counter): void {
   c.hits += 1;
 }
@@ -114,20 +92,24 @@ sxn counter.sx
 counter: 2
 ```
 
-The syntax is parsed natively today. The full control-flow ownership pass
-that enforces every rule in
-[the language contract](../language/) is still being written —
-[the implementation ledger](../implementation/) tracks exactly what is
-checked and what is only parsed, and it is worth reading before you rely on a
-rule being enforced.
+An interface whose fields are all primitives — `i32`, `f32`, `f64`, `bool` —
+describes a fixed-layout struct: declared field order, natural alignment, the
+same layout on every supported target. That is what code crossing into native
+memory needs.
+
+The syntax is parsed natively today. The full control-flow ownership pass that
+enforces every rule in [the language contract](../language/) is still being
+written, and [the implementation ledger](../implementation/) tracks exactly
+what is checked and what is only parsed. It is worth reading before you rely
+on a rule being enforced.
 
 ## An HTTP server
 
 `Sxn.serve` hands your function a `Request` and expects a `Response` back —
 the same pair of objects a handler gets on Cloudflare Workers, Deno or Bun:
 
-```js
-const server = Sxn.serve({ port: 3000 }, async (req) => {
+```sx
+const server = Sxn.serve({ port: 3000 }, async (req: Request): Promise<Response> => {
   const url = new URL(req.url);
   if (url.pathname === "/echo") return Response.json(await req.json());
   return new Response("hello from " + url.pathname);
@@ -137,7 +119,7 @@ console.log(`listening on ${server.url}`);
 ```
 
 ```sh
-sxn server.js
+sxn server.sx
 ```
 
 ```
@@ -148,16 +130,46 @@ listening on http://127.0.0.1:3000
 `server.port` then tells you which one it picked. `server.stop()` shuts the
 listener down, so one process can serve and then go on to do something else.
 
+## JavaScript and TypeScript run too
+
+Nothing above is required. `sxn` runs a plain `.js`, `.mjs`, `.cjs` or `.ts`
+file directly, and a `.sx` module can `import` any of them and vice versa. A
+`.sx` file that uses none of the extra syntax is just JavaScript with a
+different extension.
+
+```js
+const runtime = typeof Sxn !== "undefined" ? "sxn " + Sxn.version : "something else";
+console.log(`hello from ${runtime}`);
+```
+
+```sh
+sxn hello.js
+```
+
+```
+hello from sxn 0.0.1
+```
+
+TypeScript's erasable forms are all accepted: aliases, interfaces, `declare`,
+annotations, optional parameters, generics on functions, `as`/`satisfies`, and
+union types. `enum` and `namespace` are rejected on purpose rather than
+stripped, because both emit a real object at runtime in TypeScript, and
+quietly removing them would turn every use of their members into `undefined`:
+
+```
+SyntaxError: unsupported keyword: enum
+```
+
 ## Precompiling
 
 `sxn compile` writes bytecode that skips parsing on later runs:
 
 ```sh
-sxn compile app.js -o app.sxbc
+sxn compile app.sx -o app.sxbc
 sxn app.sxbc
 ```
 
-`sxn --compile-cache app.js` does the same thing automatically, building the
+`sxn --compile-cache app.sx` does the same thing automatically, building the
 cache on the first launch and reusing it afterwards. The measured gains, and
 the reason bytecode is not a safe format for untrusted input, are in
 [the bytecode spec](../bytecode/).