@derive-to/artifacts 0.0.0-stage → 0.6.1

package/dist/protocol/source-edits.js

@@ -0,0 +1,126 @@
+export class EditError extends Error {
+}
+// Count non-overlapping matches and retain only the requested position. A repeated
+// word in a large artifact must not allocate one array entry per occurrence.
+const occurrences = (haystack, needle, selected) => {
+    const chosen = selected ?? 1;
+    let count = 0;
+    let at = -1;
+    for (let i = haystack.indexOf(needle); i !== -1; i = haystack.indexOf(needle, i + needle.length)) {
+        count++;
+        if (count === chosen)
+            at = i;
+    }
+    return { count, at };
+};
+// A line, whitespace-tolerant: trimmed and internal runs collapsed to one space —
+// tabs-vs-spaces or a trailing-whitespace difference (the single most common miss)
+// normalizes away, while real content differences still don't match.
+const normalizeLine = (s) => s.trim().replace(/\s+/g, " ");
+// Tier 1 is a sliding window: O(haystack lines × needle lines) comparisons. Cheap for
+// a typical small edit on any size document (needle is short), or a large needle on a
+// typical small document — the risk is both being large at once. Cap the product
+// rather than either dimension alone, so neither shape is penalized on its own.
+// 500K comparisons is ~12ms by extrapolation from a measured 36M-comparison/~900ms case.
+const TIER1_MAX_COMPARISONS = 500_000;
+// Same cap search results already apply per line (see LINE_CLIP in
+// apps/api/src/lib/search.ts) — this file can't import that (packages/core has
+// zero external deps), so it's a local constant, not a shared one.
+const MISS_HINT_LINE_CLIP = 400;
+const isWordChar = (c) => !!c && /[A-Za-z0-9_]/.test(c);
+// Whole-word substring search without a regex (avoids escaping arbitrary user text):
+// `anchor` must not be glued to another word character on either side.
+const includesWord = (line, word) => {
+    for (let idx = line.indexOf(word); idx !== -1; idx = line.indexOf(word, idx + 1))
+        if (!isWordChar(line[idx - 1]) && !isWordChar(line[idx + word.length]))
+            return true;
+    return false;
+};
+// Diagnose a "not found" old_str: WHY didn't it match, not just that it didn't.
+// Two tiers, cheapest and most common first — never used to auto-apply anything,
+// purely a message so the agent fixes it in one round instead of a blind retry.
+const nearestMissHint = (haystack, needle) => {
+    const hLines = haystack.split("\n");
+    const nLines = needle.split("\n");
+    const normN = nLines.map(normalizeLine);
+    // Tier 1: the exact same lines exist, just with different whitespace — a sliding
+    // window match on normalized lines, reported at its real (unnormalized) line no.
+    if (hLines.length * normN.length <= TIER1_MAX_COMPARISONS) {
+        for (let i = 0; i + normN.length <= hLines.length; i++) {
+            let allMatch = true;
+            for (let j = 0; j < normN.length; j++) {
+                if (normalizeLine(hLines[i + j]) !== normN[j]) {
+                    allMatch = false;
+                    break;
+                }
+            }
+            if (allMatch)
+                return (` The text is there at line ${i + 1}, but whitespace differs (tabs vs spaces, or ` +
+                    `trailing spaces) — read format:"html" (or the doc's own format) and copy old_str exactly.`);
+        }
+    }
+    // Tier 2: the FIRST WORD of old_str's first non-empty line exists somewhere, but
+    // what follows doesn't match — the doc changed since this was written. Show what's
+    // there now. Deliberately just one word, not a phrase: for a single-line old_str the
+    // "first line" IS the whole needle (which by definition didn't match), so requiring
+    // more than a coarse token would never fire — a first-word anchor still locates the
+    // general spot even when everything after it changed. Matched as a whole word (not
+    // a bare substring) so "The" doesn't spuriously anchor onto "Theater".
+    const firstLine = nLines.find((l) => l.trim().length > 0);
+    if (firstLine) {
+        const anchor = firstLine.trim().split(/\s+/)[0] ?? "";
+        const idx = anchor.length >= 3 ? hLines.findIndex((l) => includesWord(l, anchor)) : -1;
+        if (idx >= 0) {
+            // Cap each shown line — a real, common shape (a minified/bundled single-line
+            // HTML file) can put tens of thousands of chars on ONE "line", which would
+            // otherwise blow this diagnostic's own token budget. Mirrors the same
+            // line-length cap apps/api/src/lib/search.ts applies to search hits.
+            const clipLine = (s) => s.length > MISS_HINT_LINE_CLIP ? `${s.slice(0, MISS_HINT_LINE_CLIP)}…` : s;
+            const around = hLines
+                .slice(Math.max(0, idx - 1), idx + 2)
+                .map(clipLine)
+                .join("\n");
+            return (` A similar line exists at line ${idx + 1}, but the rest of old_str doesn't match what's ` +
+                `there now:\n${around}\nRe-read the artifact for the current text.`);
+        }
+    }
+    return ' Re-read the artifact (format:"html" for HTML content), or use `search` to find the right spot.';
+};
+/**
+ * Apply `edits` to `src` in order, each seeing the previous edit's result. Every
+ * `old_str` must match EXACTLY ONCE — unless `occurrence` names which of several
+ * identical matches to replace — or the whole batch is rejected (nothing partial
+ * ever lands). A miss carries a diagnostic (why it didn't match, not just that it
+ * didn't) so the agent fixes it in one round. Same contract as the coding Edit tool,
+ * so agents already know how to recover.
+ */
+export function applyEdits(src, edits) {
+    if (!edits.length)
+        throw new EditError("`edits` is empty — provide at least one {old_str, new_str}.");
+    let result = src;
+    for (const [i, e] of edits.entries()) {
+        const label = `Edit ${i + 1} of ${edits.length}`;
+        if (!e.old_str)
+            throw new EditError(`${label} failed: old_str is empty.`);
+        const positions = occurrences(result, e.old_str, e.occurrence);
+        if (positions.count === 0)
+            throw new EditError(`${label} failed: old_str not found in the current source.${nearestMissHint(result, e.old_str)}`);
+        if (positions.count === 1) {
+            if (e.occurrence !== undefined && e.occurrence !== 1)
+                throw new EditError(`${label} failed: occurrence ${e.occurrence} is out of range — old_str matched once (occurrence 1).`);
+            result = result.replace(e.old_str, () => e.new_str);
+            continue;
+        }
+        // Multiple matches: require `occurrence` to pick one rather than guessing.
+        if (e.occurrence === undefined)
+            throw new EditError(`${label} failed: old_str matched ${positions.count} times — add more surrounding context ` +
+                `so it is unique, or pass \`occurrence\` (1..${positions.count}) to pick one.`);
+        if (!Number.isInteger(e.occurrence) || e.occurrence < 1 || e.occurrence > positions.count)
+            throw new EditError(`${label} failed: occurrence ${e.occurrence} is out of range — old_str matched ` +
+                `${positions.count} times (occurrence 1..${positions.count}).`);
+        const at = positions.at;
+        result = result.slice(0, at) + e.new_str + result.slice(at + e.old_str.length);
+    }
+    return result;
+}
+//# sourceMappingURL=source-edits.js.map

