toiljs 0.0.32 → 0.0.34

package/examples/basic/server/routes/Leaderboard.ts

@@ -0,0 +1,20 @@
+import { store } from '../core/store';
+import { Player } from '../models/Player';
+import { Standings } from '../models/Standings';
+
+/**
+ * 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;
+    }
+}

package/examples/basic/server/routes/Players.ts

@@ -0,0 +1,53 @@
+import { Response, RouteContext } from 'toiljs/server/runtime';
+
+import { allocId, store } from '../core/store';
+import { NewPlayer } from '../models/NewPlayer';
+import { Player } from '../models/Player';
+import { ScoreDelta } from '../models/ScoreDelta';
+
+/**
+ * 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 = u256.fromU64(allocId());
+        p.name = input.name;
+        p.score = 0;
+        store.set(p.id.toU64(), 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;
+    }
+}

package/examples/basic/server/scheduled/README.md

@@ -0,0 +1,7 @@
+# scheduled/
+
+Reserved for scheduled tasks: cron-style jobs that will run on the Toil edge runtime.
+
+The scheduling API has not shipped yet. The folder convention exists today so your project
+layout will not change when it lands; until then, anything in here is ignored by the build
+(only `.ts` files with a server surface are compiled).

package/examples/basic/server/services/Stats.ts

@@ -0,0 +1,11 @@
+import { store } from '../core/store';
+
+/** 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;
+    }
+}

package/examples/basic/server/services/remotes.ts

@@ -0,0 +1,7 @@
+/** Free `@remote` functions: callable as `Server.<name>()` on the client. */
+
+/** `Server.ping(n)` on the client. */
+@remote
+function ping(n: i32): i32 {
+    return n + 1;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "toiljs",
     "type": "module",
-    "version": "0.0.32",
+    "version": "0.0.34",
     "author": "Dacely",
     "description": "The modern React framework: a file-based React frontend and a ToilScript-compiled WebAssembly backend.",
     "repository": {
@@ -126,7 +126,7 @@
         "eslint-plugin-react-refresh": "^0.5.2",
         "picocolors": "^1.1.1",
         "sharp": "^0.35.0",
-        "toilscript": "^0.1.18",
+        "toilscript": "^0.1.21",
         "typescript-eslint": "^8.60.0",
         "vite": "^8.0.14",
         "vite-imagetools": "^10.0.0",

package/server/runtime/response.ts

@@ -106,4 +106,60 @@ export class Response {
 
         return this;
     }
+
+    /**
+     * Mark this response cacheable at the toil edge and/or the browser.
+     *
+     * `edgeTtlMinutes` caches the response on the edge node (per-core,
+     * keyed by host + method + path + request body) for up to that many
+     * minutes -- the ONLY way a POST response is cached. `browserTtlSeconds`
+     * emits a `Cache-Control: max-age` for the client.
+     *
+     * Host-side safety, enforced no matter what you ask for: the edge TTL
+     * is clamped to 24h, only 2xx responses are edge-cached, a response
+     * carrying a `Set-Cookie` is never edge-cached, and an AUTHENTICATED
+     * request (one with a `Cookie` or `Authorization` header) is not
+     * edge-cached unless you pass `allowAuth = true`. Only mark a response
+     * cacheable when its body is a pure function of (host, path, body) --
+     * never per-user data keyed by a cookie/header that is not in the path
+     * or body, or one user's response could be served to another.
+     *
+     * Builder-style: returns `this`.
+     */
+    public cache(
+        edgeTtlMinutes: u16,
+        browserTtlSeconds: u32 = 0,
+        privateScope: bool = false,
+        allowAuth: bool = false,
+    ): Response {
+        let v = '';
+        if (edgeTtlMinutes > 0) {
+            v = 'edge=' + edgeTtlMinutes.toString();
+        }
+        if (browserTtlSeconds > 0) {
+            if (v.length > 0) v += '; ';
+            v += 'browser=' + browserTtlSeconds.toString();
+        }
+        if (privateScope) {
+            if (v.length > 0) v += '; ';
+            v += 'scope=private';
+        }
+        if (allowAuth) {
+            if (v.length > 0) v += '; ';
+            v += 'auth=1';
+        }
+        if (v.length > 0) {
+            this.setHeader('toil-cache-control', v);
+        }
+
+        return this;
+    }
+
+    /**
+     * Shorthand for {@link cache}: edge-cache this response for `minutes`
+     * minutes (no browser caching).
+     */
+    public cacheFor(minutes: u16): Response {
+        return this.cache(minutes);
+    }
 }

package/src/cli/create.ts

@@ -175,12 +175,10 @@ function scaffold(
         'toilconfig.json':
             JSON.stringify(
                 {
-                    // `toiljs build` compiles every server/*.ts so dropped-in @data/@rest files are
-                    // picked up; these entries are the fallback when running `toilscript` directly.
-                    entries:
-                        template === 'minimal'
-                            ? ['server/main.ts']
-                            : ['server/main.ts', 'server/api.ts'],
+                    // `toiljs build` compiles every decorated server file (recursively) so
+                    // dropped-in @data/@rest files are picked up; main.ts imports the surface
+                    // modules so a direct `toilscript` run builds the same server.
+                    entries: ['server/main.ts'],
                     targets: {
                         release: {
                             outFile: 'build/server/release.wasm',
@@ -261,12 +259,18 @@ function scaffold(
     return files;
 }
 
-/** A minimal but working server for the `minimal` template (the `app` template copies examples/basic/server). */
+/**
+ * A minimal but working server for the `minimal` template (the `app` template copies
+ * examples/basic/server). Same folder conventions as the full starter, just fewer files:
+ * the entry in main.ts, the handler under core/, and a README mapping where new
+ * routes/services/models go.
+ */
 function minimalServer(): Record<string, string> {
     return {
-        'server/HelloHandler.ts':
+        'server/core/AppHandler.ts':
             "import { ToilHandler, Request, Response, Method } from 'toiljs/server/runtime';\n\n" +
-            'export class HelloHandler extends ToilHandler {\n' +
+            '/** Every request enters here. Add `@rest` controllers under routes/ as you grow. */\n' +
+            'export class AppHandler extends ToilHandler {\n' +
             '    public handle(req: Request): Response {\n' +
             '        if (req.method != Method.GET && req.method != Method.HEAD) {\n' +
             "            return Response.empty(405).setHeader('allow', 'GET, HEAD');\n" +
@@ -285,15 +289,31 @@ function minimalServer(): Record<string, string> {
             '}\n',
         'server/main.ts':
             "import { Server } from 'toiljs/server/runtime';\n" +
-            "import { revertOnError } from 'toiljs/server/runtime/abort/abort';\n" +
-            "import { HelloHandler } from './HelloHandler';\n\n" +
+            "import { revertOnError } from 'toiljs/server/runtime/abort/abort';\n\n" +
+            "import { AppHandler } from './core/AppHandler';\n\n" +
+            '// As you add surface modules (@rest routes, @service/@remote RPC), import them here\n' +
+            '// so a direct `toilscript` run builds the same server `toiljs build` does, e.g.:\n' +
+            "//   import './routes/Players';\n\n" +
             '// Wire your handler here.\n' +
-            'Server.handler = () => new HelloHandler();\n\n' +
+            'Server.handler = () => new AppHandler();\n\n' +
             '// Required: re-export the WASM entry points and the abort hook.\n' +
             "export * from 'toiljs/server/runtime/exports';\n" +
             'export function abort(message: string, fileName: string, line: u32, column: u32): void {\n' +
             '    revertOnError(message, fileName, line, column);\n' +
             '}\n',
+        'server/README.md':
+            '# server/\n\n' +
+            'Your ToilScript backend, compiled to a single WebAssembly module. One folder per concern:\n\n' +
+            '| Folder | What lives here |\n' +
+            '| --- | --- |\n' +
+            '| `main.ts` | The entry point: wires the handler and imports the surface modules. |\n' +
+            '| `core/` | The request handler and shared app logic (state, helpers). |\n' +
+            '| `models/` | `@data` classes, the typed wire model shared by HTTP and RPC. One type per file. |\n' +
+            '| `routes/` | `@rest` controllers (HTTP). One controller per file, named after its class. |\n' +
+            '| `services/` | `@service` classes and free `@remote` functions (typed RPC). |\n' +
+            '| `scheduled/` | Reserved for scheduled tasks (not shipped yet). |\n\n' +
+            'New decorated files are picked up automatically by `toiljs build`/`dev`; also add an import\n' +
+            'in `main.ts` so a direct `toilscript` run builds the same server.\n',
     };
 }
 
@@ -586,7 +606,27 @@ export async function runCreate(opts: CreateOptions): Promise<void> {
     if (template === 'app') {
         // Copy the example client + server (the single starter source), set the <title>, then style.
         await fs.cp(appClientDir(), path.join(targetDir, 'client'), { recursive: true });
-        await fs.cp(appServerDir(), path.join(targetDir, 'server'), { recursive: true });
+        // Only the canonical starter layout ships; anything else sitting in the example's
+        // server/ (local experiments, scratch entries) stays out of scaffolded apps.
+        const serverAllow = new Set([
+            'main.ts',
+            'README.md',
+            'tsconfig.json',
+            'core',
+            'models',
+            'routes',
+            'services',
+            'scheduled',
+        ]);
+        const serverSrc = appServerDir();
+        await fs.cp(serverSrc, path.join(targetDir, 'server'), {
+            recursive: true,
+            filter: (src) => {
+                const rel = path.relative(serverSrc, src);
+                if (rel === '') return true;
+                return serverAllow.has(rel.split(path.sep)[0]);
+            },
+        });
         const indexHtml = path.join(targetDir, 'client', 'public', 'index.html');
         const html = await fs.readFile(indexHtml, 'utf8');
         await fs.writeFile(
@@ -628,5 +668,5 @@ export async function runCreate(opts: CreateOptions): Promise<void> {
     steps.push(`${accent('npm run build')} ${dim('build for production')}`);
     note(steps.map((l) => dim('  ') + l).join('\n'), 'Next steps');
 
-    outro(`Created ${accent(path.basename(name))}, happy building! ${dim('· v' + version())}`);
+    outro(`Created ${accent(path.basename(name))}, happy building! ${dim('(v' + version() + ')')}`);
 }

package/src/cli/notify.ts

@@ -12,7 +12,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { detectPackageManager } from './update.js';
-import { accent, bold, dim, version as cliVersion, warn } from './ui.js';
+import { accent, bold, box, dim, version as cliVersion, warn } from './ui.js';
 import {
     findOutdated,
     isCacheFresh,
@@ -88,12 +88,12 @@ function projectToiljsVersion(root: string): string | null {
 }
 
 function noticeLines(latest: string, rows: OutdatedRow[]): string {
-    const header = warn('  ⚠ ') + bold(`a newer toiljs is available: ${accent(latest)}`);
+    const header = warn('⚠ ') + bold(`a newer toiljs is available: ${accent(latest)}`);
     const body = rows.map((row) => {
         const where = row.scope === 'project' ? 'this project has' : 'your global CLI is';
-        return `    ${where} ${row.installed}${dim(', update with')} ${accent(row.command)}`;
+        return `${where} ${row.installed}${dim(', update with')} ${accent(row.command)}`;
     });
-    return '\n' + [header, ...body].join('\n') + '\n';
+    return '\n' + box([header, '', ...body], warn) + '\n';
 }
 
 /**

package/src/cli/ui.ts

@@ -102,10 +102,69 @@ export function version(): string {
     return '0.0.0';
 }
 
-/** Prints the brand banner: gradient logo + tagline + version. */
+// eslint-disable-next-line no-control-regex -- matching our own escape sequences is the point
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+
+/** The on-screen width of `s`, ignoring ANSI color codes. */
+function visibleWidth(s: string): number {
+    return s.replace(ANSI_RE, '').length;
+}
+
+/**
+ * Frames already-colored lines in a rounded box sized to the widest line. `paint` colors the
+ * border (the content keeps its own colors); padding is measured on the visible text, so ANSI
+ * codes inside the lines never skew the right edge. Returns the box without a trailing newline.
+ */
+export function box(lines: readonly string[], paint: (s: string) => string = (s) => s): string {
+    const width = lines.reduce((w, l) => Math.max(w, visibleWidth(l)), 0);
+    const side = paint('│');
+    const body = lines.map(
+        (l) => `  ${side}  ${l}${' '.repeat(width - visibleWidth(l))}  ${side}`,
+    );
+    return [
+        '  ' + paint(`╭${'─'.repeat(width + 4)}╮`),
+        ...body,
+        '  ' + paint(`╰${'─'.repeat(width + 4)}╯`),
+    ].join('\n');
+}
+
+/**
+ * Banner taglines, one is picked at random per invocation. Each is a function so the accented
+ * words pick up the brand color (or stay plain when color is disabled). The theme: TOIL is the
+ * first full-stack framework for a globally distributed application delivery network.
+ */
+const TAGLINES: ReadonlyArray<(a: (s: string) => string) => string> = [
+    (a) => `the most performant ${a('react')} framework`,
+    (a) => `bringing ${a('hyper scale')} to anyone`,
+    (a) => `the first full-stack ${a('application delivery network')}`,
+    (a) => `your app, ${a('globally distributed')} by default`,
+    (a) => `one build, ${a('the whole planet')}`,
+    (a) => `full stack, ${a('zero distance')} to your users`,
+    (a) => `${a('react')} up front, ${a('wasm')} at every edge`,
+    (a) => `deployed where your ${a('users')} are`,
+    (a) => `the framework with a ${a('delivery network')} built in`,
+    (a) => `no regions, just ${a('the world')}`,
+    (a) => `${a('planet-scale')} apps from a single repo`,
+    (a) => `every request served ${a('next door')}`,
+    (a) => `frontend, backend, ${a('worldwide')}`,
+    (a) => `${a('hyper scale')} without the ops team`,
+    (a) => `your backend, ${a('compiled to wasm')}, running everywhere`,
+    (a) => `the internet is your ${a('runtime')}`,
+    (a) => `the speed of light is the ${a('only bottleneck')}`,
+    (a) => `static speed, ${a('dynamic everything')}`,
+    (a) => `scale to ${a('millions')} before lunch`,
+    (a) => `latency is a choice, choose ${a('zero')}`,
+    (a) => `build ${a('better')}, ship ${a('faster')}`,
+];
+
+/** A random brand tagline, accent words colored. */
+export function tagline(): string {
+    return TAGLINES[Math.floor(Math.random() * TAGLINES.length)](brand);
+}
+
+/** Prints the brand banner: gradient logo + random tagline + version. */
 export function banner(): void {
     const lines = colorEnabled() ? ART.map(gradientLine) : ART.slice();
-    const tagline = `  the most performant ${brand('react')} framework`;
     const ver = `${dim('  v')}${brand(version())}`;
-    process.stdout.write('\n' + lines.join('\n') + '\n\n' + tagline + '   ' + ver + '\n\n');
+    process.stdout.write('\n' + lines.join('\n') + '\n\n  ' + tagline() + '   ' + ver + '\n\n');
 }

package/src/devserver/index.ts

@@ -25,6 +25,7 @@ import path from 'node:path';
 import { Server, type Request, type Response } from '@dacely/hyper-express';
 import pc from 'picocolors';
 
+import { applyCacheRule, lookupCache } from './cache.js';
 import { METHOD_CODES, type EnvelopeRequest } from './envelope.js';
 import { WasmServerModule } from './module.js';
 import { proxyToVite, wireWebsocketProxy, type ViteTarget } from './proxy.js';
@@ -210,10 +211,29 @@ export async function startDevServer(options: DevServerOptions): Promise<Running
 
         if (dispatchable && module.available) {
             const envelopeReq = await toEnvelopeRequest(request);
+            // Honor the tenant cache directive locally, same rules as the
+            // edge: serve an identical request from the per-process cache,
+            // else dispatch and apply/strip the directive on the response.
+            const cacheHost = request.headers.host ?? 'dev';
+            const hasAuth =
+                request.headers.cookie !== undefined || request.headers.authorization !== undefined;
+            const cached = lookupCache(cacheHost, request.method, request.url, envelopeReq.body);
+            if (cached !== null) {
+                sendWasmResponse(response, root, cached);
+                return;
+            }
             try {
                 const result = module.dispatch(envelopeReq);
                 if (!result.unhandled) {
-                    sendWasmResponse(response, root, result);
+                    const finalized = applyCacheRule(
+                        cacheHost,
+                        request.method,
+                        request.url,
+                        envelopeReq.body,
+                        hasAuth,
+                        result,
+                    );
+                    sendWasmResponse(response, root, finalized);
                     return;
                 }
             } catch (e) {

package/test/devserver.test.ts

@@ -155,10 +155,10 @@ describe.skipIf(!fs.existsSync(EXAMPLE_WASM))('dispatch into the example server
         });
 
     it('serves a plain route', () => {
-        const r = get(load(), '/');
+        const r = get(load(), '/json');
         expect(r.status).toBe(200);
         expect(r.unhandled).toBe(false);
-        expect(Buffer.from(r.body).toString()).toBe('hello from toiljs\n');
+        expect(Buffer.from(r.body).toString()).toBe('{"hello":"toiljs"}\n');
     });
 
     it('serves a @rest route with its content-type', () => {
@@ -186,8 +186,10 @@ describe.skipIf(!fs.existsSync(EXAMPLE_WASM))('dispatch into the example server
             body: new TextEncoder().encode('{"name":"ada"}'),
         });
         expect(r.unhandled).toBe(false);
-        expect(r.status).toBeGreaterThanOrEqual(200);
-        expect(r.status).toBeLessThan(500);
+        expect(r.status).toBe(200);
+        // u256 id and i64 score cross JSON as decimal strings, exact at any size (3 seeded
+        // players, so the new player's id is 4).
+        expect(Buffer.from(r.body).toString()).toBe('{"id":"4","name":"ada","score":"0"}');
     });
 
     it('keeps requests isolated across instances (fresh state per dispatch)', () => {

package/test/fixtures/bignum-wire/spec.ts

@@ -0,0 +1,27 @@
+// Fixture for the generated-client JSON wire-format test (test/rpc-bignum-wire.test.ts).
+// Compiled by the installed toilscript with --rpcModule, then the generated TS client is
+// imported and exercised. Covers every JSON bignum width plus a nested @data so the
+// recursive toJSONValue path is hit.
+
+@data
+class Wallet {
+    u: u64 = 0;
+    i: i64 = 0;
+    a: u128 = u128.Zero;
+    b: i128 = i128.Zero;
+    c: u256 = u256.Zero;
+    d: i256 = i256.Zero;
+    label: string = '';
+}
+
+@data
+class Account {
+    main: Wallet = new Wallet();
+    ids: u256[] = [];
+}
+
+// A free @remote so buildServerModule emits a surface (it returns null otherwise).
+@remote
+function touch(n: i32): i32 {
+    return n;
+}

package/test/rpc-bignum-wire.test.ts

@@ -0,0 +1,164 @@
+/**
+ * Regression test for the bignum JSON wire format. 64-bit-and-up integers
+ * (u64/i64/u128/i128/u256/i256) must cross JSON as DECIMAL STRINGS, not number tokens
+ * or limb arrays: JSON numbers ride through a browser client's JSON.parse as IEEE
+ * doubles, which silently corrupt any integer past 2^53.
+ *
+ * Compiles test/fixtures/bignum-wire/spec.ts with the installed toilscript (so it
+ * exercises the published compiler + generated client, not a hand-written stub), then
+ * imports the generated TS client and asserts the wire shape both directions, including
+ * values far above 2^53 and the legacy limb-array shape older servers emitted.
+ */
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { beforeAll, describe, expect, it } from 'vitest';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const spec = path.join(here, 'fixtures', 'bignum-wire', 'spec.ts');
+// The generated module imports DataWriter/DataReader from this specifier.
+const codec = path.join(here, '..', 'src', 'io', 'codec.ts');
+
+/** Resolves the installed toilscript CLI entry (no PATH / .bin assumptions). */
+function toilscriptBin(): string {
+    const pkgPath = require.resolve('toilscript/package.json');
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8')) as { bin?: Record<string, string> };
+    const binRel = pkg.bin?.toilscript;
+    if (!binRel) throw new Error('toilscript declares no bin');
+    return path.join(path.dirname(pkgPath), binRel);
+}
+
+interface Wallet {
+    u: bigint;
+    i: bigint;
+    a: bigint;
+    b: bigint;
+    c: bigint;
+    d: bigint;
+    label: string;
+    toJSONValue(): Record<string, unknown>;
+}
+interface WalletStatic {
+    new (): Wallet;
+    fromJSONValue(v: unknown): Wallet;
+}
+interface AccountStatic {
+    new (): { main: Wallet; ids: bigint[]; toJSONValue(): Record<string, unknown> };
+    fromJSONValue(v: unknown): { main: Wallet; ids: bigint[] };
+}
+
+let Wallet: WalletStatic;
+let Account: AccountStatic;
+let tmp: string;
+
+beforeAll(async () => {
+    tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'bignum-wire-'));
+    fs.writeFileSync(path.join(tmp, 'package.json'), '{ "type": "module" }\n');
+    // vitest transforms the imported .ts through Vite/oxc, which walks up for a tsconfig.
+    fs.writeFileSync(
+        path.join(tmp, 'tsconfig.json'),
+        JSON.stringify({ compilerOptions: { target: 'esnext', module: 'esnext' } }),
+    );
+    const mod = path.join(tmp, 'server.ts');
+    const wasm = path.join(tmp, 'spec.wasm');
+    const res = spawnSync(
+        process.execPath,
+        [
+            toilscriptBin(),
+            spec,
+            '-o',
+            wasm,
+            '--runtime',
+            'stub',
+            '--initialMemory',
+            '32',
+            '--rpcModule',
+            mod,
+            '--rpcRuntime',
+            codec,
+        ],
+        { encoding: 'utf8' },
+    );
+    if (res.status !== 0) throw new Error('toilscript compile failed:\n' + res.stderr);
+    const gen = (await import(pathToFileURL(mod).href)) as {
+        Wallet: WalletStatic;
+        Account: AccountStatic;
+    };
+    Wallet = gen.Wallet;
+    Account = gen.Account;
+});
+
+// A few representative bignum types; `huge` is well past Number.MAX_SAFE_INTEGER.
+const huge = '123456789012345678901234567890';
+const u128Max = '340282366920938463463374607431768211455';
+const i64Min = '-9223372036854775808';
+
+describe('generated client bignum JSON wire format', () => {
+    it('serializes every 64-bit-and-up integer as a decimal string', () => {
+        const w = new Wallet();
+        w.u = BigInt(huge.slice(0, 19)); // fits u64
+        w.i = BigInt(i64Min);
+        w.a = BigInt(u128Max);
+        w.b = -123n;
+        w.c = BigInt(huge);
+        w.d = -1n;
+        w.label = 'x';
+        const json = w.toJSONValue();
+        // Each bignum field is a string, never a number or an array.
+        for (const k of ['u', 'i', 'a', 'b', 'c', 'd'] as const) {
+            expect(typeof json[k], `field ${k}`).toBe('string');
+        }
+        expect(json.a).toBe(u128Max);
+        expect(json.c).toBe(huge);
+        expect(json.i).toBe(i64Min);
+        expect(json.label).toBe('x');
+    });
+
+    it('revives a decimal string past 2^53 into an exact bigint', () => {
+        const w = Wallet.fromJSONValue({
+            u: '0',
+            i: i64Min,
+            a: u128Max,
+            b: '-123',
+            c: huge,
+            d: '-1',
+            label: 'y',
+        });
+        expect(w.c).toBe(BigInt(huge));
+        expect(w.a).toBe(BigInt(u128Max));
+        expect(w.i).toBe(BigInt(i64Min));
+        expect(w.d).toBe(-1n);
+    });
+
+    it('round-trips a value through send then revive without loss', () => {
+        const w = new Wallet();
+        w.c = BigInt(huge);
+        w.d = BigInt('-' + huge);
+        const back = Wallet.fromJSONValue(JSON.parse(JSON.stringify(w.toJSONValue())));
+        expect(back.c).toBe(BigInt(huge));
+        expect(back.d).toBe(BigInt('-' + huge));
+    });
+
+    it('still revives the legacy little-endian limb-array shape (back-compat)', () => {
+        // u256 [5,0,4,0] little-endian = 5 + 4*2^128.
+        const w = Wallet.fromJSONValue({ c: [5, 0, 4, 0], a: [9, 1] });
+        expect(w.c).toBe(2n ** 130n + 5n);
+        expect(w.a).toBe(2n ** 64n + 9n);
+    });
+
+    it('recurses into nested @data and arrays of bignums', () => {
+        const a = new Account();
+        a.main.c = BigInt(huge);
+        a.ids = [1n, BigInt(huge)];
+        const json = a.toJSONValue();
+        const main = json.main as Record<string, unknown>;
+        expect(main.c).toBe(huge);
+        expect(json.ids).toEqual(['1', huge]);
+        const back = Account.fromJSONValue(JSON.parse(JSON.stringify(json)));
+        expect(back.main.c).toBe(BigInt(huge));
+        expect(back.ids).toEqual([1n, BigInt(huge)]);
+    });
+});