@derive-to/artifacts 0.0.0-stage → 0.6.1

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

@@ -0,0 +1,181 @@
+import { DecodingMode, decodeHTML } from "entities/decode";
+import { normWs } from "./source-anchors.js";
+import { RAW_TEXT_ELEMENTS, RCDATA_ELEMENTS, walkHtmlTags } from "./source-html.js";
+import { attrValue } from "./source-html-attributes.js";
+import { projectPageText } from "./source-text.js";
+const TEXT_CAP = 4000;
+const BLOCKS = new Set([
+    "address",
+    "article",
+    "aside",
+    "blockquote",
+    "details",
+    "div",
+    "dl",
+    "fieldset",
+    "figcaption",
+    "figure",
+    "footer",
+    "form",
+    "h1",
+    "h2",
+    "h3",
+    "h4",
+    "h5",
+    "h6",
+    "header",
+    "hr",
+    "main",
+    "menu",
+    "nav",
+    "ol",
+    "p",
+    "pre",
+    "section",
+    "table",
+    "ul",
+]);
+const CLOSES = {
+    li: new Set(["li"]),
+    dt: new Set(["dt", "dd"]),
+    dd: new Set(["dt", "dd"]),
+    td: new Set(["td", "th", "tr"]),
+    th: new Set(["td", "th", "tr"]),
+    tr: new Set(["tr"]),
+    option: new Set(["option", "optgroup"]),
+    thead: new Set(["tbody", "tfoot"]),
+    tbody: new Set(["tbody", "tfoot"]),
+};
+const SKIP = new Set([
+    "html",
+    "head",
+    "body",
+    "script",
+    "style",
+    "meta",
+    "link",
+    "title",
+    "base",
+    "noscript",
+    "template",
+]);
+const KEEP = [
+    "src",
+    "href",
+    "alt",
+    "title",
+    "aria-label",
+    "role",
+    "name",
+    "data-derive-slide",
+    "data-derive-id",
+    "data-derive-review-id",
+    "data-derive-review-kind",
+    "data-derive-review-label",
+];
+const finish = (frame) => {
+    if (frame)
+        frame.element.text = normWs(frame.parts.join(""));
+};
+const append = (scan, text) => {
+    for (const frame of scan.open) {
+        if (frame.length >= TEXT_CAP)
+            continue;
+        const part = text.slice(0, TEXT_CAP - frame.length);
+        frame.parts.push(part);
+        frame.length += part.length;
+    }
+};
+const close = (scan, name) => {
+    const at = scan.open.findLastIndex((frame) => frame.element.tag === name);
+    if (at >= 0)
+        while (scan.open.length > at)
+            finish(scan.open.pop());
+};
+const closeImplicit = (scan, name) => {
+    while (scan.open.length) {
+        const top = scan.open.at(-1)?.element.tag ?? "";
+        const closes = top === "p" ? BLOCKS : CLOSES[top];
+        if (!closes?.has(name))
+            return;
+        finish(scan.open.pop());
+    }
+};
+const attributesOf = (raw) => Object.fromEntries([...KEEP, "id", "class"].flatMap((name) => {
+    const value = attrValue(raw, name);
+    return value === null ? [] : [[name, decodeHTML(value, DecodingMode.Attribute)]];
+}));
+const add = (scan, tag) => {
+    closeImplicit(scan, tag.name);
+    const all = attributesOf(tag.attrs);
+    const ordinal = scan.counts.get(tag.name) ?? 0;
+    scan.counts.set(tag.name, ordinal + 1);
+    const element = {
+        tag: tag.name,
+        id: all["id"] || undefined,
+        classes: (all["class"] ?? "").split(/[\t\n\f\r ]+/).filter(Boolean),
+        attrs: Object.fromEntries(KEEP.flatMap((name) => {
+            const value = all[name];
+            return value === undefined ? [] : [[name, value]];
+        })),
+        text: "",
+        ordinal,
+        index: scan.out.length,
+        parent: scan.open.at(-1)?.element.index ?? -1,
+        srcFraction: tag.start / (scan.html.length || 1),
+        sourceStart: tag.start,
+        sourceEnd: tag.end,
+    };
+    scan.out.push(element);
+    if (!tag.selfClosing)
+        scan.open.push({ element, parts: [], length: 0 });
+};
+const gapText = (html, raw) => {
+    if (raw === "script" || raw === "style")
+        return "";
+    if (RAW_TEXT_ELEMENTS.has(raw))
+        return html;
+    if (RCDATA_ELEMENTS.has(raw))
+        return decodeHTML(html, DecodingMode.Legacy);
+    // The tag walker already removes real tags. This fragment only needs comment,
+    // declaration, and entity handling. It introduces no inter-element separators.
+    return projectPageText(html, [], false).text;
+};
+const releaseScopes = (hidden, starts) => {
+    for (const start of starts)
+        hidden.delete(start);
+};
+const finishOpen = (frames) => {
+    for (const frame of frames)
+        finish(frame);
+};
+/** Source descriptors use the common HTML scanner and browser entity decoder. */
+export const scanElements = (html) => {
+    const scan = { html, out: [], open: [], counts: new Map() };
+    const hidden = new Set();
+    let from = 0;
+    let raw = "";
+    for (const tag of walkHtmlTags(html)) {
+        if (!hidden.size)
+            append(scan, gapText(html.slice(from, tag.start), raw));
+        from = tag.end;
+        raw = "";
+        releaseScopes(hidden, tag.closedOpenStarts);
+        if (tag.closing) {
+            if (!hidden.size)
+                close(scan, tag.name);
+            continue;
+        }
+        if (tag.namespace === "html" && ["head", "template", "noscript"].includes(tag.name))
+            hidden.add(tag.start);
+        if (RAW_TEXT_ELEMENTS.has(tag.name) || RCDATA_ELEMENTS.has(tag.name))
+            raw = tag.name;
+        if (!hidden.size && !SKIP.has(tag.name))
+            add(scan, tag);
+    }
+    if (!hidden.size)
+        append(scan, gapText(html.slice(from), raw));
+    finishOpen(scan.open);
+    return scan.out;
+};
+//# sourceMappingURL=source-element-scan.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"source-element-scan.js","sourceRoot":"","sources":["../../src/protocol/source-element-scan.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAC1D,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAE5C,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AACnF,OAAO,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAA;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAElD,MAAM,QAAQ,GAAG,IAAI,CAAA;AACrB,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC;IACrB,SAAS;IACT,SAAS;IACT,OAAO;IACP,YAAY;IACZ,SAAS;IACT,KAAK;IACL,IAAI;IACJ,UAAU;IACV,YAAY;IACZ,QAAQ;IACR,QAAQ;IACR,MAAM;IACN,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,QAAQ;IACR,IAAI;IACJ,MAAM;IACN,MAAM;IACN,KAAK;IACL,IAAI;IACJ,GAAG;IACH,KAAK;IACL,SAAS;IACT,OAAO;IACP,IAAI;CACL,CAAC,CAAA;AACF,MAAM,MAAM,GAAkD;IAC5D,EAAE,EAAE,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;IACnB,EAAE,EAAE,IAAI,GAAG,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACzB,EAAE,EAAE,IAAI,GAAG,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACzB,EAAE,EAAE,IAAI,GAAG,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IAC/B,EAAE,EAAE,IAAI,GAAG,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IAC/B,EAAE,EAAE,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;IACnB,MAAM,EAAE,IAAI,GAAG,CAAC,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IACvC,KAAK,EAAE,IAAI,GAAG,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAClC,KAAK,EAAE,IAAI,GAAG,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;CACnC,CAAA;AACD,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC;IACnB,MAAM;IACN,MAAM;IACN,MAAM;IACN,QAAQ;IACR,OAAO;IACP,MAAM;IACN,MAAM;IACN,OAAO;IACP,MAAM;IACN,UAAU;IACV,UAAU;CACX,CAAC,CAAA;AACF,MAAM,IAAI,GAAG;IACX,KAAK;IACL,MAAM;IACN,KAAK;IACL,OAAO;IACP,YAAY;IACZ,MAAM;IACN,MAAM;IACN,mBAAmB;IACnB,gBAAgB;IAChB,uBAAuB;IACvB,yBAAyB;IACzB,0BAA0B;CAC3B,CAAA;AAcD,MAAM,MAAM,GAAG,CAAC,KAAwB,EAAQ,EAAE;IAChD,IAAI,KAAK;QAAE,KAAK,CAAC,OAAO,CAAC,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAA;AAC9D,CAAC,CAAA;AACD,MAAM,MAAM,GAAG,CAAC,IAAU,EAAE,IAAY,EAAQ,EAAE;IAChD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QAC9B,IAAI,KAAK,CAAC,MAAM,IAAI,QAAQ;YAAE,SAAQ;QACtC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,GAAG,KAAK,CAAC,MAAM,CAAC,CAAA;QACnD,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACtB,KAAK,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAA;IAC7B,CAAC;AACH,CAAC,CAAA;AACD,MAAM,KAAK,GAAG,CAAC,IAAU,EAAE,IAAY,EAAQ,EAAE;IAC/C,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,KAAK,IAAI,CAAC,CAAA;IACzE,IAAI,EAAE,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,EAAE;YAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAA;AACpE,CAAC,CAAA;AACD,MAAM,aAAa,GAAG,CAAC,IAAU,EAAE,IAAY,EAAQ,EAAE;IACvD,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;QACxB,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,GAAG,IAAI,EAAE,CAAA;QAC/C,MAAM,MAAM,GAAG,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QACjD,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,CAAC;YAAE,OAAM;QAC9B,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAA;IACzB,CAAC;AACH,CAAC,CAAA;AAED,MAAM,YAAY,GAAG,CAAC,GAAW,EAA0B,EAAE,CAC3D,MAAM,CAAC,WAAW,CAChB,CAAC,GAAG,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE;IACxC,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;IAClC,OAAO,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,UAAU,CAAC,KAAK,EAAE,YAAY,CAAC,SAAS,CAAC,CAAC,CAAC,CAAA;AAClF,CAAC,CAAC,CACH,CAAA;AAEH,MAAM,GAAG,GAAG,CACV,IAAU,EACV,GAAsF,EAChF,EAAE;IACR,aAAa,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,CAAA;IAC7B,MAAM,GAAG,GAAG,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;IACnC,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAC9C,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,GAAG,CAAC,CAAC,CAAA;IACtC,MAAM,OAAO,GAAsB;QACjC,GAAG,EAAE,GAAG,CAAC,IAAI;QACb,EAAE,EAAE,GAAG,CAAC,IAAI,CAAC,IAAI,SAAS;QAC1B,OAAO,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC;QACnE,KAAK,EAAE,MAAM,CAAC,WAAW,CACvB,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE;YACpB,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,CAAC,CAAA;YACvB,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAA;QACnD,CAAC,CAAC,CACH;QACD,IAAI,EAAE,EAAE;QACR,OAAO;QACP,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,MAAM;QACtB,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC;QAC7C,WAAW,EAAE,GAAG,CAAC,KAAK,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC;QAChD,WAAW,EAAE,GAAG,CAAC,KAAK;QACtB,SAAS,EAAE,GAAG,CAAC,GAAG;KACnB,CAAA;IACD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;IACtB,IAAI,CAAC,GAAG,CAAC,WAAW;QAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAA;AACzE,CAAC,CAAA;AAED,MAAM,OAAO,GAAG,CAAC,IAAY,EAAE,GAAW,EAAU,EAAE;IACpD,IAAI,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,OAAO;QAAE,OAAO,EAAE,CAAA;IAClD,IAAI,iBAAiB,CAAC,GAAG,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAA;IAC3C,IAAI,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC;QAAE,OAAO,UAAU,CAAC,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,CAAA;IAC1E,8EAA8E;IAC9E,+EAA+E;IAC/E,OAAO,eAAe,CAAC,IAAI,EAAE,EAAE,EAAE,KAAK,CAAC,CAAC,IAAI,CAAA;AAC9C,CAAC,CAAA;AAED,MAAM,aAAa,GAAG,CAAC,MAAmB,EAAE,MAAyB,EAAQ,EAAE;IAC7E,KAAK,MAAM,KAAK,IAAI,MAAM;QAAE,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;AAClD,CAAC,CAAA;AAED,MAAM,UAAU,GAAG,CAAC,MAAe,EAAQ,EAAE;IAC3C,KAAK,MAAM,KAAK,IAAI,MAAM;QAAE,MAAM,CAAC,KAAK,CAAC,CAAA;AAC3C,CAAC,CAAA;AAED,iFAAiF;AACjF,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,IAAY,EAAuB,EAAE;IAChE,MAAM,IAAI,GAAS,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,GAAG,EAAE,EAAE,CAAA;IACjE,MAAM,MAAM,GAAG,IAAI,GAAG,EAAU,CAAA;IAChC,IAAI,IAAI,GAAG,CAAC,CAAA;IACZ,IAAI,GAAG,GAAG,EAAE,CAAA;IACZ,KAAK,MAAM,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC;QACrC,IAAI,CAAC,MAAM,CAAC,IAAI;YAAE,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAA;QACzE,IAAI,GAAG,GAAG,CAAC,GAAG,CAAA;QACd,GAAG,GAAG,EAAE,CAAA;QACR,aAAa,CAAC,MAAM,EAAE,GAAG,CAAC,gBAAgB,CAAC,CAAA;QAC3C,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;YAChB,IAAI,CAAC,MAAM,CAAC,IAAI;gBAAE,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,CAAA;YACvC,SAAQ;QACV,CAAC;QACD,IAAI,GAAG,CAAC,SAAS,KAAK,MAAM,IAAI,CAAC,MAAM,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC;YACjF,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;QACvB,IAAI,iBAAiB,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,GAAG,GAAG,GAAG,CAAC,IAAI,CAAA;QACpF,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAA;IACzD,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,IAAI;QAAE,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC,CAAA;IAC9D,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACrB,OAAO,IAAI,CAAC,GAAG,CAAA;AACjB,CAAC,CAAA"}

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