package/dist/protocol/source-edits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-edits.js","sourceRoot":"","sources":["../../src/protocol/source-edits.ts"],"names":[],"mappings":"AAUA,MAAM,OAAO,SAAU,SAAQ,KAAK;CAAG;AAEvC,mFAAmF;AACnF,6EAA6E;AAC7E,MAAM,WAAW,GAAG,CAClB,QAAgB,EAChB,MAAc,EACd,QAA4B,EACG,EAAE;IACjC,MAAM,MAAM,GAAG,QAAQ,IAAI,CAAC,CAAA;IAC5B,IAAI,KAAK,GAAG,CAAC,CAAA;IACb,IAAI,EAAE,GAAG,CAAC,CAAC,CAAA;IACX,KACE,IAAI,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,EAChC,CAAC,KAAK,CAAC,CAAC,EACR,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,EAC/C,CAAC;QACD,KAAK,EAAE,CAAA;QACP,IAAI,KAAK,KAAK,MAAM;YAAE,EAAE,GAAG,CAAC,CAAA;IAC9B,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,CAAA;AACtB,CAAC,CAAA;AAED,kFAAkF;AAClF,mFAAmF;AACnF,qEAAqE;AACrE,MAAM,aAAa,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;AAE1E,sFAAsF;AACtF,sFAAsF;AACtF,iFAAiF;AACjF,gFAAgF;AAChF,yFAAyF;AACzF,MAAM,qBAAqB,GAAG,OAAO,CAAA;AAErC,mEAAmE;AACnE,+EAA+E;AAC/E,mEAAmE;AACnE,MAAM,mBAAmB,GAAG,GAAG,CAAA;AAE/B,MAAM,UAAU,GAAG,CAAC,CAAqB,EAAW,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;AAEpF,qFAAqF;AACrF,uEAAuE;AACvE,MAAM,YAAY,GAAG,CAAC,IAAY,EAAE,IAAY,EAAW,EAAE;IAC3D,KAAK,IAAI,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG,KAAK,CAAC,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,GAAG,CAAC,CAAC;QAC9E,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;YAAE,OAAO,IAAI,CAAA;IACrF,OAAO,KAAK,CAAA;AACd,CAAC,CAAA;AAED,gFAAgF;AAChF,iFAAiF;AACjF,gFAAgF;AAChF,MAAM,eAAe,GAAG,CAAC,QAAgB,EAAE,MAAc,EAAU,EAAE;IACnE,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;IACnC,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;IACjC,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,aAAa,CAAC,CAAA;IAEvC,iFAAiF;IACjF,iFAAiF;IACjF,IAAI,MAAM,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,IAAI,qBAAqB,EAAE,CAAC;QAC1D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACvD,IAAI,QAAQ,GAAG,IAAI,CAAA;YACnB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBACtC,IAAI,aAAa,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAW,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;oBACxD,QAAQ,GAAG,KAAK,CAAA;oBAChB,MAAK;gBACP,CAAC;YACH,CAAC;YACD,IAAI,QAAQ;gBACV,OAAO,CACL,8BAA8B,CAAC,GAAG,CAAC,+CAA+C;oBAClF,2FAA2F,CAC5F,CAAA;QACL,CAAC;IACH,CAAC;IAED,iFAAiF;IACjF,mFAAmF;IACnF,qFAAqF;IACrF,oFAAoF;IACpF,oFAAoF;IACpF,mFAAmF;IACnF,uEAAuE;IACvE,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IACzD,IAAI,SAAS,EAAE,CAAC;QACd,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;QACrD,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;QACtF,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC;YACb,6EAA6E;YAC7E,2EAA2E;YAC3E,sEAAsE;YACtE,qEAAqE;YACrE,MAAM,QAAQ,GAAG,CAAC,CAAS,EAAU,EAAE,CACrC,CAAC,CAAC,MAAM,GAAG,mBAAmB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,mBAAmB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAA;YAC5E,MAAM,MAAM,GAAG,MAAM;iBAClB,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC;iBACpC,GAAG,CAAC,QAAQ,CAAC;iBACb,IAAI,CAAC,IAAI,CAAC,CAAA;YACb,OAAO,CACL,kCAAkC,GAAG,GAAG,CAAC,iDAAiD;gBAC1F,eAAe,MAAM,8CAA8C,CACpE,CAAA;QACH,CAAC;IACH,CAAC;IAED,OAAO,iGAAiG,CAAA;AAC1G,CAAC,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CAAC,GAAW,EAAE,KAAyB;IAC/D,IAAI,CAAC,KAAK,CAAC,MAAM;QACf,MAAM,IAAI,SAAS,CAAC,6DAA6D,CAAC,CAAA;IACpF,IAAI,MAAM,GAAG,GAAG,CAAA;IAChB,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;QACrC,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,OAAO,KAAK,CAAC,MAAM,EAAE,CAAA;QAChD,IAAI,CAAC,CAAC,CAAC,OAAO;YAAE,MAAM,IAAI,SAAS,CAAC,GAAG,KAAK,4BAA4B,CAAC,CAAA;QACzE,MAAM,SAAS,GAAG,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,UAAU,CAAC,CAAA;QAC9D,IAAI,SAAS,CAAC,KAAK,KAAK,CAAC;YACvB,MAAM,IAAI,SAAS,CACjB,GAAG,KAAK,oDAAoD,eAAe,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CACjG,CAAA;QACH,IAAI,SAAS,CAAC,KAAK,KAAK,CAAC,EAAE,CAAC;YAC1B,IAAI,CAAC,CAAC,UAAU,KAAK,SAAS,IAAI,CAAC,CAAC,UAAU,KAAK,CAAC;gBAClD,MAAM,IAAI,SAAS,CACjB,GAAG,KAAK,uBAAuB,CAAC,CAAC,UAAU,yDAAyD,CACrG,CAAA;YACH,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAA;YACnD,SAAQ;QACV,CAAC;QACD,2EAA2E;QAC3E,IAAI,CAAC,CAAC,UAAU,KAAK,SAAS;YAC5B,MAAM,IAAI,SAAS,CACjB,GAAG,KAAK,4BAA4B,SAAS,CAAC,KAAK,wCAAwC;gBACzF,+CAA+C,SAAS,CAAC,KAAK,gBAAgB,CACjF,CAAA;QACH,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,UAAU,GAAG,CAAC,IAAI,CAAC,CAAC,UAAU,GAAG,SAAS,CAAC,KAAK;YACvF,MAAM,IAAI,SAAS,CACjB,GAAG,KAAK,uBAAuB,CAAC,CAAC,UAAU,qCAAqC;gBAC9E,GAAG,SAAS,CAAC,KAAK,yBAAyB,SAAS,CAAC,KAAK,IAAI,CACjE,CAAA;QACH,MAAM,EAAE,GAAG,SAAS,CAAC,EAAE,CAAA;QACvB,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;IAChF,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC"}

