From d50fb7678da6baf94f9258865386a4bd22d81072 Mon Sep 17 00:00:00 2001
From: FND <fndevve@proton.me>
Date: Wed, 16 Sep 2026 13:16:35 +0200
Subject: [PATCH 1/4] feat(core): carry elementContext through html-anchor host
 helpers

Persist and project elementContext through the core host helpers; move the validator into core and drop the ui mirror; add outline-less export option.

Closes #1521.
---
 packages/core/html-anchor.test.ts             | 218 ++++++++++++++++++
 packages/core/html-anchor.ts                  | 215 ++++++++++++++++-
 .../html-viewer/useHtmlAnnotation.ts          | 156 +------------
 packages/ui/utils/parser.test.ts              |  46 +++-
 packages/ui/utils/parser.ts                   |  12 +-
 5 files changed, 490 insertions(+), 157 deletions(-)

diff --git a/packages/core/html-anchor.test.ts b/packages/core/html-anchor.test.ts
index 256f9954a..0cb15c3a5 100644
--- a/packages/core/html-anchor.test.ts
+++ b/packages/core/html-anchor.test.ts
@@ -15,7 +15,9 @@ import { describe, expect, test } from "bun:test";
 import {
   buildPersistedHtmlAnchor,
   DEFAULT_HTML_ANCHOR_MAX_BYTES,
+  MAX_ELEMENT_CONTEXT_BYTES,
   MAX_HTML_ADDITIONAL_TARGETS,
+  parseHtmlElementContext,
   projectHostThreads,
   type HostThread,
 } from "./html-anchor";
@@ -47,6 +49,98 @@ describe("buildPersistedHtmlAnchor", () => {
     expect(Object.keys(reordered.anchor.htmlAdditionalTargets![0]!)).toEqual(["text", "label", "anchor"]);
   });
 