@@ -0,0 +1,12 @@
+import type { ConfidenceBand, ElementDescriptor, ElementMatch, ElementSelector } from "./source-element-types.js";
+export interface MatchCounts {
+    fpMatches: number;
+    idMatches: number;
+}
+export declare const scoreElement: (selector: ElementSelector, elements: ElementDescriptor[], index: number, counts: MatchCounts) => ElementMatch | null;
+/** Shared content or conflicting identity signals cannot claim a certain match. */
+export declare const gradeElement: (match: ElementMatch, counts: MatchCounts, margin: number) => {
+    band: ConfidenceBand;
+    confidence: number;
+};
+//# sourceMappingURL=source-element-score.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"source-element-score.d.ts","sourceRoot":"","sources":["../../src/protocol/source-element-score.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,cAAc,EACd,iBAAiB,EACjB,YAAY,EACZ,eAAe,EAChB,MAAM,2BAA2B,CAAA;AAElC,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;CAClB;AA2DD,eAAO,MAAM,YAAY,aACb,eAAe,YACf,iBAAiB,EAAE,SACtB,MAAM,UACL,WAAW,KAClB,YAAY,GAAG,IAWjB,CAAA;AAYD,mFAAmF;AACnF,eAAO,MAAM,YAAY,UAChB,YAAY,UACX,WAAW,UACX,MAAM,KACb;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAc5C,CAAA"}

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