package/dist/protocol/source-element-edits.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Source-safe edits to a rendered element.
+ *
+ * Inline text edits locate visible words, then splice their exact source span. A
+ * resize has no visible text to quote, so it rides the same ElementSelector used by
+ * comments. The selector is resolved against the exact base version and only the
+ * matching opening tag is changed; the document is never DOM-serialized, so authored
+ * formatting, comments, scripts, and every unrelated byte remain intact.
+ */
+import { type ElementSelector } from "./source-elements.js";
+export interface ElementResizeEdit {
+    op: "resize";
+    target: ElementSelector;
+    /** Rendered CSS pixels. Kept bounded so a hostile payload cannot create absurd CSS. */
+    width: number;
+    /** Images/media preserve their aspect ratio with `auto`; boxes carry a pixel height. */
+    height: number | "auto";
+}
+export type ElementEdit = ElementResizeEdit;
+export declare const isElementEdit: (value: unknown) => value is ElementEdit;
+/** Apply element edits in order. Each op sees the preceding op, matching exact-text
+ * edit semantics; the whole call still throws before publishing if any op fails. */
+export declare const applyElementEdits: (html: string, edits: ElementEdit[]) => string;
+//# sourceMappingURL=source-element-edits.d.ts.map

package/dist/protocol/source-element-edits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-element-edits.d.ts","sourceRoot":"","sources":["../../src/protocol/source-element-edits.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAEL,KAAK,eAAe,EAKrB,MAAM,sBAAsB,CAAA;AAG7B,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,QAAQ,CAAA;IACZ,MAAM,EAAE,eAAe,CAAA;IACvB,uFAAuF;IACvF,KAAK,EAAE,MAAM,CAAA;IACb,wFAAwF;IACxF,MAAM,EAAE,MAAM,GAAG,MAAM,CAAA;CACxB;AAED,MAAM,MAAM,WAAW,GAAG,iBAAiB,CAAA;AAS3C,eAAO,MAAM,aAAa,UAAW,OAAO,KAAG,KAAK,IAAI,WAIvD,CAAA;AA2DD;oFACoF;AACpF,eAAO,MAAM,iBAAiB,SAAU,MAAM,SAAS,WAAW,EAAE,KAAG,MAyBtE,CAAA"}

