toiljs 0.0.33 → 0.0.36

package/test/ssr-render.test.ts

@@ -0,0 +1,128 @@
+/**
+ * End-to-end guest render: drive the real ToilScript-compiled `render` export
+ * of the SSR example wasm, decode its values envelope, and confirm the guest
+ * produces exactly the bytes the Rust host's `decode_values`/`assemble` expects
+ * (the same wire format proven on the host side in
+ * `toil-backend/src/host/template/assemble.rs`). Closing the loop with the
+ * golden byte-identity test (`ssr-template.test.tsx`), this proves the full
+ * chain: guest values -> splice -> React-identical HTML.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { describe, expect, it } from 'vitest';
+
+import { WasmServerModule } from '../src/devserver/index.js';
+import { spliceTemplate } from '../src/compiler/template.js';
+
+const SSR_WASM = path.resolve(
+    path.dirname(fileURLToPath(import.meta.url)),
+    '../examples/basic/build/server/ssr.wasm',
+);
+
+interface DecodedSlot {
+    slotId: number;
+    kind: number;
+    value: Buffer;
+}
+interface DecodedValues {
+    status: number;
+    hash: Buffer;
+    headers: [string, string][];
+    slots: DecodedSlot[];
+}
+
+/** Mirror of the host `decode_values`: parse the guest values envelope. */
+function decodeValues(buf: Uint8Array): DecodedValues {
+    const b = Buffer.from(buf);
+    let o = 0;
+    const status = b.readUInt16LE(o);
+    o += 2;
+    const hash = b.subarray(o, o + 32);
+    o += 32;
+    const nHeaders = b.readUInt16LE(o);
+    o += 2;
+    const headers: [string, string][] = [];
+    for (let i = 0; i < nHeaders; i++) {
+        const nameLen = b.readUInt16LE(o);
+        o += 2;
+        const valLen = b.readUInt16LE(o);
+        o += 2;
+        const name = b.toString('utf8', o, o + nameLen);
+        o += nameLen;
+        const val = b.toString('utf8', o, o + valLen);
+        o += valLen;
+        headers.push([name, val]);
+    }
+    const nSlots = b.readUInt16LE(o);
+    o += 2;
+    const slots: DecodedSlot[] = [];
+    for (let i = 0; i < nSlots; i++) {
+        const slotId = b.readUInt16LE(o);
+        o += 2;
+        const kind = b.readUInt8(o);
+        o += 1;
+        const valueLen = b.readUInt32LE(o);
+        o += 4;
+        slots.push({ slotId, kind, value: b.subarray(o, o + valueLen) });
+        o += valueLen;
+    }
+    expect(o).toBe(b.length); // no trailing garbage
+    return { status, hash, headers, slots };
+}
+
+describe.skipIf(!fs.existsSync(SSR_WASM))('edge SSR guest render (real wasm)', () => {
+    const load = (): WasmServerModule => {
+        const m = new WasmServerModule(SSR_WASM);
+        m.refresh();
+        return m;
+    };
+    const render = (m: WasmServerModule, p: string): Uint8Array =>
+        m.dispatchRender({
+            method: 'GET',
+            path: p,
+            headers: [['host', 'localhost']],
+            body: new Uint8Array(0),
+        });
+
+    it('produces a values envelope with the compiled-in hash and escaped holes', () => {
+        const d = decodeValues(render(load(), '/hello'));
+        expect(d.status).toBe(200);
+        // The HASH baked into greeting.slots.ts: bytes 0x00..0x1f.
+        expect([...d.hash]).toEqual(Array.from({ length: 32 }, (_, i) => i));
+
+        expect(d.slots.map((s) => `${s.slotId}:${s.kind}`)).toEqual([
+            '0:0', // greeting, text
+            '1:3', // count, repeat
+        ]);
+        // Text hole: React-escaped (& -> &amp;, <> -> entities, mirroring escape.ts).
+        expect(d.slots[0].value.toString('utf8')).toBe('world &amp; &lt;friends&gt;');
+        // Repeat hole: three stamped rows, each escaped.
+        expect(d.slots[1].value.toString('utf8')).toBe(
+            '<li>a &amp; b</li><li>&lt;c&gt;</li><li>d</li>',
+        );
+    });
+
+    it('splices into a template exactly (full guest -> host -> HTML chain)', () => {
+        const d = decodeValues(render(load(), '/hello'));
+        // A template with a greeting hole and a repeat region, holes removed.
+        const tmpl = Buffer.from('<h1>Hello </h1><ul></ul>', 'utf8');
+        const greetingOffset = '<h1>Hello '.length;
+        const repeatOffset = '<h1>Hello </h1><ul>'.length;
+        const out = spliceTemplate(tmpl, [
+            { offset: greetingOffset, value: Buffer.from(d.slots[0].value) },
+            { offset: repeatOffset, value: Buffer.from(d.slots[1].value) },
+        ]);
+        expect(out.toString('utf8')).toBe(
+            '<h1>Hello world &amp; &lt;friends&gt;</h1><ul><li>a &amp; b</li><li>&lt;c&gt;</li><li>d</li></ul>',
+        );
+    });
+
+    it('fails safe (status 500, zero hash, no slots) for an unmatched path', () => {
+        const d = decodeValues(render(load(), '/not-an-ssr-route'));
+        expect(d.status).toBe(500);
+        expect([...d.hash]).toEqual(Array(32).fill(0));
+        expect(d.slots).toHaveLength(0);
+    });
+});