@@ -0,0 +1,82 @@
+import { neighborAgrees, neighborText } from "./source-element-neighbors.js";
+import { fingerprintOf } from "./source-element-properties.js";
+const identityScore = (selector, element, score) => {
+    if (selector.id) {
+        score.possible += 5;
+        if (element.id === selector.id) {
+            score.points += 5;
+            score.signals.push("id");
+        }
+    }
+    score.possible += 5;
+    if (fingerprintOf(element) === selector.fingerprint) {
+        score.points += 5;
+        score.signals.push("content");
+    }
+};
+const ordinalScore = (selector, element, score) => {
+    score.possible += 3;
+    if (element.tag !== selector.tag)
+        return;
+    if (element.ordinal === selector.ordinal) {
+        score.points += 3;
+        score.signals.push("position");
+    }
+    else
+        score.points += 1;
+};
+const neighborScore = (selector, elements, index, score) => {
+    if (!selector.before && !selector.after)
+        return;
+    const near = neighborText(elements, index);
+    for (const side of ["before", "after"]) {
+        const wanted = selector[side];
+        if (!wanted)
+            continue;
+        score.possible += 1;
+        const actual = near[side];
+        if (actual && neighborAgrees(wanted, actual)) {
+            score.points += 1;
+            score.signals.push(`neighbor:${side}`);
+        }
+    }
+};
+export const scoreElement = (selector, elements, index, counts) => {
+    const element = elements[index];
+    if (!element)
+        return null;
+    const score = { points: 0, possible: 0, signals: [] };
+    identityScore(selector, element, score);
+    // Repeated content makes its ordinal unreliable after insertions and deletions.
+    if (counts.fpMatches <= 1)
+        ordinalScore(selector, element, score);
+    neighborScore(selector, elements, index, score);
+    score.possible += 1;
+    score.points += 1 - Math.min(1, Math.abs(element.srcFraction - selector.docFraction));
+    return { index, confidence: score.points / score.possible, band: "low", signals: score.signals };
+};
+const identities = (match, counts) => {
+    const id = match.signals.includes("id");
+    const content = match.signals.includes("content");
+    return {
+        unique: (id && counts.idMatches === 1) || (content && counts.fpMatches === 1),
+        ambiguous: (id && counts.idMatches > 1) || (content && counts.fpMatches > 1),
+        conflict: (id && !content && counts.fpMatches > 0) || (content && !id && counts.idMatches > 0),
+    };
+};
+/** Shared content or conflicting identity signals cannot claim a certain match. */
+export const gradeElement = (match, counts, margin) => {
+    const identity = identities(match, counts);
+    const neighbor = match.signals.some((signal) => signal.startsWith("neighbor"));
+    if (identity.ambiguous && !identity.unique && !neighbor)
+        return { band: "low", confidence: Math.min(match.confidence, 0.45) };
+    if (identity.conflict)
+        return { band: "medium", confidence: Math.min(match.confidence, 0.6) };
+    if (identity.unique && match.confidence >= 0.6 && margin >= 0.12)
+        return { band: "high", confidence: match.confidence };
+    if ((identity.unique || neighbor || match.signals.includes("position")) &&
+        match.confidence >= 0.5)
+        return { band: "medium", confidence: Math.min(match.confidence, 0.75) };
+    return { band: "low", confidence: Math.min(match.confidence, 0.5) };
+};
+//# sourceMappingURL=source-element-score.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"source-element-score.js","sourceRoot":"","sources":["../../src/protocol/source-element-score.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAA;AAC5E,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAA;AAkB9D,MAAM,aAAa,GAAG,CACpB,QAAyB,EACzB,OAA0B,EAC1B,KAAY,EACN,EAAE;IACR,IAAI,QAAQ,CAAC,EAAE,EAAE,CAAC;QAChB,KAAK,CAAC,QAAQ,IAAI,CAAC,CAAA;QACnB,IAAI,OAAO,CAAC,EAAE,KAAK,QAAQ,CAAC,EAAE,EAAE,CAAC;YAC/B,KAAK,CAAC,MAAM,IAAI,CAAC,CAAA;YACjB,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAC1B,CAAC;IACH,CAAC;IACD,KAAK,CAAC,QAAQ,IAAI,CAAC,CAAA;IACnB,IAAI,aAAa,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,WAAW,EAAE,CAAC;QACpD,KAAK,CAAC,MAAM,IAAI,CAAC,CAAA;QACjB,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;IAC/B,CAAC;AACH,CAAC,CAAA;AAED,MAAM,YAAY,GAAG,CACnB,QAAyB,EACzB,OAA0B,EAC1B,KAAY,EACN,EAAE;IACR,KAAK,CAAC,QAAQ,IAAI,CAAC,CAAA;IACnB,IAAI,OAAO,CAAC,GAAG,KAAK,QAAQ,CAAC,GAAG;QAAE,OAAM;IACxC,IAAI,OAAO,CAAC,OAAO,KAAK,QAAQ,CAAC,OAAO,EAAE,CAAC;QACzC,KAAK,CAAC,MAAM,IAAI,CAAC,CAAA;QACjB,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;IAChC,CAAC;;QAAM,KAAK,CAAC,MAAM,IAAI,CAAC,CAAA;AAC1B,CAAC,CAAA;AAED,MAAM,aAAa,GAAG,CACpB,QAAyB,EACzB,QAA6B,EAC7B,KAAa,EACb,KAAY,EACN,EAAE;IACR,IAAI,CAAC,QAAQ,CAAC,MAAM,IAAI,CAAC,QAAQ,CAAC,KAAK;QAAE,OAAM;IAC/C,MAAM,IAAI,GAAG,YAAY,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAA;IAC1C,KAAK,MAAM,IAAI,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAU,EAAE,CAAC;QAChD,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAA;QAC7B,IAAI,CAAC,MAAM;YAAE,SAAQ;QACrB,KAAK,CAAC,QAAQ,IAAI,CAAC,CAAA;QACnB,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,CAAA;QACzB,IAAI,MAAM,IAAI,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;YAC7C,KAAK,CAAC,MAAM,IAAI,CAAC,CAAA;YACjB,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,YAAY,IAAI,EAAE,CAAC,CAAA;QACxC,CAAC;IACH,CAAC;AACH,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,YAAY,GAAG,CAC1B,QAAyB,EACzB,QAA6B,EAC7B,KAAa,EACb,MAAmB,EACE,EAAE;IACvB,MAAM,OAAO,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAA;IAC/B,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAA;IACzB,MAAM,KAAK,GAAU,EAAE,MAAM,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAA;IAC5D,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,KAAK,CAAC,CAAA;IACvC,gFAAgF;IAChF,IAAI,MAAM,CAAC,SAAS,IAAI,CAAC;QAAE,YAAY,CAAC,QAAQ,EAAE,OAAO,EAAE,KAAK,CAAC,CAAA;IACjE,aAAa,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,CAAC,CAAA;IAC/C,KAAK,CAAC,QAAQ,IAAI,CAAC,CAAA;IACnB,KAAK,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,WAAW,GAAG,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAA;IACrF,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAA;AAClG,CAAC,CAAA;AAED,MAAM,UAAU,GAAG,CAAC,KAAmB,EAAE,MAAmB,EAAE,EAAE;IAC9D,MAAM,EAAE,GAAG,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;IACvC,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAA;IACjD,OAAO;QACL,MAAM,EAAE,CAAC,EAAE,IAAI,MAAM,CAAC,SAAS,KAAK,CAAC,CAAC,IAAI,CAAC,OAAO,IAAI,MAAM,CAAC,SAAS,KAAK,CAAC,CAAC;QAC7E,SAAS,EAAE,CAAC,EAAE,IAAI,MAAM,CAAC,SAAS,GAAG,CAAC,CAAC,IAAI,CAAC,OAAO,IAAI,MAAM,CAAC,SAAS,GAAG,CAAC,CAAC;QAC5E,QAAQ,EAAE,CAAC,EAAE,IAAI,CAAC,OAAO,IAAI,MAAM,CAAC,SAAS,GAAG,CAAC,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,EAAE,IAAI,MAAM,CAAC,SAAS,GAAG,CAAC,CAAC;KAC/F,CAAA;AACH,CAAC,CAAA;AAED,mFAAmF;AACnF,MAAM,CAAC,MAAM,YAAY,GAAG,CAC1B,KAAmB,EACnB,MAAmB,EACnB,MAAc,EACgC,EAAE;IAChD,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;IAC1C,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,CAAA;IAC9E,IAAI,QAAQ,CAAC,SAAS,IAAI,CAAC,QAAQ,CAAC,MAAM,IAAI,CAAC,QAAQ;QACrD,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,EAAE,IAAI,CAAC,EAAE,CAAA;IACtE,IAAI,QAAQ,CAAC,QAAQ;QAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,EAAE,GAAG,CAAC,EAAE,CAAA;IAC7F,IAAI,QAAQ,CAAC,MAAM,IAAI,KAAK,CAAC,UAAU,IAAI,GAAG,IAAI,MAAM,IAAI,IAAI;QAC9D,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,CAAA;IACvD,IACE,CAAC,QAAQ,CAAC,MAAM,IAAI,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;QACnE,KAAK,CAAC,UAAU,IAAI,GAAG;QAEvB,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,EAAE,IAAI,CAAC,EAAE,CAAA;IACzE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,EAAE,GAAG,CAAC,EAAE,CAAA;AACrE,CAAC,CAAA"}

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