+  test("rows without elementContext serialize byte-identically and pin wire fingerprint", () => {
+    // Failure caught: changing the serialization format or introducing undefined/extra keys
+    // for rows that do not carry elementContext, which breaks host wire fingerprints.
+    const withoutContext = {
+      originalText: "Text quote",
+      htmlAnchor: { selector: "p.lead", tagName: "p", text: "Text" },
+      htmlAdditionalTargets: [
+        { text: "Target", label: "Label", anchor: { selector: "#t1", tagName: "div" } },
+      ],
+    };
+    const result = buildPersistedHtmlAnchor(withoutContext);
+    expect(JSON.stringify(result.anchor)).toBe(JSON.stringify(withoutContext));
+    expect(Object.keys(result.anchor)).toEqual(["originalText", "htmlAnchor", "htmlAdditionalTargets"]);
+    expect("elementContext" in result.anchor).toBe(false);
+
+    // When elementContext IS present, it serializes strictly after htmlAdditionalTargets
+    const withContext = {
+      ...withoutContext,
+      elementContext: { tag: "p", id: "lead-para" },
+    };
+    const resultWithContext = buildPersistedHtmlAnchor(withContext);
+    expect(Object.keys(resultWithContext.anchor)).toEqual([
+      "originalText",
+      "htmlAnchor",
+      "htmlAdditionalTargets",
+      "elementContext",
+    ]);
+  });
+
+  test("shed order: per-target contexts shed first, then primary context, before dropping targets under small maxBytes", () => {
+    // Failure caught: dropping targets prematurely while expendable contexts remain,
+    // losing user-selected targets instead of shedding descriptive context.
+    const targetContext1 = { tag: "button", path: "body > form > button:nth-of-type(1)", outline: "<button>1</button>" };
+    const targetContext2 = { tag: "button", path: "body > form > button:nth-of-type(2)", outline: "<button>2</button>" };
+    const primaryContext = { tag: "form", path: "body > form#action-form", outline: "<form>…</form>" };
+
+    const source = {
+      originalText: "Save changes",
+      htmlAnchor: { selector: "form#action-form", tagName: "form" },
+      htmlAdditionalTargets: [
+        { text: "Btn 1", anchor: { selector: "button.save", tagName: "button" }, context: targetContext1 },
+        { text: "Btn 2", anchor: { selector: "button.cancel", tagName: "button" }, context: targetContext2 },
+      ],
+      elementContext: primaryContext,
+    };
+
+    // Full anchor with all contexts
+    const full = buildPersistedHtmlAnchor(source);
+    const fullBytes = bytes(full.anchor);
+    expect(full.anchor.elementContext).toBeDefined();
+    expect(full.anchor.htmlAdditionalTargets?.[0]?.context).toBeDefined();
+    expect(full.anchor.htmlAdditionalTargets?.[1]?.context).toBeDefined();
+    expect(full.anchor.htmlAdditionalTargets?.length).toBe(2);
+
+    // Budget just small enough to force shedding the last target's context
+    const budget1 = fullBytes - 30;
+    const res1 = buildPersistedHtmlAnchor(source, { maxBytes: budget1 });
+    expect(bytes(res1.anchor)).toBeLessThanOrEqual(budget1);
+    expect(res1.anchor.htmlAdditionalTargets?.length).toBe(2);
+    expect(res1.anchor.htmlAdditionalTargets?.[0]?.context).toBeDefined();
+    // Last target's context was shed first
+    expect(res1.anchor.htmlAdditionalTargets?.[1]?.context).toBeUndefined();
+    expect(res1.anchor.elementContext).toBeDefined();
+    expect(res1.droppedTargets).toBe(0);
+
+    // Budget small enough to shed all per-target contexts and primary context, but keep targets
+    const baseWithoutContexts = buildPersistedHtmlAnchor({
+      originalText: source.originalText,
+      htmlAnchor: source.htmlAnchor,
+      htmlAdditionalTargets: [
+        { text: "Btn 1", anchor: { selector: "button.save", tagName: "button" } },
+        { text: "Btn 2", anchor: { selector: "button.cancel", tagName: "button" } },
+      ],
+    });
+    const budgetNoContexts = bytes(baseWithoutContexts.anchor) + 10;
+    const res2 = buildPersistedHtmlAnchor(source, { maxBytes: budgetNoContexts });
+    expect(bytes(res2.anchor)).toBeLessThanOrEqual(budgetNoContexts);
+    // Both target contexts and primary context shed, but targets remain
+    expect(res2.anchor.htmlAdditionalTargets?.length).toBe(2);
+    expect(res2.anchor.htmlAdditionalTargets?.[0]?.context).toBeUndefined();
+    expect(res2.anchor.htmlAdditionalTargets?.[1]?.context).toBeUndefined();
+    expect(res2.anchor.elementContext).toBeUndefined();
+    expect(res2.droppedTargets).toBe(0);
+
+    // Even smaller budget: now targets are dropped from the end
+    const budgetDropTarget = bytes(baseWithoutContexts.anchor) - 20;
+    const res3 = buildPersistedHtmlAnchor(source, { maxBytes: budgetDropTarget });
+    expect(bytes(res3.anchor)).toBeLessThanOrEqual(budgetDropTarget);
+    expect(res3.anchor.htmlAdditionalTargets?.length).toBe(1);
+    expect(res3.sizeDroppedTargets).toBe(1);
+  });
+
   test("a drag capture without an element anchor writes exactly the legacy shape", () => {
     const result = buildPersistedHtmlAnchor({ originalText: "plain quote" });
     expect(result.anchor).toEqual({ originalText: "plain quote" });
@@ -224,6 +318,56 @@ describe("projectHostThreads", () => {
     expect(gamma?.htmlAdditionalTargets).toEqual([{ label: "Button", text: "Go", anchor: { selector: "#go", tagName: "button", text: "Go" } }]);
   });
 
+  test("projection carries validated primary elementContext and target contexts", () => {
+    // Failure caught: host panels and copy actions dropping elementContext and per-target
+    // context during projection from stored host rows onto viewer annotations.
+    const threadWithContext: HostThread = {
+      id: "ctx1",
+      originalText: "Quoted",
+      htmlAnchor: { selector: "#main", tagName: "main" },
+      elementContext: {
+        tag: "MAIN",
+        id: "main-content",
+        classes: ["content"],
+        role: "main",
+      },
+      htmlAdditionalTargets: [
+        {
+          text: "Extra target",
+          label: "Section",
+          anchor: { selector: "section#s1", tagName: "section" },
+          context: { tag: "SECTION", id: "s1" },
+        },
+      ],
+    };
+    const projected = projectHostThreads([threadWithContext]);
+    expect(projected.length).toBe(1);
+    expect(projected[0]?.elementContext).toEqual({
+      tag: "main",
+      id: "main-content",
+      classes: ["content"],
+      role: "main",
+    });
+    expect(projected[0]?.htmlAdditionalTargets?.[0]?.context).toEqual({
+      tag: "section",
+      id: "s1",
+    });
+
+    // Malformed context fails closed to undefined without dropping the annotation
+    const threadWithGarbage: HostThread = {
+      id: "ctx2",
+      originalText: "Quoted 2",
+      elementContext: { tag: "" } as any,
+      htmlAdditionalTargets: [
+        { text: "Extra", context: null as any },
+      ],
+    };
+    const projectedGarbage = projectHostThreads([threadWithGarbage]);
+    expect(projectedGarbage[0]?.elementContext).toBeUndefined();
+    expect(projectedGarbage[0]?.htmlAdditionalTargets?.[0]?.context).toBeUndefined();
+    expect(projectedGarbage[0]?.originalText).toBe("Quoted 2");
+  });
+
   test("is pure: the same input projects the same output and never mutates it", () => {
     const frozen = JSON.stringify(rows);
     const a = projectHostThreads(rows, { openOnly: true });
@@ -232,3 +376,77 @@ describe("projectHostThreads", () => {
     expect(JSON.stringify(rows)).toBe(frozen);
   });
 });
+
+describe("parseHtmlElementContext", () => {
+  test("accepts what the bridge builds and fails closed on garbage", () => {
+    // Failure caught: forged or malformed bridge context messages crashing the host
+    // or injecting unvalidated page-controlled content into storage.
+    expect(parseHtmlElementContext(null)).toBeUndefined();
+    expect(parseHtmlElementContext(undefined)).toBeUndefined();
+    expect(parseHtmlElementContext("not-an-object")).toBeUndefined();
+    expect(parseHtmlElementContext({})).toBeUndefined();
+    expect(parseHtmlElementContext({ tag: "" })).toBeUndefined();
+    expect(parseHtmlElementContext({ tag: "   " })).toBeUndefined();
+
+    // Valid context with lowercased tag and parsed fields
+    const valid = parseHtmlElementContext({
+      tag: "BUTTON",
+      id: "submit-btn",
+      classes: ["btn", "btn-primary"],
+      path: "body > form > button",
+      role: "button",
+      name: "Submit form",
+      attrs: [["type", "submit"], ["aria-label", "Submit form"], ["onclick", "steal()"]],
+      text: "Submit",
+      outline: "<button type=\"submit\">\n```\nSubmit\n</button>",
+      children: 1.9,
+      rect: { x: 10, y: 20, w: 100, h: 40, vw: 1280, vh: 800 },
+      landmark: "main",
+      heading: "h1 \"Checkout\"",
+      component: "data-component=SubmitBtn",
+      page: { url: "/checkout?step=2", title: "Checkout" },
+    });
+    expect(valid).toBeDefined();
+    expect(valid?.tag).toBe("button");
+    expect(valid?.id).toBe("submit-btn");
+    expect(valid?.classes).toEqual(["btn", "btn-primary"]);
+    expect(valid?.path).toBe("body > form > button");
+    expect(valid?.role).toBe("button");
+    expect(valid?.name).toBe("Submit form");
+    // Non-allowlisted attribute onclick was dropped
+    expect(valid?.attrs).toEqual([["type", "submit"], ["aria-label", "Submit form"]]);
+    expect(valid?.text).toBe("Submit");
+    // Fenced backticks defused
+    expect(valid?.outline).not.toContain("```");
+    expect(valid?.outline).toContain("'''");
+    // Children floored
+    expect(valid?.children).toBe(1);
+    expect(valid?.rect).toEqual({ x: 10, y: 20, w: 100, h: 40, vw: 1280, vh: 800 });
+    expect(valid?.landmark).toBe("main");
+    expect(valid?.heading).toBe("h1 \"Checkout\"");
+    expect(valid?.component).toBe("data-component=SubmitBtn");
+    expect(valid?.page).toEqual({ url: "/checkout?step=2", title: "Checkout" });
+
+    // Non-finite rect is dropped whole
+    const badRect = parseHtmlElementContext({ tag: "div", rect: { x: NaN, y: 0, w: 10, h: 10, vw: 100, vh: 100 } });
+    expect(badRect?.rect).toBeUndefined();
+
+    // Unknown keys dropped
+    const extraKeys = parseHtmlElementContext({ tag: "div", unknownKey: "evil", innerHTML: "<script>" });
+    expect(extraKeys).toEqual({ tag: "div" });
+    expect("unknownKey" in (extraKeys ?? {})).toBe(false);
+
+    // Bounds enforced: contextBytes <= MAX_ELEMENT_CONTEXT_BYTES
+    const huge = "x".repeat(5000);
+    const oversized = parseHtmlElementContext({
+      tag: "div",
+      text: huge,
+      outline: huge,
+      path: huge,
+      classes: Array(30).fill("c"),
+      attrs: Array(30).fill(["title", "t"]),
+    });
+    expect(oversized).toBeDefined();
+    expect(bytes(oversized)).toBeLessThanOrEqual(MAX_ELEMENT_CONTEXT_BYTES);
+  });
+});
diff --git a/packages/core/html-anchor.ts b/packages/core/html-anchor.ts
index ca646ddf0..8e28453aa 100644
--- a/packages/core/html-anchor.ts
+++ b/packages/core/html-anchor.ts
@@ -31,6 +31,38 @@ export interface HtmlAnnotationTarget {
   label?: string;
   text: string;
   anchor?: HtmlElementAnchor;
+  context?: HtmlElementContext;
+}
+
+export interface HtmlElementContext {
+  tag: string;
+  id?: string;
+  /** Author classes, generated/hashed ones skipped; may end in "+N more". */
+  classes?: string[];
+  /** Ancestor path, e.g. `body > div#root > header.site-header > nav#site-nav`. */
+  path?: string;
+  /** Explicit `role` or the tag's implicit ARIA role. */
+  role?: string;
+  /** Accessible name: aria-label, aria-labelledby, alt, title, <label for>, own short text. */
+  name?: string;
+  /** Allowlisted attributes in a fixed order (href/src scrubbed of query and fragment). */
+  attrs?: Array<[string, string]>;
+  /** Rendered text (innerText), whitespace-collapsed, word-boundary truncated. */
+  text?: string;
+  /** Collapsed HTML skeleton: opening tag with allowlisted attributes, then children as bare tags. */
+  outline?: string;
+  /** Number of element children (after skipping script/style/template and viewer overlays). */
+  children?: number;
+  /** Viewport-relative bounding box plus the viewport it was seen at. */
+  rect?: { x: number; y: number; w: number; h: number; vw: number; vh: number };
+  /** Nearest enclosing landmark/region, e.g. `header.site-header "Primary"`. */
+  landmark?: string;
+  /** Nearest preceding heading, e.g. `h2 "Usage"`. */
+  heading?: string;
+  /** Nearest author component marker, e.g. `data-component=AppNav`. */
+  component?: string;
+  /** Live-app sessions only: the route the element was seen on and the page title. */
+  page?: { url: string; title?: string };
 }
 
 /** Mirrors `MAX_ANCHOR_SELECTOR_LENGTH` in `@plannotator/ui`. */
@@ -51,6 +83,32 @@ export const MAX_HTML_TARGET_TEXT_LENGTH = 400;
 export const MAX_HTML_ADDITIONAL_TARGETS = 16;
 /** Default byte budget for a persisted anchor (16 KiB of UTF-8 JSON). */
 export const DEFAULT_HTML_ANCHOR_MAX_BYTES = 16 * 1024;
+export const MAX_ELEMENT_CONTEXT_BYTES = 2048;
+export const MAX_PAGE_URL_LENGTH = 2048;
+const MAX_CONTEXT_TAG_LENGTH = 32;
+const MAX_CONTEXT_ID_LENGTH = 100;
+const MAX_CONTEXT_CLASSES = 9; // 8 + the "+N more" marker
+const MAX_CONTEXT_CLASS_LENGTH = 48;
+const MAX_CONTEXT_PATH_LENGTH = 512;
+const MAX_CONTEXT_ROLE_LENGTH = 32;
+const MAX_CONTEXT_NAME_LENGTH = 120;
+const MAX_CONTEXT_ATTRS = 10;
+const MAX_CONTEXT_ATTR_NAME_LENGTH = 40;
+const MAX_CONTEXT_ATTR_VALUE_LENGTH = 120;
+const MAX_CONTEXT_TEXT_LENGTH = 300;
+const MAX_CONTEXT_OUTLINE_LENGTH = 600;
+const MAX_CONTEXT_OUTLINE_LINES = 40;
+const MAX_CONTEXT_LANDMARK_LENGTH = 80;
+const MAX_CONTEXT_HEADING_LENGTH = 130;
+const MAX_CONTEXT_COMPONENT_LENGTH = 100;
+const MAX_CONTEXT_PAGE_TITLE_LENGTH = 200;
+
+/** Attribute names the context may carry (mirrors CONTEXT_ATTRS in the bridge). */
+export const CONTEXT_ATTR_ALLOWLIST = new Set([
+  "href", "src", "alt", "title", "type", "name", "role", "placeholder", "for", "target", "rel",
+  "aria-label", "aria-labelledby", "aria-describedby", "aria-current", "aria-expanded", "aria-hidden", "aria-controls",
+  "data-annotate", "data-testid", "data-test", "data-test-id", "data-cy", "data-qa", "data-component", "data-id",
+]);
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null;
@@ -101,6 +159,122 @@ export function parseHtmlElementAnchor(value: unknown): HtmlElementAnchor | null
   return { selector, tagName, text, ...(point ? { point } : {}) };
 }
 
+/** Collapse control characters and whitespace runs, then cap. */
+function collapseContextScalar(value: unknown, max: number): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const collapsed = value.replace(/[\x00-\x1f\x7f]+/g, " ").replace(/\s+/g, " ").trim();
+  if (!collapsed) return undefined;
+  return collapsed.length > max ? truncateSurrogateSafe(collapsed, max) : collapsed;
+}
+
+/** The outline keeps its line breaks (it is fenced on export) but nothing
+ *  else: control characters go, each line is whitespace-collapsed, and a
+ *  backtick run that could close the export's fence is defused. */
+function collapseContextOutline(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const lines = value
+    .replace(/[\x00-\x09\x0b-\x1f\x7f]+/g, " ")
+    .replace(/`{3,}/g, "'''")
+    .split("\n")
+    .map((line) => {
+      // Keep the skeleton's indentation (capped), collapse everything else.
+      const indent = (/^ */.exec(line)?.[0] ?? "").slice(0, 12);
+      return indent + line.slice(indent.length).replace(/\s+/g, " ").trim();
+    })
+    .filter((line) => line.trim().length > 0)
+    .slice(0, MAX_CONTEXT_OUTLINE_LINES);
+  const joined = lines.join("\n").trim();
+  if (!joined) return undefined;
+  return joined.length > MAX_CONTEXT_OUTLINE_LENGTH ? truncateSurrogateSafe(joined, MAX_CONTEXT_OUTLINE_LENGTH) : joined;
+}
+
+function contextBytes(value: unknown): number {
+  return new TextEncoder().encode(JSON.stringify(value)).length;
+}
+
+/**
+ * Validate a bridge-posted element context. Pure and fail-closed: returns
+ * `undefined` if `value` is not a valid element context or tag is missing/empty.
+ * Every scalar is re-collapsed (control characters and whitespace runs),
+ * attributes are filtered to the allowlist, and unknown keys are dropped.
+ * If the serialized context exceeds MAX_ELEMENT_CONTEXT_BYTES, expendable
+ * fields are shed in order until it fits.
+ */
+export function parseHtmlElementContext(value: unknown): HtmlElementContext | undefined {
+  if (!isRecord(value)) return undefined;
+  const tag = collapseContextScalar(value.tag, MAX_CONTEXT_TAG_LENGTH);
+  if (!tag) return undefined;
+  const context: HtmlElementContext = { tag: tag.toLowerCase() };
+  const id = collapseContextScalar(value.id, MAX_CONTEXT_ID_LENGTH);
+  if (id) context.id = id;
+  if (Array.isArray(value.classes)) {
+    const classes: string[] = [];
+    for (const entry of value.classes) {
+      if (classes.length >= MAX_CONTEXT_CLASSES) break;
+      const cls = collapseContextScalar(entry, MAX_CONTEXT_CLASS_LENGTH);
+      if (cls) classes.push(cls);
+    }
+    if (classes.length) context.classes = classes;
+  }
+  const path = collapseContextScalar(value.path, MAX_CONTEXT_PATH_LENGTH);
+  if (path) context.path = path;
+  const role = collapseContextScalar(value.role, MAX_CONTEXT_ROLE_LENGTH);
+  if (role) context.role = role;
+  const name = collapseContextScalar(value.name, MAX_CONTEXT_NAME_LENGTH);
+  if (name) context.name = name;
+  if (Array.isArray(value.attrs)) {
+    const attrs: Array<[string, string]> = [];
+    for (const entry of value.attrs) {
+      if (attrs.length >= MAX_CONTEXT_ATTRS) break;
+      if (!Array.isArray(entry) || entry.length !== 2) continue;
+      const attrName = collapseContextScalar(entry[0], MAX_CONTEXT_ATTR_NAME_LENGTH);
+      if (!attrName || !CONTEXT_ATTR_ALLOWLIST.has(attrName.toLowerCase())) continue;
+      if (typeof entry[1] !== "string") continue;
+      attrs.push([attrName.toLowerCase(), collapseContextScalar(entry[1], MAX_CONTEXT_ATTR_VALUE_LENGTH) ?? ""]);
+    }
+    if (attrs.length) context.attrs = attrs;
+  }
+  const text = collapseContextScalar(value.text, MAX_CONTEXT_TEXT_LENGTH);
+  if (text) context.text = text;
+  const outline = collapseContextOutline(value.outline);
+  if (outline) context.outline = outline;
+  if (typeof value.children === "number" && Number.isFinite(value.children) && value.children >= 0) {
+    context.children = Math.min(100000, Math.floor(value.children));
+  }
+  if (isRecord(value.rect)) {
+    const rect = value.rect;
+    const nums = ["x", "y", "w", "h", "vw", "vh"].map((key) => {
+      const n = rect[key];
+      return typeof n === "number" && Number.isFinite(n) ? Math.round(Math.max(-1e6, Math.min(1e6, n))) : null;
+    });
+    if (nums.every((n) => n !== null)) {
+      const [x, y, w, h, vw, vh] = nums as number[];
+      context.rect = { x: x!, y: y!, w: w!, h: h!, vw: vw!, vh: vh! };
+    }
+  }
+  const landmark = collapseContextScalar(value.landmark, MAX_CONTEXT_LANDMARK_LENGTH);
+  if (landmark) context.landmark = landmark;
+  const heading = collapseContextScalar(value.heading, MAX_CONTEXT_HEADING_LENGTH);
+  if (heading) context.heading = heading;
+  const component = collapseContextScalar(value.component, MAX_CONTEXT_COMPONENT_LENGTH);
+  if (component) context.component = component;
+  if (isRecord(value.page)) {
+    const url = collapseContextScalar(value.page.url, MAX_PAGE_URL_LENGTH);
+    if (url) {
+      context.page = { url };
+      const title = collapseContextScalar(value.page.title, MAX_CONTEXT_PAGE_TITLE_LENGTH);
+      if (title) context.page.title = title;
+    }
+  }
+  // Serialized bound: shed the expendable fields in the bridge's order until the whole fits.
+  const shedOrder: Array<keyof HtmlElementContext> = ["outline", "text", "attrs", "classes", "path", "heading", "landmark", "component"];
+  for (const field of shedOrder) {
+    if (contextBytes(context) <= MAX_ELEMENT_CONTEXT_BYTES) break;
+    delete context[field];
+  }
+  return contextBytes(context) <= MAX_ELEMENT_CONTEXT_BYTES ? context : undefined;
+}
+
 /**
  * Validate stored additional targets. A target needs its display text; a
  * broken per-target anchor or label is dropped, not fatal (the target still
@@ -117,9 +291,10 @@ export function parseHtmlAdditionalTargets(
   for (const entry of value) {
     if (targets.length >= maxTargets) break;
     if (!isRecord(entry)) continue;
-    const { label, text, anchor } = entry;
+    const { label, text, anchor, context } = entry;
     if (typeof text !== "string" || text.length === 0) continue;
     const parsedAnchor = parseHtmlElementAnchor(anchor);
+    const parsedContext = parseHtmlElementContext(context);
     const validLabel =
       typeof label === "string" && label.length > 0 && label.length <= MAX_HTML_TARGET_LABEL_LENGTH
         ? label
@@ -128,6 +303,7 @@ export function parseHtmlAdditionalTargets(
       ...(validLabel !== undefined ? { label: validLabel } : {}),
       text: truncateSurrogateSafe(text, MAX_HTML_TARGET_TEXT_LENGTH),
       ...(parsedAnchor !== null ? { anchor: parsedAnchor } : {}),
+      ...(parsedContext !== undefined ? { context: parsedContext } : {}),
     });
   }
   return targets;
@@ -140,6 +316,7 @@ export interface PersistedHtmlAnchor {
   originalText: string;
   htmlAnchor?: HtmlElementAnchor;
   htmlAdditionalTargets?: HtmlAnnotationTarget[];
+  elementContext?: HtmlElementContext;
 }
 
 export interface BuildPersistedHtmlAnchorOptions {
@@ -195,6 +372,7 @@ export function buildPersistedHtmlAnchor(
     originalText: string;
     htmlAnchor?: HtmlElementAnchor | null;
     htmlAdditionalTargets?: readonly HtmlAnnotationTarget[] | null;
+    elementContext?: HtmlElementContext | null;
   },
   options: BuildPersistedHtmlAnchorOptions = {},
 ): PersistedHtmlAnchorResult {
@@ -203,8 +381,9 @@ export function buildPersistedHtmlAnchor(
   // Persist-side validation mirrors the read side: bounds and shape are
   // enforced on what is written, not only on what is later read back.
   const htmlAnchor = parseHtmlElementAnchor(source.htmlAnchor) ?? undefined;
+  let elementContext = parseHtmlElementContext(source.elementContext);
   const drafted = source.htmlAdditionalTargets ?? [];
-  // Kept-target key order is text, label, anchor: the order the reference
+  // Kept-target key order is text, label, anchor, context: the order the reference
   // host implementation persisted, so a stored anchor's serialization (and
   // any fingerprint over it) does not change when a host adopts this helper.
   let kept = drafted.slice(0, Math.max(0, maxTargets)).map((target) => {
@@ -216,6 +395,8 @@ export function buildPersistedHtmlAnchor(
     }
     const targetAnchor = parseHtmlElementAnchor(target.anchor);
     if (targetAnchor !== null) entry.anchor = targetAnchor;
+    const targetContext = parseHtmlElementContext(target.context);
+    if (targetContext !== undefined) entry.context = targetContext;
     return entry;
   });
   const capDroppedTargets = drafted.length - kept.length;
@@ -225,6 +406,7 @@ export function buildPersistedHtmlAnchor(
     originalText,
     ...(htmlAnchor !== undefined ? { htmlAnchor } : {}),
     ...(kept.length > 0 ? { htmlAdditionalTargets: kept } : {}),
+    ...(elementContext !== undefined ? { elementContext } : {}),
   });
 
   let anchor = compose();
@@ -244,15 +426,31 @@ export function buildPersistedHtmlAnchor(
     }
   };
 
-  // Byte budget, exact over the serialized JSON, in three stages: quote down
-  // to its useful floor, then targets from the end, then the rest of the
-  // quote (only reachable if the base anchor plus a floor-length quote alone
-  // overflow, which validated bounds make unreachable with the default budget).
+  // Byte budget, exact over the serialized JSON, in four stages:
+  // 1. Quote down to its useful floor.
   truncateQuoteWhileOver(Math.min(MIN_USEFUL_QUOTE_LENGTH, originalText.length));
+
+  // 2. Shed contexts (per-target first from the end, then primary) before dropping targets.
+  for (let i = kept.length - 1; i >= 0 && serializedAnchorBytes(anchor) > maxBytes; i--) {
+    if (kept[i]?.context !== undefined) {
+      const { context: _, ...rest } = kept[i]!;
+      kept[i] = rest;
+      anchor = compose();
+    }
+  }
+  if (serializedAnchorBytes(anchor) > maxBytes && elementContext !== undefined) {
+    elementContext = undefined;
+    anchor = compose();
+  }
+
+  // 3. Targets from the end.
   while (serializedAnchorBytes(anchor) > maxBytes && kept.length > 0) {
     kept = kept.slice(0, kept.length - 1);
     anchor = compose();
   }
+
+  // 4. Rest of the quote (only reachable if the base anchor plus a floor-length quote alone
+  // overflow, which validated bounds make unreachable with the default budget).
   truncateQuoteWhileOver(0);
   const sizeDroppedTargets =
     drafted.length - capDroppedTargets - (anchor.htmlAdditionalTargets?.length ?? 0);
@@ -271,6 +469,8 @@ export interface HostThread {
   originalText: string;
   htmlAnchor?: HtmlElementAnchor | null;
   htmlAdditionalTargets?: readonly HtmlAnnotationTarget[] | null;
+  /** Agent-facing element context for the primary target. */
+  elementContext?: HtmlElementContext | null;
   /** Thread state. Absent means the host has no state concept: the row is open. */
   state?: "open" | "resolved" | string;
   /** Optional presentational fields carried verbatim onto the projection. */
@@ -323,6 +523,7 @@ export interface ProjectedHostAnnotation {
   images?: Array<{ path: string; name: string }>;
   htmlAnchor?: HtmlElementAnchor;
   htmlAdditionalTargets?: HtmlAnnotationTarget[];
+  elementContext?: HtmlElementContext;
 }
 
 /**
@@ -360,6 +561,7 @@ export function projectHostThreads(
     if (options.openOnly && thread.state !== undefined && thread.state !== "open") continue;
     const htmlAnchor = parseHtmlElementAnchor(thread.htmlAnchor);
     const htmlAdditionalTargets = parseHtmlAdditionalTargets(thread.htmlAdditionalTargets, maxTargets);
+    const elementContext = parseHtmlElementContext(thread.elementContext);
     const originalText = typeof thread.originalText === "string" ? thread.originalText : "";
     const anchorless = originalText === "" && htmlAnchor === null;
     out.push({
@@ -375,6 +577,7 @@ export function projectHostThreads(
       ...(thread.images && thread.images.length > 0 ? { images: thread.images.map((image) => ({ ...image })) } : {}),
       ...(htmlAnchor !== null ? { htmlAnchor } : {}),
       ...(htmlAdditionalTargets.length > 0 ? { htmlAdditionalTargets } : {}),
+      ...(elementContext !== undefined ? { elementContext } : {}),
     });
   }
   return out;
diff --git a/packages/ui/components/html-viewer/useHtmlAnnotation.ts b/packages/ui/components/html-viewer/useHtmlAnnotation.ts
index 944e9ae0d..9b95f80b8 100644
--- a/packages/ui/components/html-viewer/useHtmlAnnotation.ts
+++ b/packages/ui/components/html-viewer/useHtmlAnnotation.ts
@@ -9,6 +9,10 @@ import type {
   UseAnnotationHighlighterReturn,
 } from "../../hooks/useAnnotationHighlighter";
 import { BRIDGE_PROTOCOL_VERSION } from "./bridge-script";
+import {
+  parseHtmlElementContext,
+  MAX_ELEMENT_CONTEXT_BYTES,
+} from "@plannotator/core/html-anchor";
 
 const PREFIX = "plannotator-bridge-";
 
@@ -326,154 +330,10 @@ function parseTargetLabel(value: unknown): string | undefined {
     : collapsed;
 }
 
-// Element-context caps. The bridge builds the context under the same numbers,
-// but this side is the authoritative one: every scalar is re-collapsed (a
-// hostile page can embed newlines that would become markdown structure in the
-// exported feedback), every list re-capped, unknown keys dropped, and the
-// serialized whole bounded. A malformed context is DROPPED, never fatal to
-// the annotation it rides on (the same additive rule as the anchor point).
-export const MAX_ELEMENT_CONTEXT_BYTES = 2048;
-const MAX_CONTEXT_TAG_LENGTH = 32;
-const MAX_CONTEXT_ID_LENGTH = 100;
-const MAX_CONTEXT_CLASSES = 9; // 8 + the "+N more" marker
-const MAX_CONTEXT_CLASS_LENGTH = 48;
-const MAX_CONTEXT_PATH_LENGTH = 512;
-const MAX_CONTEXT_ROLE_LENGTH = 32;
-const MAX_CONTEXT_NAME_LENGTH = 120;
-const MAX_CONTEXT_ATTRS = 10;
-const MAX_CONTEXT_ATTR_NAME_LENGTH = 40;
-const MAX_CONTEXT_ATTR_VALUE_LENGTH = 120;
-const MAX_CONTEXT_TEXT_LENGTH = 300;
-const MAX_CONTEXT_OUTLINE_LENGTH = 600;
-const MAX_CONTEXT_OUTLINE_LINES = 40;
-const MAX_CONTEXT_LANDMARK_LENGTH = 80;
-const MAX_CONTEXT_HEADING_LENGTH = 130;
-const MAX_CONTEXT_COMPONENT_LENGTH = 100;
-const MAX_CONTEXT_PAGE_TITLE_LENGTH = 200;
-/** Attribute names the context may carry (mirrors CONTEXT_ATTRS in the bridge). */
-const CONTEXT_ATTR_ALLOWLIST = new Set([
-  "href", "src", "alt", "title", "type", "name", "role", "placeholder", "for", "target", "rel",
-  "aria-label", "aria-labelledby", "aria-describedby", "aria-current", "aria-expanded", "aria-hidden", "aria-controls",
-  "data-annotate", "data-testid", "data-test", "data-test-id", "data-cy", "data-qa", "data-component", "data-id",
-]);
-
-function capAt(text: string, max: number): string {
-  let cut = max;
-  const last = text.charCodeAt(cut - 1);
-  if (last >= 0xd800 && last <= 0xdbff) cut -= 1;
-  return text.slice(0, cut);
-}
-
-/** Collapse control characters and whitespace runs, then cap. */
-function collapseContextScalar(value: unknown, max: number): string | undefined {
-  if (typeof value !== "string") return undefined;
-  const collapsed = value.replace(/[\x00-\x1f\x7f]+/g, " ").replace(/\s+/g, " ").trim();
-  if (!collapsed) return undefined;
-  return collapsed.length > max ? capAt(collapsed, max) : collapsed;
-}
-
-/** The outline keeps its line breaks (it is fenced on export) but nothing
- *  else: control characters go, each line is whitespace-collapsed, and a
- *  backtick run that could close the export's fence is defused. */
-function collapseContextOutline(value: unknown): string | undefined {
-  if (typeof value !== "string") return undefined;
-  const lines = value
-    .replace(/[\x00-\x09\x0b-\x1f\x7f]+/g, " ")
-    .replace(/`{3,}/g, "'''")
-    .split("\n")
-    .map((line) => {
-      // Keep the skeleton's indentation (capped), collapse everything else.
-      const indent = (/^ */.exec(line)?.[0] ?? "").slice(0, 12);
-      return indent + line.slice(indent.length).replace(/\s+/g, " ").trim();
-    })
-    .filter((line) => line.trim().length > 0)
-    .slice(0, MAX_CONTEXT_OUTLINE_LINES);
-  const joined = lines.join("\n").trim();
-  if (!joined) return undefined;
-  return joined.length > MAX_CONTEXT_OUTLINE_LENGTH ? capAt(joined, MAX_CONTEXT_OUTLINE_LENGTH) : joined;
-}
-
-function contextBytes(value: unknown): number {
-  return new TextEncoder().encode(JSON.stringify(value)).length;
-}
-
-/** Validate a bridge-posted element context. Exported for protocol tests. */
-export function parseHtmlElementContext(value: unknown): HtmlElementContext | undefined {
-  if (!isRecord(value)) return undefined;
-  const tag = collapseContextScalar(value.tag, MAX_CONTEXT_TAG_LENGTH);
-  if (!tag) return undefined;
-  const context: HtmlElementContext = { tag: tag.toLowerCase() };
-  const id = collapseContextScalar(value.id, MAX_CONTEXT_ID_LENGTH);
-  if (id) context.id = id;
-  if (Array.isArray(value.classes)) {
-    const classes: string[] = [];
-    for (const entry of value.classes) {
-      if (classes.length >= MAX_CONTEXT_CLASSES) break;
-      const cls = collapseContextScalar(entry, MAX_CONTEXT_CLASS_LENGTH);
-      if (cls) classes.push(cls);
-    }
-    if (classes.length) context.classes = classes;
-  }
-  const path = collapseContextScalar(value.path, MAX_CONTEXT_PATH_LENGTH);
-  if (path) context.path = path;
-  const role = collapseContextScalar(value.role, MAX_CONTEXT_ROLE_LENGTH);
-  if (role) context.role = role;
-  const name = collapseContextScalar(value.name, MAX_CONTEXT_NAME_LENGTH);
-  if (name) context.name = name;
-  if (Array.isArray(value.attrs)) {
-    const attrs: Array<[string, string]> = [];
-    for (const entry of value.attrs) {
-      if (attrs.length >= MAX_CONTEXT_ATTRS) break;
-      if (!Array.isArray(entry) || entry.length !== 2) continue;
-      const attrName = collapseContextScalar(entry[0], MAX_CONTEXT_ATTR_NAME_LENGTH);
-      if (!attrName || !CONTEXT_ATTR_ALLOWLIST.has(attrName.toLowerCase())) continue;
-      if (typeof entry[1] !== "string") continue;
-      attrs.push([attrName.toLowerCase(), collapseContextScalar(entry[1], MAX_CONTEXT_ATTR_VALUE_LENGTH) ?? ""]);
-    }
-    if (attrs.length) context.attrs = attrs;
-  }
-  const text = collapseContextScalar(value.text, MAX_CONTEXT_TEXT_LENGTH);
-  if (text) context.text = text;
-  const outline = collapseContextOutline(value.outline);
-  if (outline) context.outline = outline;
-  if (typeof value.children === "number" && Number.isFinite(value.children) && value.children >= 0) {
-    context.children = Math.min(100000, Math.floor(value.children));
-  }
-  if (isRecord(value.rect)) {
-    const rect = value.rect;
-    const nums = ["x", "y", "w", "h", "vw", "vh"].map((key) => {
-      const n = rect[key];
-      return typeof n === "number" && Number.isFinite(n) ? Math.round(Math.max(-1e6, Math.min(1e6, n))) : null;
-    });
-    if (nums.every((n) => n !== null)) {
-      const [x, y, w, h, vw, vh] = nums as number[];
-      context.rect = { x: x!, y: y!, w: w!, h: h!, vw: vw!, vh: vh! };
-    }
-  }
-  const landmark = collapseContextScalar(value.landmark, MAX_CONTEXT_LANDMARK_LENGTH);
-  if (landmark) context.landmark = landmark;
-  const heading = collapseContextScalar(value.heading, MAX_CONTEXT_HEADING_LENGTH);
-  if (heading) context.heading = heading;
-  const component = collapseContextScalar(value.component, MAX_CONTEXT_COMPONENT_LENGTH);
-  if (component) context.component = component;
-  if (isRecord(value.page)) {
-    const url = collapseContextScalar(value.page.url, MAX_PAGE_URL_LENGTH);
-    if (url) {
-      context.page = { url };
-      const title = collapseContextScalar(value.page.title, MAX_CONTEXT_PAGE_TITLE_LENGTH);
-      if (title) context.page.title = title;
-    }
-  }
-  // Serialized bound, re-enforced here: shed the expendable fields in the
-  // bridge's order until the whole fits (validated per-field caps make this
-  // unreachable for an honest bridge; a forged message cannot exceed it).
-  const shedOrder: Array<keyof HtmlElementContext> = ["outline", "text", "attrs", "classes", "path", "heading", "landmark", "component"];
-  for (const field of shedOrder) {
-    if (contextBytes(context) <= MAX_ELEMENT_CONTEXT_BYTES) break;
-    delete context[field];
-  }
-  return contextBytes(context) <= MAX_ELEMENT_CONTEXT_BYTES ? context : undefined;
-}
+export {
+  parseHtmlElementContext,
+  MAX_ELEMENT_CONTEXT_BYTES,
+};
 
 function parseBridgeRect(value: unknown): BridgeRect | null {
   if (!isRecord(value)) return null;
diff --git a/packages/ui/utils/parser.test.ts b/packages/ui/utils/parser.test.ts
index 4e9a4a64b..86cfc21d8 100644
--- a/packages/ui/utils/parser.test.ts
+++ b/packages/ui/utils/parser.test.ts
@@ -1,6 +1,8 @@
 import { describe, test, expect } from "bun:test";
-import { parseMarkdownToBlocks, computeListIndices, extractFrontmatter, exportAnnotations, exportAnnotationEntry, resolveReferenceLinks } from "./parser";
+import { parseMarkdownToBlocks, computeListIndices, extractFrontmatter, exportAnnotations, exportAnnotationEntry, elementContextExportBlock, resolveReferenceLinks } from "./parser";
 import { shouldStripFrontmatter } from "@plannotator/core/annotatable";
+import { parseHtmlElementContext as coreParseHtmlElementContext } from "@plannotator/core/html-anchor";
+import { parseHtmlElementContext as uiParseHtmlElementContext } from "../components/html-viewer/useHtmlAnnotation";
 import type { Block } from "../types";
 
 /** Tiny factory for list-item blocks used by computeListIndices tests. */
@@ -2067,4 +2069,46 @@ describe("exportAnnotations — element context (raw-HTML / live-app pinpoints)"
     expect(output).toContain('- [Button] "Cancel" — `button.btn.btn-ghost` · `body > main > form.signup > div.actions > button:nth-of-type(2)`\n');
     expect(output).toContain('- [Link] "Learn more"\n');
   });
