@jini-ai/chat 0.1.0

package/dist/core/util/parser.d.ts

@@ -0,0 +1,42 @@
+export type ArtifactEvent = {
+    type: 'text';
+    delta: string;
+} | {
+    type: 'artifact:start';
+    identifier: string;
+    artifactType: string;
+    title: string;
+} | {
+    type: 'artifact:chunk';
+    identifier: string;
+    delta: string;
+} | {
+    type: 'artifact:end';
+    identifier: string;
+    fullContent: string;
+};
+/**
+ * Create a fresh streaming artifact parser. Call `feed(delta)` for each
+ * chunk as it arrives (iterate its generator to drain queued events), and
+ * `flush()` once at end-of-stream to emit whatever is still buffered.
+ *
+ * @complexity Each `feed` call is O(buffer.length) — `findOpenTag` rescans
+ *   the buffered tail (bounded by how far behind the caller is at draining
+ *   the generator), which is the standard tradeoff for streaming tag
+ *   detection over an ever-growing buffer.
+ */
+export declare function createArtifactParser(): {
+    feed: (delta: string) => Generator<ArtifactEvent>;
+    flush: () => Generator<ArtifactEvent>;
+};
+/**
+ * Convenience wrapper over {@link createArtifactParser} for the common
+ * non-streaming case: parse a complete string in one call. Matches the
+ * `parseArtifacts()` name from the target API — feeds the whole content
+ * through a fresh parser instance and flushes it, collecting every event.
+ *
+ * @param content - A complete (already fully-arrived) message body.
+ * @complexity O(n) in `content.length` (one `feed` + one `flush` over the whole string).
+ */
+export declare function parseArtifacts(content: string): ArtifactEvent[];
+//# sourceMappingURL=parser.d.ts.map

package/dist/core/util/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../../src/core/util/parser.ts"],"names":[],"mappings":"AAYA,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACnF;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC7D;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC;AA8HtE;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,IAAI;IACtC,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,SAAS,CAAC,aAAa,CAAC,CAAC;IAClD,KAAK,EAAE,MAAM,SAAS,CAAC,aAAa,CAAC,CAAC;CACvC,CA0FA;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,EAAE,CAG/D"}

package/dist/core/util/parser.js