@@ -0,0 +1,19 @@
+import type { ConfidenceBand, ElementDescriptor, ElementMatch, ElementSelector } from "./source-element-types.js";
+/** Agents capture the same persisted selector as the browser for an authored id. */
+export declare const elementSelectorForId: (html: string, id: string) => ElementSelector | null;
+/** Each successful version hop updates identity while retaining the original snapshot. */
+export declare const rederiveSelector: (selector: ElementSelector, element: ElementDescriptor, elements: ElementDescriptor[]) => ElementSelector;
+export interface ForwardWalk {
+    resolved: boolean;
+    confidence: number;
+    band: ConfidenceBand;
+    selector: ElementSelector;
+    survived: number;
+}
+/** Ordered saved HTML lets an anchor recover through several small changes. */
+export declare const planElementForwardWalk: (start: ElementSelector, versionHtml: string[]) => ForwardWalk;
+/** Preserve the existing selector fields. Hostile scalar fields cannot break a sweep. */
+export declare const parseElementSelector: (json: string | null) => ElementSelector | null;
+export declare const isElementAnchor: (json: string | null) => boolean;
+export declare const elementResolvesIn: (selector: ElementSelector, html: string) => ElementMatch | null;
+//# sourceMappingURL=source-element-selector.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"source-element-selector.d.ts","sourceRoot":"","sources":["../../src/protocol/source-element-selector.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,cAAc,EACd,iBAAiB,EACjB,YAAY,EAEZ,eAAe,EAEhB,MAAM,2BAA2B,CAAA;AAElC,oFAAoF;AACpF,eAAO,MAAM,oBAAoB,SAAU,MAAM,MAAM,MAAM,KAAG,eAAe,GAAG,IAuBjF,CAAA;AAED,0FAA0F;AAC1F,eAAO,MAAM,gBAAgB,aACjB,eAAe,WAChB,iBAAiB,YAChB,iBAAiB,EAAE,KAC5B,eAYF,CAAA;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,OAAO,CAAA;IACjB,UAAU,EAAE,MAAM,CAAA;IAClB,IAAI,EAAE,cAAc,CAAA;IACpB,QAAQ,EAAE,eAAe,CAAA;IACzB,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,+EAA+E;AAC/E,eAAO,MAAM,sBAAsB,UAC1B,eAAe,eACT,MAAM,EAAE,KACpB,WAoBF,CAAA;AAmBD,yFAAyF;AACzF,eAAO,MAAM,oBAAoB,SAAU,MAAM,GAAG,IAAI,KAAG,eAAe,GAAG,IA2B5E,CAAA;AAED,eAAO,MAAM,eAAe,SAAU,MAAM,GAAG,IAAI,KAAG,OAA8C,CAAA;AAEpG,eAAO,MAAM,iBAAiB,aAAc,eAAe,QAAQ,MAAM,KAAG,YAAY,GAAG,IAC7C,CAAA"}

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

