@microsoft/webui 0.0.18 → 0.0.20

package/README.md

@@ -15,14 +15,15 @@ The package automatically installs the correct platform-specific native binary f
 ## Quick start
 
 ```js
-import { build, render } from "@microsoft/webui";
+import { build, Protocol } from "@microsoft/webui";
 
 // Build templates into a protocol
 const result = build({ appDir: "./src" });
 
-// Render with state data
-const html = render(result.protocol, { name: "World", items: ["a", "b"] });
-console.log(html);
+// Decode and index once, then render repeatedly
+const protocol = new Protocol(result.protocol, { plugin: "webui" });
+const html = protocol.render({ name: "World", items: ["a", "b"] });
+console.log(html.toString("utf8"));
 ```
 
 ## API
@@ -58,32 +59,151 @@ usage with a literal fallback (e.g. `var(--brand, #000)`) is exempt. Missing
 required tokens fail the build with a structured `missing-theme-token` error.
 Misspelled literal-fallback tokens are returned as non-fatal warnings.
 
-### `render(protocol: Buffer, state: object | string): string`
+### Optional state projection
 
-Renders a compiled protocol with state data and returns the full HTML string.
+The build-only `@microsoft/webui/projection.js` subpath exposes the
+bundler-neutral projection compiler and the supported esbuild adapter. esbuild
+and TypeScript are optional peer dependencies, so applications that do not use
+projection do not install or load them:
+
+```bash
+npm install -D esbuild typescript
+```
 
 ```js
-const html = render(protocol, { title: "Hello", show: true });
+import * as esbuild from "esbuild";
+import { esbuildProjection } from "@microsoft/webui/projection.js";
+
+await esbuild.build({
+  entryPoints: ["src/index.ts"],
+  outdir: "dist",
+  bundle: true,
+  splitting: true,
+  format: "esm",
+  plugins: [esbuildProjection()],
+});
+
+const result = build({
+  appDir: "./src",
+  plugin: "webui",
+  projectionManifests: ["./dist/webui-projection.json"],
+});
 ```
 
-### `renderStream(protocol: Buffer, state: object | string, onChunk: (html: string) => void): void`
+esbuild runs once and emits both browser chunks and
+`webui-projection.json`; WebUI then embeds the exact initial/navigation
+surfaces into `protocol.bin`. The adapter uses esbuild's resolved graph and
+emitted output membership, so code splitting, dynamic imports, output hashes,
+and external bundles remain application-owned.
 
-Renders with streaming output - each HTML fragment is passed to the callback as it is produced.
+Other bundler adapters can use the exported `AdapterContext`,
+`compileProjection()`, and conformance fixtures without importing esbuild. The
+package currently ships and supports `esbuildProjection()` as its official
+adapter.
+
+With no manifest, WebUI performs no JavaScript analysis and preserves full
+state. Once any manifest is supplied, coverage is strict: every scripted
+component compiled into the protocol must have exactly one entry. Shared
+controls built as external bundles should emit their own manifest fragment,
+then all fragments should be passed through `projectionManifests`.
+
+Manifest keys are exact JavaScript `@observable` and `@attr` property names.
+During hydration, an existing SSR host attribute wins over projected `@attr`
+state. Runtime hosts never load TypeScript, esbuild, or the manifest.
+
+### `new Protocol(protocol: Buffer, options?: ProtocolOptions)`
+
+Decodes and indexes a compiled protocol once. Keep this object for the server
+lifetime and use it for all runtime operations.
 
 ```js
-renderStream(protocol, state, (chunk) => {
+const protocol = new Protocol(protocolBytes, { plugin: "webui" });
+```
+
+`Protocol` owns its decoded native state. The package does not keep a hidden
+`WeakMap`, copy the source `Buffer`, or expose render functions that accept
+protocol bytes on every request.
+
+### `protocol.render(state: object | string, options?: RenderOptions): Buffer`
+
+Renders state into a UTF-8 Node.js `Buffer`, the canonical buffered result for
+direct HTTP, file, or socket writes:
+
+```js
+response.end(protocol.render({ title: "Hello" }));
+```
+
+Call `.toString("utf8")` explicitly when JavaScript string operations are
+required.
+
+### `protocol.renderStream(state, onChunk, options?): void`
+
+Renders with streaming output. Internal handler writes are coalesced around a
+16 KiB target before the callback crosses into JavaScript. The callback runs
+synchronously and its return value is ignored. In particular,
+`response.write()` returning `false` does not pause native rendering, so this
+API does not provide transport backpressure. A thrown callback error aborts
+rendering immediately and is rethrown to the caller.
+
+```js
+protocol.renderStream(state, (chunk) => {
   response.write(chunk);
 });
 ```
 