package/dist/protocol/source-element-edits.js

@@ -0,0 +1,93 @@
+/**
+ * Source-safe edits to a rendered element.
+ *
+ * Inline text edits locate visible words, then splice their exact source span. A
+ * resize has no visible text to quote, so it rides the same ElementSelector used by
+ * comments. The selector is resolved against the exact base version and only the
+ * matching opening tag is changed; the document is never DOM-serialized, so authored
+ * formatting, comments, scripts, and every unrelated byte remain intact.
+ */
+import { EditError } from "./source-edits.js";
+import { fingerprintOf, parseElementSelector, resolveElement, scanElements, } from "./source-elements.js";
+import { updateOpeningTagStyle } from "./source-style.js";
+const MIN_SIZE = 24;
+const MAX_SIZE = 8192;
+const MAX_ELEMENT_EDITS = 200;
+const agreesAtOrdinal = (selector, element) => fingerprintOf(element) === selector.fingerprint || (!!selector.id && element.id === selector.id);
+export const isElementEdit = (value) => {
+    if (!value || typeof value !== "object")
+        return false;
+    const e = value;
+    return e.op === "resize" && !!e.target && typeof e.target === "object";
+};
+const selectorOf = (raw, label) => {
+    let json = "";
+    try {
+        json = JSON.stringify(raw);
+    }
+    catch {
+        throw new EditError(`${label} failed: its element selector isn't valid JSON.`);
+    }
+    const selector = parseElementSelector(json);
+    if (!selector)
+        throw new EditError(`${label} failed: its element selector is malformed.`);
+    return selector;
+};
+const sizeOf = (raw, name, label) => {
+    if (typeof raw !== "number" || !Number.isFinite(raw) || !Number.isInteger(raw))
+        throw new EditError(`${label} failed: ${name} must be a whole number of pixels.`);
+    if (raw < MIN_SIZE || raw > MAX_SIZE)
+        throw new EditError(`${label} failed: ${name} must be between ${MIN_SIZE} and ${MAX_SIZE} pixels.`);
+    return raw;
+};
+/**
+ * Write resolution is deliberately stricter than comment relocation. This edit is
+ * based on the current version, so an unchanged element must still agree on its
+ * same-tag ordinal AND content (or authored id). Only then do we fall back to the
+ * relocation cascade, and never to a low-confidence guess.
+ */
+const editTarget = (selector, descriptors, label) => {
+    const atOrdinal = descriptors.find((d) => d.tag === selector.tag && d.ordinal === selector.ordinal);
+    if (atOrdinal && agreesAtOrdinal(selector, atOrdinal))
+        return atOrdinal;
+    const match = resolveElement(selector, descriptors);
+    const target = match ? descriptors[match.index] : undefined;
+    const strong = match?.signals.includes("id") || match?.signals.includes("content");
+    if (!target || match?.band === "low" || !strong)
+        throw new EditError(`${label} failed: that element couldn't be matched confidently in the stored source. Open the source editor instead.`);
+    return target;
+};
+/** Change/add only the opening tag's style attribute, preserving quote style and
+ * every unrelated attribute. */
+const resizeOpeningTag = (tag, width, height) => {
+    return updateOpeningTagStyle(tag, {
+        width: `${width}px`,
+        height: height === "auto" ? "auto" : `${height}px`,
+    });
+};
+/** Apply element edits in order. Each op sees the preceding op, matching exact-text
+ * edit semantics; the whole call still throws before publishing if any op fails. */
+export const applyElementEdits = (html, edits) => {
+    if (!Array.isArray(edits) || edits.length === 0)
+        throw new EditError("`edits` contains no element operations.");
+    if (edits.length > MAX_ELEMENT_EDITS)
+        throw new EditError(`Element edits has ${edits.length} entries — the maximum per request is ${MAX_ELEMENT_EDITS}.`);
+    let out = html;
+    for (const [i, raw] of edits.entries()) {
+        const label = `Element edit ${i + 1} of ${edits.length}`;
+        if (raw?.op !== "resize")
+            throw new EditError(`${label} failed: unknown operation ${JSON.stringify(raw?.op)}.`);
+        const selector = selectorOf(raw.target, label);
+        const width = sizeOf(raw.width, "width", label);
+        const height = raw.height === "auto" ? "auto" : sizeOf(raw.height, "height", label);
+        const descriptors = scanElements(out);
+        const target = editTarget(selector, descriptors, label);
+        const opening = out.slice(target.sourceStart, target.sourceEnd);
+        const resized = resizeOpeningTag(opening, width, height);
+        if (resized === opening)
+            throw new EditError(`${label} leaves that element at its existing size.`);
+        out = out.slice(0, target.sourceStart) + resized + out.slice(target.sourceEnd);
+    }
+    return out;
+};
+//# sourceMappingURL=source-element-edits.js.map