@@ -0,0 +1,115 @@
+import { resolveElement } from "./source-element-match.js";
+import { neighborText } from "./source-element-neighbors.js";
+import { elementAlt, elementLabel, elementSrc, fingerprintOf, roleOf, } from "./source-element-properties.js";
+import { scanElements } from "./source-element-scan.js";
+/** Agents capture the same persisted selector as the browser for an authored id. */
+export const elementSelectorForId = (html, id) => {
+    const elements = scanElements(html);
+    const element = elements.find((candidate) => candidate.id === id);
+    if (!element)
+        return null;
+    const role = roleOf(element);
+    const src = elementSrc(element);
+    const alt = elementAlt(element);
+    return {
+        type: "ElementSelector",
+        tag: element.tag,
+        role,
+        id,
+        fingerprint: fingerprintOf(element),
+        ordinal: element.ordinal,
+        docFraction: element.srcFraction,
+        ...neighborText(elements, element.index),
+        snapshot: {
+            tag: element.tag,
+            label: elementLabel({ ...element, role }),
+            ...(src ? { src } : {}),
+            ...(alt ? { alt } : {}),
+        },
+    };
+};
+/** Each successful version hop updates identity while retaining the original snapshot. */
+export const rederiveSelector = (selector, element, elements) => {
+    const near = neighborText(elements, element.index);
+    return {
+        ...selector,
+        tag: element.tag,
+        id: element.id,
+        fingerprint: fingerprintOf(element),
+        ordinal: element.ordinal,
+        docFraction: element.srcFraction,
+        before: near.before ?? selector.before,
+        after: near.after ?? selector.after,
+    };
+};
+/** Ordered saved HTML lets an anchor recover through several small changes. */
+export const planElementForwardWalk = (start, versionHtml) => {
+    let selector = start;
+    let survived = 0;
+    let last = null;
+    for (const html of versionHtml) {
+        const elements = scanElements(html);
+        const match = resolveElement(selector, elements);
+        if (!match)
+            return { resolved: false, confidence: 0, band: "low", selector, survived };
+        const element = elements[match.index];
+        if (element)
+            selector = rederiveSelector(selector, element, elements);
+        last = match;
+        survived++;
+    }
+    return {
+        resolved: last !== null,
+        confidence: last?.confidence ?? 0,
+        band: last?.band ?? "low",
+        selector,
+        survived,
+    };
+};
+const stringOf = (value) => typeof value === "string" ? value : undefined;
+const numberOf = (value, fallback) => typeof value === "number" && Number.isFinite(value) ? value : fallback;
+const selectorObject = (json) => {
+    if (!json)
+        return null;
+    try {
+        const value = JSON.parse(json);
+        return value && typeof value === "object" && !Array.isArray(value)
+            ? value
+            : null;
+    }
+    catch {
+        return null;
+    }
+};
+/** Preserve the existing selector fields. Hostile scalar fields cannot break a sweep. */
+export const parseElementSelector = (json) => {
+    const value = selectorObject(json);
+    if (value?.["type"] !== "ElementSelector")
+        return null;
+    const tag = stringOf(value["tag"]);
+    const fingerprint = stringOf(value["fingerprint"]);
+    if (!tag || !fingerprint)
+        return null;
+    const snapshot = value["snapshot"];
+    return {
+        type: "ElementSelector",
+        tag,
+        role: (stringOf(value["role"]) ?? "block"),
+        id: stringOf(value["id"]),
+        css: stringOf(value["css"]),
+        fingerprint,
+        ordinal: numberOf(value["ordinal"], 0),
+        docFraction: Math.max(0, Math.min(1, numberOf(value["docFraction"], 0))),
+        before: stringOf(value["before"]),
+        after: stringOf(value["after"]),
+        snapshot: snapshot && typeof snapshot === "object"
+            ? snapshot
+            : { tag, label: tag },
+        slide: typeof value["slide"] === "number" && Number.isFinite(value["slide"])
+            ? value["slide"]
+            : undefined,
+    };
+};
+export const isElementAnchor = (json) => parseElementSelector(json) !== null;
+export const elementResolvesIn = (selector, html) => resolveElement(selector, scanElements(html));
+//# sourceMappingURL=source-element-selector.js.map

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

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

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

