ngx-json-render 0.2.0 → 0.2.1

package/fesm2022/ngx-json-render.mjs

@@ -1,6 +1,6 @@
 import * as i0 from '@angular/core';
 import { signal, Injectable, inject, computed, untracked, effect, isDevMode, input, output, ChangeDetectionStrategy, Component, DestroyRef, InjectionToken, Injector, forwardRef } from '@angular/core';
-import { createStateStore, getByPath, runValidation, resolveAction, nextActionDispatchId, notifyActionDispatch, notifyActionSettle, executeAction, isDevtoolsActive, subscribeDevtoolsActive, evaluateVisibility, resolveElementProps, resolveBindings, resolveActionParam, createDirectiveRegistry, resolveRepeatStatePath, resolveRepeatItemStatePath, setByPath, removeByPath, SPEC_DATA_PART_TYPE, applySpecPatch, nestedToFlat, createMixedStreamParser, defineSchema } from '@json-render/core';
+import { createStateStore, getByPath, runValidation, resolveAction, nextActionDispatchId, notifyActionDispatch, notifyActionSettle, executeAction, isDevtoolsActive, subscribeDevtoolsActive, evaluateVisibility, resolveElementProps, resolveBindings, resolveActionParam, createDirectiveRegistry, resolveRepeatStatePath, resolveRepeatItemStatePath, removeByPath, addByPath, setByPath, SPEC_DATA_PART_TYPE, nestedToFlat, createMixedStreamParser, defineSchema } from '@json-render/core';
 export { createStateStore, nestedToFlat } from '@json-render/core';
 import { flattenToPointers } from '@json-render/core/store-utils';
 import { NgComponentOutlet } from '@angular/common';
@@ -1409,33 +1409,6 @@ function createStoreSetState(store) {
     };
 }
 
-/**
- * Parse a single JSON line (patch or metadata).
- */
-function parseLine(line) {
-    try {
-        const trimmed = line.trim();
-        if (!trimmed || trimmed.startsWith('//')) {
-            return null;
-        }
-        const parsed = JSON.parse(trimmed);
-        // Check for usage metadata
-        if (parsed.__meta === 'usage') {
-            return {
-                type: 'usage',
-                usage: {
-                    promptTokens: parsed.promptTokens ?? 0,
-                    completionTokens: parsed.completionTokens ?? 0,
-                    totalTokens: parsed.totalTokens ?? 0,
-                },
-            };
-        }
-        return { type: 'patch', patch: parsed };
-    }
-    catch {
-        return null;
-    }
-}
 /**
  * Split a JSON Pointer into its segments, undoing RFC 6901's escapes.
  *
@@ -1452,14 +1425,15 @@ function parseJsonPointer(path) {
  * Replace every node `path` descends through with a shallow copy of itself.
  *
  * `root` must already be private to the caller. Afterwards a mutating write
- * along that same path — `setByPath`, `removeByPath` — only ever touches
- * nodes nobody else is holding, while everything off the path stays shared.
- * That keeps a patch proportional to the depth of its path rather than to the
- * size of the spec, which matters when a stream applies hundreds of them.
+ * along that same path — `setByPath`, `addByPath`, `removeByPath` — only ever
+ * touches nodes nobody else is holding, while everything off the path stays
+ * shared. That keeps a patch proportional to the depth of its path rather than
+ * to the size of the spec, which matters when a stream applies hundreds of
+ * them.
  *
- * Descent stops at anything that is not an object: `setByPath` overwrites
- * such a node outright, and one that does not exist yet is created fresh, so
- * in neither case is there anything of the caller's left to protect.
+ * Descent stops at anything that is not an object: the writers overwrite such
+ * a node outright, and one that does not exist yet is created fresh, so in
+ * neither case is there anything of the caller's left to protect.
  */
 function copyAlongPath(root, path) {
     const segments = parseJsonPointer(path);
@@ -1478,9 +1452,10 @@ function copyAlongPath(root, path) {
     }
 }
 /**
- * Set a value at a spec path (for add/replace operations).
+ * Write a value at a spec path, copying every node on the way so the caller's
+ * previous spec keeps its own contents.
  */