package/dist/protocol/source-element-edits.js.map

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

package/dist/protocol/source-element-match.d.ts

@@ -0,0 +1,4 @@
+import type { ElementDescriptor, ElementMatch, ElementSelector } from "./source-element-types.js";
+/** Identity, content, neighbors, and position resolve the same persisted selector. */
+export declare const resolveElement: (selector: ElementSelector, elements: ElementDescriptor[]) => ElementMatch | null;
+//# sourceMappingURL=source-element-match.d.ts.map

package/dist/protocol/source-element-match.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-element-match.d.ts","sourceRoot":"","sources":["../../src/protocol/source-element-match.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAA;AAmBjG,sFAAsF;AACtF,eAAO,MAAM,cAAc,aACf,eAAe,YACf,iBAAiB,EAAE,KAC5B,YAAY,GAAG,IAcjB,CAAA"}

package/dist/protocol/source-element-match.js

@@ -0,0 +1,40 @@
+import { fingerprintOf } from "./source-element-properties.js";
+import { gradeElement, scoreElement } from "./source-element-score.js";
+const candidatesFor = (selector, elements) => {
+    const result = { indices: new Set(), fpMatches: 0, idMatches: 0 };
+    for (const [index, element] of elements.entries()) {
+        if (!element)
+            continue;
+        if (element.tag === selector.tag)
+            result.indices.add(index);
+        if (selector.id && element.id === selector.id) {
+            result.indices.add(index);
+            result.idMatches++;
+        }
+        if (fingerprintOf(element) === selector.fingerprint)
+            result.fpMatches++;
+    }
+    return result;
+};
+/** Identity, content, neighbors, and position resolve the same persisted selector. */
+export const resolveElement = (selector, elements) => {
+    const candidates = candidatesFor(selector, elements);
+    let best = null;
+    let runnerUp = 0;
+    for (const index of candidates.indices) {
+        const match = scoreElement(selector, elements, index, candidates);
+        if (!match)
+            continue;
+        if (!best || match.confidence > best.confidence) {
+            if (best)
+                runnerUp = Math.max(runnerUp, best.confidence);
+            best = match;
+        }
+        else if (match.confidence > runnerUp)
+            runnerUp = match.confidence;
+    }
+    if (!best || best.confidence < 0.42)
+        return null;
+    return { ...best, ...gradeElement(best, candidates, best.confidence - runnerUp) };
+};
+//# sourceMappingURL=source-element-match.js.map