+
+  test("exportAnnotationEntry with includeOutline: false omits the outline fence but keeps identity lines", () => {
+    // Failure caught: model turn wasting ~600 chars of context window on the HTML outline
+    // when disabled, or conversely dropping selector/path/role/name identity lines when outline is disabled.
+    const ann = navAnn();
+    // Default includes outline
+    const defaultEntry = exportAnnotationEntry(ann);
+    expect(defaultEntry).toContain("````html\n");
+    expect(defaultEntry).toContain("- **selector** `nav#site-nav`\n");
+    expect(defaultEntry).toContain("- **path** `body > div#root > header.site-header > nav#site-nav`\n");
+    expect(defaultEntry).toContain('- **role** navigation · **name** "Primary" · **component** `data-component=AppNav`\n');
+
+    // With includeOutline: false, outline fence is omitted, identity lines remain
+    const outlineLessEntry = exportAnnotationEntry(ann, { includeOutline: false });
+    expect(outlineLessEntry).not.toContain("````html");
+    expect(outlineLessEntry).not.toContain("<nav id=\"site-nav\"");
+    expect(outlineLessEntry).toContain("- **selector** `nav#site-nav`\n");
+    expect(outlineLessEntry).toContain("- **path** `body > div#root > header.site-header > nav#site-nav`\n");
+    expect(outlineLessEntry).toContain('- **role** navigation · **name** "Primary" · **component** `data-component=AppNav`\n');
+    expect(outlineLessEntry).toContain('- **attrs** `aria-label="Primary" data-component="AppNav"`\n');
+    expect(outlineLessEntry).toContain("- **box** 0,0 1280×64 (viewport 1280×800)\n");
+    expect(outlineLessEntry).toContain('- **near** header.site-header · heading h1 "Acme Analytics"\n');
+  });
+
+  test("elementContextExportBlock respects includeOutline option", () => {
+    // Failure caught: elementContextExportBlock ignoring includeOutline: false when called directly.
+    const ann = navAnn();
+    const blockWithOutline = elementContextExportBlock(ann, { includeOutline: true });
+    expect(blockWithOutline).toContain("````html\n");
+    expect(blockWithOutline).toContain("- **selector** `nav#site-nav`\n");
+
+    const blockWithoutOutline = elementContextExportBlock(ann, { includeOutline: false });
+    expect(blockWithoutOutline).not.toContain("````html");
+    expect(blockWithoutOutline).toContain("- **selector** `nav#site-nav`\n");
+    expect(blockWithoutOutline).toContain("- **path** `body > div#root > header.site-header > nav#site-nav`\n");
+  });
+
+  test("no mirror validator remains: useHtmlAnnotation imports and re-exports core parseHtmlElementContext", () => {
+    // Failure caught: UI keeping a duplicated/diverged hand-mirrored parseHtmlElementContext
+    // instead of importing and re-exporting the authoritative core validator.
+    expect(uiParseHtmlElementContext).toBe(coreParseHtmlElementContext);
+  });
 });