-### `buildAndRender(options: BuildOptions, state: object | string): string`
+### `protocol.streamResponse(options?): StreamingSession`
 
-Convenience function that builds and renders in a single call.
+Opens a progressive streaming session for an entry that declares `<boundary>`
+directives. Unlike `renderStream`, the session **returns** each chunk, so your
+server keeps the socket, the write order, and the backpressure contract.
 
 ```js
-const html = buildAndRender({ appDir: "./src" }, { name: "WebUI" });
+import { once } from 'node:events';
+
+const session = protocol.streamResponse({ entry: 'index.html', requestPath: '/' });
+const status = session.boundary('job-status');   // resolve names once
+
+res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+await write(res, session.writeShell(baseState));
+await write(res, session.writeBoundary(status, statusState, 'updatable'));
+
+// Patches an already-hydrated island on this same response.
+await write(res, session.update(status, { jobState: 'succeeded' }));
+res.end(session.finish({}));
+
+async function write(res, chunk) {
+  if (res.write(chunk)) return;
+  // An aborted client never emits 'drain', and surfaces as 'close', not
+  // 'error' — so waiting on 'drain' alone would hang forever.
+  await new Promise((ok, fail) => {
+    const done = (error) => {
+      res.off('drain', onDrain);
+      res.off('close', onClose);
+      if (error) fail(error);
+      else ok();
+    };
+    const onDrain = () => done();
+    const onClose = () => done(new Error('client disconnected'));
+    res.once('drain', onDrain);
+    res.once('close', onClose);
+  });
+}
 ```
 
+| Member | Returns | Description |
+|--------|---------|-------------|
+| `boundary(name)` | `number` | Integer handle for an authored boundary name |
+| `boundaryCount` | `number` | Boundaries declared by the entry |
+| `finished` | `boolean` | Whether `finish()` has been called |
+| `writeShell(state)` | `Buffer` | Document prefix through the first semantic flush |
+| `writeBoundary(id, state, mode?)` | `Buffer` | One boundary's markup and checkpoint (`'final'` \| `'updatable'`) |
+| `update(id, state)` | `Buffer` | Projected state patch to an updatable boundary |
+| `finish(state)` | `Buffer` | Tail checkpoint, terminal record, and document suffix |
+
+Ordering is enforced. A rejected call throws and leaves the session usable, so
+invalid state does not cost you the response. Sessions are independent — hold
+one per in-flight request.
+
 ### `inspect(protocol: Buffer): string`
 
 Returns a JSON representation of the protocol for debugging.
@@ -93,16 +213,16 @@ const json = inspect(protocol);
 console.log(JSON.parse(json));
 ```
 
-### `renderPartial(protocol: Buffer, stateJson: string, entryId: string, requestPath: string, inventoryHex: string): string`
+### `protocol.renderPartial(state, entryId, requestPath, inventoryHex): string`
 
 Produces a JSON partial response for client-side navigation, including state, template metadata, condition closures, and route chain.
 
-### `renderComponentTemplates(protocol: Buffer, componentTags: string[], inventoryHex: string): string`
+### `protocol.renderComponentTemplates(componentTags, inventoryHex): string`
 
 Renders templates and styles for on-demand component loading (used by `Router.ensureLoaded()`). Returns a JSON string with `templateStyles`, `templates`, `templateFunctions`, and `inventory`. Uses the same inventory bitfield as partial navigation to avoid sending duplicates.
 
 ```js
