@khorsheed/dsh-inline-html-render 0.1.13

package/lib/index.js

@@ -0,0 +1,88 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+//#region lib/types/index.js
+/**
+* Inline HTML render host half. Registers the `inline-html-card` and
+* `3d-artifact` skills, which
+* documents the fenced-block protocol the browser half consumes: the agent
+* writes a ` ```dsh-card ```` fenced block (or a `dsh-card <spec>` inline
+* fence) whose body is a fully self-contained HTML document, and the client
+* half swaps the rendered `<pre><code class="language-dsh-card">` for a
+* sandboxed iframe that runs it.
+*
+* This half owns no DOM and no Remote — it only advertises the contract so
+* the agent knows how to author a card. It degrades silently when the
+* `skills` capability is absent (a minimal composition may lack it), exactly
+* without widening the read-only file-preview host's responsibility.
+* @module @khorsheed/dsh-inline-html-render
+*/
+/**
+* Read and parse one shipped SKILL.md (`inline-html-card` / `3d-artifact`) into
+* a registration.
+*
+* This skill is content-only — it ships a single self-contained SKILL.md with
+* no sibling scripts/assets/references. Per the capability-catalog registration
+* protocol, a content-only skill OMITS `resourceBase` so the catalog renders it
+* as a virtual single-SKILL.md node (it does NOT point at a directory that
+* holds only SKILL.md). Add `resourceBase: { kind: 'directory', path }` only
+* when a bundle with files beside SKILL.md is introduced later.
+* @param ctx - plugin context (for logging).
+* @returns the parsed skill, or undefined when the file is missing/malformed
+*   (a discovery aid must never take a boot down, so each failure warns).
+*/
+function readSkill(ctx, skillName) {
+	try {
+		const skillDir = join(dirname(fileURLToPath(import.meta.url)), "..", "skills", skillName);
+		const skillFile = join(skillDir, "SKILL.md");
+		const raw = readFileSync(skillFile, "utf8");
+		const match = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/.exec(raw);
+		const name = /^name: (.+)$/m.exec(match?.[1] ?? "")?.[1]?.trim();
+		const description = /^description: (.+)$/m.exec(match?.[1] ?? "")?.[1]?.trim();
+		const content = match?.[2];
+		if (match === null || name === void 0 || description === void 0 || content === void 0) {
+			ctx.logger.warn(`inline-html-render: shipped SKILL.md is malformed — the ${skillName} skill is not registered`);
+			return;
+		}
+		return {
+			name,
+			description,
+			content,
+			source: "runtime",
+			provider: "inline-html-render"
+		};
+	} catch (error) {
+		ctx.logger.warn(`inline-html-render: shipped SKILL.md unreadable (${String(error)}) — the ${skillName} skill is not registered`);
+		return;
+	}
+}
+/** The host half requires no service; `skills` is awaited, never baked into inject. */
+const inject = [];
+/**
+* Plugin body: register the card-authoring skill once the `skills` service is
+* ready. `ctx.inject(['skills'], …)` waits for the service rather than probing
+* it synchronously at apply time, so registration is not skipped when the host
+* mounts this plugin before the skill registry is up. (The file-preview host is
+* a service class instantiated at a later point; this plugin's `apply` runs
+* earlier, so a plain synchronous `ctx.get('skills')` at apply time could see
+* the registry absent and silently skip — which is why inline-html-card did not
+* appear in the catalog while 3d-artifact did.)
+* @param ctx - Cordis context carrying the `skills` service.
+* @returns a disposer unwinding the registration effect.
+*/
+function apply(ctx) {
+	const disposers = [];
+	ctx.inject(["skills"], (scoped) => {
+		const registry = scoped.get("skills");
+		if (registry === void 0) return;
+		for (const skillName of ["inline-html-card", "3d-artifact"]) {
+			const skill = readSkill(scoped, skillName);
+			if (skill !== void 0) disposers.push(scoped.effect(() => registry.register(skill)));
+		}
+	});
+	return () => {
+		for (const disposer of disposers.reverse()) disposer();
+	};
+}
+//#endregion
+export { apply, inject };

package/lib/invariant.js

