netra-artifacts 0.1.0-alpha.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to `netra` are documented here. This project
+adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-05-29
+
+### Added
+
+- Initial experimental release.
+- `createArtifactStreamResponse()` server helper — auto-classifies a request as
+  `markdown` or `html_artifact`, then streams an SSE response over the
+  `ArtifactStreamEvent` protocol.
+- Vercel AI SDK integration via `streamText` / `generateText` (no RSC, no `streamUI`).
+- Mode classifier with model-based classification and a heuristic rule fallback.
+- `<assistant_message>` / `<html_artifact>` envelope parser with fail-open behavior.
+- Static-only HTML sanitizer (strips `<script>`, event handlers, `javascript:`
+  URLs, external CSS/JS; preserves inline styles, `<style>`, SVG, and forms).
+- `useArtifactStream()` React hook plus `ArtifactChat`, `ArtifactMessage`,
+  `MarkdownMessage` components.
+- Seamless sandboxed iframe rendering: `HtmlArtifactCard`, `HtmlArtifactPreview`,
+  `HtmlArtifactModal`, `HtmlArtifactToolbar`, `HtmlArtifactCodeView`.
+- Snapshot buffering that keeps the last valid snapshot while partial HTML streams.
+- In-memory circuit breaker that falls back to markdown after repeated failures.
+- Dual ESM + CJS builds with subpath exports.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,239 @@
+# Netra Predictive HTML Parser
+
+Experimental dependency-free package for streaming AI-generated HTML into
+sandboxed iframe previews. Bring any model SDK that can produce text chunks.
+
+The high-level server helper is provider-agnostic: pass a
+`generateTextStream(args) => AsyncIterable<string>` adapter. For lower-level
+integrations, `streamHtmlArtifactFromTextStream` accepts raw text chunks
+directly.
+
+Netra keeps two versions of streamed HTML:
+
+- **Raw HTML:** the exact model output, never mutated by predictions
+- **Snapshot HTML:** a temporary, sanitized, iframe-safe projection with missing
+  closing tags predicted from the parser stack
+
+This lets a frontend render partial HTML while the model is still producing the
+document.
+
+## Install
+
+```bash
+npm install netra
+```
+
+Add whatever provider SDK you want:
+
+```bash
+npm install @ai-sdk/google
+```
+
+## Backend
+
+```ts
+import { createGoogleGenerativeAI } from "@ai-sdk/google";
+import { generateText, streamText } from "ai";
+import { createArtifactStreamResponse } from "netra/server";
+
+const google = createGoogleGenerativeAI({
+  apiKey: process.env.GOOGLE_API_KEY,
+});
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+  const model = google("gemini-2.5-flash");
+
+  return createArtifactStreamResponse({
+    messages,
+    generateTextStream: (args) => streamText({ model, ...args }).textStream,
+    generateText: async (args) => (await generateText({ model, ...args })).text,
+    mode: "auto",
+    snapshotIntervalMs: 0,
+    allowExternalFonts: true,
+  });
+}
+```
+
+## LangChain Adapter Pattern
+
+```ts
+import {
+  HTML_ARTIFACT_SYSTEM_PROMPT,
+  createSseResponse,
+  event,
+  streamHtmlArtifactFromTextStream,
+} from "netra/server";
+
+async function* toText(chunks: AsyncIterable<unknown>) {
+  for await (const chunk of chunks) {
+    if (typeof chunk === "string") yield chunk;
+    else if (chunk && typeof chunk === "object" && "content" in chunk) {
+      yield String((chunk as { content: unknown }).content ?? "");
+    }
+  }
+}
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  return createSseResponse(async (emit) => {
+    emit(event.mode("html_artifact"));
+
+    const stream = await model.stream([
+      ["system", HTML_ARTIFACT_SYSTEM_PROMPT],
+      ...messages.map((m: { role: string; content: string }) => [
+        m.role,
+        m.content,
+      ]),
+    ]);
+
+    await streamHtmlArtifactFromTextStream(
+      {
+        textStream: toText(stream),
+        sanitize: {
+          allowForms: true,
+          allowScripts: false,
+          allowInlineStyles: true,
+          allowStyleTags: true,
+          allowSvg: true,
+          allowExternalFonts: false,
+        },
+        snapshotIntervalMs: 0,
+      },
+      emit,
+    );
+
+    emit(event.done());
+  });
+}
+```
+
+## Frontend
+
+```tsx
+"use client";
+
+import { ArtifactMessage, useArtifactStream } from "netra/client";
+
+export function Chat() {
+  const { messages, artifacts, status, sendMessage } = useArtifactStream({
+    endpoint: "/api/chat",
+  });
+
+  return (
+    <div>
+      {messages.map((message) => (
+        <ArtifactMessage
+          key={message.id}
+          message={message}
+          artifacts={artifacts}
+          cardProps={{
+            variant: "glass",
+            previewOptions: {
+              allowExternalFonts: true,
+              autoResize: true,
+              debounceMs: 0,
+            },
+          }}
+        />
+      ))}
+
+      <button
+        disabled={status === "submitted" || status === "streaming"}
+        onClick={() => sendMessage("Create a sign-up form")}
+      >
+        Generate
+      </button>
+    </div>
+  );
+}
+```
+
+## Direct Parser Usage
+
+```ts
+import { PredictiveHtmlParser } from "netra/stream";
+
+const parser = new PredictiveHtmlParser();
+
+const frameA = parser.push("<body><form>");
+// "<body><form></form></body>"
+
+parser.committedHtml;
+// "<body><form>"
+
+const frameB = parser.push('<input type="email" />');
+// '<body><form><input type="email" /></form></body>'
+```
+
+## One-Shot Assembly
+
+```ts
+import { assembleStreamingHtml } from "netra/stream";
+
+const result = assembleStreamingHtml("<html><body><main><h1>Hello");
+
+result.html;
+// "<html><body><main><h1>Hello</h1></main></body></html>"
+
+result.renderable;
+// true
+```
+
+## Exports
+
+| Import | Purpose |
+| --- | --- |
+| `netra` | Isomorphic helpers, types, parser, sanitizer |
+| `netra/server` | Server response helpers for SSE |
+| `netra/client` | React hook and UI components |
+| `netra/iframe` | Iframe card and preview primitives |
+| `netra/stream` | Parser, SSE, buffering utilities |
+| `netra/sanitizer` | Sanitizer helpers |
+| `netra/classifier` | Auto-mode classifier |
+| `netra/types` | Public types |
+
+## Protocol
+
+```ts
+type ArtifactStreamEvent =
+  | { type: "mode"; mode: "markdown" | "html_artifact" }
+  | { type: "message_start"; messageId: string }
+  | { type: "message_delta"; messageId: string; delta: string }
+  | { type: "message_done"; messageId: string; content: string }
+  | { type: "artifact_start"; artifactId: string; title: string; artifactType: "html" }
+  | { type: "artifact_delta"; artifactId: string; delta: string }
+  | { type: "artifact_snapshot"; artifactId: string; html: string }
+  | { type: "artifact_done"; artifactId: string; html: string }
+  | { type: "error"; message: string; recoverable: boolean }
+  | { type: "done" };
+```
+
+## Security
+
+Artifacts are static HTML/CSS:
+
+- Scripts are stripped
+- Event handler attributes are stripped
+- Dangerous URLs are stripped
+- Iframes, embeds, object tags, and refresh meta tags are stripped
+- The preview iframe never receives `allow-scripts`
+- `allowExternalFonts` only keeps approved Google Fonts hosts
+
+Use Netra for safe previews of generated static HTML, not for executing
+generated application logic.
+
+## Checks
+
+```bash
+npm run typecheck
+npm run build
+npm test
+```
+
+## Status
+
+Experimental. The parser is intentionally conservative and optimized for AI
+HTML streaming, especially full-document artifacts with `<head>`, `<style>`,
+`<body>`, forms, SVG, charts, and layout sections.