-const json = renderComponentTemplates(protocol, ["settings-dialog"], inventoryHex);
+const json = protocol.renderComponentTemplates(["settings-dialog"], inventoryHex);
 const { templates, templateFunctions, templateStyles, inventory } = JSON.parse(json);
 ```
 

package/dist/index.d.ts

@@ -20,6 +20,13 @@ export interface BuildOptions {
     outDir?: string;
     /** Design token theme: a JSON file path or npm package name. */
     theme?: string;
+    /** Projection manifest file paths, merged in order. */
+    projectionManifests?: string[];
+    /** Inline manifests with logical paths anchoring root/stale validation. */
+    projectionManifestObjects?: Array<{
+        path: string;
+        manifest: unknown;
+    }>;
 }
 /** Build statistics. */
 export interface BuildStats {
@@ -55,9 +62,33 @@ export interface RenderOptions {
     entry?: string;
     /** URL path to match routes against (default: "/"). */
     requestPath?: string;
+}
+/** Options fixed for the lifetime of a loaded protocol. */
+export interface ProtocolOptions {
     /** Handler plugin name. */
     plugin?: string;
 }
+/**
+ * Whether a committed boundary may receive later state updates.
+ *
+ * `final` releases every boundary-local reference once the island hydrates.
+ * `updatable` retains the roots and projection so `update()` can patch them,
+ * so use it only for boundaries you actually intend to patch.
+ */
+export type BoundaryMode = "final" | "updatable";
+/** Per-response settings for a host-driven streaming session. */
+export interface StreamOptions {
+    /** Fragment ID to start rendering from (default: "index.html"). */
+    entry?: string;
+    /** URL path to match routes against (default: "/"). */
+    requestPath?: string;
+    /** CSP nonce applied to generated inline `<script>` tags. */
+    nonce?: string;
+    /** HTML injected at the structural `head_end` boundary. */
+    headInject?: string;
+    /** HTML injected at the structural `body_end` boundary. */
+    bodyInject?: string;
+}
 /** Response from `renderComponentTemplates()` for on-demand component loading. */
 export interface ComponentTemplatesResponse {
     /** Module CSS `<style>` strings for the requested components. */
@@ -89,45 +120,97 @@ export interface PartialResponse {
         exact?: boolean;
     }>;
 }
+interface NativeStreamingSession {
+    readonly boundaryCount: number;
+    readonly finished: boolean;
+    boundary(name: string): number;
+    writeShell(stateJson: string): Buffer;
+    writeBoundary(boundary: number, stateJson: string, mode?: BoundaryMode): Buffer;
+    update(boundary: number, stateJson: string): Buffer;
+    finish(stateJson: string): Buffer;
+}
 /** Build a WebUI application from an app directory. */
 export declare function build(options: BuildOptions): BuildResult;
 /**
- * Render a pre-compiled protocol with state data.
- * Uses native addon when available, WASM fallback otherwise.
- */
-export declare function render(protocol: Buffer, state: object | string, options?: RenderOptions): string;
-/**
- * Render a protocol with streaming output.
- * Each HTML fragment is passed to the onChunk callback as it is produced.
+ * A decoded protocol with reusable indices for all runtime operations.
+ *
+ * Create one instance when the server loads `protocol.bin` and share it
+ * across requests. Construction decodes and indexes the protocol once.
  */
-export declare function renderStream(protocol: Buffer, state: object | string, onChunk: (html: string) => void, options?: RenderOptions): void;
-/** Build and render in a single call. */
-export declare function buildAndRender(options: BuildOptions, state: object | string, renderOpts?: RenderOptions): string;
-/** Inspect protocol bytes and return JSON representation. */
-export declare function inspect(protocolData: Buffer): string;
+export declare class Protocol {
+    #private;
+    constructor(protocolData: Buffer, options?: ProtocolOptions);
+    /** Render a complete HTML response as a UTF-8 Node.js buffer. */
+    render(state: object | string, options?: RenderOptions): Buffer;
+    /** Stream a complete HTML response in chunks around 16 KiB. */
+    renderStream(state: object | string, onChunk: (html: string) => void, options?: RenderOptions): void;
+    /** Produce a complete JSON partial-navigation response. */
+    renderPartial(state: object | string, entryId: string, requestPath: string, inventoryHex: string): string;
+    /** Render component templates and styles for on-demand loading. */
+    renderComponentTemplates(componentTags: string[], inventoryHex: string): string;
+    /** Return CSS token names in build order. */
+    tokens(): string[];
+    /**
+     * Open a host-driven progressive response.
+     *
+     * Unlike {@link renderStream}, which pushes every chunk during one
+     * synchronous call, the returned session hands each chunk back so this
+     * server owns the socket, the write order, and backpressure.
+     */
+    streamResponse(options?: StreamOptions): StreamingSession;
+}
 /**
- * Produce a complete JSON partial response for client-side navigation.
+ * A progressive HTML response written one chunk at a time.
  *
- * Returns a JSON string with `state`, `templates`, `inventory`, `path`, and `chain`.
- * Pipe directly to the HTTP response — no post-processing needed.
+ * Every method returns the bytes it produced instead of writing them, so the
+ * caller decides when they reach the socket and can await `drain` between
+ * chunks. The session holds no transport and never blocks on one.
  *
- * If you need to inspect the response, parse it with the exported `PartialResponse` type:
- * ```ts
- * const partial: PartialResponse = JSON.parse(renderPartial(...));
- * ```
- */
-export declare function renderPartial(protocolData: Buffer, stateJson: string, entryId: string, requestPath: string, inventoryHex: string): string;
-/**
- * Render component templates and styles for on-demand loading.
+ * Ordering is enforced: the shell first, then each boundary exactly once in
+ * declaration order, `update()` only after its boundary commits as
+ * `updatable`, and `finish()` last. A violation throws before any byte is
+ * produced.
+ *
+ * ```js
+ * const session = protocol.streamResponse({ requestPath: req.url });
+ * const weather = session.boundary("weather-shell");
+ *
+ * res.write(session.writeShell(shellState));
+ * res.write(session.writeBoundary(weather, weatherShell, "updatable"));
  *
