toiljs 0.0.34 → 0.0.37

package/src/client/auth.ts

@@ -0,0 +1,327 @@
+/**
+ * Client half of the post-quantum auth primitive (browser).
+ *
+ * The password never leaves this module. It is stretched with Argon2id into a
+ * 32-byte seed, which deterministically expands into an ML-DSA-44 keypair
+ * (FIPS 204). Only the 1312-byte PUBLIC key is ever sent; the secret key and
+ * the seed are zeroized the instant signing is done. There is no recovery: the
+ * password IS the key.
+ *
+ * Wire encoding is deterministic binary (`DataWriter`/`DataReader`), never
+ * JSON, byte-identical to the server's `AuthService.buildLoginMessage`.
+ */
+
+import { argon2id, sha256 } from 'hash-wasm';
+import { ml_dsa44 } from '@btc-vision/post-quantum/ml-dsa.js';
+
+import { DataReader, DataWriter } from 'toiljs/io';
+
+/** FIPS 204 signing context (domain separator). Byte-identical to the server. */
+export const LOGIN_CONTEXT = 'qauth:login:v1';
+
+export const PUBLIC_KEY_LEN = 1312;
+export const SECRET_KEY_LEN = 2560;
+export const SIGNATURE_LEN = 2420;
+export const SEED_LEN = 32;
+
+/** Argon2id parameters, pinned PER ACCOUNT and echoed by the server. The client
+ *  derives against whatever it is handed -- never hardcoded -- so a future
+ *  parameter bump just works. They are part of the credential. */
+export interface KdfParams {
+    /** `m`: memory in kibibytes (>= 256 MiB = 262144). */
+    readonly memKiB: number;
+    /** `t`: iterations (>= 3). */
+    readonly iterations: number;
+    /** `p`: degree of parallelism. */
+    readonly parallelism: number;
+    /** per-account salt (16 bytes, server-issued). */
+    readonly salt: Uint8Array;
+}
+
+/** A server login challenge. */
+export interface Challenge {
+    readonly cid: Uint8Array;
+    readonly aud: string;
+    readonly kdf: KdfParams;
+    readonly nonce: Uint8Array;
+    readonly iat: bigint;
+    readonly exp: bigint;
+}
+
+/** Overwrite a secret buffer with random bytes, then zero. Best-effort: JS GC
+ *  cannot scrub copies, so we never store or close over secrets beyond one call. */
+function wipe(buf: Uint8Array): void {
+    crypto.getRandomValues(buf as unknown as Uint8Array<ArrayBuffer>);
+    buf.fill(0);
+}
+
+/** Argon2id(NFKC(password), salt; m,t,p, len=32) -> 32-byte ML-DSA seed. */
+async function deriveSeed(password: string, kdf: KdfParams): Promise<Uint8Array> {
+    return argon2id({
+        password: new TextEncoder().encode(password.normalize('NFKC')),
+        salt: kdf.salt,
+        iterations: kdf.iterations,
+        parallelism: kdf.parallelism,
+        memorySize: kdf.memKiB,
+        hashLength: SEED_LEN,
+        outputType: 'binary',
+    });
+}
+
+/** The canonical login message `M`, fixed binary layout (see the server's
+ *  `AuthService.buildLoginMessage`). Both ends MUST produce identical bytes. */
+export function buildLoginMessage(
+    sub: string,
+    aud: string,
+    cid: Uint8Array,
+    nonce: Uint8Array,
+    iat: bigint,
+    exp: bigint,
+): Uint8Array {
+    return new DataWriter()
+        .writeU8(1)
+        .writeString(sub)
+        .writeString(aud)
+        .writeBytes(cid)
+        .writeBytes(nonce)
+        .writeU64(iat)
+        .writeU64(exp)
+        .toBytes();
+}
+
+// ---- wire codecs (the example `Auth` @rest controller mirrors these) -------
+
+function decodeKdf(r: DataReader): KdfParams {
+    return {
+        memKiB: r.readU32(),
+        iterations: r.readU32(),
+        parallelism: r.readU32(),
+        salt: r.readBytes(),
+    };
+}
+
+function decodeChallenge(r: DataReader): Challenge {
+    const cid = r.readBytes();
+    const aud = r.readString();
+    const kdf = decodeKdf(r);
+    const nonce = r.readBytes();
+    const iat = r.readU64();
+    const exp = r.readU64();
+    return { cid, aud, kdf, nonce, iat, exp };
+}
+
+async function postBinary(baseUrl: string, path: string, body: Uint8Array): Promise<DataReader> {
+    const res = await fetch(baseUrl + path, {
+        method: 'POST',
+        headers: { 'content-type': 'application/octet-stream' },
+        body: body as BodyInit,
+        credentials: 'same-origin',
+    });
+    if (!res.ok) throw new Error('auth: request failed');
+    return new DataReader(new Uint8Array(await res.arrayBuffer()));
+}
+
+export interface AuthOptions {
+    /** Endpoint prefix the server mounts the auth controller under. */
+    readonly baseUrl?: string;
+}
+
+/**
+ * Register a new account: the server issues a salt + KDF params, the client
+ * derives the keypair and submits ONLY the public key. Throws on failure.
+ */
+export async function register(username: string, password: string, opts: AuthOptions = {}): Promise<void> {
+    const baseUrl = opts.baseUrl ?? '/auth';
+
+    // 1. Ask the server for a salt + params (it also confirms the name is free).
+    const start = await postBinary(baseUrl, '/register/start', new DataWriter().writeString(username).toBytes());
+    const status = start.readU8();
+    if (status !== 0) throw new Error('auth: registration unavailable');
+    const kdf = decodeKdf(start);
+
+    // 2. Derive, keep only the public key, wipe the secret + seed immediately.
+    const seed = await deriveSeed(password, kdf);
+    let publicKey: Uint8Array;
+    try {
+        const kp = ml_dsa44.keygen(seed);
+        publicKey = kp.publicKey;
+        wipe(kp.secretKey);
+    } finally {
+        wipe(seed);
+    }
+    if (publicKey.length !== PUBLIC_KEY_LEN) throw new Error('auth: bad public key length');
+
+    // 3. Submit the public key.
+    const finish = await postBinary(
+        baseUrl,
+        '/register/finish',
+        new DataWriter().writeString(username).writeBytes(publicKey).toBytes(),
+    );
+    if (finish.readU8() !== 0) throw new Error('auth: registration rejected');
+}
+
+/**
+ * Log in: fetch a challenge, re-derive the keypair, sign the rebuilt message
+ * under the login context, and submit only `{cid, signature}`. The secret key
+ * and seed are wiped the instant the single sign completes. Returns the opaque
+ * session token the server mints (and any session cookie it sets). Throws on
+ * failure with one generic message.
+ */
+export async function login(username: string, password: string, opts: AuthOptions = {}): Promise<Uint8Array> {
+    const baseUrl = opts.baseUrl ?? '/auth';
+
+    // 1. Challenge (the server returns one even for unknown users -> no oracle).
+    const ch = decodeChallenge(
+        await postBinary(baseUrl, '/login/start', new DataWriter().writeString(username).toBytes()),
+    );
+
+    // Client-side fast-fail only; the server re-checks expiry authoritatively.
+    if (BigInt(Math.floor(Date.now() / 1000)) >= ch.exp) throw new Error('auth: challenge expired');
+
+    // 2. Build the exact message, derive, sign once, wipe.
+    const message = buildLoginMessage(username, ch.aud, ch.cid, ch.nonce, ch.iat, ch.exp);
+    const seed = await deriveSeed(password, ch.kdf);
+    let signature: Uint8Array;
+    try {
+        const kp = ml_dsa44.keygen(seed);
+        try {
+            signature = ml_dsa44.sign(message, kp.secretKey, { context: new TextEncoder().encode(LOGIN_CONTEXT) });
+        } finally {
+            wipe(kp.secretKey);
+        }
+    } finally {
+        wipe(seed);
+    }
+    if (signature.length !== SIGNATURE_LEN) throw new Error('auth: bad signature length');
+
+    // 3. Submit {cid, signature}; the server consumes the challenge atomically,
+    //    rebuilds the message from its own stored values, and verifies.
+    const res = await postBinary(
+        baseUrl,
+        '/login/finish',
+        new DataWriter().writeBytes(ch.cid).writeBytes(signature).toBytes(),
+    );
+    if (res.readU8() !== 0) throw new Error('auth: login failed');
+    return res.readBytes(); // session token
+}
+
+/** Lowercase hex of `bytes`. */
+function toHex(bytes: Uint8Array): string {
+    let s = '';
+    for (const b of bytes) s += b.toString(16).padStart(2, '0');
+    return s;
+}
+
+/** The signed identity proof produced by {@link proveIdentity}. */
+export interface IdentityProof {
+    /** The wire envelope to POST to `/pq/verify`: `str(sub) str(token)
+     *  bytes(publicKey) bytes(signature)`, where `token` is the edge's
+     *  HMAC-signed challenge. The server re-opens the token, rebuilds the login
+     *  message from the values inside it, and `AuthService.verifyLogin`s it. */
+    readonly envelope: Uint8Array;
+    /** First bytes of the 1312-byte ML-DSA-44 public key, for display. */
+    readonly publicKeyHex: string;
+    /** First bytes of the SERVER-issued nonce that was signed, for display. */
+    readonly nonceHex: string;
+    /** Signature length (always 2420 for ML-DSA-44), for display. */
+    readonly signatureLen: number;
+    /** Argon2id wall-clock spent deriving the keypair, ms (for display). */
+    readonly deriveMs: number;
+}
+
+/** Deterministic 16-byte Argon2id salt for the demo, so the same
+ *  username + password always maps to the same identity (keypair).
+ *  Uses hash-wasm's SHA-256 (pure WebAssembly), not `crypto.subtle`, so it
+ *  works in an insecure context (plain HTTP), where `crypto.subtle` is
+ *  undefined. */
+async function demoSalt(username: string): Promise<Uint8Array> {
+    const hex = await sha256('pq-demo|' + username);
+    const out = new Uint8Array(16);
+    for (let i = 0; i < 16; i++) out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    return out;
+}
+
+/**
+ * DEMO helper: run the full post-quantum challenge-response in the browser.
+ * Fetches a SERVER-issued challenge (`GET {baseUrl}/challenge`), stretches the
+ * password with Argon2id into an ML-DSA-44 keypair, signs the login message
+ * built from the SERVER's nonce/cid/iat/exp, and returns the wire envelope the
+ * edge verifies (`AuthService.verifyLogin`). The secret key and seed are wiped
+ * before returning; only the public key + signature leave the tab.
+ *
+ * The nonce is server-chosen and tamper-proof (the challenge token is
+ * HMAC-signed by the edge), so a client cannot pre-sign or substitute its own.
+ * It is still NOT the full production login -- there is no single-use consume, so
+ * within the challenge TTL a captured proof could be replayed; that needs an
+ * atomic store (see {@link login} and server/routes/Auth.ts). Demo-light
+ * Argon2id params (16 MiB / 2 passes) keep it responsive in a tab; a real
+ * deployment uses >= 256 MiB.
+ */
+export async function proveIdentity(
+    username: string,
+    password: string,
+    opts: { baseUrl?: string } = {},
+): Promise<IdentityProof> {
+    const baseUrl = opts.baseUrl ?? '/pq';
+
+    // 1. Server-issued challenge: aud, cid, nonce, iat, exp, and the signed token.
+    const cres = await fetch(baseUrl + '/challenge', { credentials: 'same-origin' });
+    if (!cres.ok) throw new Error('pq: challenge request failed');
+    const cr = new DataReader(new Uint8Array(await cres.arrayBuffer()));
+    const aud = cr.readString();
+    const cid = cr.readBytes();
+    const nonce = cr.readBytes();
+    const iat = cr.readU64();
+    const exp = cr.readU64();
+    const token = cr.readString();
+
+    // 2. Derive the keypair and sign the message built from the SERVER's values.
+    const salt = await demoSalt(username);
+    const t0 = Date.now();
+    const seed = await argon2id({
+        password: new TextEncoder().encode(password.normalize('NFKC')),
+        salt,
+        iterations: 2,
+        parallelism: 1,
+        memorySize: 16 * 1024, // 16 MiB: demo-light, responsive in a tab
+        hashLength: SEED_LEN,
+        outputType: 'binary',
+    });
+    const deriveMs = Date.now() - t0;
+
+    const message = buildLoginMessage(username, aud, cid, nonce, iat, exp);
+    let publicKey: Uint8Array;
+    let signature: Uint8Array;
+    try {
+        const kp = ml_dsa44.keygen(seed);
+        publicKey = kp.publicKey;
+        try {
+            signature = ml_dsa44.sign(message, kp.secretKey, {
+                context: new TextEncoder().encode(LOGIN_CONTEXT),
+            });
+        } finally {
+            wipe(kp.secretKey);
+        }
+    } finally {
+        wipe(seed);
+    }
+
+    // 3. Envelope: sub + the server's token + the public key + the signature.
+    const envelope = new DataWriter()
+        .writeString(username)
+        .writeString(token)
+        .writeBytes(publicKey)
+        .writeBytes(signature)
+        .toBytes();
+
+    return {
+        envelope,
+        publicKeyHex: toHex(publicKey.slice(0, 16)),
+        nonceHex: toHex(nonce.slice(0, 16)),
+        signatureLen: signature.length,
+        deriveMs,
+    };
+}
+
+/** The client auth surface, grouped for `Auth.register` / `Auth.login` use. */
+export const Auth = { register, login, proveIdentity, buildLoginMessage, LOGIN_CONTEXT } as const;