package/dist/artifacts/artifactEnvelope.d.ts

@@ -0,0 +1,46 @@
+import type { ParsedArtifactEnvelope } from "../types/artifact.js";
+/** Strip a leading/trailing markdown code fence if the model wrapped output. */
+export declare function stripOuterFence(input: string): string;
+/**
+ * Clean common model wrapping around artifact HTML. This only trims code fences
+ * at the boundary of the artifact, so literal backticks inside the document are
+ * left alone.
+ */
+export declare function cleanArtifactHtml(input: string): string;
+/**
+ * Final, non-streaming parse of a model envelope. Fail-open: it never throws,
+ * and degrades gracefully when tags are missing or malformed. This is the
+ * authoritative parser used to produce the final artifact.
+ */
+export declare function parseArtifactEnvelope(raw: string): ParsedArtifactEnvelope;
+export type EnvelopeStreamEvent = {
+    kind: "message";
+    delta: string;
+} | {
+    kind: "artifact_open";
+    title: string;
+} | {
+    kind: "artifact";
+    delta: string;
+};
+/**
+ * Incremental envelope parser for live streaming. Feed it model-text chunks;
+ * it emits message/artifact deltas as they become safe to forward (holding
+ * back a small tail so partial delimiters are never emitted as content).
+ *
+ * The server still re-parses the full output at the end with
+ * {@link parseArtifactEnvelope} for the authoritative final artifact, so this
+ * parser only needs to be good enough for smooth live updates.
+ */
+export declare class StreamingEnvelopeParser {
+    private buf;
+    private cursor;
+    private state;
+    private artifactOpened;
+    feed(chunk: string): EnvelopeStreamEvent[];
+    flush(): EnvelopeStreamEvent[];
+    get hasOpenedArtifact(): boolean;
+    private safeEnd;
+    private process;
+}
+//# sourceMappingURL=artifactEnvelope.d.ts.map