- * Used by `Router.ensureLoaded()` to fetch templates for components that
- * are not part of the route tree (e.g., dialogs, popovers). Uses the same
- * inventory bitfield as partial navigation to avoid sending duplicates.
+ * const forecast = await forecastReady;
+ * if (!res.write(session.update(weather, forecast))) {
+ *   await once(res, "drain");
+ * }
  *
- * Returns a JSON string. Parse with the exported `ComponentTemplatesResponse` type:
- * ```ts
- * const resp: ComponentTemplatesResponse = JSON.parse(renderComponentTemplates(...));
+ * res.end(session.finish({}));
  * ```
  */
-export declare function renderComponentTemplates(protocolData: Buffer, componentTags: string[], inventoryHex: string): string;
+export declare class StreamingSession {
+    #private;
+    /** @internal Created by {@link Protocol.streamResponse}. */
+    constructor(native: NativeStreamingSession);
+    /** Number of compile-time boundaries declared by this entry. */
+    get boundaryCount(): number;
+    /** Whether the terminal record has been written. */
+    get finished(): boolean;
+    /**
+     * Resolve an authored boundary name to a stable integer handle.
+     *
+     * Resolve once outside the write loop; reusing the handle costs nothing.
+     * An unknown name throws with the valid names and a suggestion.
+     */
+    boundary(name: string): number;
+    /** Render everything before the first boundary. */
+    writeShell(state: object | string): Buffer;
+    /** Render and commit the next boundary in declaration order. */
+    writeBoundary(boundary: number, state: object | string, mode?: BoundaryMode): Buffer;
+    /** Push a projected state patch to a committed `updatable` boundary. */
+    update(boundary: number, state: object | string): Buffer;
+    /** Render the document tail and emit the terminal record. */
+    finish(state?: object | string): Buffer;
+}
+/** Inspect protocol bytes and return JSON representation. */
+export declare function inspect(protocolData: Buffer): string;
+export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAaA,gDAAgD;AAChD,MAAM,WAAW,YAAY;IAC3B,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;IAClC,0BAA0B;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,oEAAoE;IACpE,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,6GAA6G;IAC7G,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,6DAA6D;IAC7D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,2EAA2E;IAC3E,yBAAyB,CAAC,EAAE,KAAK,CAAC;QAChC,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,OAAO,CAAC;KACnB,CAAC,CAAC;CACJ;AAED,wBAAwB;AACxB,MAAM,WAAW,UAAU;IACzB,sCAAsC;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,aAAa,EAAE,MAAM,CAAC;IACtB,uCAAuC;IACvC,cAAc,EAAE,MAAM,CAAC;IACvB,oCAAoC;IACpC,YAAY,EAAE,MAAM,CAAC;IACrB,gDAAgD;IAChD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,8CAA8C;AAC9C,MAAM,WAAW,WAAW;IAC1B,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,4EAA4E;IAC5E,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,wBAAwB;IACxB,KAAK,EAAE,UAAU,CAAC;CACnB;AAED,wCAAwC;AACxC,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,2DAA2D;AAC3D,MAAM,WAAW,eAAe;IAC9B,2BAA2B;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,WAAW,CAAC;AAEjD,iEAAiE;AACjE,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6DAA6D;IAC7D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,kFAAkF;AAClF,MAAM,WAAW,0BAA0B;IACzC,iEAAiE;IACjE,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,+DAA+D;IAC/D,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,6DAA6D;IAC7D,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,iFAAiF;AACjF,MAAM,WAAW,eAAe;IAC9B,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,+DAA+D;IAC/D,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,6DAA6D;IAC7D,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3C,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,KAAK,EAAE,KAAK,CAAC;QACX,SAAS,EAAE,MAAM,CAAC;QAClB,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAChC,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB,CAAC,CAAC;CACJ;AA8CD,UAAU,sBAAsB;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IACtC,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,MAAM,CAAC;IAChF,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IACpD,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;CACnC;AAuCD,uDAAuD;AACvD,wBAAgB,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,WAAW,CA8ExD;AAmBD;;;;;GAKG;AACH,qBAAa,QAAQ;;gBAGP,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe;IAY3D,iEAAiE;IACjE,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,MAAM;IAS/D,+DAA+D;IAC/D,YAAY,CACV,KAAK,EAAE,MAAM,GAAG,MAAM,EACtB,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,EAC/B,OAAO,CAAC,EAAE,aAAa,GACtB,IAAI;IAUP,2DAA2D;IAC3D,aAAa,CACX,KAAK,EAAE,MAAM,GAAG,MAAM,EACtB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,GACnB,MAAM;IAKT,mEAAmE;IACnE,wBAAwB,CACtB,aAAa,EAAE,MAAM,EAAE,EACvB,YAAY,EAAE,MAAM,GACnB,MAAM;IAIT,6CAA6C;IAC7C,MAAM,IAAI,MAAM,EAAE;IAIlB;;;;;;OAMG;IACH,cAAc,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,gBAAgB;CAa1D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,gBAAgB;;IAG3B,4DAA4D;gBAChD,MAAM,EAAE,sBAAsB;IAI1C,gEAAgE;IAChE,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED,oDAAoD;IACpD,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAI9B,mDAAmD;IACnD,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM;IAI1C,gEAAgE;IAChE,aAAa,CACX,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GAAG,MAAM,EACtB,IAAI,GAAE,YAAsB,GAC3B,MAAM;IAIT,wEAAwE;IACxE,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM;IAIxD,6DAA6D;IAC7D,MAAM,CAAC,KAAK,GAAE,MAAM,GAAG,MAAW,GAAG,MAAM;CAG5C;AAMD,6DAA6D;AAC7D,wBAAgB,OAAO,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAMpD"}

