toiljs 0.0.70 → 0.0.72

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [v0.0.71] - 2026-06-26
+
+- No changes
+
+
+## [v0.0.70] - 2026-06-26
+
+- No changes
+
+
 ## [v0.0.69] - 2026-06-25
 
 - No changes

package/examples/basic/client/routes/features/index.tsx

@@ -79,8 +79,22 @@ const groups: { heading: string; items: { href: Toil.Href; label: string; note:
     {
         heading: 'Components and runtime',
         items: [
-            { href: '/features/script', label: 'Script', note: 'Toil.Script with a load strategy' },
-            { href: '/features/realtime', label: 'WebSocket channel', note: 'Toil.useChannel against /_toil' }
+            { href: '/features/script', label: 'Script', note: 'Toil.Script with a load strategy' }
+        ]
+    },
+    {
+        heading: 'Realtime and streams',
+        items: [
+            {
+                href: '/features/realtime',
+                label: 'Realtime socket',
+                note: 'Toil.useChannel -> a resident @stream box at /echo'
+            },
+            {
+                href: '/features/stream',
+                label: 'Typed @stream',
+                note: 'Server.Stream.Echo.connect(), a resident per-connection box'
+            }
         ]
     }
 ];

package/examples/basic/client/routes/features/realtime.tsx

@@ -1,18 +1,20 @@
 export const metadata: Toil.Metadata = {
-    title: 'Realtime',
-    description: 'A typed WebSocket channel to the server with connect, reconnect, and message decoding.'
+    title: 'Realtime socket',
+    description: 'A raw WebSocket channel to a resident @stream box: send a frame, watch the box reply.'
 };
 
-// Toil.useChannel opens a WebSocket to the server (default path /_toil), tracks `connected`, collects
-// `messages`, and exposes `send`. It reconnects automatically. With no server socket running the demo
-// simply shows "disconnected", the API is the same once the server handles the channel.
+// Toil.useChannel opens a raw WebSocket to a @stream route (here /echo, served by the Echo @stream box in
+// server/streams/Echo.ts). It tracks `connected`, collects every reply in `messages`, and exposes `send`;
+// it reconnects automatically. The dev server bridges the socket to the resident box (each frame ->
+// @message -> reply), and the Toil edge does the same over a real WebTransport session.
 export default function RealtimeDemo() {
-    const chat = Toil.useChannel({ path: '/_toil' });
+    const chat = Toil.useChannel({ path: '/echo' });
+    const text = (m: string | ArrayBuffer): string => (typeof m === 'string' ? m : new TextDecoder().decode(m));
     return (
         <main>
-            <h1>Realtime</h1>
+            <h1>Realtime socket</h1>
             <p>
-                Connection: <strong>{chat.connected ? 'connected' : 'disconnected'}</strong>, messages received:{' '}
+                Connection: <strong>{chat.connected ? 'connected' : 'disconnected'}</strong>, replies:{' '}
                 <strong>{chat.messages.length}</strong>.
             </p>
             <p>
@@ -20,11 +22,21 @@ export default function RealtimeDemo() {
                     Send ping
                 </button>
             </p>
+            {chat.messages.length > 0 && (
+                <ul>
+                    {chat.messages.map((m, i) => (
+                        <li key={i}>
+                            <code>{text(m)}</code>
+                        </li>
+                    ))}
+                </ul>
+            )}
             <p style={{ opacity: 0.6 }}>
                 <code>
-                    const chat = Toil.useChannel({'{'} path: '/_toil' {'}'})
-                </code>
-                , connect, reconnect, and decoding are handled for you.
+                    Toil.useChannel({'{'} path: '/echo' {'}'})
+                </code>{' '}
+                - the resident box replies <code>pong #N</code>; the advancing counter proves its state survives every
+                frame.
             </p>
             <p>
                 <Toil.Link href="/features">Back to features</Toil.Link>

package/examples/basic/client/routes/features/stream.tsx

@@ -0,0 +1,81 @@
+import { useState } from 'react';
+
+import type { StreamChannel } from 'toiljs/client';
+
+export const metadata: Toil.Metadata = {
+    title: 'Typed @stream',
+    description: 'The generated Server.Stream.Echo client: a resident per-connection @stream box.'
+};
+
+// The typed @stream client (Server.Stream.Echo, generated into shared/server.ts from the @stream catalog)
+// opens a resident box. In `npm run dev` it speaks the same-origin dev WebSocket; on the Toil edge it is a
+// real WebTransport session. The box (server/streams/Echo.ts) replies `pong #N` - the counter proves the
+// SAME box handled every message (residency).
+export default function StreamDemo() {
+    const [log, setLog] = useState<string[]>([]);
+    const [msg, setMsg] = useState('hello from Server.Stream');
+    const [channel, setChannel] = useState<StreamChannel | null>(null);
+    const add = (line: string): void => setLog((l) => [...l, line]);
+
+    async function connect(): Promise<void> {
+        // shared/server.ts (generated by the server build) attaches globalThis.Server. Import it lazily,
+        // browser-only, so SSR never touches its globalThis.location access.
+        await import('../../../shared/server');
+        add('connecting -> /echo');
+        try {
+            const c = await Server.Stream.Echo.connect();
+            add('session READY');
+            c.onMessage((bytes) => add('<- ' + new TextDecoder().decode(bytes)));
+            c.onClose((code) => add('closed (0x' + code.toString(16) + ')'));
+            setChannel(c);
+        } catch (e) {
+            add('connect failed: ' + String(e));
+        }
+    }
+
+    function send(): void {
+        if (channel === null) return;
+        channel.send(new TextEncoder().encode(msg));
+        add('-> ' + msg);
+    }
+
+    return (
+        <main>
+            <h1>Typed @stream</h1>
+            <p>
+                <code>Server.Stream.Echo.connect()</code> opens a resident <code>@stream</code> box. In{' '}
+                <code>npm run dev</code> it is the same-origin dev WebSocket; on the edge it is a real WebTransport
+                session. The box replies <code>pong #N</code> - the counter proves its state survives every message.
+            </p>
+            <p>
+                <input
+                    value={msg}
+                    onChange={(e) => setMsg(e.target.value)}
+                    style={{ font: 'inherit', padding: '4px 8px', minWidth: 260 }}
+                />
+            </p>
+            <p>
+                <button type="button" onClick={() => void connect()} disabled={channel !== null}>
+                    Connect
+                </button>{' '}
+                <button type="button" onClick={send} disabled={channel === null}>
+                    Send
+                </button>
+            </p>
+            <pre
+                style={{
+                    background: '#111',
+                    color: '#ddd',
+                    padding: 10,
+                    borderRadius: 6,
+                    minHeight: 90,
+                    whiteSpace: 'pre-wrap'
+                }}>
+                {log.join('\n')}
+            </pre>
+            <p>
+                <Toil.Link href="/features">Back to features</Toil.Link>
+            </p>
+        </main>
+    );
+}

package/examples/basic/server/main.stream.ts

@@ -0,0 +1,20 @@
+// The L2/L3 STREAM surface entry.
+//
+// This is a SECOND entry point of the project, distinct from `main.ts` (the L1 request surface). It
+// compiles into its OWN artifact - `build/server/release-stream.wasm` - which the Toil edge loads as a
+// RESIDENT per-connection box on the L2/L3 stream tier, and which the dev server serves over a WebSocket.
+//
+// Importing the `@stream` modules here pulls their compiler-generated `stream_dispatch` export (the
+// connect/message/close/disconnect lifecycle entry) into this artifact. Add a stream as you grow:
+//   import './streams/Echo';
+
+import { revertOnError } from 'toiljs/server/runtime/abort/abort';
+
+import './streams/Echo';
+
+// Required: re-export the WASM entry points (the linear memory + the runtime hooks the host binds) and
+// the abort hook, exactly like main.ts.
+export * from 'toiljs/server/runtime/exports';
+export function abort(message: string, fileName: string, line: u32, column: u32): void {
+    revertOnError(message, fileName, line, column);
+}

package/examples/basic/server/streams/Echo.ts

@@ -0,0 +1,44 @@
+/**
+ * A `@stream` protocol handler mounted at `/echo` - the SERVER side of the Realtime feature.
+ *
+ * Unlike a `@rest` route (a fresh handler per request), a `@stream` runs as a RESIDENT wasm box per
+ * connection: it is created on `@connect`, lives for the whole connection, and is torn down on `@close`.
+ * On the Toil edge that box is distributed across the L2/L3 stream nodes and pinned to ONE worker for the
+ * connection's life via QUIC connection-id steering, so its in-box state survives every event.
+ *
+ * The `count` field below is the proof: it persists across every `@message` because the box is never
+ * reset between events (a `@rest` handler's fields reset each request). Each reply carries the running
+ * count, so the client can watch the SAME resident box advance.
+ *
+ * Two browser clients drive this exact box (both land here in dev over a WebSocket, and on the edge over
+ * WebTransport):
+ *   - the raw socket:   Toil.useChannel({ path: '/echo' })   (client/routes/features/realtime.tsx)
+ *   - the typed stream: await Server.Stream.Echo.connect()    (client/routes/features/stream.tsx)
+ */
+@stream('echo')
+class Echo {
+    // Resident per-connection state: survives across events (the box is never reset between them).
+    private count: i32 = 0;
+
+    @connect
+    onConnect(): void {
+        // A fresh connection: its dedicated box starts the counter at 0.
+        this.count = 0;
+    }
+
+    @message
+    onMessage(packet: StreamPacket): StreamOutbound {
+        // Count every inbound frame - and PERSIST across them, because this is the same resident box for
+        // the whole connection - then reply with the running count so the client sees it advance.
+        this.count = this.count + 1;
+        // The count proves residency (the same box handled every frame); the inbound length proves the
+        // frame arrived. We avoid decoding the inbound here to keep the handler bytes-safe.
+        const reply = 'pong #' + this.count.toString() + ' (' + packet.bytes().length.toString() + ' bytes in)';
+        return StreamOutbound.reply(Uint8Array.wrap(String.UTF8.encode(reply)));
+    }
+
+    @close
+    onClose(): void {
+        // Graceful close: the per-connection box is torn down after this hook.
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "toiljs",
     "type": "module",
-    "version": "0.0.70",
+    "version": "0.0.72",
     "author": "Dacely",
     "description": "The modern React framework: a file-based React frontend and a ToilScript-compiled WebAssembly backend.",
     "repository": {
@@ -134,7 +134,7 @@
         "nodemailer": "^9.0.1",
         "picocolors": "^1.1.1",
         "sharp": "^0.35.2",
-        "toilscript": "^0.1.45",
+        "toilscript": "^0.1.47",
         "typescript-eslint": "^8.62.0",
         "vite": "^8.1.0",
         "vite-imagetools": "^10.0.1",
@@ -145,7 +145,7 @@
         "prettier": ">=3.0.0",
         "react": ">=18.0.0",
         "react-dom": ">=18.0.0",
-        "toilscript": ">=0.1.45",
+        "toilscript": ">=0.1.47",
         "typescript": ">=6.0.0"
     },
     "overrides": {