package/test/ssr-template.test.tsx

@@ -0,0 +1,348 @@
+/**
+ * The load-bearing test for edge SSR: prove that the build's
+ * template-with-holes + a guest-style stamp reproduces, BYTE FOR BYTE, what
+ * React renders for the same data. If this holds, the browser's `hydrateRoot`
+ * sees identical markup and hydration is clean.
+ *
+ * Strategy:
+ *   1. Render the component with markers in SENTINEL mode (build) -> strip ->
+ *      `.tmpl` + slot records.
+ *   2. Render the SAME component with REAL data normally -> `expected`.
+ *   3. Simulate the guest: stamp each hole's value (React-escaped text, raw
+ *      verbatim, repeat = stamp the captured row template per real item) and
+ *      splice into the `.tmpl`.
+ *   4. assert stamped === expected.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it } from 'vitest';
+
+import { Hole, Island, RawHtml, Repeat, __setSsrBuild } from '../src/client/ssr/markers';
+import { LoaderDataContext, useLoaderData } from '../src/client/routing/loader';
+import {
+    extractRouteTemplate,
+    injectIntoShell,
+    routeTemplateName,
+    writeTemplateArtifacts,
+} from '../src/compiler/template-build';
+import {
+    assignSlotIds,
+    coherenceHash,
+    encodeSlots,
+    extractFromHtml,
+    kindByte,
+    reactEscapeHtml,
+    spliceTemplate,
+    type SlotRecord,
+} from '../src/compiler/template';
+import { generateSlotsModule } from '../src/compiler/ssr-codegen';
+
+interface Post {
+    title: string;
+}
+interface ProfileData {
+    username: string;
+    bioHtml: string;
+    posts: Post[];
+}
+
+function Profile({ d }: { d: ProfileData }): React.ReactElement {
+    return (
+        <main>
+            <h1>
+                @<Hole id="username">{d.username}</Hole>
+            </h1>
+            <RawHtml id="bio" html={d.bioHtml} />
+            <ul>
+                <Repeat id="posts" each={d.posts}>
+                    {(p: Post) => (
+                        <li>
+                            <Hole id="title">{p.title}</Hole>
+                        </li>
+                    )}
+                </Repeat>
+            </ul>
+        </main>
+    );
+}
+
+/** Render under the build sentinel pass (always restores the flag). */
+function renderBuild(el: React.ReactElement): string {
+    __setSsrBuild(true);
+    try {
+        return renderToStaticMarkup(el);
+    } finally {
+        __setSsrBuild(false);
+    }
+}
+
+/** Simulate the guest: produce the bytes for one top-level slot from real data. */
+function stampSlot(slot: SlotRecord, d: ProfileData): Buffer {
+    if (slot.kind === 'text' && slot.id === 'username') {
+        return Buffer.from(reactEscapeHtml(d.username), 'utf8');
+    }
+    if (slot.kind === 'raw' && slot.id === 'bio') {
+        return Buffer.from(d.bioHtml, 'utf8');
+    }
+    if (slot.kind === 'repeat' && slot.id === 'posts') {
+        const rowTmpl = slot.rowTemplate!;
+        const rows: Buffer[] = d.posts.map((p) =>
+            spliceTemplate(
+                rowTmpl,
+                slot.rowSlots!.map((rs) => ({
+                    offset: rs.offset,
+                    value: Buffer.from(reactEscapeHtml(p.title), 'utf8'),
+                })),
+            ),
+        );
+        return Buffer.concat(rows);
+    }
+    throw new Error(`unexpected slot ${slot.id}/${slot.kind}`);
+}
+
+function assemble(tmpl: Buffer, slots: SlotRecord[], d: ProfileData): Buffer {
+    return spliceTemplate(
+        tmpl,
+        slots.map((s) => ({ offset: s.offset, value: stampSlot(s, d) })),
+    );
+}
+
+describe('ssr template extraction', () => {
+    it('strips sentinels and records hole offsets', () => {
+        const sample: ProfileData = {
+            username: 'ada',
+            bioHtml: '<em>hi</em>',
+            posts: [{ title: 'first' }],
+        };
+        const { tmpl, slots } = extractFromHtml(renderBuild(<Profile d={sample} />));
+
+        // Static scaffold = React's own output, holes removed. The <div> from
+        // RawHtml's wrapper is present and empty; the <ul> is empty.
+        expect(tmpl.toString('utf8')).toBe('<main><h1>@</h1><div></div><ul></ul></main>');
+
+        expect(slots.map((s) => `${s.id}:${s.kind}`)).toEqual([
+            'username:text',
+            'bio:raw',
+            'posts:repeat',
+        ]);
+        // Offsets are ascending and land at the right spots.
+        const t = tmpl.toString('utf8');
+        expect(t.slice(0, slots[0].offset)).toBe('<main><h1>@');
+        expect(slots[1].offset).toBe(t.indexOf('<div>') + '<div>'.length);
+        expect(slots[2].offset).toBe(t.indexOf('<ul>') + '<ul>'.length);
+
+        // Repeat captured the single-row sub-template + its nested hole.
+        const posts = slots[2];
+        expect(posts.rowTemplate!.toString('utf8')).toBe('<li></li>');
+        expect(posts.rowSlots!.map((r) => `${r.id}:${r.kind}`)).toEqual(['title:text']);
+        expect(posts.rowSlots![0].offset).toBe('<li>'.length);
+    });
+
+    it('collapses Island to nothing server-side', () => {
+        const html = renderBuild(
+            <div>
+                <Island>
+                    <span>client only</span>
+                </Island>
+            </div>,
+        );
+        expect(extractFromHtml(html).tmpl.toString('utf8')).toBe('<div></div>');
+    });
+});
+
+describe('ssr GOLDEN byte-identity (template+stamp === React render)', () => {
+    const sample: ProfileData = {
+        username: 'ada',
+        bioHtml: '<em>sample</em>',
+        posts: [{ title: 'sample' }],
+    };
+
+    function check(real: ProfileData): void {
+        const { tmpl, slots } = extractFromHtml(renderBuild(<Profile d={sample} />));
+        const stamped = assemble(tmpl, slots, real);
+        const expected = renderToStaticMarkup(<Profile d={real} />);
+        expect(stamped.toString('utf8')).toBe(expected);
+    }
+
+    it('matches for plain data', () => {
+        check({
+            username: 'grace',
+            bioHtml: '<strong>Rear Admiral</strong>',
+            posts: [{ title: 'COBOL' }, { title: 'the bug' }, { title: 'compilers' }],
+        });
+    });
+
+    it('matches when values need React escaping (the &#x27; / &quot; cases)', () => {
+        check({
+            username: `A<b>&"'x`,
+            bioHtml: '<em>raw & <kept></em>', // raw: NOT escaped, verbatim
+            posts: [{ title: 'a & b' }, { title: '<script>' }, { title: `it's "ok"` }],
+        });
+    });
+
+    it('matches for an empty list (zero rows)', () => {
+        check({ username: 'zero', bioHtml: '<i/>', posts: [] });
+    });
+
+    it('matches for a single row', () => {
+        check({ username: 'one', bioHtml: 'x', posts: [{ title: 'only' }] });
+    });
+});
+
+describe('ssr .slots binary manifest', () => {
+    it('encodes the documented layout and round-trips offsets/kinds', () => {
+        const sample: ProfileData = {
+            username: 'ada',
+            bioHtml: '<em>x</em>',
+            posts: [{ title: 't' }],
+        };
+        const { tmpl, slots } = extractFromHtml(renderBuild(<Profile d={sample} />));
+        const ids = assignSlotIds(slots);
+        const hash = coherenceHash(tmpl, slots);
+        const buf = encodeSlots(tmpl.length, hash, slots, ids);
+
+        // Header: magic "TSLT", version 1, flags 0, tmpl_len, hash, n_slots.
+        expect(buf.subarray(0, 4).toString('ascii')).toBe('TSLT');
+        expect(buf.readUInt16LE(4)).toBe(1);
+        expect(buf.readUInt16LE(6)).toBe(0);
+        expect(buf.readUInt32LE(8)).toBe(tmpl.length);
+        expect(buf.subarray(12, 44).equals(hash)).toBe(true);
+        expect(buf.readUInt16LE(44)).toBe(slots.length);
+
+        // Slot entries: offset u32, slot_id u16, kind u8, reserved u8.
+        let o = 46;
+        slots.forEach((s, i) => {
+            expect(buf.readUInt32LE(o)).toBe(s.offset);
+            expect(buf.readUInt16LE(o + 4)).toBe(ids.get(s.id));
+            expect(buf.readUInt8(o + 6)).toBe(kindByte(s.kind));
+            expect(buf.readUInt8(o + 7)).toBe(0);
+            expect(ids.get(s.id)).toBe(i); // document-order numbering
+            o += 8;
+        });
+        expect(o).toBe(buf.length);
+    });
+
+    it('coherence hash changes when the template changes', () => {
+        const a = extractFromHtml(
+            renderBuild(<Profile d={{ username: 'a', bioHtml: 'x', posts: [{ title: 't' }] }} />),
+        );
+        const h1 = coherenceHash(a.tmpl, a.slots);
+        const h2 = coherenceHash(Buffer.concat([a.tmpl, Buffer.from('!')]), a.slots);
+        expect(h1.equals(h2)).toBe(false);
+    });
+});
+
+describe('ssr guest codegen (Slot enum + HASH)', () => {
+    const sample: ProfileData = {
+        username: 'ada',
+        bioHtml: '<em>x</em>',
+        posts: [{ title: 't' }],
+    };
+
+    it('emits a Slot enum matching the .slots numbering and the 32-byte HASH', () => {
+        const { tmpl, slots } = extractFromHtml(renderBuild(<Profile d={sample} />));
+        const ids = assignSlotIds(slots);
+        const hash = coherenceHash(tmpl, slots);
+        const mod = generateSlotsModule('u_name', slots, hash);
+
+        // Enum members use the SAME ids the host .slots carries.
+        expect(mod).toContain('export enum Slot {');
+        expect(mod).toContain(`username = ${ids.get('username')},`);
+        expect(mod).toContain(`bio = ${ids.get('bio')},`);
+        expect(mod).toContain(`posts = ${ids.get('posts')},`);
+        // HASH literal has exactly 32 bytes.
+        const arr = mod.match(/HASH: StaticArray<u8> = \[([^\]]*)\]/)![1];
+        expect(arr.split(',').filter((s) => s.trim().length > 0)).toHaveLength(32);
+        expect(mod).toContain(`0x${hash[0].toString(16).padStart(2, '0')}`);
+    });
+
+    it('rejects a hole id that is not a valid identifier', () => {
+        const bad: SlotRecord[] = [{ id: 'has-dash', kind: 'text', offset: 0 }];
+        expect(() => generateSlotsModule('r', bad, Buffer.alloc(32))).toThrow(/not a valid identifier/);
+    });
+});
+
+describe('ssr build orchestration', () => {
+    const SHELL =
+        '<!doctype html><html><head><title>t</title></head><body><div id="root"></div>' +
+        '<script type="module" src="/assets/app-abc123.js"></script></body></html>';
+
+    // A page that reads its data from the loader context (exercises the provider
+    // path), wrapped in a simple SSR-safe layout.
+    function ProfilePage(): React.ReactElement {
+        const d = useLoaderData<ProfileData>();
+        return <Profile d={d} />;
+    }
+    function Layout({ children }: { children?: React.ReactNode }): React.ReactElement {
+        return <div className="app">{children}</div>;
+    }
+
+    const sample: ProfileData = {
+        username: 'ada',
+        bioHtml: '<em>x</em>',
+        posts: [{ title: 't' }],
+    };
+
+    it('sanitizes route patterns into file-safe names', () => {
+        expect(routeTemplateName('/u/:name')).toBe('u_name');
+        expect(routeTemplateName('/')).toBe('index');
+        expect(routeTemplateName('/blog/[id]')).toBe('blog_id');
+    });
+
+    it('injects rendered route HTML into the shell #root with the SSR marker', () => {
+        const out = injectIntoShell(SHELL, '<main>hi</main>');
+        expect(out).toContain('<div id="root"><main>hi</main></div>');
+        expect(out).toContain('<template id="__toil_ssr"></template>');
+        // the hashed script tag is preserved (so hydration boots)
+        expect(out).toContain('/assets/app-abc123.js');
+    });
+
+    it('renders a route (page + layout + loader data) to template artifacts and writes them', () => {
+        const art = extractRouteTemplate({
+            name: 'profile',
+            Page: ProfilePage,
+            layouts: [Layout],
+            loaderData: sample,
+            loaderContext: LoaderDataContext,
+            setSsrBuild: __setSsrBuild,
+            shell: SHELL,
+        });
+
+        const tmpl = art.tmpl.toString('utf8');
+        // Full document with the layout + page scaffold spliced into #root, holes removed.
+        expect(tmpl).toContain(
+            '<div id="root"><div class="app"><main><h1>@</h1><div></div><ul></ul></main></div></div>',
+        );
+        expect(tmpl).toContain('<template id="__toil_ssr"></template>');
+        expect(tmpl).toContain('/assets/app-abc123.js'); // bootstrap script preserved
+        expect(art.slotCount).toBe(3); // username, bio, posts
+        expect(art.hash).toHaveLength(32);
+
+        // The generated AS Slot module names every hole.
+        expect(art.slotsModule).toContain('export enum Slot {');
+        for (const id of ['username', 'bio', 'posts']) expect(art.slotsModule).toContain(`${id} =`);
+
+        // Write to disk and read back; the .slots header is well-formed and the
+        // tmpl_len in it matches the .tmpl byte length (the host's first check).
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'toil-ssr-'));
+        try {
+            writeTemplateArtifacts(dir, art);
+            const tmplFile = fs.readFileSync(path.join(dir, 'profile.tmpl'));
+            const slotsFile = fs.readFileSync(path.join(dir, 'profile.slots'));
+            const modFile = fs.readFileSync(path.join(dir, 'profile.slots.ts'), 'utf8');
+
+            expect(tmplFile.equals(art.tmpl)).toBe(true);
+            expect(slotsFile.subarray(0, 4).toString('ascii')).toBe('TSLT');
+            expect(slotsFile.readUInt16LE(4)).toBe(1); // version
+            expect(slotsFile.readUInt32LE(8)).toBe(tmplFile.length); // tmpl_len matches .tmpl
+            expect(slotsFile.subarray(12, 44).equals(art.hash)).toBe(true);
+            expect(slotsFile.readUInt16LE(44)).toBe(3); // n_slots
+            expect(modFile).toContain('export const HASH: StaticArray<u8>');
+        } finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+});