@@ -0,0 +1,79 @@
+/** Persisted element selectors retain their existing field names. */
+export type ElementRole = "image" | "chart" | "loop-step" | "loop-policy" | "loop-transition" | "graph-node" | "graph-edge" | "media" | "embed" | "table" | "code" | "figure" | "block";
+/** What the element looked like when the comment was made — shown when the live
+ *  element can no longer be found, so an orphaned comment still has a referent. */
+export interface ElementSnapshot {
+    tag: string;
+    /** Human descriptor, e.g. "Image — revenue.png", "Table (4×3)", "Embedded video". */
+    label: string;
+    /** Normalized text content (truncated). */
+    text?: string | undefined;
+    /** img/video/iframe/embed source, if any. */
+    src?: string | undefined;
+    /** alt / aria-label / title / caption, if any. */
+    alt?: string | undefined;
+    /** Displayed size at capture (for a placeholder aspect ratio). */
+    w?: number | undefined;
+    h?: number | undefined;
+    /** Truncated outerHTML for a visual preview. Sanitized again at render time. */
+    html?: string | undefined;
+}
+export interface ElementSelector {
+    type: "ElementSelector";
+    tag: string;
+    role: ElementRole;
+    /** Element id — only recorded when it looks authored (not a hashy/generated id). */
+    id?: string | undefined;
+    /** Structural css path (`tag:nth-of-type(n)` chain). Captured + verified in the
+     *  browser, where a real DOM exists; the server cascade skips it. */
+    css?: string | undefined;
+    /** Content hash over {tag, src, alt, leading text}. The single strongest signal. */
+    fingerprint: string;
+    /** 0-based index among same-tag elements in document order. */
+    ordinal: number;
+    /** Vertical position at capture as a fraction of the document (0..1) — "save
+     *  position". A weak geometric tiebreaker; the server approximates it from the
+     *  element's offset in the HTML source. */
+    docFraction: number;
+    /** Normalized text of the nearest preceding / following text-bearing block. */
+    before?: string | undefined;
+    after?: string | undefined;
+    snapshot: ElementSnapshot;
+    /** Deck artifacts only: the 0-based slide the comment was made on. */
+    slide?: number | undefined;
+}
+/** A flat, parent-free description of one element, the server-side stand-in for a
+ *  live DOM node (we ship no HTML parser, so `scanElements` builds these). */
+export interface ElementDescriptor {
+    tag: string;
+    id?: string | undefined;
+    classes: string[];
+    /** Selected attributes only (src/href/alt/title/aria-label/role/data-*). */
+    attrs: Record<string, string>;
+    /** Normalized subtree text (truncated). */
+    text: string;
+    /** 0-based index among same-tag elements, document order. */
+    ordinal: number;
+    /** Global element index in document order. */
+    index: number;
+    /** Index of the enclosing element (-1 at top level). Lets neighbour lookup skip
+     *  ancestors/descendants so a wrapped element (`<div><img><p>…`) resolves the same
+     *  preceding/following block the browser-side walk does. */
+    parent: number;
+    /** Start offset in the HTML source / total length (0..1) — geometry proxy. */
+    srcFraction: number;
+    /** Exact opening-tag span in the stored source. Element edits use this to change
+     *  attributes without serializing (and therefore rewriting) the rest of the page. */
+    sourceStart: number;
+    sourceEnd: number;
+}
+export type ConfidenceBand = "high" | "medium" | "low";
+export interface ElementMatch {
+    /** Index into the `ElementDescriptor[]` passed to `resolveElement`. */
+    index: number;
+    confidence: number;
+    band: ConfidenceBand;
+    /** Which signals agreed — useful for debugging + UI ("matched by id, content"). */
+    signals: string[];
+}
+//# sourceMappingURL=source-element-types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"source-element-types.d.ts","sourceRoot":"","sources":["../../src/protocol/source-element-types.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,MAAM,MAAM,WAAW,GACnB,OAAO,GACP,OAAO,GACP,WAAW,GACX,aAAa,GACb,iBAAiB,GACjB,YAAY,GACZ,YAAY,GACZ,OAAO,GACP,OAAO,GACP,OAAO,GACP,MAAM,GACN,QAAQ,GACR,OAAO,CAAA;AAEX;mFACmF;AACnF,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAA;IACX,qFAAqF;IACrF,KAAK,EAAE,MAAM,CAAA;IACb,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB,6CAA6C;IAC7C,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACxB,kDAAkD;IAClD,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACxB,kEAAkE;IAClE,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACtB,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACtB,gFAAgF;IAChF,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,iBAAiB,CAAA;IACvB,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,WAAW,CAAA;IACjB,oFAAoF;IACpF,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACvB;yEACqE;IACrE,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACxB,oFAAoF;IACpF,WAAW,EAAE,MAAM,CAAA;IACnB,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAA;IACf;;+CAE2C;IAC3C,WAAW,EAAE,MAAM,CAAA;IACnB,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC3B,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1B,QAAQ,EAAE,eAAe,CAAA;IACzB,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC3B;AAED;8EAC8E;AAC9E,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAA;IACX,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACvB,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC7B,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAA;IACZ,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAA;IACf,8CAA8C;IAC9C,KAAK,EAAE,MAAM,CAAA;IACb;;gEAE4D;IAC5D,MAAM,EAAE,MAAM,CAAA;IACd,8EAA8E;IAC9E,WAAW,EAAE,MAAM,CAAA;IACnB;yFACqF;IACrF,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAA;AAEtD,MAAM,WAAW,YAAY;IAC3B,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,EAAE,MAAM,CAAA;IAClB,IAAI,EAAE,cAAc,CAAA;IACpB,mFAAmF;IACnF,OAAO,EAAE,MAAM,EAAE,CAAA;CAClB"}

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=source-element-types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"source-element-types.js","sourceRoot":"","sources":["../../src/protocol/source-element-types.ts"],"names":[],"mappings":""}