package/dist/artifacts/artifactEnvelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifactEnvelope.d.ts","sourceRoot":"","sources":["../../src/artifacts/artifactEnvelope.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAcnE,gFAAgF;AAChF,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIrD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKvD;AAOD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,sBAAsB,CAoDzE;AAgBD,MAAM,MAAM,mBAAmB,GAC3B;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AASxC;;;;;;;;GAQG;AACH,qBAAa,uBAAuB;IAClC,OAAO,CAAC,GAAG,CAAM;IACjB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,KAAK,CAAiC;IAC9C,OAAO,CAAC,cAAc,CAAS;IAE/B,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,mBAAmB,EAAE;IAK1C,KAAK,IAAI,mBAAmB,EAAE;IAI9B,IAAI,iBAAiB,IAAI,OAAO,CAE/B;IAED,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,OAAO;CAoFhB"}

package/dist/artifacts/artifactEnvelope.js

@@ -0,0 +1,217 @@
+const MSG_OPEN = "<assistant_message>";
+const MSG_CLOSE = "</assistant_message>";
+const ART_OPEN = "<html_artifact";
+const ART_CLOSE = "</html_artifact>";
+const GUARD = Math.max(MSG_OPEN.length, MSG_CLOSE.length, ART_OPEN.length, ART_CLOSE.length);
+/** Strip a leading/trailing markdown code fence if the model wrapped output. */
+export function stripOuterFence(input) {
+    const trimmed = input.trim();
+    const fence = /^```[a-z]*\n([\s\S]*?)\n```$/i.exec(trimmed);
+    return fence?.[1] ?? input;
+}
+/**
+ * Clean common model wrapping around artifact HTML. This only trims code fences
+ * at the boundary of the artifact, so literal backticks inside the document are
+ * left alone.
+ */
+export function cleanArtifactHtml(input) {
+    let html = input.trim();
+    html = html.replace(/^```(?:html)?[ \t]*\r?\n/i, "");
+    html = html.replace(/\r?\n```[ \t]*$/i, "");
+    return html.trim();
+}
+function parseTitle(openTag) {
+    const match = /title\s*=\s*("([^"]*)"|'([^']*)')/i.exec(openTag);
+    return (match?.[2] ?? match?.[3] ?? "Untitled artifact").trim();
+}
+/**
+ * Final, non-streaming parse of a model envelope. Fail-open: it never throws,
+ * and degrades gracefully when tags are missing or malformed. This is the
+ * authoritative parser used to produce the final artifact.
+ */
+export function parseArtifactEnvelope(raw) {
+    const empty = {
+        assistantMessage: "",
+        title: "Untitled artifact",
+        html: "",
+        hasArtifact: false,
+    };
+    if (typeof raw !== "string" || raw.trim() === "")
+        return empty;
+    try {
+        const source = stripOuterFence(raw);
+        const msgMatch = /<assistant_message>([\s\S]*?)<\/assistant_message>/i.exec(source);
+        const artMatch = /<html_artifact\b([^>]*)>([\s\S]*?)<\/html_artifact>/i.exec(source);
+        if (artMatch) {
+            const title = parseTitle(`<html_artifact${artMatch[1] ?? ""}>`);
+            const html = cleanArtifactHtml(artMatch[2] ?? "");
+            const assistantMessage = (msgMatch?.[1] ?? deriveMessage(source, artMatch.index)).trim();
+            return {
+                assistantMessage,
+                title,
+                html,
+                hasArtifact: html.length > 0,
+            };
+        }
+        // No artifact tag: try to recover a bare HTML document.
+        const recovered = recoverBareHtml(source);
+        if (recovered) {
+            return {
+                assistantMessage: (msgMatch?.[1] ?? "Here is the generated artifact.").trim(),
+                title: "Untitled artifact",
+                html: recovered,
+                hasArtifact: true,
+            };
+        }
+        // Pure text — treat as the assistant message.
+        return {
+            assistantMessage: (msgMatch?.[1] ?? source).trim(),
+            title: "Untitled artifact",
+            html: "",
+            hasArtifact: false,
+        };
+    }
+    catch {
+        return { ...empty, assistantMessage: raw };
+    }
+}
+function deriveMessage(source, artifactIndex) {
+    const before = source.slice(0, artifactIndex).trim();
+    return before || "Here is the generated artifact.";
+}
+function recoverBareHtml(source) {
+    const cleaned = cleanArtifactHtml(stripOuterFence(source));
+    const doctype = cleaned.search(/<!DOCTYPE html>/i);
+    if (doctype !== -1)
+        return cleanArtifactHtml(cleaned.slice(doctype));
+    const htmlTag = cleaned.search(/<html[\s>]/i);
+    if (htmlTag !== -1)
+        return cleanArtifactHtml(cleaned.slice(htmlTag));
+    return null;
+}
+/**
+ * Incremental envelope parser for live streaming. Feed it model-text chunks;
+ * it emits message/artifact deltas as they become safe to forward (holding
+ * back a small tail so partial delimiters are never emitted as content).
+ *
+ * The server still re-parses the full output at the end with
+ * {@link parseArtifactEnvelope} for the authoritative final artifact, so this
+ * parser only needs to be good enough for smooth live updates.
+ */
+export class StreamingEnvelopeParser {
+    buf = "";
+    cursor = 0;
+    state = "before_message";
+    artifactOpened = false;
+    feed(chunk) {
+        this.buf += chunk;
+        return this.process(false);
+    }
+    flush() {
+        return this.process(true);
+    }
+    get hasOpenedArtifact() {
+        return this.artifactOpened;
+    }
+    safeEnd(isFinal) {
+        return isFinal ? this.buf.length : Math.max(this.cursor, this.buf.length - GUARD);
+    }
+    process(isFinal) {
+        const out = [];
+        // Guard against unbounded loops.
+        for (let guard = 0; guard < 10_000; guard++) {
+            if (this.state === "done")
+                break;
+            if (this.state === "before_message") {
+                const iMsg = this.buf.indexOf(MSG_OPEN, this.cursor);
+                const iArt = this.buf.indexOf(ART_OPEN, this.cursor);
+                const iBare = findBareHtmlStart(this.buf, this.cursor);
+                if (iMsg !== -1 && (iArt === -1 || iMsg < iArt)) {
+                    this.cursor = iMsg + MSG_OPEN.length;
+                    this.state = "in_message";
+                    continue;
+                }
+                if (iArt !== -1) {
+                    this.state = "before_artifact";
+                    continue;
+                }
+                if (iBare !== -1) {
+                    const prefix = cleanStreamingPrefix(this.buf.slice(this.cursor, iBare));
+                    if (prefix)
+                        out.push({ kind: "message", delta: prefix });
+                    out.push({ kind: "artifact_open", title: "Untitled artifact" });
+                    this.artifactOpened = true;
+                    this.cursor = iBare;
+                    this.state = "in_artifact";
+                    continue;
+                }
+                break; // wait for an opener
+            }
+            if (this.state === "in_message") {
+                const iClose = this.buf.indexOf(MSG_CLOSE, this.cursor);
+                if (iClose !== -1) {
+                    if (iClose > this.cursor) {
+                        out.push({ kind: "message", delta: this.buf.slice(this.cursor, iClose) });
+                    }
+                    this.cursor = iClose + MSG_CLOSE.length;
+                    this.state = "before_artifact";
+                    continue;
+                }
+                const end = this.safeEnd(isFinal);
+                if (end > this.cursor) {
+                    out.push({ kind: "message", delta: this.buf.slice(this.cursor, end) });
+                    this.cursor = end;
+                }
+                break;
+            }
+            if (this.state === "before_artifact") {
+                const iArt = this.buf.indexOf(ART_OPEN, this.cursor);
+                if (iArt === -1)
+                    break;
+                const iGt = this.buf.indexOf(">", iArt);
+                if (iGt === -1)
+                    break; // wait for full open tag
+                const title = parseTitle(this.buf.slice(iArt, iGt + 1));
+                out.push({ kind: "artifact_open", title });
+                this.artifactOpened = true;
+                this.cursor = iGt + 1;
+                this.state = "in_artifact";
+                continue;
+            }
+            if (this.state === "in_artifact") {
+                const iClose = this.buf.indexOf(ART_CLOSE, this.cursor);
+                if (iClose !== -1) {
+                    if (iClose > this.cursor) {
+                        out.push({ kind: "artifact", delta: this.buf.slice(this.cursor, iClose) });
+                    }
+                    this.cursor = iClose + ART_CLOSE.length;
+                    this.state = "done";
+                    continue;
+                }
+                const end = this.safeEnd(isFinal);
+                if (end > this.cursor) {
+                    out.push({ kind: "artifact", delta: this.buf.slice(this.cursor, end) });
+                    this.cursor = end;
+                }
+                break;
+            }
+        }
+        return out;
+    }
+}
+function findBareHtmlStart(input, from) {
+    const slice = input.slice(from);
+    const doctype = slice.search(/<!DOCTYPE html>/i);
+    const html = slice.search(/<html[\s>]/i);
+    if (doctype === -1)
+        return html === -1 ? -1 : from + html;
+    if (html === -1)
+        return from + doctype;
+    return from + Math.min(doctype, html);
+}
+function cleanStreamingPrefix(input) {
+    return input
+        .replace(/```(?:html)?[ \t]*\r?\n?/gi, "")
+        .trim();
+}
+//# sourceMappingURL=artifactEnvelope.js.map

package/dist/artifacts/artifactEnvelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifactEnvelope.js","sourceRoot":"","sources":["../../src/artifacts/artifactEnvelope.ts"],"names":[],"mappings":"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"}

package/dist/artifacts/artifactStatus.d.ts

@@ -0,0 +1,9 @@
+import type { ArtifactStatus } from "../types/artifact.js";
+export declare const ARTIFACT_STATUS: {
+    readonly IDLE: "idle";
+    readonly STREAMING: "streaming";
+    readonly COMPLETE: "complete";
+    readonly ERROR: "error";
+};
+export declare function isTerminalStatus(status: ArtifactStatus): boolean;
+//# sourceMappingURL=artifactStatus.d.ts.map

package/dist/artifacts/artifactStatus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifactStatus.d.ts","sourceRoot":"","sources":["../../src/artifacts/artifactStatus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,eAAO,MAAM,eAAe;;;;;CAKuB,CAAC;AAEpD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAEhE"}

package/dist/artifacts/artifactStatus.js

@@ -0,0 +1,10 @@
+export const ARTIFACT_STATUS = {
+    IDLE: "idle",
+    STREAMING: "streaming",
+    COMPLETE: "complete",
+    ERROR: "error",
+};
+export function isTerminalStatus(status) {
+    return status === "complete" || status === "error";
+}
+//# sourceMappingURL=artifactStatus.js.map

package/dist/artifacts/artifactStatus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifactStatus.js","sourceRoot":"","sources":["../../src/artifacts/artifactStatus.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,IAAI,EAAE,MAAM;IACZ,SAAS,EAAE,WAAW;IACtB,QAAQ,EAAE,UAAU;IACpB,KAAK,EAAE,OAAO;CACmC,CAAC;AAEpD,MAAM,UAAU,gBAAgB,CAAC,MAAsB;IACrD,OAAO,MAAM,KAAK,UAAU,IAAI,MAAM,KAAK,OAAO,CAAC;AACrD,CAAC"}

package/dist/artifacts/artifactStore.d.ts

@@ -0,0 +1,15 @@
+import type { HtmlArtifact } from "../types/artifact.js";
+/**
+ * A tiny in-memory store keyed by artifact id. The client hook uses it to
+ * reduce stream events into a stable `Record<id, HtmlArtifact>`.
+ */
+export declare class ArtifactStore {
+    private map;
+    has(id: string): boolean;
+    get(id: string): HtmlArtifact | undefined;
+    ensure(id: string, title?: string): HtmlArtifact;
+    update(id: string, patch: Partial<Omit<HtmlArtifact, "id" | "type" | "createdAt">>): HtmlArtifact;
+    toRecord(): Record<string, HtmlArtifact>;
+    clear(): void;
+}
+//# sourceMappingURL=artifactStore.d.ts.map

package/dist/artifacts/artifactStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifactStore.d.ts","sourceRoot":"","sources":["../../src/artifacts/artifactStore.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD;;;GAGG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,GAAG,CAAmC;IAE9C,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAIxB,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAIzC,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,YAAY;IAQhD,MAAM,CACJ,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,IAAI,GAAG,MAAM,GAAG,WAAW,CAAC,CAAC,GAC9D,YAAY;IAOf,QAAQ,IAAI,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC;IAIxC,KAAK,IAAI,IAAI;CAGd"}

package/dist/artifacts/artifactStore.js

@@ -0,0 +1,35 @@
+import { createHtmlArtifact, updateHtmlArtifact } from "./htmlArtifact.js";
+/**
+ * A tiny in-memory store keyed by artifact id. The client hook uses it to
+ * reduce stream events into a stable `Record<id, HtmlArtifact>`.
+ */
+export class ArtifactStore {
+    map = new Map();
+    has(id) {
+        return this.map.has(id);
+    }
+    get(id) {
+        return this.map.get(id);
+    }
+    ensure(id, title) {
+        const existing = this.map.get(id);
+        if (existing)
+            return existing;
+        const created = createHtmlArtifact({ id, title });
+        this.map.set(id, created);
+        return created;
+    }
+    update(id, patch) {
+        const current = this.ensure(id);
+        const next = updateHtmlArtifact(current, patch);
+        this.map.set(id, next);
+        return next;
+    }
+    toRecord() {
+        return Object.fromEntries(this.map);
+    }
+    clear() {
+        this.map.clear();
+    }
+}
+//# sourceMappingURL=artifactStore.js.map

package/dist/artifacts/artifactStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifactStore.js","sourceRoot":"","sources":["../../src/artifacts/artifactStore.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAG3E;;;GAGG;AACH,MAAM,OAAO,aAAa;IAChB,GAAG,GAAG,IAAI,GAAG,EAAwB,CAAC;IAE9C,GAAG,CAAC,EAAU;QACZ,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC1B,CAAC;IAED,GAAG,CAAC,EAAU;QACZ,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC1B,CAAC;IAED,MAAM,CAAC,EAAU,EAAE,KAAc;QAC/B,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAClC,IAAI,QAAQ;YAAE,OAAO,QAAQ,CAAC;QAC9B,MAAM,OAAO,GAAG,kBAAkB,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QAClD,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;QAC1B,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,MAAM,CACJ,EAAU,EACV,KAA+D;QAE/D,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAChC,MAAM,IAAI,GAAG,kBAAkB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAChD,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,QAAQ;QACN,OAAO,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACtC,CAAC;IAED,KAAK;QACH,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC;IACnB,CAAC;CACF"}

package/dist/artifacts/htmlArtifact.d.ts

@@ -0,0 +1,10 @@
+import type { HtmlArtifact, ArtifactStatus } from "../types/artifact.js";
+/** Create a fresh artifact record in the `streaming` state. */
+export declare function createHtmlArtifact(params: {
+    id: string;
+    title?: string;
+    status?: ArtifactStatus;
+}): HtmlArtifact;
+/** Immutably apply a partial update, refreshing `updatedAt`. */
+export declare function updateHtmlArtifact(artifact: HtmlArtifact, patch: Partial<Omit<HtmlArtifact, "id" | "type" | "createdAt">>): HtmlArtifact;
+//# sourceMappingURL=htmlArtifact.d.ts.map