package/dist/protocol/source-element-match.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-element-match.js","sourceRoot":"","sources":["../../src/protocol/source-element-match.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAA;AAC9D,OAAO,EAAE,YAAY,EAAoB,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAGxF,MAAM,aAAa,GAAG,CACpB,QAAyB,EACzB,QAA6B,EACW,EAAE;IAC1C,MAAM,MAAM,GAAG,EAAE,OAAO,EAAE,IAAI,GAAG,EAAU,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,CAAA;IACzE,KAAK,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC;QAClD,IAAI,CAAC,OAAO;YAAE,SAAQ;QACtB,IAAI,OAAO,CAAC,GAAG,KAAK,QAAQ,CAAC,GAAG;YAAE,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;QAC3D,IAAI,QAAQ,CAAC,EAAE,IAAI,OAAO,CAAC,EAAE,KAAK,QAAQ,CAAC,EAAE,EAAE,CAAC;YAC9C,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;YACzB,MAAM,CAAC,SAAS,EAAE,CAAA;QACpB,CAAC;QACD,IAAI,aAAa,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,WAAW;YAAE,MAAM,CAAC,SAAS,EAAE,CAAA;IACzE,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC,CAAA;AAED,sFAAsF;AACtF,MAAM,CAAC,MAAM,cAAc,GAAG,CAC5B,QAAyB,EACzB,QAA6B,EACR,EAAE;IACvB,MAAM,UAAU,GAAG,aAAa,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAA;IACpD,IAAI,IAAI,GAAwB,IAAI,CAAA;IACpC,IAAI,QAAQ,GAAG,CAAC,CAAA;IAChB,KAAK,MAAM,KAAK,IAAI,UAAU,CAAC,OAAO,EAAE,CAAC;QACvC,MAAM,KAAK,GAAG,YAAY,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,CAAC,CAAA;QACjE,IAAI,CAAC,KAAK;YAAE,SAAQ;QACpB,IAAI,CAAC,IAAI,IAAI,KAAK,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;YAChD,IAAI,IAAI;gBAAE,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,UAAU,CAAC,CAAA;YACxD,IAAI,GAAG,KAAK,CAAA;QACd,CAAC;aAAM,IAAI,KAAK,CAAC,UAAU,GAAG,QAAQ;YAAE,QAAQ,GAAG,KAAK,CAAC,UAAU,CAAA;IACrE,CAAC;IACD,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,UAAU,GAAG,IAAI;QAAE,OAAO,IAAI,CAAA;IAChD,OAAO,EAAE,GAAG,IAAI,EAAE,GAAG,YAAY,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,GAAG,QAAQ,CAAC,EAAE,CAAA;AACnF,CAAC,CAAA"}

package/dist/protocol/source-element-neighbors.d.ts

@@ -0,0 +1,8 @@
+import type { ElementDescriptor } from "./source-element-types.js";
+/** Enclosing and contained elements are not neighboring blocks. */
+export declare const neighborText: (elements: ElementDescriptor[], index: number) => {
+    before?: string | undefined;
+    after?: string | undefined;
+};
+export declare const neighborAgrees: (wanted: string, actual: string) => boolean;
+//# sourceMappingURL=source-element-neighbors.d.ts.map

package/dist/protocol/source-element-neighbors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-element-neighbors.d.ts","sourceRoot":"","sources":["../../src/protocol/source-element-neighbors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAA;AAwBlE,mEAAmE;AACnE,eAAO,MAAM,YAAY,aACb,iBAAiB,EAAE,SACtB,MAAM,KACZ;IAAE,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAG1D,CAAA;AAEF,eAAO,MAAM,cAAc,WAAY,MAAM,UAAU,MAAM,KAAG,OAU/D,CAAA"}

package/dist/protocol/source-element-neighbors.js

@@ -0,0 +1,39 @@
+const ancestor = (elements, parent, child) => {
+    for (let at = elements[child]?.parent ?? -1; at >= 0; at = elements[at]?.parent ?? -1)
+        if (at === parent)
+            return true;
+    return false;
+};
+const nearest = (elements, index, direction) => {
+    let seen = 0;
+    for (let at = index + direction; at >= 0 && at < elements.length && seen < 6; at += direction) {
+        const related = direction < 0 ? ancestor(elements, at, index) : ancestor(elements, index, at);
+        if (related)
+            continue;
+        seen++;
+        const text = elements[at]?.text;
+        if (text && text.length >= 2)
+            return text;
+    }
+    return undefined;
+};
+/** Enclosing and contained elements are not neighboring blocks. */
+export const neighborText = (elements, index) => ({
+    before: nearest(elements, index, -1),
+    after: nearest(elements, index, 1),
+});
+export const neighborAgrees = (wanted, actual) => {
+    if (typeof wanted !== "string" || typeof actual !== "string")
+        return false;
+    const a = wanted.toLowerCase();
+    const b = actual.toLowerCase();
+    if (a === b)
+        return true;
+    const short = a.length < b.length ? a : b;
+    const long = a.length < b.length ? b : a;
+    if (short.length >= 8 && long.includes(short))
+        return true;
+    const width = Math.min(16, short.length);
+    return width >= 8 && long.slice(0, width) === short.slice(0, width);
+};
+//# sourceMappingURL=source-element-neighbors.js.map