package/dist/protocol/source-elements.d.ts

@@ -0,0 +1,7 @@
+export { resolveElement } from "./source-element-match.js";
+export { elementLabel, fingerprintOf, roleOf } from "./source-element-properties.js";
+export { scanElements } from "./source-element-scan.js";
+export { gradeElement } from "./source-element-score.js";
+export { elementResolvesIn, elementSelectorForId, type ForwardWalk, isElementAnchor, parseElementSelector, planElementForwardWalk, rederiveSelector, } from "./source-element-selector.js";
+export type * from "./source-element-types.js";
+//# sourceMappingURL=source-elements.d.ts.map

package/dist/protocol/source-elements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-elements.d.ts","sourceRoot":"","sources":["../../src/protocol/source-elements.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAA;AAC1D,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,gCAAgC,CAAA;AACpF,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AACxD,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,KAAK,WAAW,EAChB,eAAe,EACf,oBAAoB,EACpB,sBAAsB,EACtB,gBAAgB,GACjB,MAAM,8BAA8B,CAAA;AACrC,mBAAmB,2BAA2B,CAAA"}

package/dist/protocol/source-elements.js

@@ -0,0 +1,6 @@
+export { resolveElement } from "./source-element-match.js";
+export { elementLabel, fingerprintOf, roleOf } from "./source-element-properties.js";
+export { scanElements } from "./source-element-scan.js";
+export { gradeElement } from "./source-element-score.js";
+export { elementResolvesIn, elementSelectorForId, isElementAnchor, parseElementSelector, planElementForwardWalk, rederiveSelector, } from "./source-element-selector.js";
+//# sourceMappingURL=source-elements.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"source-elements.js","sourceRoot":"","sources":["../../src/protocol/source-elements.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAA;AAC1D,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,gCAAgC,CAAA;AACpF,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AACxD,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EAEpB,eAAe,EACf,oBAAoB,EACpB,sBAAsB,EACtB,gBAAgB,GACjB,MAAM,8BAA8B,CAAA"}