@@ -0,0 +1,238 @@
+/**
+ * @module parser
+ *
+ * Streaming parser for `<artifact identifier="..." type="..." title="...">
+ * ...</artifact>` tags. Handles one artifact at a time (no nesting). Feed
+ * deltas in, iterate events — every event type has a stable meaning so
+ * consumers don't need to rewrite their reducer if this parser is later
+ * swapped for a fuller one.
+ */
+import { computeSkipRanges, FENCE_OPEN_RE, isRealArtifactOpenAt, rangeContains } from './markdown-context.js';
+import { parseQuotedAttrs } from './markup-attributes.js';
+const OPEN_PREFIX = '<artifact';
+const CLOSE_TAG = '</artifact>';
+// Scan the buffer for `<artifact …>` while skipping any positions that a
+// Markdown renderer would render as a fenced code block or inline code span
+// — see markdown-context.ts for the shared classification used by both this
+// streaming parser and the post-stream `<artifact>` stripper.
+//
+// Streaming caveats handled here on top of the shared ranges:
+//   * Open fence with no close yet → hold back from its opening line.
+//   * Unterminated tail line that could still resolve into a fence delimiter
+//     (e.g. "```", "```ht") → hold back from the line start.
+//   * Unmatched opening backtick after the last \n → hold back from it; a
+//     future chunk may turn it into an inline code span.
+function findOpenTag(buffer) {
+    const len = buffer.length;
+    const { ranges, unclosedFenceStart } = computeSkipRanges(buffer);
+    // Pass 1: scan for the earliest *complete* real `<artifact …>` open outside
+    // any skip range, before any hold-back decision — otherwise a stray
+    // backtick or fence-opener prefix on a tail line would suppress an
+    // already self-contained artifact earlier in the buffer.
+    let earliestPartialOpen = -1;
+    let from = 0;
+    while (from < len) {
+        const idx = buffer.indexOf(OPEN_PREFIX, from);
+        if (idx === -1)
+            break;
+        if (rangeContains(ranges, idx)) {
+            from = idx + OPEN_PREFIX.length;
+            continue;
+        }
+        if (unclosedFenceStart !== null && idx >= unclosedFenceStart) {
+            // Anything past an unclosed fence opener is inside a code block that
+            // will close in a later chunk; treat as skip range, not a real tag.
+            break;
+        }
+        const after = idx + OPEN_PREFIX.length;
+        const next = buffer.charAt(after);
+        if (next === '') {
+            // `<artifact` at very end of buffer — could become real with the next
+            // chunk. Remember the earliest one and keep looking for a complete tag.
+            if (earliestPartialOpen === -1)
+                earliestPartialOpen = idx;
+            break;
+        }
+        if (!isRealArtifactOpenAt(buffer, idx)) {
+            from = after; // e.g. "<artifactual" — not a real open, keep scanning
+            continue;
+        }
+        let j = after;
+        let quote = null;
+        while (j < len) {
+            const c = buffer.charAt(j);
+            if (quote !== null) {
+                if (c === quote)
+                    quote = null;
+            }
+            else if (c === '"' || c === "'") {
+                quote = c;
+            }
+            else if (c === '>') {
+                return { kind: 'complete', start: idx, end: j + 1, attrs: buffer.slice(after, j) };
+            }
+            j++;
+        }
+        // Ran out of buffer before the closing `>` arrived — an open tag mid-stream.
+        if (earliestPartialOpen === -1)
+            earliestPartialOpen = idx;
+        break;
+    }
+    // Pass 2: no complete open found. Decide whether to hold back, and if so,
+    // from which position. Earliest hold-back wins so the text-flush boundary
+    // never crosses something that might still resolve into a tag/fence/span.
+    let holdback = -1;
+    const note = (pos) => {
+        if (pos !== null && pos !== -1 && (holdback === -1 || pos < holdback))
+            holdback = pos;
+    };
+    note(earliestPartialOpen);
+    note(unclosedFenceStart);
+    const lastNl = buffer.lastIndexOf('\n');
+    if (lastNl < len - 1) {
+        const tailLineStart = lastNl + 1;
+        const tail = buffer.slice(tailLineStart);
+        if (FENCE_OPEN_RE.test(tail) || /^`{1,2}$/.test(tail)) {
+            note(tailLineStart);
+        }
+    }
+    let firstUnmatched = -1;
+    let parity = 0;
+    for (let k = lastNl + 1; k < len; k++) {
+        if (buffer.charAt(k) !== '`')
+            continue;
+        if (rangeContains(ranges, k))
+            continue;
+        if (parity === 0) {
+            firstUnmatched = k;
+            parity = 1;
+        }
+        else {
+            firstUnmatched = -1;
+            parity = 0;
+        }
+    }
+    note(firstUnmatched);
+    // Strict prefix at the tail (e.g. "<art") — hold back.
+    const tailLt = buffer.lastIndexOf('<');
+    if (tailLt !== -1 && !rangeContains(ranges, tailLt)) {
+        const slice = buffer.slice(tailLt);
+        if (OPEN_PREFIX.startsWith(slice) && slice.length < OPEN_PREFIX.length) {
+            note(tailLt);
+        }
+    }
+    if (holdback !== -1)
+        return { kind: 'partial', start: holdback };
+    return { kind: 'none' };
+}
+/**
+ * Create a fresh streaming artifact parser. Call `feed(delta)` for each
+ * chunk as it arrives (iterate its generator to drain queued events), and
+ * `flush()` once at end-of-stream to emit whatever is still buffered.
+ *
+ * @complexity Each `feed` call is O(buffer.length) — `findOpenTag` rescans
+ *   the buffered tail (bounded by how far behind the caller is at draining
+ *   the generator), which is the standard tradeoff for streaming tag
+ *   detection over an ever-growing buffer.
+ */
+export function createArtifactParser() {
+    const state = {
+        inside: false,
+        buffer: '',
+        identifier: '',
+        artifactType: '',
+        title: '',
+        content: '',
+    };
+    function* feed(delta) {
+        state.buffer += delta;
+        while (state.buffer.length > 0) {
+            if (!state.inside) {
+                const open = findOpenTag(state.buffer);
+                if (open.kind === 'none') {
+                    yield { type: 'text', delta: state.buffer };
+                    state.buffer = '';
+                    return;
+                }
+                if (open.kind === 'partial') {
+                    if (open.start > 0) {
+                        yield { type: 'text', delta: state.buffer.slice(0, open.start) };
+                        state.buffer = state.buffer.slice(open.start);
+                    }
+                    return;
+                }
+                if (open.start > 0) {
+                    yield { type: 'text', delta: state.buffer.slice(0, open.start) };
+                }
+                const attrs = parseQuotedAttrs(open.attrs);
+                state.inside = true;
+                state.identifier = attrs['identifier'] ?? '';
+                state.artifactType = attrs['type'] ?? '';
+                state.title = attrs['title'] ?? '';
+                state.content = '';
+                state.buffer = state.buffer.slice(open.end);
+                yield {
+                    type: 'artifact:start',
+                    identifier: state.identifier,
+                    artifactType: state.artifactType,
+                    title: state.title,
+                };
+                continue;
+            }
+            const closeIdx = state.buffer.indexOf(CLOSE_TAG);
+            if (closeIdx === -1) {
+                // Hold back enough bytes to detect a partial close tag at the tail.
+                const flushUpTo = state.buffer.length - (CLOSE_TAG.length - 1);
+                if (flushUpTo > 0) {
+                    const chunk = state.buffer.slice(0, flushUpTo);
+                    state.content += chunk;
+                    state.buffer = state.buffer.slice(flushUpTo);
+                    yield { type: 'artifact:chunk', identifier: state.identifier, delta: chunk };
+                }
+                return;
+            }
+            const finalChunk = state.buffer.slice(0, closeIdx);
+            if (finalChunk.length > 0) {
+                state.content += finalChunk;
+                yield { type: 'artifact:chunk', identifier: state.identifier, delta: finalChunk };
+            }
+            yield { type: 'artifact:end', identifier: state.identifier, fullContent: state.content };
+            state.buffer = state.buffer.slice(closeIdx + CLOSE_TAG.length);
+            state.inside = false;
+            state.identifier = '';
+            state.artifactType = '';
+            state.title = '';
+            state.content = '';
+        }
+    }
+    function* flush() {
+        if (state.inside) {
+            if (state.buffer.length > 0) {
+                state.content += state.buffer;
+                yield { type: 'artifact:chunk', identifier: state.identifier, delta: state.buffer };
+                state.buffer = '';
+            }
+            yield { type: 'artifact:end', identifier: state.identifier, fullContent: state.content };
+        }
+        else if (state.buffer.length > 0) {
+            yield { type: 'text', delta: state.buffer };
+        }
+        state.buffer = '';
+        state.inside = false;
+    }
+    return { feed, flush };
+}
+/**
+ * Convenience wrapper over {@link createArtifactParser} for the common
+ * non-streaming case: parse a complete string in one call. Matches the
+ * `parseArtifacts()` name from the target API — feeds the whole content
+ * through a fresh parser instance and flushes it, collecting every event.
+ *
+ * @param content - A complete (already fully-arrived) message body.
+ * @complexity O(n) in `content.length` (one `feed` + one `flush` over the whole string).
+ */
+export function parseArtifacts(content) {
+    const parser = createArtifactParser();
+    return [...parser.feed(content), ...parser.flush()];
+}
+//# sourceMappingURL=parser.js.map

package/dist/core/util/parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.js","sourceRoot":"","sources":["../../../src/core/util/parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC9G,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAQ1D,MAAM,WAAW,GAAG,WAAW,CAAC;AAChC,MAAM,SAAS,GAAG,aAAa,CAAC;AAahC,yEAAyE;AACzE,4EAA4E;AAC5E,4EAA4E;AAC5E,8DAA8D;AAC9D,EAAE;AACF,8DAA8D;AAC9D,sEAAsE;AACtE,6EAA6E;AAC7E,6DAA6D;AAC7D,0EAA0E;AAC1E,yDAAyD;AACzD,SAAS,WAAW,CAAC,MAAc;IACjC,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC;IAC1B,MAAM,EAAE,MAAM,EAAE,kBAAkB,EAAE,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAEjE,4EAA4E;IAC5E,oEAAoE;IACpE,mEAAmE;IACnE,yDAAyD;IACzD,IAAI,mBAAmB,GAAG,CAAC,CAAC,CAAC;IAC7B,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,OAAO,IAAI,GAAG,GAAG,EAAE,CAAC;QAClB,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;QAC9C,IAAI,GAAG,KAAK,CAAC,CAAC;YAAE,MAAM;QACtB,IAAI,aAAa,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;YAC/B,IAAI,GAAG,GAAG,GAAG,WAAW,CAAC,MAAM,CAAC;YAChC,SAAS;QACX,CAAC;QACD,IAAI,kBAAkB,KAAK,IAAI,IAAI,GAAG,IAAI,kBAAkB,EAAE,CAAC;YAC7D,qEAAqE;YACrE,oEAAoE;YACpE,MAAM;QACR,CAAC;QACD,MAAM,KAAK,GAAG,GAAG,GAAG,WAAW,CAAC,MAAM,CAAC;QACvC,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAClC,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;YAChB,sEAAsE;YACtE,wEAAwE;YACxE,IAAI,mBAAmB,KAAK,CAAC,CAAC;gBAAE,mBAAmB,GAAG,GAAG,CAAC;YAC1D,MAAM;QACR,CAAC;QACD,IAAI,CAAC,oBAAoB,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;YACvC,IAAI,GAAG,KAAK,CAAC,CAAC,uDAAuD;YACrE,SAAS;QACX,CAAC;QACD,IAAI,CAAC,GAAG,KAAK,CAAC;QACd,IAAI,KAAK,GAAqB,IAAI,CAAC;QACnC,OAAO,CAAC,GAAG,GAAG,EAAE,CAAC;YACf,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;YAC3B,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBACnB,IAAI,CAAC,KAAK,KAAK;oBAAE,KAAK,GAAG,IAAI,CAAC;YAChC,CAAC;iBAAM,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;gBAClC,KAAK,GAAG,CAAC,CAAC;YACZ,CAAC;iBAAM,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;gBACrB,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC;YACrF,CAAC;YACD,CAAC,EAAE,CAAC;QACN,CAAC;QACD,6EAA6E;QAC7E,IAAI,mBAAmB,KAAK,CAAC,CAAC;YAAE,mBAAmB,GAAG,GAAG,CAAC;QAC1D,MAAM;IACR,CAAC;IAED,0EAA0E;IAC1E,0EAA0E;IAC1E,0EAA0E;IAC1E,IAAI,QAAQ,GAAG,CAAC,CAAC,CAAC;IAClB,MAAM,IAAI,GAAG,CAAC,GAAkB,EAAE,EAAE;QAClC,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,QAAQ,KAAK,CAAC,CAAC,IAAI,GAAG,GAAG,QAAQ,CAAC;YAAE,QAAQ,GAAG,GAAG,CAAC;IACxF,CAAC,CAAC;IACF,IAAI,CAAC,mBAAmB,CAAC,CAAC;IAC1B,IAAI,CAAC,kBAAkB,CAAC,CAAC;IAEzB,MAAM,MAAM,GAAG,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;IACxC,IAAI,MAAM,GAAG,GAAG,GAAG,CAAC,EAAE,CAAC;QACrB,MAAM,aAAa,GAAG,MAAM,GAAG,CAAC,CAAC;QACjC,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;QACzC,IAAI,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACtD,IAAI,CAAC,aAAa,CAAC,CAAC;QACtB,CAAC;IACH,CAAC;IAED,IAAI,cAAc,GAAG,CAAC,CAAC,CAAC;IACxB,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,KAAK,IAAI,CAAC,GAAG,MAAM,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,IAAI,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,GAAG;YAAE,SAAS;QACvC,IAAI,aAAa,CAAC,MAAM,EAAE,CAAC,CAAC;YAAE,SAAS;QACvC,IAAI,MAAM,KAAK,CAAC,EAAE,CAAC;YACjB,cAAc,GAAG,CAAC,CAAC;YACnB,MAAM,GAAG,CAAC,CAAC;QACb,CAAC;aAAM,CAAC;YACN,cAAc,GAAG,CAAC,CAAC,CAAC;YACpB,MAAM,GAAG,CAAC,CAAC;QACb,CAAC;IACH,CAAC;IACD,IAAI,CAAC,cAAc,CAAC,CAAC;IAErB,uDAAuD;IACvD,MAAM,MAAM,GAAG,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACvC,IAAI,MAAM,KAAK,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;QACpD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QACnC,IAAI,WAAW,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,WAAW,CAAC,MAAM,EAAE,CAAC;YACvE,IAAI,CAAC,MAAM,CAAC,CAAC;QACf,CAAC;IACH,CAAC;IAED,IAAI,QAAQ,KAAK,CAAC,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;IACjE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AAC1B,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,oBAAoB;IAIlC,MAAM,KAAK,GAAgB;QACzB,MAAM,EAAE,KAAK;QACb,MAAM,EAAE,EAAE;QACV,UAAU,EAAE,EAAE;QACd,YAAY,EAAE,EAAE;QAChB,KAAK,EAAE,EAAE;QACT,OAAO,EAAE,EAAE;KACZ,CAAC;IAEF,QAAQ,CAAC,CAAC,IAAI,CAAC,KAAa;QAC1B,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC;QAEtB,OAAO,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC/B,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;gBAClB,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;gBACvC,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;oBACzB,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC;oBAC5C,KAAK,CAAC,MAAM,GAAG,EAAE,CAAC;oBAClB,OAAO;gBACT,CAAC;gBACD,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;oBAC5B,IAAI,IAAI,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC;wBACnB,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;wBACjE,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;oBAChD,CAAC;oBACD,OAAO;gBACT,CAAC;gBACD,IAAI,IAAI,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC;oBACnB,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;gBACnE,CAAC;gBACD,MAAM,KAAK,GAAG,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;gBAC3C,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC;gBACpB,KAAK,CAAC,UAAU,GAAG,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC;gBAC7C,KAAK,CAAC,YAAY,GAAG,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;gBACzC,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;gBACnC,KAAK,CAAC,OAAO,GAAG,EAAE,CAAC;gBACnB,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBAC5C,MAAM;oBACJ,IAAI,EAAE,gBAAgB;oBACtB,UAAU,EAAE,KAAK,CAAC,UAAU;oBAC5B,YAAY,EAAE,KAAK,CAAC,YAAY;oBAChC,KAAK,EAAE,KAAK,CAAC,KAAK;iBACnB,CAAC;gBACF,SAAS;YACX,CAAC;YAED,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;YACjD,IAAI,QAAQ,KAAK,CAAC,CAAC,EAAE,CAAC;gBACpB,oEAAoE;gBACpE,MAAM,SAAS,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;gBAC/D,IAAI,SAAS,GAAG,CAAC,EAAE,CAAC;oBAClB,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;oBAC/C,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC;oBACvB,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;oBAC7C,MAAM,EAAE,IAAI,EAAE,gBAAgB,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;gBAC/E,CAAC;gBACD,OAAO;YACT,CAAC;YACD,MAAM,UAAU,GAAG,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;YACnD,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC1B,KAAK,CAAC,OAAO,IAAI,UAAU,CAAC;gBAC5B,MAAM,EAAE,IAAI,EAAE,gBAAgB,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;YACpF,CAAC;YACD,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,WAAW,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC;YACzF,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;YAC/D,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC;YACrB,KAAK,CAAC,UAAU,GAAG,EAAE,CAAC;YACtB,KAAK,CAAC,YAAY,GAAG,EAAE,CAAC;YACxB,KAAK,CAAC,KAAK,GAAG,EAAE,CAAC;YACjB,KAAK,CAAC,OAAO,GAAG,EAAE,CAAC;QACrB,CAAC;IACH,CAAC;IAED,QAAQ,CAAC,CAAC,KAAK;QACb,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;YACjB,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC5B,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,MAAM,CAAC;gBAC9B,MAAM,EAAE,IAAI,EAAE,gBAAgB,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC;gBACpF,KAAK,CAAC,MAAM,GAAG,EAAE,CAAC;YACpB,CAAC;YACD,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,WAAW,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC;QAC3F,CAAC;aAAM,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACnC,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC;QAC9C,CAAC;QACD,KAAK,CAAC,MAAM,GAAG,EAAE,CAAC;QAClB,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC;IACvB,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AACzB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe;IAC5C,MAAM,MAAM,GAAG,oBAAoB,EAAE,CAAC;IACtC,OAAO,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,GAAG,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;AACtD,CAAC"}

package/dist/core/util/pointer.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @module pointer
+ *
+ * Detects an assistant reply that is *only* a pointer to an existing file
+ * ("see design.html") rather than new content, so a host can resolve it to
+ * that file instead of treating the short reply as a fresh artifact.
+ */
+interface HtmlPointerArtifactTargetInput {
+    content: string;
+    candidateFileName: string;
+    projectFiles: Array<{
+        name: string;
+        path?: string;
+    }>;
+}
+/**
+ * Resolve a short "see foo.html"-style reply to the referenced file name, if
+ * `content` is (after stripping tags) nothing but such a pointer and the
+ * target unambiguously resolves against `projectFiles`.
+ *
+ * @returns The resolved target file path/name, or `null` when `content`
+ *   isn't a bare pointer, the target is unsafe, or it doesn't resolve to
+ *   exactly one known file.
+ * @complexity O(n + m) in `content.length` plus `projectFiles.length`.
+ */
+export declare function resolveHtmlPointerArtifactTarget(input: HtmlPointerArtifactTargetInput): string | null;
+export {};
+//# sourceMappingURL=pointer.d.ts.map

package/dist/core/util/pointer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pointer.d.ts","sourceRoot":"","sources":["../../../src/core/util/pointer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,UAAU,8BAA8B;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACtD;AAOD;;;;;;;;;GASG;AACH,wBAAgB,gCAAgC,CAAC,KAAK,EAAE,8BAA8B,GAAG,MAAM,GAAG,IAAI,CA4BrG"}

package/dist/core/util/pointer.js

@@ -0,0 +1,75 @@
+const MAX_POINTER_TEXT_BYTES = 100;
+const POINTER_TARGET_RE = /^(?:见|see)(?:\s*[:：]\s*|\s+)[`"'“”‘’]?(.+?\.html?)[`"'“”‘’]?[.。]?$/iu;
+const SCRIPT_OR_STYLE_RE = /<(script|style)\b[^>]*>[\s\S]*?<\/\1>/gi;
+const HTML_TAG_RE = /<[^>]+>/g;
+/**
+ * Resolve a short "see foo.html"-style reply to the referenced file name, if
+ * `content` is (after stripping tags) nothing but such a pointer and the
+ * target unambiguously resolves against `projectFiles`.
+ *
+ * @returns The resolved target file path/name, or `null` when `content`
+ *   isn't a bare pointer, the target is unsafe, or it doesn't resolve to
+ *   exactly one known file.
+ * @complexity O(n + m) in `content.length` plus `projectFiles.length`.
+ */
+export function resolveHtmlPointerArtifactTarget(input) {
+    const pointerText = visiblePointerText(input.content);
+    if (!pointerText || utf8ByteLength(pointerText) > MAX_POINTER_TEXT_BYTES) {
+        return null;
+    }
+    const match = POINTER_TARGET_RE.exec(pointerText);
+    if (!match)
+        return null;
+    // The target group is a mandatory (non-optional) part of the pattern, not
+    // inside an alternation, so it's always defined when `match` is non-null;
+    // the assertion just satisfies `noUncheckedIndexedAccess`.
+    const target = normalizeTarget(match[1]);
+    if (!target || target === input.candidateFileName || !isSafeHtmlTarget(target)) {
+        return null;
+    }
+    const projectFileNames = input.projectFiles.map((file) => file.path || file.name).filter((name) => name.toLowerCase().endsWith('.html') || name.toLowerCase().endsWith('.htm'));
+    if (projectFileNames.includes(target))
+        return target;
+    const basenameMatches = projectFileNames.filter((name) => basename(name) === target);
+    const [basenameMatch] = basenameMatches;
+    if (basenameMatches.length === 1 && basenameMatch && basenameMatch !== input.candidateFileName) {
+        return basenameMatch;
+    }
+    return null;
+}
+function visiblePointerText(content) {
+    const stripped = content
+        .replace(/^/, '')
+        .replace(SCRIPT_OR_STYLE_RE, ' ')
+        .replace(HTML_TAG_RE, ' ');
+    return decodeBasicHtmlEntities(stripped).replace(/\s+/g, ' ').trim();
+}
+function normalizeTarget(value) {
+    return value.trim().replace(/^[`"'“”‘’]+|[`"'“”‘’]+$/g, '');
+}
+function isSafeHtmlTarget(value) {
+    if (!/\.(?:html?|HTML?)$/.test(value))
+        return false;
+    if (/^[a-z][a-z0-9+.-]*:/i.test(value))
+        return false;
+    if (value.startsWith('/') || value.includes('\\') || value.includes('\0'))
+        return false;
+    return value.split('/').every((segment) => segment && segment !== '.' && segment !== '..');
+}
+function basename(value) {
+    const i = value.lastIndexOf('/');
+    return i >= 0 ? value.slice(i + 1) : value;
+}
+function utf8ByteLength(value) {
+    return new TextEncoder().encode(value).length;
+}
+function decodeBasicHtmlEntities(value) {
+    return value
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&apos;/g, "'")
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&amp;/g, '&');
+}
+//# sourceMappingURL=pointer.js.map

package/dist/core/util/pointer.js.map

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

package/dist/core/util/recover.d.ts

@@ -0,0 +1,40 @@
+type RecoverHtmlArtifactInput = {
+    artifactHtml: string;
+    identifier?: string | undefined;
+    sourceText?: string | undefined;
+};
+/**
+ * When an `<artifact>` body fails {@link validateHtmlArtifact} (looks like
+ * prose, not a document) but a complete `<html>…</html>` document
+ * immediately precedes the artifact tag in the same turn's `sourceText`,
+ * recover that preceding document as the real artifact content.
+ *
+ * @returns The recovered HTML, or `null` when the artifact body already
+ *   validates, or no adjacent recoverable document is found.
+ * @complexity O(n) in `sourceText.length`.
+ */
+export declare function recoverHtmlArtifactFromPrecedingDocument({ artifactHtml, identifier, sourceText }: RecoverHtmlArtifactInput): string | null;
+/**
+ * Resolve the HTML that should actually be persisted for an artifact. When
+ * a model emits a prose-only `<artifact>` next to a complete `<html>`
+ * document in the same turn, recover the real document from the preceding
+ * text; otherwise keep the artifact body as-is.
+ *
+ * A same-turn duplicate-content lookup and the actual persist path MUST
+ * resolve this identically — feeding a dedup check the raw prose summary
+ * while persisting the recovered document would make an exact-match dedup
+ * miss the same-turn write, causing the recovered document to persist twice.
+ */
+export declare function resolvePersistedArtifactHtml(input: RecoverHtmlArtifactInput): string;
+/** Recover a complete `<html>…</html>` document that IS the entire (trimmed) `sourceText`, or `null` otherwise. */
+export declare function recoverStandaloneHtmlDocument(sourceText: string | null | undefined): string | null;
+/**
+ * Recover a complete HTML document from a *single* ```html fenced block in
+ * `sourceText`. Returns `null` when there is no such fence, more than one
+ * candidate, or the recovered text doesn't validate as a document — multiple
+ * candidates are ambiguous about which one is "the" artifact, so none is
+ * chosen automatically.
+ */
+export declare function recoverHtmlDocumentFromMarkdownFence(sourceText: string | null | undefined): string | null;
+export {};
+//# sourceMappingURL=recover.d.ts.map

package/dist/core/util/recover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recover.d.ts","sourceRoot":"","sources":["../../../src/core/util/recover.ts"],"names":[],"mappings":"AASA,KAAK,wBAAwB,GAAG;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC,CAAC;AA8BF;;;;;;;;;GASG;AACH,wBAAgB,wCAAwC,CAAC,EAAE,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,EAAE,wBAAwB,GAAG,MAAM,GAAG,IAAI,CA4B1I;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,wBAAwB,GAAG,MAAM,CAEpF;AAED,mHAAmH;AACnH,wBAAgB,6BAA6B,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAIlG;AAED;;;;;;GAMG;AACH,wBAAgB,oCAAoC,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAczG"}

package/dist/core/util/recover.js

@@ -0,0 +1,117 @@
+/**
+ * @module recover
+ *
+ * Recovery helpers for HTML artifacts a model emitted outside the
+ * `<artifact>` protocol — as prose next to a complete `<html>` document, as
+ * a standalone document reply, or as a single fenced ```html block.
+ */
+import { validateHtmlArtifact } from './validate.js';
+const HTML_OPEN_RE = /<html\b/gi;
+const HTML_CLOSE_RE = /<\/html\s*>/gi;
+const ADJACENT_DOCTYPE_RE = /<!doctype\s+html\b[^>]*>\s*$/i;
+const HTML_FENCE_RE = /```(?:html|HTML)\s*\n([\s\S]*?)\n```/g;
+function findLastArtifactOpen(sourceText, identifier) {
+    if (!identifier)
+        return sourceText.lastIndexOf('<artifact');
+    const escapedIdentifier = identifier.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const taggedOpenRe = new RegExp(`<artifact\\b(?=[^>]*\\bidentifier\\s*=\\s*(?:"${escapedIdentifier}"|'${escapedIdentifier}'))[^>]*>`, 'gi');
+    let last = -1;
+    let match;
+    while ((match = taggedOpenRe.exec(sourceText)) !== null) {
+        last = match.index;
+    }
+    return last !== -1 ? last : sourceText.lastIndexOf('<artifact');
+}
+function lastIndexOfRegex(re, text) {
+    re.lastIndex = 0;
+    let last = -1;
+    let match;
+    while ((match = re.exec(text)) !== null) {
+        last = match.index;
+    }
+    return last;
+}
+/**
+ * When an `<artifact>` body fails {@link validateHtmlArtifact} (looks like
+ * prose, not a document) but a complete `<html>…</html>` document
+ * immediately precedes the artifact tag in the same turn's `sourceText`,
+ * recover that preceding document as the real artifact content.
+ *
+ * @returns The recovered HTML, or `null` when the artifact body already
+ *   validates, or no adjacent recoverable document is found.
+ * @complexity O(n) in `sourceText.length`.
+ */
+export function recoverHtmlArtifactFromPrecedingDocument({ artifactHtml, identifier, sourceText }) {
+    if (!sourceText)
+        return null;
+    if (validateHtmlArtifact(artifactHtml).ok)
+        return null;
+    const artifactOpen = findLastArtifactOpen(sourceText, identifier);
+    if (artifactOpen === -1)
+        return null;
+    const beforeArtifact = sourceText.slice(0, artifactOpen);
+    if (!/<\/html\s*>\s*$/i.test(beforeArtifact))
+        return null;
+    const htmlOpenStart = lastIndexOfRegex(HTML_OPEN_RE, beforeArtifact);
+    if (htmlOpenStart === -1)
+        return null;
+    // The guard above (`beforeArtifact` ends with `</html\s*>` plus only
+    // trailing whitespace) already pins HTML_CLOSE_RE's last match to that exact
+    // trailing tag: `htmlClose` can't be -1, can't fall before `htmlOpenStart`
+    // (no room for another `<html` open after it), and the slice from `htmlClose`
+    // always re-matches `/^<\/html\s*>/i` — the assertion just satisfies
+    // `String.prototype.match`'s generically-nullable return type.
+    const htmlClose = lastIndexOfRegex(HTML_CLOSE_RE, beforeArtifact);
+    const closeMatch = beforeArtifact.slice(htmlClose).match(/^<\/html\s*>/i);
+    const beforeHtmlOpen = beforeArtifact.slice(0, htmlOpenStart);
+    const adjacentDoctype = beforeHtmlOpen.match(ADJACENT_DOCTYPE_RE);
+    const htmlStart = adjacentDoctype ? htmlOpenStart - adjacentDoctype[0].length : htmlOpenStart;
+    const candidate = beforeArtifact.slice(htmlStart, htmlClose + closeMatch[0].length).trim();
+    return validateHtmlArtifact(candidate).ok ? candidate : null;
+}
+/**
+ * Resolve the HTML that should actually be persisted for an artifact. When
+ * a model emits a prose-only `<artifact>` next to a complete `<html>`
+ * document in the same turn, recover the real document from the preceding
+ * text; otherwise keep the artifact body as-is.
+ *
+ * A same-turn duplicate-content lookup and the actual persist path MUST
+ * resolve this identically — feeding a dedup check the raw prose summary
+ * while persisting the recovered document would make an exact-match dedup
+ * miss the same-turn write, causing the recovered document to persist twice.
+ */
+export function resolvePersistedArtifactHtml(input) {
+    return recoverHtmlArtifactFromPrecedingDocument(input) ?? input.artifactHtml;
+}
+/** Recover a complete `<html>…</html>` document that IS the entire (trimmed) `sourceText`, or `null` otherwise. */
+export function recoverStandaloneHtmlDocument(sourceText) {
+    const candidate = String(sourceText || '').replace(/^/, '').trim();
+    if (!/<\/html\s*>$/i.test(candidate))
+        return null;
+    return validateHtmlArtifact(candidate).ok ? candidate : null;
+}
+/**
+ * Recover a complete HTML document from a *single* ```html fenced block in
+ * `sourceText`. Returns `null` when there is no such fence, more than one
+ * candidate, or the recovered text doesn't validate as a document — multiple
+ * candidates are ambiguous about which one is "the" artifact, so none is
+ * chosen automatically.
+ */
+export function recoverHtmlDocumentFromMarkdownFence(sourceText) {
+    const text = String(sourceText || '');
+    HTML_FENCE_RE.lastIndex = 0;
+    let recovered = null;
+    let count = 0;
+    let match;
+    while ((match = HTML_FENCE_RE.exec(text)) !== null) {
+        const candidate = (match[1] || '').replace(/^/, '').trim();
+        if (!/<\/html\s*>$/i.test(candidate))
+            continue;
+        if (!validateHtmlArtifact(candidate).ok)
+            continue;
+        recovered = candidate;
+        count += 1;
+    }
+    return count === 1 ? recovered : null;
+}
+//# sourceMappingURL=recover.js.map

package/dist/core/util/recover.js.map

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