package/examples/basic/server/HelloHandler.ts

@@ -1,42 +0,0 @@
-import { Method, Request, Response, Rest, ToilHandler } from 'toiljs/server/runtime';
-
-export class HelloHandler extends ToilHandler {
-    public handle(req: Request): Response {
-        // Try the @rest controllers first (see api.ts). Rest.dispatch returns the
-        // first matching route's Response, or null if nothing matched - then we fall
-        // through to our own logic. REST composes; it never takes over handle().
-        const hit = Rest.dispatch(req);
-        if (hit != null) {
-            return hit;
-        }
-
-        if (req.method != Method.GET && req.method != Method.HEAD) {
-            return Response.empty(405).setHeader('allow', 'GET, HEAD');
-        }
-
-        if (req.path == '/json') {
-            return Response.json('{"hello":"toiljs"}\n');
-        }
-
-        if (req.path == '/echo') {
-            return Response.text('you GET ' + req.path + '\n');
-        }
-
-        // Web Crypto demo. `crypto` is a global (no import), synchronous: the
-        // same SubtleCrypto-style API the browser has, running in the server
-        // wasm via metered host functions.
-        if (req.path == '/api/hash') {
-            const digest = crypto.sha256Text(req.path);
-            return Response.json('{"sha256":"' + crypto.toHex(digest) + '"}\n');
-        }
-
-        if (req.path == '/api/uuid') {
-            return Response.text(crypto.randomUUID() + '\n');
-        }
-
-        // Unhandled (not a plain notFound): tells the host this server has no
-        // answer for the path, so it may serve it itself. Under `toiljs dev`
-        // that falls through to Vite (client routes, assets).
-        return Response.unhandled();
-    }
-}