package/dist/protocol/source-entities.d.ts

@@ -0,0 +1,17 @@
+import { DecodingMode } from "entities/decode";
+export declare const ENTITY_RE: RegExp;
+export interface DecodedEntity {
+    start: number;
+    end: number;
+    text: string;
+}
+/** Browser-compatible character references and their exact raw spans. The entity
+ *  decoder reports how many source characters it consumed, which is essential for
+ *  mapping legacy semicolonless names and multi-code-point named entities back to
+ *  authored bytes without guessing. */
+export declare function decodedEntitiesIn(input: string, from?: number, to?: number, mode?: DecodingMode): DecodedEntity[];
+/** Decode numeric character references and the common named entities the browser
+ *  would. Unknown named entities pass through untouched. Shared by `pageText` and
+ *  the doc-text markdown conversion so both read an `&` the same way. */
+export declare function decodeEntities(s: string): string;
+//# sourceMappingURL=source-entities.d.ts.map

package/dist/protocol/source-entities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-entities.d.ts","sourceRoot":"","sources":["../../src/protocol/source-entities.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAA6C,MAAM,iBAAiB,CAAA;AAEzF,eAAO,MAAM,SAAS,EAAE,MAAiE,CAAA;AAEzF,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;CACb;AAED;;;uCAGuC;AACvC,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,MAAU,EAChB,EAAE,GAAE,MAAqB,EACzB,IAAI,GAAE,YAAkC,GACvC,aAAa,EAAE,CA0BjB;AAED;;6EAE6E;AAC7E,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEhD"}

package/dist/protocol/source-entities.js

@@ -0,0 +1,45 @@
+import { DecodingMode, decodeHTML, EntityDecoder, htmlDecodeTree } from "entities/decode";
+export const ENTITY_RE = /&(?:#(?:x[0-9a-fA-F]+|[0-9]+)|[a-zA-Z][a-zA-Z0-9]+);?/g;
+/** Browser-compatible character references and their exact raw spans. The entity
+ *  decoder reports how many source characters it consumed, which is essential for
+ *  mapping legacy semicolonless names and multi-code-point named entities back to
+ *  authored bytes without guessing. */
+export function decodedEntitiesIn(input, from = 0, to = input.length, mode = DecodingMode.Legacy) {
+    const out = [];
+    let decoded = "";
+    const decoder = new EntityDecoder(htmlDecodeTree, (cp) => {
+        decoded += cp === 0xa0 ? " " : String.fromCodePoint(cp);
+    });
+    let cursor = from;
+    for (;;) {
+        // `indexOf("&", cursor)` has no end bound. When this helper runs once per visible
+        // text run, an entity-free run near the start of a large document would scan every
+        // later run again before the result was rejected as `>= to`. Walk only this run so
+        // all calls made by one page projection examine each source character at most once.
+        let amp = cursor;
+        while (amp < to && input.charCodeAt(amp) !== 38)
+            amp++;
+        if (amp >= to)
+            break;
+        decoded = "";
+        decoder.startEntity(mode);
+        let consumed = decoder.write(input, amp + 1);
+        if (consumed < 0)
+            consumed = decoder.end();
+        const end = amp + consumed;
+        if (consumed > 1 && decoded && end <= to) {
+            out.push({ start: amp, end, text: decoded });
+            cursor = end;
+        }
+        else
+            cursor = amp + 1;
+    }
+    return out;
+}
+/** Decode numeric character references and the common named entities the browser
+ *  would. Unknown named entities pass through untouched. Shared by `pageText` and
+ *  the doc-text markdown conversion so both read an `&amp;` the same way. */
+export function decodeEntities(s) {
+    return decodeHTML(s, DecodingMode.Legacy).replaceAll("\u00a0", " ");
+}
+//# sourceMappingURL=source-entities.js.map