@@ -0,0 +1,25 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@khorsheed/dsh-inline-html-render`.
+* @module @khorsheed/dsh-inline-html-render/invariant
+*/
+const PACKAGE_NAME = "@khorsheed/dsh-inline-html-render";
+/** Cordis companion plugin name. */
+const name = "client-inline-html-render-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: the renderer is a pure DOM-layer effect owning its own
+* MutationObserver and a per-document iframe/`<pre>` pair; there is no durable
+* state shared with other packages. Reserved here so the loader knows this
+* package is alive (and so a future invariant can attach without a rename).
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns The installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/client/bridge.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Host-side capability bridge for an inline card iframe: validates EVERY
+ * message — the `message.source` must be the controlled iframe's window, `fn`
+ * must be in the whitelist, and args are shape-checked per function — then
+ * executes and replies `{ id, ok, result }` back. Unknown or malformed calls
+ * get an error reply, never an exception in the host.
+ * @module @khorsheed/dsh-inline-html-render
+ */
+/**
+ * Host capabilities the plugin wires from its context at install time. Every
+ * one is optional: absence keeps the plain-browser default.
+ */
+export interface BridgeCapabilities {
+    /**
+     * Open an https card link. The plugin routes this into the right-Sidebar
+     * Browser tab when the host registers that type (0.1.6-alpha.2's
+     * ui-sidebar-browser), falling back to a new window otherwise.
+     */
+    readonly openLink?: (url: string) => void;
+}
+/**
+ * Listen for bridge/height messages from one controlled iframe.
+ * @param frame - the card iframe; only its window's messages are honored.
+ * @param capabilities - wired host capabilities; absence keeps browser defaults.
+ * @returns a disposer removing the listener.
+ */
+export declare function attachBridge(frame: HTMLIFrameElement, capabilities?: BridgeCapabilities): () => void;
+//# sourceMappingURL=bridge.d.ts.map

package/lib/types/client/bridge.js

@@ -0,0 +1,110 @@
+/**
+ * Host-side capability bridge for an inline card iframe: validates EVERY
+ * message — the `message.source` must be the controlled iframe's window, `fn`
+ * must be in the whitelist, and args are shape-checked per function — then
+ * executes and replies `{ id, ok, result }` back. Unknown or malformed calls
+ * get an error reply, never an exception in the host.
+ * @module @khorsheed/dsh-inline-html-render
+ */
+/** The default link route: a new window, https only enforced by the caller. */
+function openLinkInWindow(url) {
+    window.open(url, '_blank', 'noopener,noreferrer');
+}
+/**
+ * Each handler runs with validated args and may throw; errors become an error reply.
+ * @param capabilities - the install's wired capabilities (openLink falls back to a new window).
+ */
+function handlersFor(capabilities) {
+    return {
+        // Default: https only, noopener. `javascript:`/`file:`/`data:` are refused.
+        openLink: (args) => {
+            const url = String(args[0] ?? '');
+            if (!/^https:/i.test(url))
+                throw new Error(`openLink: only https: targets are allowed (got ${url.slice(0, 40)})`);
+            (capabilities.openLink ?? openLinkInWindow)(url);
+        },
+        copy: async (args) => {
+            const text = String(args[0] ?? '');
+            if (text.length > 1_000_000)
+                throw new Error('copy: text too large');
+            try {
+                await navigator.clipboard.writeText(text);
+            }
+            catch {
+                fallbackCopy(text);
+            }
+        },
+        download: (args) => {
+            const name = String(args[0] ?? 'download');
+            const dataUrl = String(args[1] ?? '');
+            if (!/^data:/i.test(dataUrl))
+                throw new Error('download: only data: URLs are allowed');
+            const anchor = document.createElement('a');
+            anchor.href = dataUrl;
+            anchor.download = name;
+            anchor.click();
+        },
+    };
+}
+/** execCommand copy fallback for contexts without the async clipboard API. */
+function fallbackCopy(text) {
+    const area = document.createElement('textarea');
+    area.value = text;
+    area.setAttribute('readonly', '');
+    area.style.position = 'fixed';
+    area.style.opacity = '0';
+    document.body.appendChild(area);
+    area.select();
+    try {
+        document.execCommand('copy');
+    }
+    finally {
+        area.remove();
+    }
+}
+function reply(frame, message) {
+    frame.contentWindow?.postMessage(message, '*');
+}
+/** Cap on the reported height, guarding against a runaway or adversarial card. */
+const MAX_FRAME_HEIGHT = 20_000;
+/**
+ * Listen for bridge/height messages from one controlled iframe.
+ * @param frame - the card iframe; only its window's messages are honored.
+ * @param capabilities - wired host capabilities; absence keeps browser defaults.
+ * @returns a disposer removing the listener.
+ */
+export function attachBridge(frame, capabilities = {}) {
+    const handlers = handlersFor(capabilities);
+    const onMessage = (event) => {
+        if (event.source !== frame.contentWindow)
+            return;
+        const data = event.data;
+        if (data === null || typeof data !== 'object')
+            return;
+        const id = data.id;
+        const fn = data.fn;
+        // The height report is a message without an `id`; it is not a call and gets
+        // no reply, only the frame resize.
+        if (fn === 'resize') {
+            const args = Array.isArray(data.args) ? data.args : [];
+            const height = Number(args[0] ?? 0);
+            if (Number.isFinite(height) && height > 0) {
+                frame.style.height = `${Math.min(Math.ceil(height) + 1, MAX_FRAME_HEIGHT)}px`;
+            }
+            return;
+        }
+        if (typeof id !== 'string' || typeof fn !== 'string')
+            return;
+        const handler = handlers[fn];
+        if (handler === undefined) {
+            reply(frame, { id, ok: false, error: `unknown bridge function: ${fn}` });
+            return;
+        }
+        const args = Array.isArray(data.args) ? data.args : [];
+        Promise.resolve()
+            .then(() => handler(args))
+            .then(() => reply(frame, { id, ok: true, result: undefined }), (error) => reply(frame, { id, ok: false, error: error instanceof Error ? error.message : String(error) }));
+    };
+    addEventListener('message', onMessage);
+    return () => removeEventListener('message', onMessage);
+}

package/lib/types/client/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Inline HTML card client plugin, browser half. Installs a DOM-layer renderer
+ * that swaps rendered ` ```dsh-card ```` fenced blocks for sandboxed iframes
+ * running the authored HTML, inline in the conversation flow.
+ *
+ * It owns no slot and no Remote service — the browser half only mutates the
+ * already-rendered DOM (the repo-accepted last-resort pattern, like
+ * message-tools' dom-hider), so it composes as an independent package with no
+ * edits to core packages. Card links open in the right-Sidebar Browser tab
+ * when the host ships that type (0.1.6-alpha.2's ui-sidebar-browser), else in
+ * a new window — a probe, not a dependency. Without this plugin the fenced
+ * block simply renders as a normal code block: it degrades, never crashes.
+ * @module @khorsheed/dsh-inline-html-render/client
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** The client half requires no service: every host capability is probed, never injected. */
+export declare const inject: readonly string[];
+/**
+ * The card-link route: host 0.1.6-alpha.2's ui-sidebar-browser registers the
+ * `browser` right-Sidebar tab kind, so a card link opens as a Sidebar tab
+ * there; any older host or missing piece (service, type, or a registry race
+ * on open) falls back to a new window. Probed per open, so a hot-added tab
+ * type counts and a hot-removed one just falls back.
+ * @param ctx - client root context.
+ * @returns the bridge's openLink capability.
+ */
+export declare function createLinkOpener(ctx: Context): (url: string) => void;
+/**
+ * Plugin body: install the card renderer for the browser lifetime.
+ * @param ctx - client root context (probed for the optional Sidebar Browser route).
+ * @returns a disposer tearing the renderer down.
+ */
+export declare function apply(ctx: Context): () => void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/client/index.js

@@ -0,0 +1,60 @@
+/**
+ * Inline HTML card client plugin, browser half. Installs a DOM-layer renderer
+ * that swaps rendered ` ```dsh-card ```` fenced blocks for sandboxed iframes
+ * running the authored HTML, inline in the conversation flow.
+ *
+ * It owns no slot and no Remote service — the browser half only mutates the
+ * already-rendered DOM (the repo-accepted last-resort pattern, like
+ * message-tools' dom-hider), so it composes as an independent package with no
+ * edits to core packages. Card links open in the right-Sidebar Browser tab
+ * when the host ships that type (0.1.6-alpha.2's ui-sidebar-browser), else in
+ * a new window — a probe, not a dependency. Without this plugin the fenced
+ * block simply renders as a normal code block: it degrades, never crashes.
+ * @module @khorsheed/dsh-inline-html-render/client
+ */
+import { installCardRenderer } from './renderer.js';
+/** The client half requires no service: every host capability is probed, never injected. */
+export const inject = [];
+/**
+ * The card-link route: host 0.1.6-alpha.2's ui-sidebar-browser registers the
+ * `browser` right-Sidebar tab kind, so a card link opens as a Sidebar tab
+ * there; any older host or missing piece (service, type, or a registry race
+ * on open) falls back to a new window. Probed per open, so a hot-added tab
+ * type counts and a hot-removed one just falls back.
+ * @param ctx - client root context.
+ * @returns the bridge's openLink capability.
+ */
+export function createLinkOpener(ctx) {
+    return (url) => {
+        const tabs = ctx.get('sidebarRightTabs');
+        const sidebarRight = ctx.get('sidebarRight');
+        if (tabs?.get('browser') !== undefined && sidebarRight !== undefined) {
+            try {
+                sidebarRight.openTab('browser', { params: { url } });
+                return;
+            }
+            catch {
+                // The kind raced out of the registry between probe and open: fall through.
+            }
+        }
+        window.open(url, '_blank', 'noopener,noreferrer');
+    };
+}
+/**
+ * Plugin body: install the card renderer for the browser lifetime.
+ * @param ctx - client root context (probed for the optional Sidebar Browser route).
+ * @returns a disposer tearing the renderer down.
+ */
+export function apply(ctx) {
+    let renderer;
+    // Effect so teardown/re-composition unwinds cleanly; a re-apply replaces the
+    // previous renderer.
+    const install = () => {
+        renderer = installCardRenderer({ openLink: createLinkOpener(ctx) });
+    };
+    install();
+    return () => {
+        renderer?.dispose();
+        renderer = undefined;
+    };
+}

package/lib/types/client/renderer.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Inline card renderer: finds the rendered `.md-code-block` whose infostring is
+ * `dsh-card` and replaces its visual slot with a sandboxed iframe running the
+ * authored HTML, inline in the conversation flow.
+ *
+ * React owns the markdown tree, so this plugin NEVER removes a node React
+ * created — that would make React's reconciliation fight the DOM and could
+ * throw or resurrect the block. Instead it inserts the iframe as a SIBLING
+ * right after the block and hides the block (`display:none`, a style React
+ * does not manage), then re-applies on any mutation. Because React replaces
+ * nodes (it does not reuse them across a re-render of changed content), each
+ * replacement is detected fresh and re-hidden; the data marker on the *block*
+ * keeps one block from being processed twice in a single pass.
+ *
+ * Streaming gate: while a turn is running, `AssistantMarkdown` sets
+ * `data-streaming` on its root and the block content is partial and will be
+ * re-rendered. We only swap settled blocks (no `[data-streaming]` ancestor),
+ * so a card never mounts on a half-streamed body. On settle, React re-renders
+ * the markdown, which removes `data-streaming` and re-creates the block; the
+ * observer sees that and swaps then.
+ *
+ * @module @khorsheed/dsh-inline-html-render
+ */
+import { type BridgeCapabilities } from './bridge.ts';
+/** Info string that marks a fence as an inline card. */
+export declare const CARD_INFO_STRING = "dsh-card";
+/** A mounted card: the block it replaced and the disposer of its bridge. */
+interface MountedCard {
+    readonly block: HTMLElement;
+    readonly frame: HTMLIFrameElement;
+    /** Hides the block and guards duplicate disposal. */
+    dispose: () => void;
+}
+/** Find every rendered `dsh-card` block under `root`. */
+export declare function findCardBlocks(root: ParentNode): HTMLElement[];
+/** Reconcile: swap every unprocessed, settled `dsh-card` block under `root`, then drop orphans. */
+export declare function reconcile(root: ParentNode, capabilities?: BridgeCapabilities): MountedCard[];
+/** A live renderer installation: reconcile on mutation, dispose cleanly. */
+export interface CardRenderer {
+    /** Manually run a reconcile pass (also fired by the observer). */
+    run: () => void;
+    /** Remove the observer and every mounted card frame. */
+    dispose: () => void;
+}
+/**
+ * Install the inline-card renderer over the document.
+ * @param capabilities - wired host capabilities handed to every card's bridge.
+ * @returns a {@link CardRenderer} whose `dispose` tears everything down.
+ */
+export declare function installCardRenderer(capabilities?: BridgeCapabilities): CardRenderer;
+export {};
+//# sourceMappingURL=renderer.d.ts.map

package/lib/types/client/renderer.js

@@ -0,0 +1,220 @@
+/**
+ * Inline card renderer: finds the rendered `.md-code-block` whose infostring is
+ * `dsh-card` and replaces its visual slot with a sandboxed iframe running the
+ * authored HTML, inline in the conversation flow.
+ *
+ * React owns the markdown tree, so this plugin NEVER removes a node React
+ * created — that would make React's reconciliation fight the DOM and could
+ * throw or resurrect the block. Instead it inserts the iframe as a SIBLING
+ * right after the block and hides the block (`display:none`, a style React
+ * does not manage), then re-applies on any mutation. Because React replaces
+ * nodes (it does not reuse them across a re-render of changed content), each
+ * replacement is detected fresh and re-hidden; the data marker on the *block*
+ * keeps one block from being processed twice in a single pass.
+ *
+ * Streaming gate: while a turn is running, `AssistantMarkdown` sets
+ * `data-streaming` on its root and the block content is partial and will be
+ * re-rendered. We only swap settled blocks (no `[data-streaming]` ancestor),
+ * so a card never mounts on a half-streamed body. On settle, React re-renders
+ * the markdown, which removes `data-streaming` and re-creates the block; the
+ * observer sees that and swaps then.
+ *
+ * @module @khorsheed/dsh-inline-html-render
+ */
+import { buildCardSrcDoc } from './srcdoc.js';
+import { attachBridge } from './bridge.js';
+/** Info string that marks a fence as an inline card. */
+export const CARD_INFO_STRING = 'dsh-card';
+/** Marker set on the block once it has been swapped, making a pass idempotent. */
+const PROCESSED_ATTR = 'data-dsh-card-processed';
+/** The injected iframe's class, for cleanup. */
+const FRAME_CLASS = 'dsh-inline-card-frame';
+/** Attribute used to find the bridge-ready frame and its disposer. */
+const BRIDGE_ATTR = 'data-dsh-bridge';
+/** True when one `.md-code-block` was authored with the `dsh-card` info string.
+ *
+ * The official `CodeBlock` renders the fence info string in the banner, but the
+ * DOM shape is not a stable contract: some builds render a dedicated
+ * `.infostring` element, while this release flattens the banner wrap
+ * (`_bannerWrap_…`) whose leading text is `<info>复制` (info string first, then
+ * the localized copy label), with no `.infostring`. So we match on the block's
+ * leading text: the info string is always rendered before the code body, and a
+ * normal code block cannot begin with `dsh-card` unless it was authored that
+ * way. Prefer the explicit `.infostring` element when present, then fall back
+ * to the text prefix.
+ */
+function isCardInfoBlock(block) {
+    const explicit = block.querySelector('.infostring');
+    if (explicit !== null)
+        return explicit.textContent?.trim() === CARD_INFO_STRING;
+    // `textContent` begins with the info string baked before the copy label.
+    return block.textContent.trimStart().startsWith(CARD_INFO_STRING);
+}
+/** Find every rendered `dsh-card` block under `root`. */
+export function findCardBlocks(root) {
+    const out = [];
+    for (const node of root.querySelectorAll('.md-code-block')) {
+        if (isCardInfoBlock(node))
+            out.push(node);
+    }
+    return out;
+}
+/** True when the block (or an ancestor) is inside a still-streaming message. */
+function isStreaming(node) {
+    return node.closest('[data-streaming]') !== null;
+}
+/** Extract the authored HTML from a card block's `<pre>` text body. */
+function readCardHtml(block) {
+    const pre = block.querySelector('pre');
+    return (pre?.textContent ?? '').replace(/\n$/, '');
+}
+/**
+ * Render one card block: read the HTML, build a sandboxed srcDoc, insert the
+ * iframe after the block, hide the block, and attach the capability bridge.
+ * @param block - the rendered `dsh-card` block.
+ * @param capabilities - wired host capabilities handed to the bridge.
+ * @returns a {@link MountedCard} or null when the block had no content.
+ */
+function mountCard(block, capabilities) {
+    const html = readCardHtml(block);
+    if (html.trim() === '')
+        return null;
+    const frame = document.createElement('iframe');
+    frame.className = FRAME_CLASS;
+    frame.setAttribute('sandbox', 'allow-scripts');
+    frame.setAttribute('title', 'inline card');
+    // A fresh container each mount: the frame is opaque-origin so nothing can
+    // spoof it, and setting srcDoc after insertion is fine (load fires async).
+    frame.srcdoc = buildCardSrcDoc(html);
+    frame.style.display = 'block';
+    frame.style.width = '100%';
+    // A small default so an unloaded frame is not collapsed; the bridge inside
+    // the frame posts the real content height on load/resize (see srcdoc.ts),
+    // because the parent cannot read contentDocument on an opaque-origin frame.
+    frame.style.height = 'auto';
+    frame.style.border = 'none';
+    block.parentNode?.insertBefore(frame, block.nextSibling);
+    // Hide the block with a style React does not reconcile (React only manages
+    // the class/style it rendered; this element's `style` is set once by us).
+    block.style.display = 'none';
+    block.setAttribute(PROCESSED_ATTR, '');
+    const disposeBridge = attachBridge(frame, capabilities);
+    frame.setAttribute(BRIDGE_ATTR, '');
+    const dispose = () => {
+        disposeBridge();
+        frame.remove();
+        block.removeAttribute(PROCESSED_ATTR);
+        // Do NOT clear block.style.display — React may not have re-rendered; a
+        // cleared style would flash the code block back. Cleaning up the frame is
+        // enough; the block node itself belongs to React.
+    };
+    return { block, frame, dispose };
+}
+/**
+ * Drop frames whose owning block is gone. React may replace a processed block
+ * with a fresh node (a re-render of the settled markdown); the old block's
+ * frame then has no matching block before it and would sit orphaned. A frame
+ * is owned by the immediately-preceding `.md-code-block` carrying the
+ * processed marker that paired with it — so a frame not preceded by exactly
+ * that is stale. Reactive re-scanning keeps the two in lockstep.
+ */
+function collectCardFrames(root) {
+    return [...root.querySelectorAll(`.${FRAME_CLASS}`)];
+}
+/** Remove every card frame whose predecessor block is no longer its partner. */
+function dropOrphanFrames(root, mounted) {
+    for (const frame of collectCardFrames(root)) {
+        const prev = frame.previousElementSibling;
+        const owned = prev instanceof HTMLElement && prev.classList.contains('md-code-block')
+            && prev.hasAttribute(PROCESSED_ATTR);
+        if (owned)
+            continue;
+        frame.remove();
+        // Best-effort detach from the mounted registry (the handle holds the same
+        // node, so a later dispose of the registry still finds it already gone).
+        for (const card of mounted) {
+            if (card.frame === frame) {
+                mounted.delete(card);
+                break;
+            }
+        }
+    }
+}
+/** Reconcile: swap every unprocessed, settled `dsh-card` block under `root`, then drop orphans. */
+export function reconcile(root, capabilities = {}) {
+    const mounted = [];
+    for (const block of findCardBlocks(root)) {
+        if (block.hasAttribute(PROCESSED_ATTR))
+            continue;
+        if (isStreaming(block))
+            continue;
+        const card = mountCard(block, capabilities);
+        if (card !== null)
+            mounted.push(card);
+    }
+    return mounted;
+}
+const CHAT_ROOT = '[data-conversation-scroll]';
+/**
+ * Install the inline-card renderer over the document.
+ * @param capabilities - wired host capabilities handed to every card's bridge.
+ * @returns a {@link CardRenderer} whose `dispose` tears everything down.
+ */
+export function installCardRenderer(capabilities = {}) {
+    // jsdom lacks requestAnimationFrame; fall back to a macrotask so the plugin
+    // never throws headless (and tests run synchronously via `run`).
+    const nextFrame = typeof requestAnimationFrame === 'function'
+        ? requestAnimationFrame
+        : (cb) => { setTimeout(cb, 0); };
+    const cancelFrame = typeof cancelAnimationFrame === 'function'
+        ? cancelAnimationFrame
+        : (id) => { clearTimeout(id); };
+    // Track mounted cards so dispose can take every frame down. Set keeps one
+    // entry per frame; re-runs of reconcile mount new frames and re-insert here.
+    const mounted = new Set();
+    const run = () => {
+        // Scope to the chat pane when present; fall back to the whole document so
+        // a not-yet-mounted chat (or headless test) still sees a first pass.
+        const root = document.querySelector(CHAT_ROOT) ?? document.body;
+        for (const card of reconcile(root, capabilities))
+            mounted.add(card);
+        dropOrphanFrames(root, mounted);
+    };
+    // Re-scan when the observed subtree mutates. Chat is the hot path; the full
+    // document observer would be noisy, so a chat bound improves cost — but the
+    // chat pane may not be mounted yet, so a document fallback keeps discovery
+    // working. Both observers coalesce via `nextFrame`.
+    let raf = 0;
+    const schedule = () => {
+        if (raf !== 0)
+            return;
+        raf = nextFrame(() => {
+            raf = 0;
+            run();
+        });
+    };
+    const observer = new MutationObserver(schedule);
+    observer.observe(document.body, {
+        childList: true,
+        subtree: true,
+        attributes: true,
+        attributeFilter: ['data-streaming'],
+    });
+    // First pass right away. `nextFrame` so the observer itself is not spammed
+    // before the first commit; a settled render only needs a microtask, so a
+    // caller wanting deterministic behavior calls `run()` directly.
+    schedule();
+    return {
+        run,
+        dispose: () => {
+            if (raf !== 0) {
+                cancelFrame(raf);
+                raf = 0;
+            }
+            observer.disconnect();
+            for (const card of mounted)
+                card.dispose();
+            mounted.clear();
+        },
+    };
+}

package/lib/types/client/srcdoc.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Sandboxed srcDoc builder for inline HTML cards.
+ *
+ * The parent web shell has no Content-Security-Policy of its own and an
+ * iframe's `srcdoc` is not served as an HTTP response, so CSP inheritance
+ * cannot be relied on — the policy must be embedded IN the document. This
+ * helper guarantees exactly that for both shapes of input:
+ *
+ * - a bare fragment (no `<html>`/`<head>`) is wrapped into a full document
+ *   whose head carries the CSP and the capability bridge;
+ * - a full document keeps its own structure and gets the CSP meta injected
+ *   right after its `<head …>` tag (skipped when it already declares one,
+ *   e.g. a skill-compliant output that embeds the same policy).
+ *
+ * The sandbox is `allow-scripts`, NEVER `allow-same-origin` — the opaque
+ * origin is what keeps the frame's scripts from touching the host, and the
+ * CSP is the network/capability boundary. This is deliberately stricter than
+ * file-preview's Tier1 (no whitelisted CDNs): an inline card should never
+ * reach the network at all.
+ * @module @khorsheed/dsh-inline-html-render
+ */
+/** Strict sandbox CSP: no network, no navigation, scripts only inline. */
+export declare const CARD_CSP = "default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src data: blob:; font-src data:; connect-src 'none'; worker-src blob:; object-src 'none'; base-uri 'none'; form-action 'none'";
+/**
+ * Wrap or annotate an untrusted HTML document so it runs inside the sandbox CSP.
+ * @param content - the card HTML, as authored inside the fenced block.
+ * @returns a complete document carrying the strict CSP and the bridge.
+ */
+export declare function buildCardSrcDoc(content: string): string;
+//# sourceMappingURL=srcdoc.d.ts.map