-function setSpecValue(newSpec, path, value) {
+function writeSpecValue(newSpec, path, value, write) {
     if (path === '/root') {
         newSpec.root = value;
         return;
@@ -1495,7 +1470,7 @@ function setSpecValue(newSpec, path, value) {
         const statePath = path.slice('/state'.length); // e.g. "/posts"
         const state = newSpec.state;
         copyAlongPath(state, statePath);
-        setByPath(state, statePath, value);
+        write(state, statePath, value);
         return;
     }
     if (path.startsWith('/elements/')) {
@@ -1505,22 +1480,32 @@ function setSpecValue(newSpec, path, value) {
             return;
         if (pathParts.length === 1) {
             newSpec.elements[elementKey] = value;
+            return;
         }
-        else {
-            const element = newSpec.elements[elementKey];
-            if (element) {
-                const propPath = '/' + pathParts.slice(1).join('/');
-                const newElement = { ...element };
-                copyAlongPath(newElement, propPath);
-                setByPath(newElement, propPath, value);
-                newSpec.elements[elementKey] = newElement;
-            }
-        }
+        // A prop path whose element is not there is dropped rather than
+        // auto-created: the generic writers would happily conjure an element with
+        // props and no `type`, which renders as nothing and warns about an unknown
+        // component. A malformed patch should lose its own write, not add a broken
+        // element to the tree.
+        const element = newSpec.elements[elementKey];
+        if (!element)
+            return;
+        const propPath = '/' + pathParts.slice(1).join('/');
+        const newElement = { ...element };
+        copyAlongPath(newElement, propPath);
+        write(newElement, propPath, value);
+        newSpec.elements[elementKey] = newElement;
+        return;
     }
+    // Any other top-level path is applied verbatim. The spec grammar is
+    // upstream's and grows without this renderer: dropping what we do not
+    // recognise would silently discard a field a newer `@json-render/core`
+    // understands.
+    const root = newSpec;
+    copyAlongPath(root, path);
+    write(root, path, value);
 }
-/**
- * Remove a value at a spec path.
- */
+/** Remove the value at a spec path, with the same copy-on-write discipline. */
 function removeSpecValue(newSpec, path) {
     if (path === '/state') {
         delete newSpec.state;
@@ -1539,39 +1524,38 @@ function removeSpecValue(newSpec, path) {
         if (!elementKey)
             return;
         if (pathParts.length === 1) {
-            const { [elementKey]: _, ...rest } = newSpec.elements;
+            const { [elementKey]: _removed, ...rest } = newSpec.elements;
             newSpec.elements = rest;
+            return;
         }
-        else {
-            const element = newSpec.elements[elementKey];
-            if (element) {
-                const propPath = '/' + pathParts.slice(1).join('/');
-                const newElement = { ...element };
-                copyAlongPath(newElement, propPath);
-                removeByPath(newElement, propPath);
-                newSpec.elements[elementKey] = newElement;
-            }
-        }
-    }
-}
-/**
- * Get a value at a spec path.
- */
-function getSpecValue(spec, path) {
-    if (path === '/root')
-        return spec.root;
-    if (path === '/state')
-        return spec.state;
-    if (path.startsWith('/state/') && spec.state) {
-        const statePath = path.slice('/state'.length);
-        return getByPath(spec.state, statePath);
+        const element = newSpec.elements[elementKey];
+        if (!element)
+            return;
+        const propPath = '/' + pathParts.slice(1).join('/');
+        const newElement = { ...element };
+        copyAlongPath(newElement, propPath);
+        removeByPath(newElement, propPath);
+        newSpec.elements[elementKey] = newElement;
+        return;
     }
-    return getByPath(spec, path);
+    const root = newSpec;
+    copyAlongPath(root, path);
+    removeByPath(root, path);
 }
 /**
- * Apply an RFC 6902 JSON patch to the current spec, returning a new spec
- * object (structural sharing for untouched elements).
- * Supports add, remove, replace, move, copy, and test operations.
+ * Apply an RFC 6902 JSON patch to a spec, returning a new spec object and
+ * sharing every subtree the patch did not touch.
+ *
+ * This is the only patch engine in the package: `injectUIStream`,
+ * `injectChatUI` and `buildSpecFromParts` all route through it, so the same
+ * stream produces the same spec whichever one an app reached for. The write
+ * primitives come from `@json-render/core`, so `add` splices into an array
+ * where `replace` overwrites, exactly as the other renderers do.
+ *
+ * One deliberate deviation from RFC 6902: a failing `test` op is a no-op
+ * rather than an abort. These patches come off a model's output, where the
+ * established behaviour — see the line parser — is to drop what does not make
+ * sense and keep rendering rather than kill a generation mid-flight.
  */
 function applyPatch(spec, patch) {
     const newSpec = {
@@ -1580,9 +1564,12 @@ function applyPatch(spec, patch) {
         ...(spec.state ? { state: { ...spec.state } } : {}),
     };
     switch (patch.op) {
-        case 'add':
+        case 'add': {
+            writeSpecValue(newSpec, patch.path, patch.value, addByPath);
+            break;
+        }
         case 'replace': {
-            setSpecValue(newSpec, patch.path, patch.value);
+            writeSpecValue(newSpec, patch.path, patch.value, setByPath);
             break;
         }
         case 'remove': {
@@ -1592,170 +1579,29 @@ function applyPatch(spec, patch) {
         case 'move': {
             if (!patch.from)
                 break;
-            const moveValue = getSpecValue(newSpec, patch.from);
+            const moveValue = getByPath(newSpec, patch.from);
             removeSpecValue(newSpec, patch.from);
-            setSpecValue(newSpec, patch.path, moveValue);
+            writeSpecValue(newSpec, patch.path, moveValue, addByPath);
             break;
         }
         case 'copy': {
             if (!patch.from)
                 break;
-            const copyValue = getSpecValue(newSpec, patch.from);
-            setSpecValue(newSpec, patch.path, copyValue);
+            // RFC 6902 copies the *value*. Handing over the live reference instead
+            // aliases source and target, and a `path` that descends into its own
+            // `from` then makes the spec self-referential — which the next request
+            // discovers when it tries to serialise it into the body.
+            const copyValue = structuredClone(getByPath(newSpec, patch.from));
+            writeSpecValue(newSpec, patch.path, copyValue, addByPath);
             break;
         }
         case 'test': {
-            // test is a no-op for rendering purposes (validation only)
             break;
         }
     }
     return newSpec;
 }
-/**
- * Streaming UI generation. POSTs `{ prompt, context, currentSpec }` to the
- * endpoint and progressively applies the returned JSONL patch stream to the
- * `spec` signal, so partial UIs render as they arrive.
- *
- * Must be called in an injection context (aborts in-flight requests on
- * destroy).
- *
- * @example
- * ```ts
- * export class GeneratePage {
- *   readonly ui = injectUIStream({ api: '/api/generate' });
- * }
- * // template:
- * // <json-render [spec]="ui.spec()" [registry]="registry" [loading]="ui.isStreaming()" />
- * ```
- */
-function injectUIStream(options) {
-    const spec = signal(null, ...(ngDevMode ? [{ debugName: "spec" }] : /* istanbul ignore next */ []));
-    const isStreaming = signal(false, ...(ngDevMode ? [{ debugName: "isStreaming" }] : /* istanbul ignore next */ []));
-    const error = signal(null, ...(ngDevMode ? [{ debugName: "error" }] : /* istanbul ignore next */ []));
-    const usage = signal(null, ...(ngDevMode ? [{ debugName: "usage" }] : /* istanbul ignore next */ []));
-    const rawLines = signal([], ...(ngDevMode ? [{ debugName: "rawLines" }] : /* istanbul ignore next */ []));
-    let abortController = null;
-    inject(DestroyRef).onDestroy(() => {
-        abortController?.abort();
-    });
-    const clear = () => {
-        spec.set(null);
-        error.set(null);
-    };
-    const send = async (prompt, context) => {
-        // Abort any existing request
-        abortController?.abort();
-        const controller = new AbortController();
-        abortController = controller;
-        // A superseded request must not write to the shared signals on its way
-        // out: its `finally` would otherwise clear `isStreaming` while the request
-        // that replaced it is still streaming.
-        const isCurrent = () => abortController === controller;
-        isStreaming.set(true);
-        error.set(null);
-        usage.set(null);
-        rawLines.set([]);
-        // Start with previous spec if provided, otherwise empty spec
-        const previousSpec = context?.['previousSpec'];
-        let currentSpec = previousSpec && previousSpec.root
-            ? { ...previousSpec, elements: { ...previousSpec.elements } }
-            : { root: '', elements: {} };
-        spec.set(currentSpec);
-        const handleLine = (trimmed) => {
-            const result = parseLine(trimmed);
-            if (!result)
-                return;
-            if (result.type === 'usage') {
-                usage.set(result.usage);
-            }
-            else {
-                rawLines.update((prev) => [...prev, trimmed]);
-                currentSpec = applyPatch(currentSpec, result.patch);
-                spec.set(currentSpec);
-            }
-        };
-        // Bound, because a bare `globalThis.fetch` called as a plain function is
-        // an illegal invocation in the browser.
-        const doFetch = options.fetch ?? globalThis.fetch.bind(globalThis);
-        try {
-            const response = await doFetch(options.api, {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json' },
-                body: JSON.stringify({
-                    prompt,
-                    context,
-                    currentSpec,
-                }),
-                signal: controller.signal,
-            });
-            if (!response.ok) {
-                // Try to parse JSON error response for better error messages
-                let errorMessage = `HTTP error: ${response.status}`;
-                try {
-                    const errorData = await response.json();
-                    if (errorData.message) {
-                        errorMessage = errorData.message;
-                    }
-                    else if (errorData.error) {
-                        errorMessage = errorData.error;
-                    }
-                }
-                catch {
-                    // Ignore JSON parsing errors, use default message
-                }
-                throw new Error(errorMessage);
-            }
-            const reader = response.body?.getReader();
-            if (!reader) {
-                throw new Error('No response body');
-            }
-            const decoder = new TextDecoder();
-            let buffer = '';
-            while (true) {
-                const { done, value } = await reader.read();
-                if (done)
-                    break;
-                buffer += decoder.decode(value, { stream: true });
-                // Process complete lines
-                const lines = buffer.split('\n');
-                buffer = lines.pop() ?? '';
-                for (const line of lines) {
-                    const trimmed = line.trim();
-                    if (!trimmed)
-                        continue;
-                    handleLine(trimmed);
-                }
-            }
-            // Process any remaining buffer
-            if (buffer.trim()) {
-                handleLine(buffer.trim());
-            }
-            options.onComplete?.(currentSpec);
-        }
-        catch (err) {
-            if (err.name === 'AbortError' || !isCurrent()) {
-                return;
-            }
-            const resolvedError = err instanceof Error ? err : new Error(String(err));
-            error.set(resolvedError);
-            options.onError?.(resolvedError);
-        }
-        finally {
-            if (isCurrent()) {
-                isStreaming.set(false);
-            }
-        }
-    };
-    return {
-        spec: spec.asReadonly(),
-        isStreaming: isStreaming.asReadonly(),
-        error: error.asReadonly(),
-        usage: usage.asReadonly(),
-        rawLines: rawLines.asReadonly(),
-        send,
-        clear,
-    };
-}
+
 /**
  * Convert a flat element list to a Spec.
  * Input elements use key/parentKey to establish identity and relationships.
@@ -1814,7 +1660,7 @@ function isSpecDataPart(data) {
  * parts are present.
  */
 function buildSpecFromParts(parts) {
-    const spec = { root: '', elements: {} };
+    let spec = { root: '', elements: {} };
     let hasSpec = false;
     for (const part of parts) {
         if (part.type === SPEC_DATA_PART_TYPE) {
@@ -1823,16 +1669,15 @@ function buildSpecFromParts(parts) {
             const payload = part.data;
             if (payload.type === 'patch') {
                 hasSpec = true;
-                applySpecPatch(spec, payload.patch);
+                spec = applyPatch(spec, payload.patch);
             }
             else if (payload.type === 'flat') {
                 hasSpec = true;
-                Object.assign(spec, payload.spec);
+                spec = { ...spec, ...payload.spec };
             }
             else if (payload.type === 'nested') {
                 hasSpec = true;
-                const flat = nestedToFlat(payload.spec);
-                Object.assign(spec, flat);
+                spec = { ...spec, ...nestedToFlat(payload.spec) };
             }
         }
     }
@@ -1876,6 +1721,254 @@ function jsonRenderMessage(parts) {
         }),
     };
 }
+
+function createStreamSession() {
+    let current = null;
+    return {
+        begin() {
+            current?.abort();
+            const controller = new AbortController();
+            current = controller;
+            const isCurrent = () => current === controller;
+            return {
+                signal: controller.signal,
+                isCurrent,
+                commit(write) {
+                    if (isCurrent())
+                        write();
+                },
+            };
+        },
+        cancel() {
+            current?.abort();
+            // Cleared, not just aborted: with no current controller the in-flight
+            // request's gate closes too, so a stop() cannot be undone a moment later
+            // by the request it just cancelled.
+            current = null;
+        },
+    };
+}
+/** True for the rejection `fetch` and a stream reader raise on abort. */
+function isAbortError(error) {
+    return error?.name === 'AbortError';
+}
+/**
+ * Buffer decoded text and hand back whole lines, dropping blank ones. What is
+ * left when the stream ends is flushed as a final line, since a model's last
+ * line often arrives without its newline.
+ */
+function createLineConsumer(onLine) {
+    let buffer = '';
+    return {
+        push(text) {
+            buffer += text;
+            const lines = buffer.split('\n');
+            buffer = lines.pop() ?? '';
+            for (const line of lines) {
+                const trimmed = line.trim();
+                if (trimmed)
+                    onLine(trimmed);
+            }
+        },
+        flush() {
+            const trimmed = buffer.trim();
+            buffer = '';
+            if (trimmed)
+                onLine(trimmed);
+        },
+    };
+}
+/**
+ * Mine an error response for something better to show than its status code.
+ */
+async function readErrorMessage(response) {
+    try {
+        const body = await response.json();
+        if (body.message)
+            return String(body.message);
+        if (body.error)
+            return String(body.error);
+    }
+    catch {
+        // A non-JSON error body is ordinary; the status line still says enough.
+    }
+    return `HTTP error: ${response.status}`;
+}
+/**
+ * POST `body` and feed the streamed response to `consumer` until it ends.
+ *
+ * Both hooks share this so the request lifecycle — error mining, the reader
+ * loop, the decoder's final flush — has one implementation to get right
+ * rather than one per hook that has to be fixed twice.
+ */
+async function streamRequest(request, consumer) {
+    // Bound, because a bare `globalThis.fetch` called as a plain function is
+    // an illegal invocation in the browser.
+    const doFetch = request.fetch ?? globalThis.fetch.bind(globalThis);
+    const response = await doFetch(request.api, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(request.body),
+        signal: request.signal,
+    });
+    if (!response.ok) {
+        throw new Error(await readErrorMessage(response));
+    }
+    const reader = response.body?.getReader();
+    if (!reader) {
+        throw new Error('No response body');
+    }
+    const decoder = new TextDecoder();
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        consumer.push(decoder.decode(value, { stream: true }));
+    }
+    // Without the final, non-streaming decode a multi-byte character split
+    // across the last chunk is dropped instead of surfacing.
+    const tail = decoder.decode();
+    if (tail)
+        consumer.push(tail);
+    consumer.flush();
+}
+
+/**
+ * Parse a single JSON line (patch or metadata). Anything that is not one of
+ * the two is dropped: half-written lines and stray prose are ordinary in a
+ * model's output, and aborting the generation over one would lose the UI
+ * built so far.
+ */
+function parseLine(line) {
+    try {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('//')) {
+            return null;
+        }
+        const parsed = JSON.parse(trimmed);
+        // Check for usage metadata
+        if (parsed.__meta === 'usage') {
+            return {
+                type: 'usage',
+                usage: {
+                    promptTokens: parsed.promptTokens ?? 0,
+                    completionTokens: parsed.completionTokens ?? 0,
+                    totalTokens: parsed.totalTokens ?? 0,
+                },
+            };
+        }
+        // Parseable JSON is not yet a patch: without this, a stray object would be
+        // recorded as a raw line and handed to the engine as an opless patch.
+        if (typeof parsed?.op !== 'string' || typeof parsed?.path !== 'string') {
+            return null;
+        }
+        return { type: 'patch', patch: parsed };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Streaming UI generation. POSTs `{ prompt, context, currentSpec }` to the
+ * endpoint and progressively applies the returned JSONL patch stream to the
+ * `spec` signal, so partial UIs render as they arrive.
+ *
+ * Must be called in an injection context (aborts in-flight requests on
+ * destroy).
+ *
+ * @example
+ * ```ts
+ * export class GeneratePage {
+ *   readonly ui = injectUIStream({ api: '/api/generate' });
+ * }
+ * // template:
+ * // <json-render [spec]="ui.spec()" [registry]="registry" [loading]="ui.isStreaming()" />
+ * ```
+ */
+function injectUIStream(options) {
+    const spec = signal(null, ...(ngDevMode ? [{ debugName: "spec" }] : /* istanbul ignore next */ []));
+    const isStreaming = signal(false, ...(ngDevMode ? [{ debugName: "isStreaming" }] : /* istanbul ignore next */ []));
+    const error = signal(null, ...(ngDevMode ? [{ debugName: "error" }] : /* istanbul ignore next */ []));
+    const usage = signal(null, ...(ngDevMode ? [{ debugName: "usage" }] : /* istanbul ignore next */ []));
+    const rawLines = signal([], ...(ngDevMode ? [{ debugName: "rawLines" }] : /* istanbul ignore next */ []));
+    const session = createStreamSession();
+    inject(DestroyRef).onDestroy(() => session.cancel());
+    const stop = () => {
+        session.cancel();
+        isStreaming.set(false);
+    };
+    const clear = () => {
+        // Aborting first is what makes this true: without it the in-flight
+        // request puts its spec straight back on the next patch it applies.
+        stop();
+        spec.set(null);
+        error.set(null);
+        usage.set(null);
+        rawLines.set([]);
+    };
+    const send = async (prompt, sendOptions) => {
+        const gate = session.begin();
+        isStreaming.set(true);
+        error.set(null);
+        usage.set(null);
+        rawLines.set([]);
+        const previousSpec = sendOptions?.previousSpec;
+        let currentSpec = previousSpec && previousSpec.root
+            ? { ...previousSpec, elements: { ...previousSpec.elements } }
+            : { root: '', elements: {} };
+        spec.set(currentSpec);
+        const handleLine = (line) => {
+            const parsed = parseLine(line);
+            if (!parsed)
+                return;
+            gate.commit(() => {
+                if (parsed.type === 'usage') {
+                    usage.set(parsed.usage);
+                    return;
+                }
+                rawLines.update((prev) => [...prev, line]);
+                currentSpec = applyPatch(currentSpec, parsed.patch);
+                spec.set(currentSpec);
+            });
+        };
+        try {
+            await streamRequest({
+                api: options.api,
+                body: {
+                    prompt,
+                    context: sendOptions?.context,
+                    currentSpec,
+                },
+                fetch: options.fetch,
+                signal: gate.signal,
+            }, createLineConsumer(handleLine));
+            gate.commit(() => options.onComplete?.(currentSpec));
+        }
+        catch (err) {
+            if (isAbortError(err))
+                return;
+            const resolvedError = err instanceof Error ? err : new Error(String(err));
+            gate.commit(() => {
+                error.set(resolvedError);
+                options.onError?.(resolvedError);
+            });
+        }
+        finally {
+            gate.commit(() => isStreaming.set(false));
+        }
+    };
+    return {
+        spec: spec.asReadonly(),
+        isStreaming: isStreaming.asReadonly(),
+        error: error.asReadonly(),
+        usage: usage.asReadonly(),
+        rawLines: rawLines.asReadonly(),
+        send,
+        stop,
+        clear,
+    };
+}
+
 let chatMessageIdCounter = 0;
 function generateChatId() {
     if (typeof crypto !== 'undefined' &&
@@ -1897,24 +1990,21 @@ function injectChatUI(options) {
     const messages = signal([], ...(ngDevMode ? [{ debugName: "messages" }] : /* istanbul ignore next */ []));
     const isStreaming = signal(false, ...(ngDevMode ? [{ debugName: "isStreaming" }] : /* istanbul ignore next */ []));
     const error = signal(null, ...(ngDevMode ? [{ debugName: "error" }] : /* istanbul ignore next */ []));
-    let abortController = null;
-    inject(DestroyRef).onDestroy(() => {
-        abortController?.abort();
-    });
+    const session = createStreamSession();
+    inject(DestroyRef).onDestroy(() => session.cancel());
+    const stop = () => {
+        session.cancel();
+        isStreaming.set(false);
+    };
     const clear = () => {
+        stop();
         messages.set([]);
         error.set(null);
     };
     const send = async (text) => {
         if (!text.trim())
             return;
-        // Abort any existing request
-        abortController?.abort();
-        const controller = new AbortController();
-        abortController = controller;
-        // See injectUIStream: a superseded request must not clear `isStreaming`
-        // out from under the request that replaced it.
-        const isCurrent = () => abortController === controller;
+        const gate = session.begin();
         const userMessage = {
             id: generateChatId(),
             role: 'user',
@@ -1928,10 +2018,25 @@ function injectChatUI(options) {
             text: '',
             spec: null,
         };
-        // Build messages array for the API (full conversation history + new message).
+        /**
+         * Drop this turn's assistant bubble if it never got any text.
+         *
+         * Deliberately outside the gate: the edit is scoped to this request's own
+         * message id, so it is safe even once a newer request has appended its
+         * turn — and a superseded request is exactly when it is needed, since an
+         * empty bubble left behind renders as a blank reply and is serialised
+         * into every later turn's history.
+         */
+        const dropEmptyPlaceholder = () => {
+            messages.update((prev) => prev.filter((m) => m.id !== assistantId || m.text.length > 0));
+        };
+        // Built before the new turn is appended, so it carries the conversation so
+        // far. Assistant turns with no text are left out: they say nothing to the
+        // model, some providers reject empty content outright, and a turn being
+        // superseded right now may still have its placeholder in the list.
         const historyForApi = [
             ...messages()
-                .filter((m) => m.id !== userMessage.id && m.id !== assistantId)
+                .filter((m) => m.role !== 'assistant' || m.text.length > 0)
                 .map((m) => ({
                 role: m.role,
                 content: m.text,
@@ -1944,87 +2049,54 @@ function injectChatUI(options) {
         error.set(null);
         // Mutable state for accumulating the assistant response
         let accumulatedText = '';
-        const currentSpec = { root: '', elements: {} };
+        let currentSpec = { root: '', elements: {} };
         let hasSpec = false;
-        const snapshotSpec = () => ({
-            root: currentSpec.root,
-            elements: { ...currentSpec.elements },
-            ...(currentSpec.state ? { state: { ...currentSpec.state } } : {}),
+        const parser = createMixedStreamParser({
+            onPatch(patch) {
+                hasSpec = true;
+                // applyPatch returns a fresh spec that shares what the patch did not
+                // touch, so the message can hold it directly — no snapshot copy.
+                currentSpec = applyPatch(currentSpec, patch);
+                const snapshot = currentSpec;
+                gate.commit(() => messages.update((prev) => prev.map((m) => m.id === assistantId ? { ...m, spec: snapshot } : m)));
+            },
+            onText(line) {
+                accumulatedText += (accumulatedText ? '\n' : '') + line;
+                const snapshot = accumulatedText;
+                gate.commit(() => messages.update((prev) => prev.map((m) => m.id === assistantId ? { ...m, text: snapshot } : m)));
+            },
         });
-        // Bound, because a bare `globalThis.fetch` called as a plain function is
-        // an illegal invocation in the browser.
-        const doFetch = options.fetch ?? globalThis.fetch.bind(globalThis);
         try {
-            const response = await doFetch(options.api, {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json' },
-                body: JSON.stringify({ messages: historyForApi }),
-                signal: controller.signal,
-            });
-            if (!response.ok) {
-                let errorMessage = `HTTP error: ${response.status}`;
-                try {
-                    const errorData = await response.json();
-                    if (errorData.message) {
-                        errorMessage = errorData.message;
-                    }
-                    else if (errorData.error) {
-                        errorMessage = errorData.error;
-                    }
-                }
-                catch {
-                    // Ignore JSON parsing errors
-                }
-                throw new Error(errorMessage);
-            }
-            const reader = response.body?.getReader();
-            if (!reader) {
-                throw new Error('No response body');
-            }
-            const decoder = new TextDecoder();
-            // Use createMixedStreamParser to classify lines
-            const parser = createMixedStreamParser({
-                onPatch(patch) {
-                    hasSpec = true;
-                    applySpecPatch(currentSpec, patch);
-                    const snapshot = snapshotSpec();
-                    messages.update((prev) => prev.map((m) => m.id === assistantId ? { ...m, spec: snapshot } : m));
-                },
-                onText(line) {
-                    accumulatedText += (accumulatedText ? '\n' : '') + line;
-                    messages.update((prev) => prev.map((m) => m.id === assistantId ? { ...m, text: accumulatedText } : m));
-                },
-            });
-            while (true) {
-                const { done, value } = await reader.read();
-                if (done)
-                    break;
-                parser.push(decoder.decode(value, { stream: true }));
-            }
-            parser.flush();
-            // Build final message for onComplete callback
+            await streamRequest({
+                api: options.api,
+                body: { messages: historyForApi },
+                fetch: options.fetch,
+                signal: gate.signal,
+            }, parser);
             const finalMessage = {
                 id: assistantId,
                 role: 'assistant',
                 text: accumulatedText,
-                spec: hasSpec ? snapshotSpec() : null,
+                spec: hasSpec ? currentSpec : null,
             };
-            options.onComplete?.(finalMessage);
+            gate.commit(() => options.onComplete?.(finalMessage));
         }
         catch (err) {
-            if (err.name === 'AbortError' || !isCurrent()) {
+            // Unconditional: however this turn ended, its own bubble goes with it if
+            // nothing was ever said into it. A superseded request usually unwinds by
+            // abort, but one whose stream failed for its own reason after being
+            // replaced would otherwise leave the placeholder behind.
+            dropEmptyPlaceholder();
+            if (isAbortError(err))
                 return;
-            }
             const resolvedError = err instanceof Error ? err : new Error(String(err));
-            error.set(resolvedError);
-            // Remove empty assistant message on error
-            messages.update((prev) => prev.filter((m) => m.id !== assistantId || m.text.length > 0));
-            options.onError?.(resolvedError);
+            gate.commit(() => {
+                error.set(resolvedError);
+                options.onError?.(resolvedError);
+            });
         }
         finally {
-            if (isCurrent()) {
-                isStreaming.set(false);
-            }
+            gate.commit(() => isStreaming.set(false));
         }
     };
     return {
@@ -2032,10 +2104,20 @@ function injectChatUI(options) {
         isStreaming: isStreaming.asReadonly(),
         error: error.asReadonly(),
         send,
+        stop,
         clear,
     };
 }
 
+/**
+ * Streaming: applying a model's output to a spec as it arrives.
+ *
+ * - `patch` — the immutable RFC 6902 engine every entry point applies through.
+ * - `transport` — one streamed request lifecycle, shared by both hooks.
+ * - `parts` — adapters for the AI SDK's message parts.
+ * - `ui-stream` / `chat-ui` — the two hooks, composed from the above.
+ */
+
 /**
  * The schema for ngx-json-render.
  *