diff --git a/packages/ui/utils/parser.ts b/packages/ui/utils/parser.ts
index b53b82f3c..cf73a4c05 100644
--- a/packages/ui/utils/parser.ts
+++ b/packages/ui/utils/parser.ts
@@ -1131,6 +1131,9 @@ export interface ElementContextExportOptions {
   /** Emit the live-app route line. The grouped export already prints a
    *  `## Page:` heading, so it passes false; a single copied entry passes true. */
   includeRoute?: boolean;
+  /** Print the identity lines WITHOUT the fenced outline, for model turns where
+   *  the 600-char outline is the expensive part. Default true. */
+  includeOutline?: boolean;
 }
 
 /** The agent-facing element block for a raw-HTML / live-app pinpoint: a
@@ -1141,8 +1144,9 @@ export interface ElementContextExportOptions {
 export const elementContextExportBlock = (ann: any, opts: ElementContextExportOptions = {}): string => {
   const context = ann?.elementContext;
   if (!context || typeof context !== 'object' || typeof context.tag !== 'string') return '';
+  const includeOutline = opts.includeOutline ?? true;
   let block = '';
-  if (typeof context.outline === 'string' && context.outline.trim()) {
+  if (includeOutline && typeof context.outline === 'string' && context.outline.trim()) {
     // Fence at 4 backticks; the boundary already defuses 3+ runs inside the
     // outline, and a 4-run here cannot be closed by anything the page wrote.
     const outline = context.outline.replace(/`{3,}/g, "'''").trim();
@@ -1248,7 +1252,11 @@ export const exportAnnotationEntry = (ann: any, opts: ElementContextExportOption
         output += `${commentHeadingLine(ann)}\n> ${ann?.text ?? ''}\n`;
       }
   }
-  output += elementContextExportBlock(ann, opts);
+  const resolvedOpts: ElementContextExportOptions = {
+    includeRoute: opts.includeRoute ?? true,
+    ...(opts.includeOutline !== undefined ? { includeOutline: opts.includeOutline } : {}),
+  };
+  output += elementContextExportBlock(ann, resolvedOpts);
   output += additionalTargetsExportBlock(ann);
   if (Array.isArray(ann?.images) && ann.images.length > 0) {
     output += `**Attached images:**\n`;

From 5c331a060b2d316b20dff137da74361832a069ef Mon Sep 17 00:00:00 2001
From: Michael Ramos <mdramos8@gmail.com>
Date: Thu, 17 Sep 2026 00:19:06 -0700
Subject: [PATCH 2/4] refactor(ui): single definition of MAX_PAGE_URL_LENGTH in
 core
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`packages/core/html-anchor.ts` gained its own `MAX_PAGE_URL_LENGTH` when
`parseHtmlElementContext` moved there, leaving a second copy in
`useHtmlAnnotation.ts` — exactly the hand-mirrored-constant shape the move
was meant to end. Delete the ui copy, import the core one, and re-export it
from `components/html-viewer` so the host import site and the live-protocol
tests keep reading it from where they already do.
---
 packages/core/html-anchor.ts                            | 6 ++++++
 packages/ui/components/html-viewer/useHtmlAnnotation.ts | 8 +++++---
 2 files changed, 11 insertions(+), 3 deletions(-)

diff --git a/packages/core/html-anchor.ts b/packages/core/html-anchor.ts
index 8e28453aa..05c86d94a 100644
--- a/packages/core/html-anchor.ts
+++ b/packages/core/html-anchor.ts
@@ -83,7 +83,13 @@ export const MAX_HTML_TARGET_TEXT_LENGTH = 400;
 export const MAX_HTML_ADDITIONAL_TARGETS = 16;
 /** Default byte budget for a persisted anchor (16 KiB of UTF-8 JSON). */
 export const DEFAULT_HTML_ANCHOR_MAX_BYTES = 16 * 1024;