package/dist/index.js

@@ -44,7 +44,14 @@ function warnFallback() {
 export function build(options) {
     const native = loadAddon();
     if (native?.build) {
-        return native.build(options);
+        const { projectionManifestObjects, ...nativeOptions } = options;
+        return native.build({
+            ...nativeOptions,
+            projectionManifestObjects: projectionManifestObjects?.map(({ path, manifest }) => ({
+                path,
+                json: JSON.stringify(manifest),
+            })),
+        });
     }
     // Fallback: shell out to CLI binary.
     const binPath = resolve("bin");
@@ -63,6 +70,15 @@ export function build(options) {
             args.push("--components", c);
         }
     }
+    if (options.projectionManifests) {
+        for (const manifest of options.projectionManifests) {
+            args.push("--projection-manifest", manifest);
+        }
+    }
+    if (options.projectionManifestObjects &&
+        options.projectionManifestObjects.length > 0) {
+        throw new Error("[webui] Inline projection manifest objects require the native addon; write the manifest and pass projectionManifests when using the CLI fallback.");
+    }
     if (options.componentAssetRoots && options.componentAssetRoots.length > 0) {
         args.push("--emit-component-assets", options.componentAssetRoots.join(","));
     }
@@ -112,50 +128,131 @@ function readComponentAssetFiles(outDir) {
     }
     return files;
 }