package/examples/basic/server/api.ts

@@ -1,137 +0,0 @@
-// A small REST demo: a players list + a leaderboard.
-//
-// IMPORTANT - the server runs with a FRESH WebAssembly instance per request, so linear memory
-// (and any module-level state, like the `store` below) is reset on every request. It does NOT
-// persist across requests. We seed a few players at module init so the read routes always have
-// data; the write routes (create / addScore) take effect only for the current request's response.
-// For real persistence, call out to a database or KV store from your handler.
-//
-// `@data` types are the wire model (shared by HTTP and RPC). `@rest` controllers expose HTTP
-// routes; `@service`/`@remote` expose typed RPC. Building the server (toilscript --rpcModule)
-// regenerates the typed client into shared/server.ts:
-//   @rest    -> Server.REST.<controller>.<route>(args)  (a working fetch client)
-//   @service -> Server.<service>.<method>()             (RPC, transport TODO)
-
-import { Response, RouteContext } from 'toiljs/server/runtime';
-
-/** A leaderboard player. */
-@data
-class Player {
-    id: u64 = 0;
-    name: string = '';
-    score: i64 = 0;
-}
-
-/** Request body for `POST /players` - the fields a client supplies to create a player. */
-@data
-class NewPlayer {
-    name: string = '';
-}
-
-/** Request body for `POST /players/:id/score` - points to add to a player's score. */
-@data
-class ScoreDelta {
-    points: i64 = 0;
-}
-
-/** A leaderboard page. A `@data` wrapper so the `Player[]` round-trips through the codec. */
-@data
-class Standings {
-    players: Player[] = [];
-}
-
-// Re-seeded on EVERY request - module memory does not persist across requests (see the note at
-// the top of the file). Swap this for a database/KV to keep data between requests.
-const store = new Map<u64, Player>();
-let nextId: u64 = 1;
-
-function seed(name: string, score: i64): void {
-    const p = new Player();
-    p.id = nextId++;
-    p.name = name;
-    p.score = score;
-    store.set(p.id, p);
-}
-seed('Ada', 120);
-seed('Linus', 95);
-seed('Grace', 140);
-
-/**
- * Players, mounted at `/players`. On the client:
- *   await Server.REST.players.get({ params: { id } })
- *   await Server.REST.players.create({ body: new NewPlayer('Bob') })
- *   await Server.REST.players.addScore({ params: { id }, body: new ScoreDelta(10n) })
- */
-@rest('players')
-class Players {
-    /** `GET /players/:id` - returns a `Response` for full control: a real 404 for a missing id,
-     *  a custom header, and the `@data` body serialized with `toJSON()`. (The toilscript editor
-     *  plugin types the compiler-injected `toJSON()`, so this is clean; return the `@data` type
-     *  directly, like the other routes, when you do not need that control.) */
-    @get('/:id')
-    public get(ctx: RouteContext): Response {
-        const id = u64.parse(ctx.param('id'));
-        if (!store.has(id)) return Response.notFound();
-        const p = store.get(id);
-
-        return Response.json(p.toJSON().toString()).setHeader('cache-control', 'no-store');
-    }
-
-    /** `POST /players` - build a player from the request body and return it with a fresh id.
-     *  Note: it is NOT saved (memory resets next request); persist to a real store to keep it. */
-    @post('/')
-    public create(input: NewPlayer): Player {
-        const p = new Player();
-        p.id = nextId++;
-        p.name = input.name;
-        p.score = 0;
-        store.set(p.id, p);
-
-        return p;
-    }
-
-    /** `POST /players/:id/score` - add `points` (from the body) to the seeded player named by
-     *  `:id` and return it. The change applies to this response only (memory resets next request). */
-    @post('/:id/score')
-    public addScore(input: ScoreDelta, ctx: RouteContext): Player {
-        const id = u64.parse(ctx.param('id'));
-        if (!store.has(id)) return new Player();
-        const p = store.get(id);
-        p.score += input.points;
-
-        return p;
-    }
-}
-
-/**
- * The leaderboard, mounted at `/leaderboard`. On the client:
- *   const board = await Server.REST.leaderboard.top(); // typed Standings { players: Player[] }
- */
-@rest('leaderboard')
-class Leaderboard {
-    /** `GET /leaderboard` - the seeded players, highest score first. */
-    @get('/')
-    public top(): Standings {
-        const board = new Standings();
-        const all = store.values();
-        for (let i = 0; i < all.length; i++) board.players.push(all[i]);
-        board.players.sort((a: Player, b: Player): i32 => (a.score < b.score ? 1 : a.score > b.score ? -1 : 0));
-        return board;
-    }
-}
-
-/** Typed RPC service (transport still a TODO): reached as `Server.stats.playerCount()` on the client. */
-@service
-class Stats {
-    /** Number of seeded players (the RPC transport is a TODO, so this throws on the client for now). */
-    @remote
-    public playerCount(): i32 {
-        return store.size;
-    }
-}
-
-/** A free `@remote` function: `Server.ping(n)` on the client. */
-@remote
-function ping(n: i32): i32 {
-    return n + 1;
-}