package/dist/protocol/source-element-neighbors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-element-neighbors.js","sourceRoot":"","sources":["../../src/protocol/source-element-neighbors.ts"],"names":[],"mappings":"AAEA,MAAM,QAAQ,GAAG,CAAC,QAA6B,EAAE,MAAc,EAAE,KAAa,EAAW,EAAE;IACzF,KAAK,IAAI,EAAE,GAAG,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,IAAI,CAAC,CAAC,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,GAAG,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,IAAI,CAAC,CAAC;QACnF,IAAI,EAAE,KAAK,MAAM;YAAE,OAAO,IAAI,CAAA;IAChC,OAAO,KAAK,CAAA;AACd,CAAC,CAAA;AAED,MAAM,OAAO,GAAG,CACd,QAA6B,EAC7B,KAAa,EACb,SAAiB,EACG,EAAE;IACtB,IAAI,IAAI,GAAG,CAAC,CAAA;IACZ,KAAK,IAAI,EAAE,GAAG,KAAK,GAAG,SAAS,EAAE,EAAE,IAAI,CAAC,IAAI,EAAE,GAAG,QAAQ,CAAC,MAAM,IAAI,IAAI,GAAG,CAAC,EAAE,EAAE,IAAI,SAAS,EAAE,CAAC;QAC9F,MAAM,OAAO,GAAG,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,EAAE,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,EAAE,KAAK,EAAE,EAAE,CAAC,CAAA;QAC7F,IAAI,OAAO;YAAE,SAAQ;QACrB,IAAI,EAAE,CAAA;QACN,MAAM,IAAI,GAAG,QAAQ,CAAC,EAAE,CAAC,EAAE,IAAI,CAAA;QAC/B,IAAI,IAAI,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC;YAAE,OAAO,IAAI,CAAA;IAC3C,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC,CAAA;AAED,mEAAmE;AACnE,MAAM,CAAC,MAAM,YAAY,GAAG,CAC1B,QAA6B,EAC7B,KAAa,EACgD,EAAE,CAAC,CAAC;IACjE,MAAM,EAAE,OAAO,CAAC,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;IACpC,KAAK,EAAE,OAAO,CAAC,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC;CACnC,CAAC,CAAA;AAEF,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,MAAc,EAAE,MAAc,EAAW,EAAE;IACxE,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAA;IAC1E,MAAM,CAAC,GAAG,MAAM,CAAC,WAAW,EAAE,CAAA;IAC9B,MAAM,CAAC,GAAG,MAAM,CAAC,WAAW,EAAE,CAAA;IAC9B,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IACxB,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IACzC,MAAM,IAAI,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IACxC,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IAC1D,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;IACxC,OAAO,KAAK,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,KAAK,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAA;AACrE,CAAC,CAAA"}

package/dist/protocol/source-element-properties.d.ts

@@ -0,0 +1,25 @@
+import type { ElementRole } from "./source-element-types.js";
+type Attributes = {
+    attrs: Record<string, string>;
+};
+export declare const elementSrc: (element: Attributes) => string;
+export declare const elementAlt: (element: Attributes) => string;
+/** The browser and source resolver use the same fingerprint assembly. */
+export declare const fingerprintOf: (element: Attributes & {
+    tag: string;
+    text: string;
+}) => string;
+/** Existing authored review attributes remain part of the content contract. */
+export declare const roleOf: (element: Attributes & {
+    tag: string;
+    id?: string | undefined;
+    classes: string[];
+}) => ElementRole;
+/** A preserved label lets a comment explain an element that later disappears. */
+export declare const elementLabel: (element: Attributes & {
+    tag: string;
+    role: ElementRole;
+    text?: string | undefined;
+}) => string;
+export {};
+//# sourceMappingURL=source-element-properties.d.ts.map