+/** Serialized bound for one element context (2 KiB of UTF-8 JSON). */
 export const MAX_ELEMENT_CONTEXT_BYTES = 2048;
+/**
+ * Cap for live-app page identity strings (mirrors the bridge's own slice).
+ * The single definition: `@plannotator/ui`'s parent trust boundary imports
+ * and re-exports it from here rather than keeping its own copy.
+ */
 export const MAX_PAGE_URL_LENGTH = 2048;
 const MAX_CONTEXT_TAG_LENGTH = 32;
 const MAX_CONTEXT_ID_LENGTH = 100;
diff --git a/packages/ui/components/html-viewer/useHtmlAnnotation.ts b/packages/ui/components/html-viewer/useHtmlAnnotation.ts
index 9b95f80b8..fa065281e 100644
--- a/packages/ui/components/html-viewer/useHtmlAnnotation.ts
+++ b/packages/ui/components/html-viewer/useHtmlAnnotation.ts
@@ -12,6 +12,7 @@ import { BRIDGE_PROTOCOL_VERSION } from "./bridge-script";
 import {
   parseHtmlElementContext,
   MAX_ELEMENT_CONTEXT_BYTES,
+  MAX_PAGE_URL_LENGTH,
 } from "@plannotator/core/html-anchor";
 
 const PREFIX = "plannotator-bridge-";
@@ -137,9 +138,6 @@ export interface HtmlLiveSession {
   token: string;
 }
 
-/** Cap for live-mode page identity strings (mirrors the bridge's slice). */
-export const MAX_PAGE_URL_LENGTH = 2048;
-
 /** Cap for a link href relayed out of the framed document. */
 const MAX_LINK_HREF_LENGTH = 2048;
 /** Control characters never appear in a real href; they are how structure gets smuggled. */
@@ -330,9 +328,13 @@ function parseTargetLabel(value: unknown): string | undefined {
     : collapsed;
 }
 
