toiljs 0.0.61 → 0.0.63

package/build/compiler/index.js

@@ -90,15 +90,22 @@ export async function buildServer(root) {
     const binJs = resolveToilscriptBin(root);
     const files = serverEntryFiles(root);
     const split = splitSurfaceFiles(root, files);
-    if (split.hasDaemon) {
+    if (split.hasDaemon || split.hasStream) {
         const artifacts = serverArtifacts(root);
-        await runToilscriptPass(root, binJs, split.cold, {
-            mode: 'cold',
-            outFile: artifacts.cold,
-            withRpc: false,
-        });
-        if (split.hot.length > 0)
-            await runToilscriptPass(root, binJs, split.hot, {
+        if (split.hasDaemon)
+            await runToilscriptPass(root, binJs, split.cold, {
+                mode: 'cold',
+                outFile: artifacts.cold,
+                withRpc: false,
+            });
+        if (split.hasStream && split.stream.length > 0)
+            await runToilscriptPass(root, binJs, split.stream, {
+                mode: 'hot',
+                outFile: artifacts.stream,
+                withRpc: false,
+            });
+        if (split.request.length > 0)
+            await runToilscriptPass(root, binJs, split.request, {
                 mode: 'hot',
                 outFile: serverWasmFile(root),
                 withRpc: true,
@@ -123,11 +130,21 @@ function resolveToilscriptBin(root) {
     }
 }
 const COLD_DECORATOR = /^[ \t]*@(daemon|scheduled)\b/m;
-const HOT_DECORATOR = /^[ \t]*@(rest|route|stream|service|remote)\b/m;
+const STREAM_DECORATOR = /^[ \t]*@stream\b/m;
+const REQUEST_DECORATOR = /^[ \t]*@(rest|route|service|remote)\b/m;
+const RUNTIME_ENTRY = /from\s+['"]toiljs\/server\/runtime\/exports['"]/;
+function isStreamEntryFile(rel) {
+    return rel.endsWith('.stream.ts');
+}
+function isDaemonEntryFile(rel) {
+    return rel.endsWith('.daemon.ts');
+}
 export function splitSurfaceFiles(root, files) {
     let hasDaemon = false;
+    let hasStream = false;
     const cold = [];
-    const hot = [];
+    const stream = [];
+    const request = [];
     for (const rel of files) {
         let src = '';
         try {
@@ -135,19 +152,27 @@ export function splitSurfaceFiles(root, files) {
         }
         catch {
             cold.push(rel);
-            hot.push(rel);
+            stream.push(rel);
+            request.push(rel);
             continue;
         }
-        const isCold = COLD_DECORATOR.test(src);
-        const isHot = HOT_DECORATOR.test(src);
+        const isCold = COLD_DECORATOR.test(src) || isDaemonEntryFile(rel);
+        const isStream = STREAM_DECORATOR.test(src) || isStreamEntryFile(rel);
+        const isRequest = REQUEST_DECORATOR.test(src) ||
+            (RUNTIME_ENTRY.test(src) && !isStreamEntryFile(rel) && !isDaemonEntryFile(rel));
         if (isCold)
-            hasDaemon ||= /^[ \t]*@daemon\b/m.test(src);
-        if (!(isCold && !isHot))
-            hot.push(rel);
-        if (!(isHot && !isCold))
+            hasDaemon ||= /^[ \t]*@daemon\b/m.test(src) || isDaemonEntryFile(rel);
+        if (isStream)
+            hasStream = true;
+        const shared = !isCold && !isStream && !isRequest;
+        if (isCold || shared)
             cold.push(rel);
+        if (isStream || shared)
+            stream.push(rel);
+        if (isRequest || shared)
+            request.push(rel);
     }
-    return { hasDaemon, cold, hot };
+    return { hasDaemon, hasStream, cold, stream, request };
 }
 function runToilscriptPass(root, binJs, files, opts) {
     const args = [binJs, ...files, '--target', 'release'];
@@ -259,11 +284,13 @@ export function serverArtifacts(root) {
     let out = 'build/server/release.wasm';
     let hot;
     let cold;
+    let stream;
     try {
         const cfg = JSON.parse(fs.readFileSync(path.join(root, 'toilconfig.json'), 'utf8'));
         out = cfg.targets?.release?.outFile ?? out;
         hot = cfg.targets?.release?.hotFile;
         cold = cfg.targets?.release?.coldFile;
+        stream = cfg.targets?.release?.streamFile;
     }
     catch {
     }
@@ -274,6 +301,7 @@ export function serverArtifacts(root) {
     return {
         hot: path.resolve(root, hot ?? ins('hot')),
         cold: path.resolve(root, cold ?? ins('cold')),
+        stream: path.resolve(root, stream ?? ins('stream')),
     };
 }
 async function freeLoopbackPort() {

package/build/compiler/template-build.d.ts

@@ -1,5 +1,5 @@
-import { type ComponentType, type Context, createElement, type ReactNode } from 'react';
-import { renderToStaticMarkup } from 'react-dom/server';
+import { type ComponentType, type Context, createElement, type ReactNode, Suspense } from 'react';
+import { renderToString } from 'react-dom/server';
 import { type ResolvedToilConfig } from './config.js';
 export interface RouteRenderInput {
     name: string;
@@ -12,7 +12,8 @@ export interface RouteRenderInput {
     setSsrBuild: (on: boolean) => void;
     shell: string;
     createElement?: typeof createElement;
-    renderToStaticMarkup?: typeof renderToStaticMarkup;
+    renderToString?: typeof renderToString;
+    Suspense?: typeof Suspense;
 }
 export interface TemplateArtifacts {
     name: string;
@@ -24,7 +25,7 @@ export interface TemplateArtifacts {
 }
 export declare function assembleRouteElement(Page: ComponentType, layouts: ComponentType<{
     children?: ReactNode;
-}>[], loaderData: unknown, loaderContext: Context<unknown> | null, h?: typeof createElement): ReactNode;
+}>[], loaderData: unknown, loaderContext: Context<unknown> | null, h?: typeof createElement, SuspenseComp?: typeof Suspense): ReactNode;
 export declare function injectIntoShell(shell: string, routeHtml: string): string;
 export declare function extractRouteTemplate(input: RouteRenderInput): TemplateArtifacts;
 export declare function writeTemplateArtifacts(ssrDir: string, art: TemplateArtifacts): void;

package/build/compiler/template-build.js

@@ -1,8 +1,8 @@
 import fs from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
-import { createElement } from 'react';
-import { renderToStaticMarkup } from 'react-dom/server';
+import { createElement, Suspense } from 'react';
+import { renderToString } from 'react-dom/server';
 import { createServer } from 'vite';
 import { findLayout, findSpecialChain } from './generate.js';
 import { scanRoutes } from './routes.js';
@@ -11,13 +11,14 @@ import { assignSlotIds, coherenceHash, encodeSlots, extractFromHtml, } from './t
 import { createViteConfig } from './vite.js';
 const SSR_MARKER = '<template id="__toil_ssr"></template>';
 const ROOT_DIV = '<div id="root"></div>';
-export function assembleRouteElement(Page, layouts, loaderData, loaderContext, h = createElement) {
+export function assembleRouteElement(Page, layouts, loaderData, loaderContext, h = createElement, SuspenseComp = Suspense) {
     let node = h(Page);
     if (loaderContext) {
         node = h(loaderContext.Provider, { value: loaderData }, node);
     }
+    node = h(SuspenseComp, { fallback: null }, node);
     for (let i = layouts.length - 1; i >= 0; i--) {
-        node = h(layouts[i], null, node);
+        node = h(SuspenseComp, { fallback: null }, h(layouts[i], null, node));
     }
     return node;
 }
@@ -27,10 +28,17 @@ export function injectIntoShell(shell, routeHtml) {
     }
     return shell.replace(ROOT_DIV, `<div id="root">${routeHtml}</div>${SSR_MARKER}`);
 }
+function stripHoistedResourceTags(html) {
+    return html
+        .replace(/<link\b[^>]*>/gi, '')
+        .replace(/<meta\b[^>]*>/gi, '')
+        .replace(/<title\b[^>]*>[\s\S]*?<\/title>/gi, '');
+}
 export function extractRouteTemplate(input) {
     const h = input.createElement ?? createElement;
-    const render = input.renderToStaticMarkup ?? renderToStaticMarkup;
-    const element = assembleRouteElement(input.Page, input.layouts, input.loaderData, input.loaderContext, h);
+    const render = input.renderToString ?? renderToString;
+    const SuspenseComp = input.Suspense ?? Suspense;
+    const element = assembleRouteElement(input.Page, input.layouts, input.loaderData, input.loaderContext, h, SuspenseComp);
     input.setSsrBuild(true);
     let routeHtml;
     try {
@@ -39,7 +47,7 @@ export function extractRouteTemplate(input) {
     finally {
         input.setSsrBuild(false);
     }
-    const full = injectIntoShell(input.shell, routeHtml);
+    const full = injectIntoShell(input.shell, stripHoistedResourceTags(routeHtml));
     const extracted = extractFromHtml(full);
     const ids = assignSlotIds(extracted.slots);
     const hash = coherenceHash(extracted.tmpl, extracted.slots);
@@ -133,8 +141,9 @@ async function renderSsrRoutes(cfg, shell) {
                 const loaderData = typeof mod.loader === 'function'
                     ? await mod.loader({ params, searchParams: new URLSearchParams() })
                     : undefined;
+                const rootLayout = findLayout(cfg);
                 const layoutFiles = [
-                    ...(findLayout(cfg) ? [findLayout(cfg)] : []),
+                    ...(rootLayout ? [rootLayout] : []),
                     ...findSpecialChain(cfg, r.file, 'layout', false),
                 ];
                 const layouts = [];
@@ -143,6 +152,7 @@ async function renderSsrRoutes(cfg, shell) {
                     layouts.push(lm.default);
                 }
                 const name = routeTemplateName(r.pattern);
+                client.__setSsrLocation(samplePath(r.pattern));
                 const art = extractRouteTemplate({
                     name,
                     Page: mod.default,
@@ -152,13 +162,17 @@ async function renderSsrRoutes(cfg, shell) {
                     setSsrBuild: client.__setSsrBuild,
                     shell,
                     createElement: react.createElement,
-                    renderToStaticMarkup: reactDomServer.renderToStaticMarkup,
+                    renderToString: reactDomServer.renderToString,
+                    Suspense: react.Suspense,
                 });
                 rendered.push({ pattern: r.pattern, art });
             }
             catch (err) {
                 warn(`skipped ${r.pattern} (render failed: ${err instanceof Error ? err.message : String(err)}) — falls back to client rendering`);
             }
+            finally {
+                client.__setSsrLocation(null);
+            }
         }
     }
     finally {
@@ -213,6 +227,9 @@ function sampleParams(pattern) {
     }
     return params;
 }
+function samplePath(pattern) {
+    return pattern.replace(/[:*]+([A-Za-z0-9_]+)/g, 'sample');
+}
 export async function extractTemplates(cfg, hostName = 'edge', priorServerSlots = new Map()) {
     const shell = resolveShell(cfg, true);
     if (shell === null)

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

@@ -1,11 +1,10 @@
 import { store } from '../core/store';
 
 /** Typed RPC service (transport still a TODO): reached as `Server.stats.playerCount()` on the client. */
-@service
+/*@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

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

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "toiljs",
     "type": "module",
-    "version": "0.0.61",
+    "version": "0.0.63",
     "author": "Dacely",
     "description": "The modern React framework: a file-based React frontend and a ToilScript-compiled WebAssembly backend.",
     "repository": {

package/src/client/index.ts

@@ -40,6 +40,7 @@ export {
     useSearchParams,
     useRouter,
     useNavigationPending,
+    __setSsrLocation,
 } from './routing/hooks.js';
 export type { RouterInstance } from './routing/hooks.js';
 export {

package/src/client/routing/hooks.ts

@@ -101,12 +101,25 @@ function useLocationSubscription(): void {
     );
 }
 
+/** Build-only override for the SSR pathname, set by the template extractor per route via
+ * {@link __setSsrLocation}. Lets location-dependent markup (a `NavLink`'s active class /
+ * `aria-current`) render as the route's own URL so it matches what the client computes on
+ * hydration, instead of the `/` default. Ignored in the browser (the live URL wins). */
+let ssrLocationOverride: string | null = null;
+
+/** Build-only: set the pathname the extractor is currently rendering (or `null` to clear).
+ * No effect in the browser. Exported through `toiljs/client` for the compiler. */
+export function __setSsrLocation(path: string | null): void {
+    ssrLocationOverride = path;
+}
+
 /** Subscribes to and returns the current `location.pathname`. SSR-safe: during a
- *  server render (build-time template extraction / edge SSR) there is no `window`,
- *  so it reports `/`; the client recomputes on hydration. */
+ *  server render there is no `window`, so it reports the extractor's override (the route
+ *  being rendered) or `/`; the client recomputes on hydration. */
 export function useLocation(): string {
     useLocationSubscription();
-    return typeof window === 'undefined' ? '/' : window.location.pathname;
+    if (typeof window === 'undefined') return ssrLocationOverride ?? '/';
+    return window.location.pathname;
 }
 
 /** Alias of {@link useLocation}: the current `location.pathname`. */

package/src/client/routing/mount.tsx

@@ -4,39 +4,16 @@ import { DevToolbar } from '../dev/devtools.js';
 import { DevErrorBoundary, DevErrorOverlay, initDevErrorOverlay } from '../dev/error-overlay.js';
 import { initNavigation } from '../navigation/navigation.js';
 import { startPrefetcher } from '../navigation/prefetch.js';
-import { hydrateLoaderData } from './loader.js';
-import { matchRoute } from './match.js';
 import { Router } from './Router.js';
 import type { ErrorComponentLoader, LayoutLoader, NotFoundLoader, RouteDef } from '../types.js';
 
 /** An edge-SSR document carries a `<* id="__toil_ssr">` marker baked into the
- * template; its presence flips `mount` to `hydrateRoot`. */
+ * template; its presence means the server rendered real first-paint HTML into
+ * `#root`, so `mount` hydrates it in place rather than client-rendering. */
 function isSsrDocument(): boolean {
     return typeof document !== 'undefined' && document.getElementById('__toil_ssr') !== null;
 }
 
-/** Seed the loader cache from the server's `#__toil_state` JSON so the first
- * client render uses the same data the server stamped (clean hydration). */
-function seedSsrHydration(routes: RouteDef[]): void {
-    if (typeof document === 'undefined' || typeof window === 'undefined') return;
-    const el = document.getElementById('__toil_state');
-    if (!el || !el.textContent) return;
-    let state: { data?: unknown };
-    try {
-        state = JSON.parse(el.textContent) as { data?: unknown };
-    } catch {
-        return;
-    }
-    const { pathname, search } = window.location;
-    for (const route of routes) {
-        const params = matchRoute(route.pattern, pathname);
-        if (params) {
-            hydrateLoaderData(route, params, pathname, search, state.data);
-            return;
-        }
-    }
-}
-
 /**
  * Mounts the toil client app into `#root` and starts idle link prefetching. Called by the
  * compiler-generated `.toil/entry.tsx`.
@@ -66,9 +43,9 @@ export function mount(
     if ((import.meta as unknown as { env: { DEV: boolean } }).env.DEV) {
         initDevErrorOverlay();
         // Dev tools (error overlay + toolbar) render into their OWN body-level
-        // container, never inside #root, so they don't perturb #root's markup.
-        // That lets a dev SSR document hydrate cleanly (the server only rendered
-        // the app into #root), and is harmless for a plain client-rendered page.
+        // container, never inside `#root`, so `#root` holds only the app markup.
+        // That lets an SSR document hydrate cleanly (the server only rendered the
+        // app into `#root`), and is harmless for a plain client-rendered page.
         const devEl = document.createElement('div');
         devEl.id = '__toil_dev';
         document.body.appendChild(devEl);
@@ -83,19 +60,14 @@ export function mount(
         );
         const tree = <DevErrorBoundary>{app}</DevErrorBoundary>;
         if (isSsrDocument()) {
-            // Dev edge-SSR: the dev server served real server-rendered markup
-            // (guest `render` + splice); hydrate it in place, same as production,
-            // instead of client-rendering from scratch.
-            seedSsrHydration(routes);
+            // Edge-SSR: hydrate the server-rendered markup in place.
             hydrateRoot(el, tree);
         } else {
             createRoot(el).render(tree);
         }
     } else if (isSsrDocument()) {
-        // Edge-SSR: the document already holds server-rendered markup. Seed the
-        // loader cache from `#__toil_state` and hydrate in place (reuse the DOM)
-        // rather than client-rendering from scratch.
-        seedSsrHydration(routes);
+        // Edge-SSR: the document already holds server-rendered markup; hydrate it
+        // (reuse the DOM) rather than client-rendering from scratch.
         hydrateRoot(el, app);
     } else {
         createRoot(el).render(app);

package/src/client/ssr/markers.tsx

@@ -21,7 +21,7 @@
  * does (it does: see `server/runtime/ssr/escape.ts`).
  */
 
-import { createElement, Fragment, type ReactNode } from 'react';
+import { createElement, Fragment, type ReactNode, useEffect, useState } from 'react';
 
 /** Token framing codepoints (Unicode Private Use Area). */
 export const SENTINEL_START = String.fromCharCode(0xe000);
@@ -145,7 +145,10 @@ export function Repeat<T>(props: RepeatProps<T>): ReactNode {
     return createElement(
         Fragment,
         null,
-        props.each.map((item, i) => props.children(item, i)),
+        // Each row is wrapped in a keyed Fragment so React has a stable list key (the
+        // row markup itself need not carry one). Index keys are fine here: an SSR'd
+        // region hydrates 1:1 against the host's pre-stamped rows and does not reorder.
+        props.each.map((item, i) => createElement(Fragment, { key: i }, props.children(item, i))),
     );
 }
 
@@ -154,9 +157,16 @@ export interface IslandProps {
 }
 
 /** A client-only escape hatch for content outside the server-template subset.
- * Client: renders `children`. Build: renders nothing (the block is empty in the
- * server HTML and appears after hydration; it gets no first-paint/SEO). */
+ * Build: renders nothing (empty in the server HTML). Client: ALSO renders nothing
+ * on the first (hydration) render, so it matches the empty server markup, then a
+ * mount effect reveals `children` on the next commit. Rendering the children
+ * during hydration instead would diverge from the server's empty markup and trip
+ * a hydration mismatch. So an island gets no first-paint / SEO, by design. */
 export function Island(props: IslandProps): ReactNode {
-    if (ssrBuild) return null;
+    const [hydrated, setHydrated] = useState(false);
+    useEffect(() => {
+        setHydrated(true);
+    }, []);
+    if (ssrBuild || !hydrated) return null;
     return createElement(Fragment, null, props.children);
 }