package/src/client/index.ts

@@ -10,6 +10,8 @@
 
 export { mount } from './routing/mount.js';
 export { Router } from './routing/Router.js';
+export { Auth, register as authRegister, login as authLogin, proveIdentity, buildLoginMessage, LOGIN_CONTEXT } from './auth.js';
+export type { KdfParams, Challenge, AuthOptions, IdentityProof } from './auth.js';
 export { Link } from './navigation/Link.js';
 export type { LinkProps } from './navigation/Link.js';
 export { NavLink, matchActive } from './navigation/NavLink.js';
@@ -34,7 +36,7 @@ export {
     useNavigationPending,
 } from './routing/hooks.js';
 export type { RouterInstance } from './routing/hooks.js';
-export { useLoaderData, revalidate, invalidateLoaderData } from './routing/loader.js';
+export { useLoaderData, revalidate, invalidateLoaderData, LoaderDataContext } from './routing/loader.js';
 export type {
     LoaderArgs,
     LoaderFunction,
@@ -89,3 +91,5 @@ export { Slot } from './components/Slot.js';
 export type { SlotProps } from './components/Slot.js';
 export { Server } from './rpc.js';
 export { parseError } from './errors.js';
+export { Hole, RawHtml, Repeat, Island, __setSsrBuild, __isSsrBuild } from './ssr/markers.js';
+export type { HoleProps, RawHtmlProps, RepeatProps, IslandProps } from './ssr/markers.js';

package/src/client/routing/loader.ts

@@ -260,6 +260,62 @@ export function readRouteData(
     return entry.value;
 }
 
+/**
+ * Seed the loader cache from server-rendered hydration state, BEFORE the first
+ * client render (called by `mount` on an SSR document). The route's module
+ * still loads (the browser needs the component), but its `loader` does NOT
+ * re-run: the server's `data` is used, so the first client render reproduces
+ * the server HTML and `hydrateRoot` stays clean. The entry is `prefetched`, so
+ * the NEXT navigation re-evaluates the route's `revalidate` policy normally.
+ *
+ * For a flash-free hydrate the SSR document should modulepreload the route
+ * chunk, so `route.load()` resolves in a microtask and the root never suspends.
+ */
+export function hydrateLoaderData(
+    route: RouteDef,
+    params: RouteParams,
+    pathname: string,
+    search: string,
+    data: unknown,
+): void {
+    const key = loaderKey(pathname, search);
+    if (cache.has(key)) return;
+    const epoch = navigationEpoch();
+    const entry: Entry = {
+        status: 'pending',
+        promise: Promise.resolve(),
+        loadedAt: 0,
+        revalidate: 0,
+        epoch,
+        hasLoader: true,
+        prefetched: true,
+    };
+    entry.promise = route.load().then(
+        async (mod: RouteModule) => {
+            const searchParams = new URLSearchParams(search);
+            let head: HeadSpec | undefined;
+            if (mod.generateMetadata) {
+                head = resolveMetadata(await mod.generateMetadata({ params, searchParams, data }));
+            } else if (mod.metadata) {
+                head = resolveMetadata(mod.metadata);
+            }
+            entry.value = { Component: mod.default, data, head };
+            entry.revalidate = mod.revalidate ?? 0;
+            entry.loadedAt = Date.now();
+            entry.status = 'done';
+            emitCache();
+        },
+        (error: unknown) => {
+            entry.error = error;
+            entry.loadedAt = Date.now();
+            entry.status = 'error';
+            emitCache();
+        },
+    );
+    cache.set(key, entry);
+    emitCache();
+}
+
 /** Clears all cached loader data, so the next render re-runs loaders (used by router.refresh). */
 export function clearLoaderData(): void {
     cache.clear();

package/src/client/routing/mount.tsx

@@ -1,4 +1,4 @@
-import { createRoot } from 'react-dom/client';
+import { createRoot, hydrateRoot } from 'react-dom/client';
 
 import { DevToolbar } from '../dev/devtools.js';
 import {
@@ -8,9 +8,39 @@ import {
 } 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`. */
+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`.
@@ -46,6 +76,12 @@ export function mount(
                 <DevToolbar routes={routes} slots={slots} />
             </>,
         );
+    } 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);
+        hydrateRoot(el, app);
     } else {
         createRoot(el).render(app);
     }