+// Re-exported so `components/html-viewer` stays the one import site a host
+// needs for the parent trust boundary; the definitions live in
+// `@plannotator/core/html-anchor`, never mirrored here.
 export {
   parseHtmlElementContext,
   MAX_ELEMENT_CONTEXT_BYTES,
+  MAX_PAGE_URL_LENGTH,
 };
 
 function parseBridgeRect(value: unknown): BridgeRect | null {

From 95129a56dcadd6b935ad6abd83a99c2e616cdbe9 Mon Sep 17 00:00:00 2001
From: Michael Ramos <mdramos8@gmail.com>
Date: Thu, 17 Sep 2026 00:23:00 -0700
Subject: [PATCH 3/4] docs(ui): document the element-context host contract
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

HANDOFF.md still told hosts the element-context gap was open — that
`@plannotator/core/html-anchor` does not carry `elementContext` and that they
must persist and project it themselves. It ships in the ui tarball, so that
line was about to be wrong in a consumer's node_modules.

- HANDOFF.md: the stale gap sentence now names 0.39.0 as the release it
  describes and points forward. A new "Element context through the host seam"
  section says where the validator lives (`parseHtmlElementContext` in
  `@plannotator/core/html-anchor`, re-exported unchanged from
  `components/html-viewer`), what a host passes (`elementContext` on the
  build source, `context` per additional target, `elementContext` on a
  `HostThread`), what it gets back (`PersistedHtmlAnchor.elementContext`,
  `HtmlAnnotationTarget.context`, both on the projection) with the fixed key
  order that keeps context-less rows byte-identical on the wire, and that the
  caps, the attribute allowlist, the shed order and the 16 KiB budget are all
  unchanged — contexts are simply shed before targets. Plus a publishing
  bullet: core moves, so publish core first.
- README.md: the host-seam bullet now mentions the round trip.
- html-anchor.ts: the module doc claimed the validators mirror what ui
  enforces. They no longer mirror it; they are it.
---
 packages/core/html-anchor.ts | 14 +++++++++-----
 packages/ui/HANDOFF.md       | 27 ++++++++++++++++++++++++++-
 packages/ui/README.md        |  2 +-
 3 files changed, 36 insertions(+), 7 deletions(-)

diff --git a/packages/core/html-anchor.ts b/packages/core/html-anchor.ts
index 05c86d94a..94c699d30 100644
--- a/packages/core/html-anchor.ts
+++ b/packages/core/html-anchor.ts
@@ -6,13 +6,17 @@
  *   bounded record a host can persist (target cap, byte budget).
  * - `projectHostThreads` projects stored host rows back onto the viewer's
  *   `annotations` prop shape, in the order that becomes the marker numbering.
+ * - `parseHtmlElementAnchor` and `parseHtmlElementContext` are the pure,
+ *   fail-closed validators both of those run on the way through.
  *
  * Browser-safe and dependency-free (this package is `@plannotator/core`).
- * The types below are structurally identical to `HtmlElementAnchor` and
- * `HtmlAnnotationTarget` in `@plannotator/ui/types`; the validators mirror
- * the caps `@plannotator/ui` enforces at its own parent trust boundary
- * (`components/html-viewer/useHtmlAnnotation.ts`), so nothing persisted here
- * is ever refused on read.
+ * The types below are structurally identical to `HtmlElementAnchor`,
+ * `HtmlAnnotationTarget` and `HtmlElementContext` in `@plannotator/ui/types`,
+ * and the caps here ARE the caps enforced at `@plannotator/ui`'s own parent
+ * trust boundary (`components/html-viewer/useHtmlAnnotation.ts`), which
+ * imports and re-exports these validators rather than keeping its own copy —
+ * one definition, never mirrored — so nothing persisted here is ever refused
+ * on read.
  */
 
 export interface HtmlAnchorPoint {
diff --git a/packages/ui/HANDOFF.md b/packages/ui/HANDOFF.md
index cc46b3abd..47fe32eb1 100644
--- a/packages/ui/HANDOFF.md
+++ b/packages/ui/HANDOFF.md
@@ -691,10 +691,35 @@ Mermaid diagrams used to render from one static config in every palette and both
 
 **Known limits.** `GraphvizBlock` already maps its output to `var(--foreground)` / `var(--muted-foreground)` / `var(--muted)` and needs nothing. Mermaid hardcodes a `#000000` stroke on the sequence `crosshead` marker (lost messages, `-x`), which no theme variable reaches; it stays as in every Mermaid theme. A Mermaid 12 upgrade is a separate follow-up that reuses this mapping unchanged.
 
+## Element context through the host seam (next publish)
+
+`@plannotator/ui` 0.39.0 captured **element context** on raw-HTML and live-app pinpoints but deliberately left `@plannotator/core/html-anchor` untouched, so a host persisting through `buildPersistedHtmlAnchor` and reading through `projectHostThreads` dropped the field on save and never got it back on projection. That gap (#1521) is closed: the field now survives the whole host round trip.
+
+**The validator lives in core.** `parseHtmlElementContext` is exported by **`@plannotator/core/html-anchor`**, beside `parseHtmlElementAnchor`, along with `MAX_ELEMENT_CONTEXT_BYTES` (2048) and `MAX_PAGE_URL_LENGTH` (2048). `@plannotator/ui/components/html-viewer` imports it and **re-exports it unchanged**, so the 0.39.0 import site keeps working and no host code has to move; what is gone is the hand-mirrored copy that used to live in `components/html-viewer/useHtmlAnnotation.ts` (the rule since core 0.25.0: no mirror validators). Behavior is byte-faithful to 0.39.0 — the same scalar bounds, the same `CONTEXT_ATTR_ALLOWLIST` with href/src scrubbed of query and fragment, the same `outline → text → attrs → classes → path → heading → landmark → component` shed order inside the 2 KiB serialized bound, and the same fail-closed `undefined` for anything that is not a record or carries no `tag`. A host that calls the validator directly gets identical output for identical input.
+
+**What a host passes.** `buildPersistedHtmlAnchor(source, options)` now accepts `elementContext?: HtmlElementContext | null` on `source`, and each entry of `source.htmlAdditionalTargets` accepts `context?`. Both go through the same fail-closed parser the read path uses, so nothing is persisted that would be refused on read back. `HostThread` (the `projectHostThreads` input) accepts `elementContext?` the same way.
+
+**What a host gets back.** `PersistedHtmlAnchor` gains `elementContext?` and `HtmlAnnotationTarget` gains `context?`. **Key order is fixed and matters:** `elementContext` serializes strictly AFTER `htmlAdditionalTargets`, and a target's `context` after its `anchor` (so a kept target's key order is `text, label, anchor, context`). A row that carries no context serializes byte-identically to what 0.39.0 wrote — the key is absent, not `undefined` — so a wire fingerprint over stored anchors does not move when you adopt this. `projectHostThreads` returns `elementContext` on the projection and `context` on each projected target, so a host's panel and its per-row Copy (which calls `exportAnnotationEntry`) see the field. Paint never reads it: the repaint path still posts only anchors to the bridge.
+
+**The 16 KiB budget is unchanged, and contexts are the first thing it sheds.** `DEFAULT_HTML_ANCHOR_MAX_BYTES` stays 16384: one primary context at 2 KiB plus 16 extras at 1 KiB each already exceeds it, and raising the default is not the answer (the 48 KiB figure that appeared in the design write-up was never shipped). Under `maxBytes` the stages are now: the quote down to its 400-char floor → **per-target contexts, from the end** → **the primary context** → targets from the end → the rest of the quote. Shedding context before targets is deliberate: a context is descriptive and re-derivable on the next click, while a dropped target loses a marker the reviewer placed. Context shedding is silent — `droppedTargets`, `capDroppedTargets` and `sizeDroppedTargets` count targets only and keep their exact 0.39.0 meanings, so a host notice that distinguishes a product-cap drop from a size drop is unaffected.
+
+**The field stays descriptive.** Restore never reads it, `HtmlElementAnchor` and the restore path are untouched, there is no `BRIDGE_PROTOCOL_VERSION` bump, and share links still drop it exactly as they drop anchors.
+
+### Export without the outline
+
+`elementContextExportBlock(ann, opts)` and `exportAnnotationEntry(ann, opts)` on `@plannotator/ui/utils/parser` take a new **`includeOutline?: boolean`, default `true`**. Pass `false` to print the identity lines (`selector`, `path`, `role · name · component`, `attrs`, `text`, `route`, `box`, `near`) WITHOUT the fenced HTML skeleton: in a model turn the 600-char outline is the expensive part per annotation, and the identity lines are what an agent greps. Defaulting to true keeps every existing caller's bytes unchanged.
+
+**Default change to know about before you upgrade:** `exportAnnotationEntry`'s **`includeRoute` now defaults to `true` per field**, not only when `opts` is omitted. In 0.39.0 the default lived on the parameter (`opts = { includeRoute: true }`), so passing any explicit options object replaced it and `exportAnnotationEntry(ann, {})` silently dropped the live-app `route` line. A host that was passing an options object in order to suppress the route must now pass `includeRoute: false` explicitly. Callers that pass nothing, or that already pass `{ includeRoute: true }` or `{ includeRoute: false }`, are unaffected. `elementContextExportBlock`'s own default is unchanged (route off unless asked, because the grouped export prints a `## Page:` heading above the entries).
+
+Behavior is pinned by `../core/html-anchor.test.ts` (the wire fingerprint of a context-less row, the shed order, and the projection) and the element-context cases in `utils/parser.test.ts`.
+
+---
+
 ## Publishing & versioning
 
 - **Unreleased (next `@plannotator/ui` publish, minor bump):** theme-aware Mermaid diagrams. New additive exports `utils/mermaidTheme` (`buildMermaidThemeVariables`, `readThemeTokens`, `applyMermaidTheme`, `mermaidThemeKey`, `buildMermaidConfig`, `ensureContrast`, `isDarkBackground`, `MERMAID_THEME_TOKEN_NAMES`) and `utils/cssColor` (parser + OKLab/contrast toolkit). `MermaidBlock` now calls `useTheme()` and `applyMermaidTheme` before each render; `MERMAID_CONFIG`, `loadMermaidRuntime`, `mermaid-eager` and `securityLevel: 'strict'` are unchanged. A host whose document carries no theme tokens renders diagrams byte-identically to 0.39.0; a host that mounts `ThemeProvider` with `theme.css` gets diagrams in its palette and mode with no configuration. No new peer dependencies; core unchanged. See "Theme-aware Mermaid diagrams (next publish)".
-- The current pair is `@plannotator/ui` `0.39.0` on `@plannotator/core` `0.25.2` (core unchanged; nothing under `packages/core` moved). UI 0.39.0 adds **element context** to raw-HTML and live-app pinpoint annotations (#1517, #1520): a new optional `Annotation.elementContext` (`HtmlElementContext` in `@plannotator/ui/types`) and `HtmlAnnotationTarget.context`, captured by the bridge at click time (tag, id, author classes, ancestor `path`, `role`, accessible `name`, an allowlisted `attrs` set with href/src scrubbed of query and fragment, rendered `text`, an adaptive collapsed HTML `outline`, child count, viewport `rect`, nearest `landmark` and `heading`, a `component` hint, and in live-app sessions `page`), hard-capped at 2 KiB serialized per primary and 1 KiB per extra target, and re-validated at the parent trust boundary by the new `parseHtmlElementContext` export of `@plannotator/ui/components/html-viewer`. New helpers on `@plannotator/ui/utils/parser`: `elementContextExportBlock(ann, { includeRoute })` (the fenced skeleton plus selector/path/role/name/attrs/text/box/near lines the full export now prints under a context-bearing comment) and `exportAnnotationEntry(ann, { includeRoute })` (one annotation as a standalone feedback entry, a pure helper for hosts; `AnnotationPanel`'s card chrome is unchanged from 0.38.2). The field is purely descriptive: `HtmlElementAnchor` and restore are untouched, no `BRIDGE_PROTOCOL_VERSION` bump, share links drop it like anchors, annotations without it export byte-identically, and the repaint path posts only anchors to the bridge. **Host persistence gap, tracked as #1521**: `@plannotator/core/html-anchor` (`buildPersistedHtmlAnchor`, `projectHostThreads`) does not carry `elementContext` yet, so a host persisting through those helpers drops it on save; until #1521 lands, hosts that want it must persist and project the field themselves. Peer ranges are unchanged from 0.38.2: `react` / `react-dom` `^19.2.3`, `tailwindcss` as before, and `@codemirror/state ^6.7.2` beside `@codemirror/view ^6.43.10`. Decision-control change in the same window (#1516): the header primary reads `Send Feedback` / `Post Comments` with no inline count (`DecisionPrimary.count` removed; internal, not host-supported surface).
+- **Unreleased (same publish, and it moves `core`): element context through the host seam (#1521).** `@plannotator/core/html-anchor` gains `parseHtmlElementContext`, `MAX_ELEMENT_CONTEXT_BYTES` and `MAX_PAGE_URL_LENGTH`; `PersistedHtmlAnchor.elementContext?` and `HtmlAnnotationTarget.context?` now round-trip through `buildPersistedHtmlAnchor` and `projectHostThreads`. **Core changes here, so bump and publish `core` first** and update UI's exact core dependency before packing ui — a ui build that imports these from an older published core fails to compile in a consumer, the 0.38.0 failure mode. `@plannotator/ui/components/html-viewer` re-exports the validator, so 0.39.0's import site is unchanged, and rows without context stay byte-identical on the wire. `utils/parser` gains `includeOutline` on `elementContextExportBlock` / `exportAnnotationEntry`, and `exportAnnotationEntry`'s `includeRoute` now defaults to true per field. See "Element context through the host seam".
+- The current pair is `@plannotator/ui` `0.39.0` on `@plannotator/core` `0.25.2` (core unchanged; nothing under `packages/core` moved). UI 0.39.0 adds **element context** to raw-HTML and live-app pinpoint annotations (#1517, #1520): a new optional `Annotation.elementContext` (`HtmlElementContext` in `@plannotator/ui/types`) and `HtmlAnnotationTarget.context`, captured by the bridge at click time (tag, id, author classes, ancestor `path`, `role`, accessible `name`, an allowlisted `attrs` set with href/src scrubbed of query and fragment, rendered `text`, an adaptive collapsed HTML `outline`, child count, viewport `rect`, nearest `landmark` and `heading`, a `component` hint, and in live-app sessions `page`), hard-capped at 2 KiB serialized per primary and 1 KiB per extra target, and re-validated at the parent trust boundary by the new `parseHtmlElementContext` export of `@plannotator/ui/components/html-viewer`. New helpers on `@plannotator/ui/utils/parser`: `elementContextExportBlock(ann, { includeRoute })` (the fenced skeleton plus selector/path/role/name/attrs/text/box/near lines the full export now prints under a context-bearing comment) and `exportAnnotationEntry(ann, { includeRoute })` (one annotation as a standalone feedback entry, a pure helper for hosts; `AnnotationPanel`'s card chrome is unchanged from 0.38.2). The field is purely descriptive: `HtmlElementAnchor` and restore are untouched, no `BRIDGE_PROTOCOL_VERSION` bump, share links drop it like anchors, annotations without it export byte-identically, and the repaint path posts only anchors to the bridge. **Host persistence gap in 0.39.0 itself, closed in the next publish (#1521, #1549)**: as shipped, 0.39.0's `@plannotator/core/html-anchor` (`buildPersistedHtmlAnchor`, `projectHostThreads`) does not carry `elementContext`, so a host pinned to 0.39.0 that persists through those helpers drops it on save and must persist and project the field itself. The next publish carries it end to end — see "Element context through the host seam". Peer ranges are unchanged from 0.38.2: `react` / `react-dom` `^19.2.3`, `tailwindcss` as before, and `@codemirror/state ^6.7.2` beside `@codemirror/view ^6.43.10`. Decision-control change in the same window (#1516): the header primary reads `Send Feedback` / `Post Comments` with no inline count (`DecisionPrimary.count` removed; internal, not host-supported surface).
 - The previous pair was `@plannotator/ui` `0.38.2` on `@plannotator/core` `0.25.2`. UI 0.38.2 keeps the type word in a titled alert's accessible name through a visually hidden `sr-only` span before the title instead of an `aria-label` on the title row (naming a generic `div` is prohibited by ARIA and WebKit drops it, so VoiceOver on Safari read only the bold title in 0.38.1), and loosens the React peer back to `^19.2.3` (0.38.1 declared `^19.2.8` only because the dependency batch moved it; nothing in the package needs a newer API). **Do not consume ui 0.38.0**: it imports `@plannotator/core/token-hover` (the hover-card trigger settings, #1462) but pins core 0.25.1, which never exported that subpath, so it fails to compile in any consumer; 0.38.1 is the same UI pinning core 0.25.2, which publishes `./token-hover`, the rotated `guide-viewer-manifest` pin, and the `config-types` hover fields (core 0.25.2 is the first core publish since 0.25.1 even though those changes landed over several releases; the package smoke now diffs the UI's core imports against the registry so an unpublished core subpath fails preflight instead of the consumer). UI 0.38.1 also aligns `@codemirror/state` to `^6.7.2` beside `@codemirror/view ^6.43.10`, so a consumer can no longer resolve two state copies. UI 0.38.0 also renders a GitHub alert's bold-only first body line as its title on the icon row (an emoji on that line becomes the icon; `<!-- icon: name -->` is stripped and resolved through the new `alertIconRenderer` seam, null by default; grammar in `utils/alertTitle`, importable by a host editor so it writes the bytes the reader parses; a fenced code block inside an alert body still renders as text, deferred because nesting a `CodeBlock` inside a block interacts with the positional annotation anchors and needs its own design). UI 0.38.0 carries the whole unified decision-control stack: the internal primitives (`DecisionControl`, `utils/decisionSpec`, `hooks/useDismissablePopover` — not host-supported surface, see the unsupported list; `useDismissablePopover` also replaced the hand-rolled dismissal inside `ActionMenu`/`ApproveDropdown`, both likewise unsupported) plus one blessed-barrel addition: `decisionControlShortcuts` on `@plannotator/ui/shortcuts` (pure scope data, fetch-free, same contract as the other scopes). The removal of `ToolbarButtons`' platform-mode `muted` prop is internal — `ToolbarButtons` is not host-supported surface. UI 0.37.0 added the Viewer-owned document-header seam (a new public API, hence the minor bump; 0.36.1 was reserved for it but never published) while retaining the `hideQuickLabel` and `StickyHeaderLane` seams from the 0.35.x and 0.36.0 releases; core 0.25.1 publishes the `annotation-threads` subpath already used by `AnnotationPanel` and `utils/parser`, and UI pins that corrected core exactly.
 - Recent pairs, for the consumer's install matrix: ui 0.32.0 on core 0.25.0 (lockstep, `html-anchor`), ui 0.33.0 and ui 0.34.0 on core 0.25.0 (ui only), and ui 0.35.2, ui 0.36.0, and ui 0.37.0 on core 0.25.1 (0.36.1 was never published), and ui 0.38.1, ui 0.38.2, and ui 0.39.0 on core 0.25.2. Do not consume ui 0.35.0 externally because its published manifest contains `workspace:*`; do not consume ui 0.35.1 because its exact core 0.25.0 dependency lacks the `annotation-threads` export. Do not consume ui 0.38.0 because its exact core 0.25.1 dependency lacks the `token-hover` export.
 - When both packages change, **publish `core` first**: ui 0.32.0 imports the `@plannotator/core/html-anchor` subpath, which no earlier published core (0.24.0 and before) has, just as ui 0.29.0 needed core 0.23.0 for `@plannotator/core/annotatable`. Bump core, update UI's exact core dependency to the same new version, and run `bun install` so `bun.lock` records the new workspace versions before packing either package.
diff --git a/packages/ui/README.md b/packages/ui/README.md
index 100b421dd..b446f5838 100644
--- a/packages/ui/README.md
+++ b/packages/ui/README.md
@@ -103,7 +103,7 @@ Requires `@plannotator/markdown-editor ^0.4.0` and `@plannotator/atomic-editor ^
 
 Everything a host needs around `HtmlViewer` to match Plannotator's HTML annotation experience, all additive and all defaulting to today's behavior. Requires `@plannotator/core` 0.25.0 (the `html-anchor` subpath), so install and publish core before ui:
 
-- **`projectHostThreads(threads, { openOnly?, documentLevel?, maxTargets? })`** and **`buildPersistedHtmlAnchor(source, { maxBytes?, maxTargets? })`** from `components/html-viewer` (pure, from `@plannotator/core/html-anchor`): project stored rows onto the `annotations` prop in the order that becomes the marker numbering, and trim a composed comment's anchor for persistence with cap drops and size drops reported separately. A row with nothing restorable projects as a document-level `GLOBAL_COMMENT` by default (`documentLevel: 'global'`, never reported as unanchored) or, with `documentLevel: 'unanchored'`, as a textless page `COMMENT` the unanchored report names. **HTML-only:** the projection carries `originalText`, `htmlAnchor` and `htmlAdditionalTargets`, and pins `blockId` to `""`, offsets to `0` and no `startMeta` / `endMeta`; on the markdown `Viewer` a projected `COMMENT` with quoted text still re-anchors by whole-document text search, but with `blockId` `""` and offsets `0` it loses export ordering (every such row sorts first and ties), the "lines N-M" location label, disambiguation when the same text repeats (first match wins), and the no-flash meta restore; a host that needs those carries `blockId`, the offsets and the web-highlighter metas in its own projection.
+- **`projectHostThreads(threads, { openOnly?, documentLevel?, maxTargets? })`** and **`buildPersistedHtmlAnchor(source, { maxBytes?, maxTargets? })`** from `components/html-viewer` (pure, from `@plannotator/core/html-anchor`): project stored rows onto the `annotations` prop in the order that becomes the marker numbering, and trim a composed comment's anchor for persistence with cap drops and size drops reported separately. A row with nothing restorable projects as a document-level `GLOBAL_COMMENT` by default (`documentLevel: 'global'`, never reported as unanchored) or, with `documentLevel: 'unanchored'`, as a textless page `COMMENT` the unanchored report names. **HTML-only:** the projection carries `originalText`, `htmlAnchor` and `htmlAdditionalTargets`, and pins `blockId` to `""`, offsets to `0` and no `startMeta` / `endMeta`; on the markdown `Viewer` a projected `COMMENT` with quoted text still re-anchors by whole-document text search, but with `blockId` `""` and offsets `0` it loses export ordering (every such row sorts first and ties), the "lines N-M" location label, disambiguation when the same text repeats (first match wins), and the no-flash meta restore; a host that needs those carries `blockId`, the offsets and the web-highlighter metas in its own projection. **Element context rides both helpers** (next publish, #1521): `buildPersistedHtmlAnchor` accepts `elementContext` on its source and `context` on each additional target and writes them back as `PersistedHtmlAnchor.elementContext` / `HtmlAnnotationTarget.context` (serialized after `htmlAdditionalTargets` and after each target's `anchor`, so a row without context stays byte-identical on the wire), and `projectHostThreads` returns both on the projection so a host panel and its per-row Copy see them. Contexts are shed before targets under `maxBytes`, whose 16 KiB default is unchanged. The validator, `parseHtmlElementContext`, lives in `@plannotator/core/html-anchor` and is re-exported from `components/html-viewer`.
 - **`onUnanchoredChange`** is keyed to the bridge's restore (one complete report per document after the restore batch, the empty set included) and complete over the `annotations` prop: textless page rows are reported without being posted, and a locally minted id the host swapped out of its list is not. It replaces a host's `mark-applied` bookkeeping for the unanchored set; the local-to-server mark swap itself stays host-side. **Nothing is delivered before the bridge's first post-restore report for a document (per reload generation):** a prop-side change before that point does not fire the callback, so do not gate host state on a prop-side delivery arriving first; treat the first call as the restore's verdict.
 - **`hooks/useHtmlRefresh({ fetchSnapshot, onSnapshot, onUnanchored?, onResult? })`**: the refresh cycle with the stale-response and document-change guards, backend behind `fetchSnapshot`.
 - **`components/HtmlSurfaceControls`**: the eye / refresh / pen header controls with Plannotator's markup and `labels` overrides.

From 4239d8ff0c23d9ceec616c5db16b698c5b7ee3ef Mon Sep 17 00:00:00 2001
From: Michael Ramos <mdramos8@gmail.com>
Date: Thu, 17 Sep 2026 00:23:00 -0700
Subject: [PATCH 4/4] docs: name the validator's new home in the
 element-context section

---
 AGENTS.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/AGENTS.md b/AGENTS.md
index ebc51b9a3..4edb25685 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -966,7 +966,7 @@ Text highlighting uses `web-highlighter` library. Code blocks use manual `<mark>
 
 **Raw-HTML annotate:** the sandboxed viewer never mutates the visited page's DOM. Committed annotations render as numbered placed comment markers plus overlay-projected highlight rectangles inside a shadow-rooted fixed overlay host: the durable anchor data (element selector, text snapshot, normalized selected point) is persisted, and the markers/highlights are disposable projections re-resolved from it on every reconcile. Shift-click multi-select joins additional elements to one comment (`htmlAdditionalTargets`).
 
-**Element context (agent-facing).** A pinpoint also captures a bounded description of the element at click time, `elementContext` on the annotation (`HtmlElementContext` in `packages/ui/types.ts`; extra targets carry a smaller one as `context`), built by `buildElementContext` in the bridge and re-validated by `parseHtmlElementContext` at the parent trust boundary (`useHtmlAnnotation.ts`). It is purely descriptive, never read by restore. Fields: tag, id, author classes, an ancestor `path`, explicit-or-implicit `role`, accessible `name`, an ALLOWLISTED attribute set (href/src scrubbed of query and fragment, `data:` truncated to its media type), rendered `text` (300), a collapsed HTML `outline` (600 chars; two child levels, then one, then a per-tag count, whichever first fits), child count, viewport `rect`, nearest `landmark` and `heading`, a `component` hint from `data-component`/`data-testid` ancestry (deliberately no React fiber reads), and in live-app sessions the `page` route and title. Never captured: form values, `on*` handlers, `style`, script/style/template contents, full innerHTML. Hard cap 2 KiB serialized per primary (1 KiB per extra target), shedding outline → text → attrs → classes → path → heading → landmark → component. The export (`elementContextExportBlock` in `packages/ui/utils/parser.ts`) prints a 4-backtick `html` fence of the outline plus `selector` / `path` / `role` · `name` · `component` / `attrs` / `text` / `box` / `near` lines under the comment; a text-less pinpoint's placeholder quote (`[element: Navigation]`) becomes `Feedback on the <nav> element — "Primary"` in the heading, while a pinpoint with real quoted text keeps its quote line and gains the block. Annotations without the field export byte-identically. The grouped live-app export omits the `route` line (the `## Page:` heading carries it); `exportAnnotationEntry` (one annotation, no number) includes it; it is a pure helper for hosts and tests, and the annotation panel's card chrome is unchanged. Share links drop `elementContext` exactly like anchors. The feedback archive records identity only (`elementTag`, `elementSelector`, `elementPath`, `elementRole`, `elementName`, `pageUrl`), never the outline. No `BRIDGE_PROTOCOL_VERSION` bump: the field is additive in both directions.
+**Element context (agent-facing).** A pinpoint also captures a bounded description of the element at click time, `elementContext` on the annotation (`HtmlElementContext` in `packages/ui/types.ts`; extra targets carry a smaller one as `context`), built by `buildElementContext` in the bridge and re-validated at the parent trust boundary by `parseHtmlElementContext`, which lives in `packages/core/html-anchor.ts` beside `parseHtmlElementAnchor` (#1549); `useHtmlAnnotation.ts` imports and re-exports it rather than mirroring it, and the host persistence helpers in that same core module (`buildPersistedHtmlAnchor`, `projectHostThreads`) run it too, so a host that persists and projects through core keeps the field instead of dropping it on save. It is purely descriptive, never read by restore. Fields: tag, id, author classes, an ancestor `path`, explicit-or-implicit `role`, accessible `name`, an ALLOWLISTED attribute set (href/src scrubbed of query and fragment, `data:` truncated to its media type), rendered `text` (300), a collapsed HTML `outline` (600 chars; two child levels, then one, then a per-tag count, whichever first fits), child count, viewport `rect`, nearest `landmark` and `heading`, a `component` hint from `data-component`/`data-testid` ancestry (deliberately no React fiber reads), and in live-app sessions the `page` route and title. Never captured: form values, `on*` handlers, `style`, script/style/template contents, full innerHTML. Hard cap 2 KiB serialized per primary (1 KiB per extra target), shedding outline → text → attrs → classes → path → heading → landmark → component. Under the persisted anchor's own 16 KiB budget `buildPersistedHtmlAnchor` sheds contexts — per-target first, from the end, then the primary — BEFORE it drops any target, since a context is descriptive and re-derivable on the next click while a dropped target loses a marker the reviewer placed; `DEFAULT_HTML_ANCHOR_MAX_BYTES` is unchanged and the dropped-target counts still count targets only. The export (`elementContextExportBlock` in `packages/ui/utils/parser.ts`) prints a 4-backtick `html` fence of the outline plus `selector` / `path` / `role` · `name` · `component` / `attrs` / `text` / `box` / `near` lines under the comment; a text-less pinpoint's placeholder quote (`[element: Navigation]`) becomes `Feedback on the <nav> element — "Primary"` in the heading, while a pinpoint with real quoted text keeps its quote line and gains the block. Annotations without the field export byte-identically. The grouped live-app export omits the `route` line (the `## Page:` heading carries it); `exportAnnotationEntry` (one annotation, no number) includes it; it is a pure helper for hosts and tests, and the annotation panel's card chrome is unchanged. Both helpers also take `includeOutline` (default `true`): `false` prints the identity lines without the fenced outline, for model turns where the 600-char outline is the expensive part per annotation. Share links drop `elementContext` exactly like anchors. The feedback archive records identity only (`elementTag`, `elementSelector`, `elementPath`, `elementRole`, `elementName`, `pageUrl`), never the outline. No `BRIDGE_PROTOCOL_VERSION` bump: the field is additive in both directions.
 
 **HTML and live-app interaction model:** raw-HTML sessions and live app sessions (`mode: "annotate-app"`) share one contract. Both open with pinpoint **armed** (`htmlAnnotateArmed` defaults to `true`, `packages/editor/App.tsx:493`; live sessions open armed like every other HTML surface, `App.tsx:2871`). `Esc` walks a ladder instead of exiting outright: a pending draft closes first, then the pinpoint hover outline clears, and only then does `Esc` drop the surface to **Interact**, where the bridge goes passive so clicks, forms, text selection, and SPA navigation reach the page natively (`packages/ui/components/html-viewer/bridge-script.ts:3066-3080`; committed markers stay visible and a marker click still opens its comment, and in Interact an open drag-comment draft still closes before `Esc` is handed back to the page). Vim owns its own ladder and is skipped here. The header **pen** button toggles Annotate/Interact (`packages/editor/components/AppHeader.tsx:386-404`, `aria-pressed`), as does `Mod+Shift+A` (`packages/ui/shortcuts/plan-review/htmlAnnotate.shortcuts.ts`) — a real toggle in BOTH directions, which is what makes it the answer to "Esc dropped me to Interact, how do I get back?". Disarming through either path tears down any pending draft, because the bridge's `set-annotate-mode(false)` handler clears every pending affordance (`bridge-script.ts:719-739`), exactly as the Esc ladder does. The bridge mirrors the chord inside the iframe on the capture phase and forwards it to the parent, so it works whichever document owns focus. Text drag-selection commenting is **always live**, on both surfaces and in both states, ungated from the armed flag and from the input method (`bridge-script.ts:384-386`, `:1420-1436`): while armed, a click pins an element and a drag selects text at the same time, and the one-shot `dragEndedClick` guard stops a completed drag's trailing click from re-pinning (`bridge-script.ts:1381-1390`).