package/dist/protocol/source-element-properties.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-element-properties.d.ts","sourceRoot":"","sources":["../../src/protocol/source-element-properties.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAA;AAE5D,KAAK,UAAU,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAAA;AAEnD,eAAO,MAAM,UAAU,YAAa,UAAU,KAAG,MACI,CAAA;AAErD,eAAO,MAAM,UAAU,YAAa,UAAU,KAAG,MACoC,CAAA;AAErF,yEAAyE;AACzE,eAAO,MAAM,aAAa,YAAa,UAAU,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,KAAG,MACE,CAAA;AAyBtF,+EAA+E;AAC/E,eAAO,MAAM,MAAM,YACR,UAAU,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,KAChF,WAOF,CAAA;AA6BD,iFAAiF;AACjF,eAAO,MAAM,YAAY,YACd,UAAU,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,KAClF,MAqBF,CAAA"}

package/dist/protocol/source-element-properties.js

@@ -0,0 +1,71 @@
+import { clip, fingerprintFrom, normWs } from "./source-anchors.js";
+export const elementSrc = (element) => element.attrs["src"] || element.attrs["href"] || "";
+export const elementAlt = (element) => element.attrs["alt"] || element.attrs["aria-label"] || element.attrs["title"] || "";
+/** The browser and source resolver use the same fingerprint assembly. */
+export const fingerprintOf = (element) => fingerprintFrom(element.tag, elementSrc(element), elementAlt(element), element.text);
+const REVIEW_ROLES = [
+    "loop-step",
+    "loop-policy",
+    "loop-transition",
+    "graph-node",
+    "graph-edge",
+];
+const TAG_ROLES = {
+    img: "image",
+    picture: "image",
+    video: "media",
+    audio: "media",
+    iframe: "embed",
+    embed: "embed",
+    object: "embed",
+    table: "table",
+    pre: "code",
+    code: "code",
+    svg: "chart",
+    canvas: "chart",
+    figure: "figure",
+};
+/** Existing authored review attributes remain part of the content contract. */
+export const roleOf = (element) => {
+    const review = REVIEW_ROLES.find((role) => role === element.attrs["data-derive-review-kind"]);
+    if (review)
+        return review;
+    const concrete = TAG_ROLES[element.tag];
+    if (concrete)
+        return concrete;
+    const hint = `${element.classes.join(" ")} ${element.id ?? ""} ${element.attrs["role"] ?? ""}`;
+    return /\b(chart|graph|plot|viz|sparkline|d3)\b/i.test(hint) ? "chart" : "block";
+};
+const hostOf = (url) => url.match(/^https?:\/\/([^/]+)/i)?.[1]?.replace(/^www\./, "") ?? "";
+const imageLabel = (alt, host) => alt ? `Image — ${clip(alt, 48)}` : host ? `Image — ${host}` : "Image";
+const mediaLabel = (tag, host) => tag === "audio" ? "Audio" : host ? `Video — ${host}` : "Video";
+const concreteLabel = (role, tag, alt, host) => {
+    const labels = {
+        image: imageLabel(alt, host),
+        chart: alt ? `Chart — ${clip(alt, 48)}` : "Chart",
+        media: mediaLabel(tag, host),
+        embed: host ? `Embedded — ${host}` : "Embedded content",
+        table: "Table",
+        code: "Code block",
+        figure: alt ? `Figure — ${clip(alt, 48)}` : "Figure",
+    };
+    return labels[role];
+};
+/** A preserved label lets a comment explain an element that later disappears. */
+export const elementLabel = (element) => {
+    const review = normWs(element.attrs["data-derive-review-label"] ?? "");
+    if (review)
+        return review;
+    const text = clip(normWs(element.text ?? ""), 48) || "Untitled";
+    const semantic = {
+        "loop-step": `Loop step — ${text}`,
+        "loop-policy": `Loop policy — ${text}`,
+        "loop-transition": `Loop transition — ${text}`,
+        "graph-node": `Graph node — ${text}`,
+        "graph-edge": `Graph edge — ${text}`,
+    };
+    return (semantic[element.role] ??
+        concreteLabel(element.role, element.tag, normWs(elementAlt(element)), hostOf(elementSrc(element))) ??
+        (clip(normWs(element.text ?? "") || element.tag, 48) || "Element"));
+};
+//# sourceMappingURL=source-element-properties.js.map

package/dist/protocol/source-element-properties.js.map

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

package/dist/protocol/source-element-scan.d.ts

@@ -0,0 +1,4 @@
+import type { ElementDescriptor } from "./source-element-types.js";
+/** Source descriptors use the common HTML scanner and browser entity decoder. */
+export declare const scanElements: (html: string) => ElementDescriptor[];
+//# sourceMappingURL=source-element-scan.d.ts.map

package/dist/protocol/source-element-scan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-element-scan.d.ts","sourceRoot":"","sources":["../../src/protocol/source-element-scan.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAA;AAuKlE,iFAAiF;AACjF,eAAO,MAAM,YAAY,SAAU,MAAM,KAAG,iBAAiB,EAsB5D,CAAA"}