-// ── Render API ───────────────────────────────────────────────────────
+// ── Runtime protocol API ─────────────────────────────────────────────
 /**
- * Render a pre-compiled protocol with state data.
- * Uses native addon when available, WASM fallback otherwise.
+ * A decoded protocol with reusable indices for all runtime operations.
+ *
+ * Create one instance when the server loads `protocol.bin` and share it
+ * across requests. Construction decodes and indexes the protocol once.
  */
-export function render(protocol, state, options) {
-    const native = loadAddon();
-    if (native) {
-        let result = "";
-        const stateStr = typeof state === "string" ? state : JSON.stringify(state);
-        const entry = options?.entry ?? "index.html";
-        const requestPath = options?.requestPath ?? "/";
-        native.render(protocol, stateStr, entry, requestPath, (chunk) => {
-            result += chunk;
-        }, options?.plugin);
-        return result;
-    }
-    warnFallback();
-    throw new Error("[webui] render() requires the native addon. WASM render fallback not yet wired.");
+export class Protocol {
+    #native;
+    constructor(protocolData, options) {
+        const native = loadAddon();
+        const NativeProtocol = native?.Protocol;
+        if (!NativeProtocol) {
+            warnFallback();
+            throw new Error("[webui] Native addon is incompatible: Protocol is required.");
+        }
+        this.#native = new NativeProtocol(protocolData, options?.plugin);
+    }
+    /** Render a complete HTML response as a UTF-8 Node.js buffer. */
+    render(state, options) {
+        const stateJson = typeof state === "string" ? state : JSON.stringify(state);
+        return this.#native.render(stateJson, options?.entry ?? "index.html", options?.requestPath ?? "/");
+    }
+    /** Stream a complete HTML response in chunks around 16 KiB. */
+    renderStream(state, onChunk, options) {
+        const stateJson = typeof state === "string" ? state : JSON.stringify(state);
+        this.#native.renderStream(stateJson, options?.entry ?? "index.html", options?.requestPath ?? "/", onChunk);
+    }
+    /** Produce a complete JSON partial-navigation response. */
+    renderPartial(state, entryId, requestPath, inventoryHex) {
+        const stateJson = typeof state === "string" ? state : JSON.stringify(state);
+        return this.#native.renderPartial(stateJson, entryId, requestPath, inventoryHex);
+    }
+    /** Render component templates and styles for on-demand loading. */
+    renderComponentTemplates(componentTags, inventoryHex) {
+        return this.#native.renderComponentTemplates(componentTags, inventoryHex);
+    }
+    /** Return CSS token names in build order. */
+    tokens() {
+        return this.#native.tokens();
+    }
+    /**
+     * Open a host-driven progressive response.
+     *
+     * Unlike {@link renderStream}, which pushes every chunk during one
+     * synchronous call, the returned session hands each chunk back so this
+     * server owns the socket, the write order, and backpressure.
+     */
+    streamResponse(options) {
+        return new StreamingSession(this.#native.streamResponse(options?.entry ?? "index.html", options?.requestPath ?? "/", {
+            nonce: options?.nonce,
+            headInject: options?.headInject,
+            bodyInject: options?.bodyInject,
+        }));
+    }
 }
 /**
- * Render a protocol with streaming output.
- * Each HTML fragment is passed to the onChunk callback as it is produced.
+ * A progressive HTML response written one chunk at a time.
+ *
+ * Every method returns the bytes it produced instead of writing them, so the
+ * caller decides when they reach the socket and can await `drain` between
+ * chunks. The session holds no transport and never blocks on one.
+ *
+ * Ordering is enforced: the shell first, then each boundary exactly once in
+ * declaration order, `update()` only after its boundary commits as
+ * `updatable`, and `finish()` last. A violation throws before any byte is
+ * produced.
+ *
+ * ```js
+ * const session = protocol.streamResponse({ requestPath: req.url });
+ * const weather = session.boundary("weather-shell");
+ *
+ * res.write(session.writeShell(shellState));
+ * res.write(session.writeBoundary(weather, weatherShell, "updatable"));
+ *
+ * const forecast = await forecastReady;
+ * if (!res.write(session.update(weather, forecast))) {
+ *   await once(res, "drain");
+ * }
+ *
+ * res.end(session.finish({}));
+ * ```
  */