package/src/client/ssr/markers.tsx

@@ -0,0 +1,140 @@
+/**
+ * Edge-SSR hole markers. A route opts into server rendering by wrapping its
+ * dynamic bits in these components; the compiler's template extractor finds
+ * them deterministically (rather than guessing which `{expr}` is dynamic).
+ *
+ * The markers are TRANSPARENT at runtime: in the browser `<Hole>` renders its
+ * children, `<Repeat>` renders `each.map(...)`, `<RawHtml>` renders a
+ * `dangerouslySetInnerHTML` wrapper, `<Island>` renders its children. So the
+ * client's React tree is exactly the normal app.
+ *
+ * Under the BUILD extractor (which calls {@link __setSsrBuild}(true) before
+ * `renderToStaticMarkup`), each marker instead emits a unique PUA sentinel
+ * token marking an insertion point. The extractor strips the tokens, records
+ * their byte offsets, and emits the `.tmpl` + `.slots`. PUA codepoints
+ * (U+E000..) never occur in real HTML and React serialises them verbatim, so
+ * the tokens are collision-proof and strip to zero bytes.
+ *
+ * Because the static scaffold around every hole is React's OWN
+ * `renderToStaticMarkup` output, the browser's `hydrateRoot` sees byte-
+ * identical markup as long as the guest escapes hole values the same way React
+ * does (it does: see `server/runtime/ssr/escape.ts`).
+ */
+
+import { createElement, Fragment, type ReactNode } from 'react';
+
+/** Token framing codepoints (Unicode Private Use Area). */
+export const SENTINEL_START = String.fromCharCode(0xe000);
+export const SENTINEL_SEP = String.fromCharCode(0xe001);
+export const SENTINEL_END = String.fromCharCode(0xe002);
+
+/** Kind chars embedded in a sentinel token. Lowercase letters; `R`/`r` open and
+ * close a repeat region. */
+export const enum HoleKindChar {
+    Text = 't',
+    Raw = 'h',
+    Attr = 'a',
+    RepeatOpen = 'R',
+    RepeatClose = 'r',
+}
+
+let ssrBuild = false;
+
+/** Build-extractor switch. Flipped on around a `renderToStaticMarkup` pass so
+ * the markers emit sentinels; left `false` in the browser bundle so they are
+ * transparent. */
+export function __setSsrBuild(on: boolean): void {
+    ssrBuild = on;
+}
+
+/** `true` while the extractor is rendering (test/diagnostic use). */
+export function __isSsrBuild(): boolean {
+    return ssrBuild;
+}
+
+/** A self-closing insertion-point token, e.g. `␀t<id>␂`. */
+function token(kind: HoleKindChar, id: string): string {
+    return SENTINEL_START + kind + id + SENTINEL_END;
+}
+
+/** Wrap a string so a component always returns a `ReactElement` (a Fragment
+ * with one text child renders the string verbatim). */
+function textNode(s: string): ReactNode {
+    return createElement(Fragment, null, s);
+}
+
+export interface HoleProps {
+    /** Stable hole name; the extractor maps it to a numeric slot id. */
+    id: string;
+    children?: ReactNode;
+}
+
+/** A scalar text hole. Client: renders `children`. Build: a text insertion
+ * point the guest fills with the React-escaped value. */
+export function Hole(props: HoleProps): ReactNode {
+    if (ssrBuild) return textNode(token(HoleKindChar.Text, props.id));
+    return createElement(Fragment, null, props.children);
+}
+
+export interface RawHtmlProps {
+    id: string;
+    /** Raw HTML string. The author owns sanitisation (same as React
+     * `dangerouslySetInnerHTML`). */
+    html: string;
+    /** Wrapper element tag (raw HTML needs a host element to live in so server
+     * and client DOM match). Defaults to `div`. */
+    as?: keyof React.JSX.IntrinsicElements;
+}
+
+/** A raw-HTML block hole. Client: `<as dangerouslySetInnerHTML>`. Build:
+ * `<as>SENTINEL</as>` so the `.tmpl` carries the wrapper and the guest fills
+ * its inner HTML. */
+export function RawHtml(props: RawHtmlProps): ReactNode {
+    const tag = props.as ?? 'div';
+    if (ssrBuild) {
+        return createElement(tag, null, token(HoleKindChar.Raw, props.id));
+    }
+    return createElement(tag, { dangerouslySetInnerHTML: { __html: props.html } });
+}
+
+export interface RepeatProps<T> {
+    id: string;
+    /** The data rows. The build extractor requires a representative sample with
+     * at least one row to capture the row sub-template. */
+    each: readonly T[];
+    children: (item: T, index: number) => ReactNode;
+}
+
+/** A repeat region. Client: `each.map(children)`. Build: a region wrapping
+ * exactly ONE representative row (so the extractor captures the row sub-
+ * template + its nested holes); the host inserts the guest's pre-stamped,
+ * concatenated rows at the region offset. */
+export function Repeat<T>(props: RepeatProps<T>): ReactNode {
+    if (ssrBuild) {
+        const sample = props.each.length > 0 ? props.each[0] : undefined;
+        return createElement(
+            Fragment,
+            null,
+            token(HoleKindChar.RepeatOpen, props.id),
+            sample !== undefined ? props.children(sample, 0) : null,
+            token(HoleKindChar.RepeatClose, props.id),
+        );
+    }
+    return createElement(
+        Fragment,
+        null,
+        props.each.map((item, i) => props.children(item, i)),
+    );
+}
+
+export interface IslandProps {
+    children?: ReactNode;
+}
+
+/** 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). */
+export function Island(props: IslandProps): ReactNode {
+    if (ssrBuild) return null;
+    return createElement(Fragment, null, props.children);
+}