-export function renderStream(protocol, state, onChunk, options) {
-    const native = loadAddon();
-    if (native) {
-        const stateStr = typeof state === "string" ? state : JSON.stringify(state);
-        const entry = options?.entry ?? "index.html";
-        const requestPath = options?.requestPath ?? "/";
-        native.render(protocol, stateStr, entry, requestPath, onChunk, options?.plugin);
-        return;
+export class StreamingSession {
+    #native;
+    /** @internal Created by {@link Protocol.streamResponse}. */
+    constructor(native) {
+        this.#native = native;
+    }
+    /** Number of compile-time boundaries declared by this entry. */
+    get boundaryCount() {
+        return this.#native.boundaryCount;
+    }
+    /** Whether the terminal record has been written. */
+    get finished() {
+        return this.#native.finished;
+    }
+    /**
+     * Resolve an authored boundary name to a stable integer handle.
+     *
+     * Resolve once outside the write loop; reusing the handle costs nothing.
+     * An unknown name throws with the valid names and a suggestion.
+     */
+    boundary(name) {
+        return this.#native.boundary(name);
+    }
+    /** Render everything before the first boundary. */
+    writeShell(state) {
+        return this.#native.writeShell(toStateJson(state));
+    }
+    /** Render and commit the next boundary in declaration order. */
+    writeBoundary(boundary, state, mode = "final") {
+        return this.#native.writeBoundary(boundary, toStateJson(state), mode);
+    }
+    /** Push a projected state patch to a committed `updatable` boundary. */
+    update(boundary, state) {
+        return this.#native.update(boundary, toStateJson(state));
+    }
+    /** Render the document tail and emit the terminal record. */
+    finish(state = {}) {
+        return this.#native.finish(toStateJson(state));
     }
-    warnFallback();
-    throw new Error("[webui] renderStream() requires the native addon. WASM render fallback not yet wired.");
 }
-// ── Convenience ──────────────────────────────────────────────────────
-/** Build and render in a single call. */
-export function buildAndRender(options, state, renderOpts) {
-    const result = build(options);
-    if (!result.protocol || result.protocol.length === 0) {
-        throw new Error("[webui] Build did not return protocol data.");
-    }
-    return render(result.protocol, state, renderOpts);
+function toStateJson(state) {
+    return typeof state === "string" ? state : JSON.stringify(state);
 }
 /** Inspect protocol bytes and return JSON representation. */
 export function inspect(protocolData) {
@@ -165,43 +262,6 @@ export function inspect(protocolData) {
     }
     throw new Error("[webui] inspect() requires the native addon.");
 }
-/**
- * Produce a complete JSON partial response for client-side navigation.
- *
- * Returns a JSON string with `state`, `templates`, `inventory`, `path`, and `chain`.
- * Pipe directly to the HTTP response — no post-processing needed.
- *
- * If you need to inspect the response, parse it with the exported `PartialResponse` type:
- * ```ts
- * const partial: PartialResponse = JSON.parse(renderPartial(...));
- * ```
- */
-export function renderPartial(protocolData, stateJson, entryId, requestPath, inventoryHex) {
-    const native = loadAddon();
-    if (native?.renderPartial) {
-        return native.renderPartial(protocolData, stateJson, entryId, requestPath, inventoryHex);
-    }
-    throw new Error("[webui] renderPartial() requires the native addon.");
-}
-/**
- * Render component templates and styles for on-demand loading.
- *
- * Used by `Router.ensureLoaded()` to fetch templates for components that
- * are not part of the route tree (e.g., dialogs, popovers). Uses the same
- * inventory bitfield as partial navigation to avoid sending duplicates.
- *
- * Returns a JSON string. Parse with the exported `ComponentTemplatesResponse` type:
- * ```ts
- * const resp: ComponentTemplatesResponse = JSON.parse(renderComponentTemplates(...));
- * ```
- */
-export function renderComponentTemplates(protocolData, componentTags, inventoryHex) {
-    const native = loadAddon();
-    if (native?.renderComponentTemplates) {
-        return native.renderComponentTemplates(protocolData, JSON.stringify(componentTags), inventoryHex);
-    }
-    throw new Error("[webui] renderComponentTemplates() requires the native addon.");
-}
 // ── Helpers ──────────────────────────────────────────────────────────
 function emptyStats() {
     return {