@kontourai/survey 2.2.3 → 2.3.0

package/dist/src/review-workbench/extraction-inspector.js

@@ -41,7 +41,77 @@ export function buildExtractionInspectorModel(input) {
                 candidates[index].alignment = "excerpt-mismatch";
         }
     }
-    return { sources, candidates };
+    return { sources, candidates: bindHighlightElementIds(candidates) };
+}
+const HIGHLIGHT_ID_PREFIX = "highlight-";
+/**
+ * Assigns every candidate the element id its source highlight will carry.
+ *
+ * Done here, over the whole model, rather than by a pure per-id derivation:
+ * sanitizing a candidate id to an HTML identifier is lossy (`a:b.c` and `a:b-c`
+ * both reduce to `a-b-c`), and two anchors sharing an id silently resolve a
+ * host's link to the wrong sentence. Today's candidate-id scheme happens not to
+ * produce that collision — the entry index always separates two sources — so
+ * the disambiguating suffix is defensive rather than a fix for a reachable bug.
+ * It is here because uniqueness is now a published promise
+ * ({@link ExtractionInspectorCandidate.highlightElementId}) that must survive a
+ * later change to the key scheme rather than depend on one.
+ */
+function bindHighlightElementIds(candidates) {
+    const used = new Set();
+    return candidates.map((candidate) => ({
+        ...candidate,
+        highlightElementId: uniqueHighlightElementId(candidate.id, used),
+    }));
+}
+/**
+ * Derives an element id not already taken.
+ *
+ * `used` holds finished element ids — prefix included — and so does the value
+ * returned, because the two have to be the same form to be comparable. They were
+ * not: uniqueness was checked on the bare token while the set held prefixed ids,
+ * so a published `highlight-alpha` did not stop a candidate with id `alpha` from
+ * deriving `highlight-alpha` and mounting a second element under it. A host's
+ * `href` then resolved to whichever came first.
+ */
+function uniqueHighlightElementId(candidateId, used) {
+    const base = `${HIGHLIGHT_ID_PREFIX}${safeId(candidateId)}`;
+    let elementId = base;
+    for (let suffix = 2; used.has(elementId); suffix += 1)
+        elementId = `${base}-${suffix}`;
+    used.add(elementId);
+    return elementId;
+}
+/** The inspector's own candidate-list id, paired 1:1 with a highlight anchor. Not public. */
+function candidateElementId(highlightElementId) {
+    return `candidate-${highlightElementId.slice(HIGHLIGHT_ID_PREFIX.length)}`;
+}
+/**
+ * The element id each candidate's anchor will carry, for one mount.
+ *
+ * A model from {@link buildExtractionInspectorModel} already carries one per
+ * candidate and it is used verbatim — rewriting a published id is precisely the
+ * drift this contract exists to prevent. A hand-authored model may omit some or
+ * all of them; those get an id derived here, seeded with the published ones so a
+ * derived id can never collide with one a host is already linking to.
+ *
+ * Keyed on the candidate OBJECT, not on `candidate.id`. The builder's ids are
+ * structurally unique, but this function exists for models a caller assembled,
+ * where nothing enforces that — and an id-keyed map silently collapsed two such
+ * candidates into one entry, handing the second's derived id to the first and
+ * discarding the very `highlightElementId` a host was already linking to. Object
+ * identity cannot collide, whatever the data says.
+ */
+function resolveHighlightElementIds(model) {
+    const used = new Set();
+    for (const candidate of model.candidates)
+        if (candidate.highlightElementId)
+            used.add(candidate.highlightElementId);
+    const resolved = new Map();
+    for (const candidate of model.candidates) {
+        resolved.set(candidate, candidate.highlightElementId ?? uniqueHighlightElementId(candidate.id, used));
+    }
+    return resolved;
 }
 function assertResolvedArtifact(artifact) {
     if (!artifact || typeof artifact !== "object" || Array.isArray(artifact))
@@ -164,7 +234,9 @@ export function exportExtractionInspector(model, options = {}) {
     return canonicalJson({ apiVersion: "survey.kontourai.io/v1alpha1", kind: "ExtractionInspectorExport", spec: {
             redaction: { preparedTextIncluded: options.includePreparedText === true, excerptsIncluded: options.includeExcerpts === true },
             sources: model.sources.map(({ artifactText, message: _message, ...source }) => ({ ...source, preparedText: options.includePreparedText ? artifactText ?? null : "[redacted]" })),
-            candidates: model.candidates.map((candidate) => ({ ...candidate, excerpt: options.includeExcerpts ? candidate.excerpt : "[redacted]" })),
+            // highlightElementId is a DOM binding for a live inspector, not extraction
+            // evidence — it stays out of the canonical export (and out of its digest).
+            candidates: model.candidates.map(({ highlightElementId: _highlightElementId, ...candidate }) => ({ ...candidate, excerpt: options.includeExcerpts ? candidate.excerpt : "[redacted]" })),
         } });
 }
 export function mountExtractionInspector(container, model, options = {}) {
@@ -172,6 +244,8 @@ export function mountExtractionInspector(container, model, options = {}) {
         ? Math.min(Number(options.pageSize), 500)
         : 100;
     let page = 0;
+    const highlightIds = resolveHighlightElementIds(model);
+    const highlightIdFor = (candidate) => highlightIds.get(candidate);
     const root = document.createElement("section");
     root.className = "extraction-inspector";
     root.setAttribute("aria-label", "Source-linked extraction inspector");
@@ -188,7 +262,7 @@ export function mountExtractionInspector(container, model, options = {}) {
         page = Math.min(page, pageCount - 1);
         const start = page * pageSize;
         const visible = matching.slice(start, start + pageSize);
-        list.innerHTML = visible.map(c => `<li><button type="button" class="inspector-candidate" id="candidate-${safeId(c.id)}" data-candidate-id="${escapeHtml(c.id)}" aria-controls="highlight-${safeId(c.id)}"><strong>${escapeHtml(c.field)}</strong><span>${escapeHtml(c.provider)}${c.model ? ` / ${escapeHtml(c.model)}` : ""}</span><span>${escapeHtml(c.inferenceType)} ${escapeHtml(c.valueType)} · ${escapeHtml(c.alignment)}</span>${formatContext(c)}</button></li>`).join("") || "<li>No candidates match these filters.</li>";
+        list.innerHTML = visible.map(c => `<li><button type="button" class="inspector-candidate" id="${escapeHtml(candidateElementId(highlightIdFor(c)))}" data-candidate-id="${escapeHtml(c.id)}" data-highlight-element-id="${escapeHtml(highlightIdFor(c))}" aria-controls="${escapeHtml(highlightIdFor(c))}"><strong>${escapeHtml(c.field)}</strong><span>${escapeHtml(c.provider)}${c.model ? ` / ${escapeHtml(c.model)}` : ""}</span><span>${escapeHtml(c.inferenceType)} ${escapeHtml(c.valueType)} · ${escapeHtml(c.alignment)}</span>${formatContext(c)}</button></li>`).join("") || "<li>No candidates match these filters.</li>";
         resultCount.textContent = matching.length === 0 ? "No matching candidates" : `${start + 1}–${Math.min(start + pageSize, matching.length)} of ${matching.length}`;
         pageLabel.textContent = `Page ${page + 1} of ${pageCount}`;
         pageLabel.hidden = pageCount === 1;
@@ -197,7 +271,7 @@ export function mountExtractionInspector(container, model, options = {}) {
         previous.disabled = page === 0;
         next.disabled = page >= pageCount - 1;
         postures.innerHTML = model.sources.map(s => `<div class="inspector-posture ${s.alignment}" role="status"><strong>${escapeHtml(s.importName)}: ${escapeHtml(s.alignment)}</strong><span>${escapeHtml(s.message)}</span></div>`).join("");
-        sourcesRoot.innerHTML = model.sources.map(s => { const candidates = visible.filter(c => c.sourceKey === s.key); return `<div class="inspector-source" aria-label="Prepared source for ${escapeHtml(s.importName)}"><h3>${escapeHtml(s.importName)}</h3><pre tabindex="0">${s.artifactText === undefined ? `<span class="source-unavailable">${escapeHtml(s.message)}</span>` : renderSource(s.artifactText, candidates)}</pre></div>`; }).join("");
+        sourcesRoot.innerHTML = model.sources.map(s => { const anchored = model.candidates.filter(c => c.sourceKey === s.key); const marked = visible.filter(c => c.sourceKey === s.key); return `<div class="inspector-source" aria-label="Prepared source for ${escapeHtml(s.importName)}"><h3>${escapeHtml(s.importName)}</h3><pre tabindex="0">${s.artifactText === undefined ? `${anchored.map(c => anchorHtml(c, highlightIdFor(c))).join("")}<span class="source-unavailable">${escapeHtml(s.message)}</span>` : renderSource(s.artifactText, anchored, marked, highlightIdFor)}</pre></div>`; }).join("");
     };
     root.querySelectorAll("select").forEach(select => select.addEventListener("change", event => { event.stopPropagation(); const key = select.dataset.filter; if (select.value)
         filters[key] = select.value;
@@ -209,50 +283,187 @@ export function mountExtractionInspector(container, model, options = {}) {
         delete filters.query; page = 0; render(); });
     previous.addEventListener("click", () => { page = Math.max(0, page - 1); render(); list.querySelector("button")?.focus(); });
     next.addEventListener("click", () => { page += 1; render(); list.querySelector("button")?.focus(); });
-    const activateCandidate = (id) => { const candidate = model.candidates.find(c => c.id === id); if (!candidate)
-        return; root.dispatchEvent(new CustomEvent("survey-extraction-candidate-activate", { bubbles: true, composed: true, detail: { candidateId: id, reviewItemName: candidate.reviewItemName } })); };
-    root.addEventListener("click", event => { const candidate = event.target.closest("button[data-candidate-id]"); if (candidate) {
+    // The event carries the resolved binding as well as the identity: a listener
+    // that wants to focus the highlight must never reconstruct the id, and the
+    // first-party custom element is the reference implementation of that rule.
+    const candidateFor = (highlightElementId) => model.candidates.find(c => highlightIdFor(c) === highlightElementId);
+    const activateCandidate = (highlightElementId) => { const candidate = candidateFor(highlightElementId); if (!candidate)
+        return; root.dispatchEvent(new CustomEvent("survey-extraction-candidate-activate", { bubbles: true, composed: true, detail: { candidateId: candidate.id, reviewItemName: candidate.reviewItemName, highlightElementId } })); };
+    const clearFilters = () => {
+        for (const key of Object.keys(filters))
+            delete filters[key];
+        root.querySelectorAll("select[data-filter]").forEach(select => { select.value = ""; });
+        const search = root.querySelector('input[data-filter="query"]');
+        if (search)
+            search.value = "";
+    };
+    /**
+     * Brings a candidate's row onto the mounted page so it can be focused.
+     *
+     * Anchors exist for every candidate, so a highlight can be activated while its
+     * candidate row is on another page or filtered out entirely. Returning focus
+     * to a row that is not mounted would silently do nothing, so page to it —
+     * clearing the filters first if they are what is hiding it.
+     */
+    const revealCandidateRow = (highlightElementId) => {
+        const candidate = candidateFor(highlightElementId);
+        if (!candidate)
+            return undefined;
+        let index = filterExtractionInspectorCandidates(model, filters).indexOf(candidate);
+        if (index < 0) {
+            clearFilters();
+            index = model.candidates.indexOf(candidate);
+        }
+        if (index < 0)
+            return undefined;
+        page = Math.floor(index / pageSize);
+        render();
+        return candidate;
+    };
+    const returnToCandidate = (highlightElementId) => {
+        if (revealCandidateRow(highlightElementId))
+            root.querySelector(`#${CSS.escape(candidateElementId(highlightElementId))}`)?.focus();
+    };
+    /**
+     * Follows a host's `href="#<highlightElementId>"`.
+     *
+     * The anchor that id names always exists, but a candidate off the current page
+     * or excluded by a filter has no painted highlight, so the link would land the
+     * reader on an invisible marker in the middle of the source text. Page to the
+     * candidate instead, so the highlight it points at is actually painted, and put
+     * focus on it.
+     */
+    const followHighlightFragment = () => {
+        const fragment = typeof location === "undefined" ? "" : location.hash.slice(1);
+        if (!fragment)
+            return;
+        if (!candidateFor(fragment))
+            return;
+        revealCandidateRow(fragment);
+        // `~=` matches one whitespace-separated token: a mark painted over a span
+        // shared by several candidates lists all of them, and this is the one the
+        // reader asked for. Record it, so activating that mark returns to the
+        // candidate they arrived by rather than to whichever is listed first.
+        const mark = root.querySelector(`[data-highlight-return-to~="${CSS.escape(fragment)}"]`);
+        if (!mark)
+            return;
+        mark.dataset.highlightArrivedBy = fragment;
+        mark.focus();
+        mark.scrollIntoView({ block: "center" });
+    };
+    const onHashChange = () => followHighlightFragment();
+    if (typeof window !== "undefined")
+        window.addEventListener("hashchange", onHashChange);
+    /** The candidate a shared mark returns to: the one the reader arrived by, else the first it covers. */
+    const returnTargetOf = (mark) => mark.dataset.highlightArrivedBy ?? mark.dataset.highlightReturnTo.split(" ")[0];
+    root.addEventListener("click", event => { const candidate = event.target.closest("button[data-highlight-element-id]"); if (candidate) {
         event.preventDefault();
         event.stopPropagation();
-        activateCandidate(candidate.dataset.candidateId);
+        activateCandidate(candidate.dataset.highlightElementId);
         return;
-    } const highlight = event.target.closest("button[data-highlight-candidate-id]"); if (highlight) {
+    } const highlight = event.target.closest("[data-highlight-return-to]"); if (highlight) {
         event.preventDefault();
         event.stopPropagation();
-        root.querySelector(`#candidate-${CSS.escape(safeId(highlight.dataset.highlightCandidateId))}`)?.focus();
+        returnToCandidate(returnTargetOf(highlight));
     } });
-    root.addEventListener("keydown", event => { const button = event.target.closest("button[data-candidate-id]"); if (!button)
+    root.addEventListener("keydown", event => { const highlight = event.target.closest("[data-highlight-return-to]"); if (highlight) {
+        if (event.key !== "Enter" && event.key !== " ")
+            return;
+        event.preventDefault();
+        event.stopPropagation();
+        returnToCandidate(returnTargetOf(highlight));
+        return;
+    } const button = event.target.closest("button[data-highlight-element-id]"); if (!button)
         return; if (event.key === "Enter" || event.key === " ") {
         event.preventDefault();
         event.stopPropagation();
-        activateCandidate(button.dataset.candidateId);
+        activateCandidate(button.dataset.highlightElementId);
         return;
     } if (event.key === "ArrowDown" || event.key === "ArrowUp") {
         event.preventDefault();
-        const buttons = [...list.querySelectorAll("button[data-candidate-id]")];
+        const buttons = [...list.querySelectorAll("button[data-highlight-element-id]")];
         const index = buttons.indexOf(button);
         buttons[event.key === "ArrowDown" ? Math.min(index + 1, buttons.length - 1) : Math.max(index - 1, 0)]?.focus();
     } });
     render();
-    return () => root.remove();
+    followHighlightFragment();
+    return () => { if (typeof window !== "undefined")
+        window.removeEventListener("hashchange", onHashChange); root.remove(); };
 }
-function renderSource(text, candidates) {
+/**
+ * Renders the prepared text with a return anchor for every candidate and a
+ * `<mark>` for the ones on the current page.
+ *
+ * The two sets are deliberately different. `marked` follows the candidate
+ * list's paging and filtering, so the painting tracks what the reviewer is
+ * looking at. `anchored` is every candidate the source has, so that the element
+ * id published on the model resolves whatever page the reviewer is on and
+ * whatever they have typed into the filter box — the anchors carry the contract,
+ * the marks carry the view.
+ */
+function renderSource(text, anchored, marked, highlightIdFor) {
     const boundaries = new Set([0, text.length]);
-    candidates.forEach(c => { boundaries.add(c.start); boundaries.add(c.end); });
-    const points = [...boundaries].sort((a, b) => a - b);
+    anchored.forEach(c => boundaries.add(c.start));
+    marked.forEach(c => { boundaries.add(c.start); boundaries.add(c.end); });
+    const points = [...boundaries].filter(point => point >= 0 && point <= text.length).sort((a, b) => a - b);
     let html = "";
     const starts = new Map();
-    candidates.forEach(c => starts.set(c.start, [...(starts.get(c.start) ?? []), c]));
+    anchored.forEach(c => starts.set(c.start, [...(starts.get(c.start) ?? []), c]));
+    const emitted = new Set();
     for (let i = 0; i < points.length - 1; i++) {
         const start = points[i], end = points[i + 1];
-        for (const c of starts.get(start) ?? [])
-            html += `<button type="button" class="highlight-anchor" id="highlight-${safeId(c.id)}" data-highlight-candidate-id="${escapeHtml(c.id)}" aria-label="Source highlight for ${escapeHtml(c.field)}; activate to return to candidate"></button>`;
+        for (const c of starts.get(start) ?? []) {
+            emitted.add(c);
+            html += anchorHtml(c, highlightIdFor(c));
+        }
         const segment = escapeHtml(text.slice(start, end));
-        const active = candidates.filter(c => c.start < end && c.end > start);
-        html += active.length ? `<mark aria-label="Highlighted for ${active.map(c => escapeHtml(c.field)).join(", ")}">${segment}</mark>` : segment;
+        const active = marked.filter(c => c.start < end && c.end > start);
+        html += active.length ? markHtml(segment, active, highlightIdFor) : segment;
     }
+    // A span starting at or past the end of the prepared text has no segment to
+    // lead; its anchor still has to exist, or its published id resolves nowhere.
+    for (const c of anchored)
+        if (!emitted.has(c))
+            html += anchorHtml(c, highlightIdFor(c));
     return html;
 }
+/**
+ * The link target a host's `href` resolves to: an empty, inert span at the start
+ * of the candidate's span.
+ *
+ * Deliberately NOT a control. It exists for every candidate in the model, which
+ * is what makes the published id resolve unconditionally — but a thing that
+ * exists per candidate must cost nothing to a keyboard or screen-reader user, and
+ * as a `<button>` it did: 600 candidates put 600 invisible tab stops in sequence,
+ * several of them stacked together in the non-grounded postures. It was also a
+ * one-pixel pointer target once its accidental user-agent chrome was removed —
+ * an affordance in name only, at any size, because nothing about it was visible.
+ *
+ * Returning to the candidate is now the job of the thing a reader can actually
+ * see and aim at: the highlight itself. See {@link markHtml}.
+ */
+function anchorHtml(candidate, highlightElementId) {
+    return `<span class="highlight-anchor" id="${escapeHtml(highlightElementId)}" data-highlight-candidate-id="${escapeHtml(candidate.id)}"></span>`;
+}
+/**
+ * The painted highlight, and the control that returns to its candidate.
+ *
+ * The highlight is the only part of this surface a reader can see, so it is the
+ * target: full phrase width rather than a sliver, discoverable because it is
+ * already visibly marked, and one tab stop per painted highlight rather than one
+ * per candidate in the model. `data-highlight-return-to` is separate from the
+ * anchor's `data-highlight-candidate-id` so the documented reverse lookup keeps
+ * resolving to exactly one element.
+ */
+function markHtml(segment, active, highlightIdFor) {
+    const fields = active.map(c => escapeHtml(c.field)).join(", ");
+    // Every candidate the mark covers, not just the first. Two claims over one
+    // span is ordinary in extraction, and naming both in the label while binding
+    // only one left the others with a highlight that could not be navigated to or
+    // returned from — the label said two, the binding said one.
+    const bindings = active.map(c => escapeHtml(highlightIdFor(c))).join(" ");
+    return `<mark class="source-highlight" role="button" tabindex="0" data-highlight-return-to="${bindings}" aria-label="Highlighted for ${fields}; activate to return to candidate">${segment}</mark>`;
+}
 function formatContext(candidate) {
     const context = [];
     if (candidate.pdfRegion) {

package/dist/src/review-workbench/review-presentation.js

@@ -1,3 +1,4 @@
+import { findSoleCandidateById } from "../review-resource.js";
 import { formatValue } from "./review-surface-preview.js";
 export function buildReviewItemPresentation(item, adapter = {}) {
     const context = { item };
@@ -34,7 +35,7 @@ export function buildReviewResultPresentation(result, item, adapter = {}) {
     const targetLabel = item && itemContext
         ? adapter.labelForTarget?.(target, itemContext) ?? humanizeIdentifier(target)
         : humanizeIdentifier(target);
-    const selectedCandidate = item?.spec.candidates.find((candidate) => candidate.role === result.selectedCandidateRole || candidate.id === result.selectedCandidateId);
+    const selectedCandidate = item ? selectedCandidateForResult(item, result) : undefined;
     return {
         result,
         item,
@@ -53,6 +54,32 @@ export function buildReviewResultPresentation(result, item, adapter = {}) {
             : [{ label: "Survey ReviewItem", value: result.reviewItemName, kind: "review-item" }],
     };
 }
+/**
+ * The candidate a result selected, resolved by its complete identity.
+ *
+ * `find(role === … || id === …)` returned whichever candidate matched EITHER
+ * half, so on an item carrying a repeated candidate id it could return a
+ * different candidate than the result names — presenting one candidate's value
+ * against another's decision, which is exactly what it did.
+ *
+ * The id is the identity; {@link findSoleCandidateById} makes it fail closed
+ * rather than pick a winner when it is ambiguous, and the declared role has to
+ * agree when the result states one. Falling back to the role alone is kept for
+ * results that carry no id, and requires the role to be unambiguous too.
+ */
+function selectedCandidateForResult(item, result) {
+    if (result.selectedCandidateId) {
+        const candidate = findSoleCandidateById(item, result.selectedCandidateId);
+        if (candidate && (result.selectedCandidateRole === undefined || candidate.role === result.selectedCandidateRole)) {
+            return candidate;
+        }
+    }
+    if (result.selectedCandidateRole === undefined) {
+        return undefined;
+    }
+    const byRole = item.spec.candidates.filter((candidate) => candidate.role === result.selectedCandidateRole);
+    return byRole.length === 1 ? byRole[0] : undefined;
+}
 export function humanizeIdentifier(value) {
     return value
         .replace(/[_-]+/g, " ")

package/dist/src/review-workbench/review-queue-session.d.ts

@@ -91,6 +91,17 @@ export declare function reviewSessionSummary(session: ReviewQueueSessionState):
  * would invent a prior value, with provenance, that the source never had.
  */
 export declare function keepActionDecision(item: ReviewItem, flaggedWrong: boolean): ReviewWorkbenchDecision | undefined;
+/**
+ * The candidate a workbench decision applies to.
+ *
+ * Selection is by role, but the id this returns is what every caller makes
+ * durable — a ReviewDecision's `candidateId`, a session event's, a result's, a
+ * replay expectation. So the id has to name exactly one candidate before it
+ * leaves here. Guarding the render path alone let the workbench emit an
+ * undecidable decision through the export path and then present a different
+ * candidate's value against it; this is the shared selector all of those go
+ * through, which is why the check belongs here rather than at each of them.
+ */
 export declare function candidateForDecision(item: ReviewItem, decision: ReviewWorkbenchDecision): ReviewCandidate;
 /**
  * The value that should actually be applied for a decision: the reviewer's inline

package/dist/src/review-workbench/review-queue-session.js

@@ -1,6 +1,6 @@
 import { publicDirectoryReviewItemExample, reviewWorkbenchQueueExamples } from "./review-workbench-data.js";
 import { assertReviewResolutionConsistency } from "../producer-discipline.js";
-import { reviewResourceApiVersion, } from "../../src/review-resource.js";
+import { assertSoleCandidateId, reviewResourceApiVersion, } from "../../src/review-resource.js";
 export const reviewWorkbenchSessionStorageKey = "kontourai.survey.review-workbench.session-events.v1";
 export const defaultReviewSessionName = "review-workbench-session";
 export const workbenchDecisionDefinitions = {
@@ -148,12 +148,24 @@ export function keepActionDecision(item, flaggedWrong) {
     }
     return "keep-current";
 }
+/**
+ * The candidate a workbench decision applies to.
+ *
+ * Selection is by role, but the id this returns is what every caller makes
+ * durable — a ReviewDecision's `candidateId`, a session event's, a result's, a
+ * replay expectation. So the id has to name exactly one candidate before it
+ * leaves here. Guarding the render path alone let the workbench emit an
+ * undecidable decision through the export path and then present a different
+ * candidate's value against it; this is the shared selector all of those go
+ * through, which is why the check belongs here rather than at each of them.
+ */
 export function candidateForDecision(item, decision) {
     const definition = workbenchDecisionDefinitions[decision];
     const candidate = item.spec.candidates.find((entry) => entry.role === definition.candidateRole);
     if (!candidate) {
         throw new Error(`ReviewItem ${item.metadata.name} has no ${definition.candidateRole} candidate.`);
     }
+    assertSoleCandidateId(item, candidate.id);
     return candidate;
 }
 /**

package/dist/src/review-workbench/review-surface-preview.js

@@ -1,3 +1,4 @@
+import { findSoleCandidateById } from "../review-resource.js";
 export function buildSurfaceProjectionPreview(item, decision, presentationAdapter = {}) {
     const selectedCandidate = selectedPreviewCandidate(item, decision);
     if (!selectedCandidate || !decision) {
@@ -38,7 +39,7 @@ function selectedPreviewCandidate(item, decision) {
     if (!decision?.spec.candidateId) {
         return undefined;
     }
-    const candidate = item.spec.candidates.find((entry) => entry.id === decision.spec.candidateId);
+    const candidate = findSoleCandidateById(item, decision.spec.candidateId);
     if (!candidate) {
         throw new Error(`ReviewItem ${item.metadata.name} has no candidate ${decision.spec.candidateId}.`);
     }

package/dist/src/review-workbench/review-workbench-css.generated.js

@@ -202,11 +202,37 @@ export const REVIEW_WORKBENCH_CSS = `/* Bundled, scoped Survey Review Workbench
 .survey-workbench-embed .inspector-pager button:disabled, .survey-workbench-embed .queue-pager button:disabled{ opacity: .45; }
 .survey-workbench-embed .inspector-candidates{ margin: 0; padding-left: 1.5rem; }
 .survey-workbench-embed .inspector-candidate{ width: 100%; display: grid; gap: .2rem; text-align: left; padding: .65rem; color: var(--k-text); background: transparent; border: 1px solid var(--k-line); }
-.survey-workbench-embed .inspector-source pre{ white-space: pre-wrap; overflow-wrap: anywhere; margin: 0; padding: 1rem; background: var(--k-sunken); border: 1px solid var(--k-line); min-height: 8rem; }
+.survey-workbench-embed .inspector-source pre{ white-space: pre-wrap; overflow-wrap: anywhere; margin: 0; padding: 1rem; background: var(--k-sunken); border: 1px solid var(--k-line); min-height: 8rem; line-height: 2.2; }
 .survey-workbench-embed .inspector-source mark{ background: var(--k-brand-wash); color: var(--k-text); outline: 1px solid var(--k-brand); }
 .survey-workbench-embed .inspector-candidate:focus{ outline: 3px solid var(--k-active); outline-offset: 2px; }
-.survey-workbench-embed .highlight-anchor{ display: inline-block; width: 1px; height: 1em; }
-.survey-workbench-embed .highlight-anchor:focus{ outline: 3px solid var(--k-active); }
+/* An inert link target, one per candidate in the model, so a host's
+   \`href="#<highlightElementId>"\` always resolves. It is not a control and must
+   not behave like one: no size, no tab stop, nothing painted. */
+.survey-workbench-embed .highlight-anchor{
+  display: inline;
+  width: 0;
+  height: 0;
+  overflow: hidden;
+}
+
+/* The highlight IS the return control — the only part of this surface a reader
+   can see, so it is the thing to aim at. Full phrase width, already visibly
+   marked, one tab stop per painted highlight. */
+.survey-workbench-embed .source-highlight{
+  cursor: pointer;
+  border-radius: 2px;
+  /* Vertical padding on an inline box grows the hit area without moving the
+     line box, and the prepared text's line-height below leaves room for it, so
+     the target reaches ~24px tall without lines overlapping each other. The
+     phrase itself supplies the width. */
+  padding: 5px 3px;
+  margin: 0 -3px;
+}
+
+.survey-workbench-embed .source-highlight:focus-visible{
+  outline: 3px solid var(--k-active);
+  outline-offset: 1px;
+}
 .survey-workbench-embed .source-unavailable{ color: var(--k-negative); font-weight: 700; }
 @container (max-width: 720px) { .inspector-heading, .inspector-layout { grid-template-columns: 1fr !important; } }
 
@@ -639,6 +665,22 @@ export const REVIEW_WORKBENCH_CSS = `/* Bundled, scoped Survey Review Workbench
   display: none;
 }
 
+/* Why a decision was refused, next to the button that refused it. The input
+   that satisfies the precondition can be inside the collapsed audit accordion,
+   so the message cannot live only with the input (kontourai/survey#208). */
+.survey-workbench-embed .derr{
+  display: block;
+  margin-top: 6px;
+  text-align: right;
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--k-negative);
+}
+
+.survey-workbench-embed .derr[hidden]{
+  display: none;
+}
+
 /* confidence + provenance */
 
 .survey-workbench-embed .prov{
@@ -1080,14 +1122,6 @@ export const REVIEW_WORKBENCH_CSS = `/* Bundled, scoped Survey Review Workbench
   text-transform: uppercase;
 }
 
-.survey-workbench-embed .preview-section.is-neutral{
-  background: var(--k-raised);
-}
-
-.survey-workbench-embed .preview-section.is-neutral h3{
-  color: var(--k-faint);
-}
-
 .survey-workbench-embed .reference-details{
   margin-top: 8px;
 }

package/dist/src/review-workbench/review-workbench-element.js

@@ -298,7 +298,30 @@ export class SurveyReviewWorkbenchElement extends HTMLElement {
             if (this.#session.activeItemName !== item.metadata.name)
                 this.#session = { ...this.#session, activeItemName: item.metadata.name };
             this.#remount();
-            queueMicrotask(() => this.#root.querySelector(`#highlight-${CSS.escape(detail.candidateId.replace(/[^a-zA-Z0-9_-]/g, "-"))}`)?.focus());
+            // Both lookups below are published contracts, used as published.
+            // Reconstructing the element id from candidateId — which this did — meant
+            // carrying a copy of Survey's private id sanitizer and ignoring the
+            // collision suffix that makes the id unique, which is exactly what the
+            // consumer guide tells embedders not to do.
+            const { highlightElementId } = detail;
+            if (!highlightElementId)
+                return;
+            queueMicrotask(() => {
+                // Routed on the highlight element id, which is unique by construction.
+                // candidateId is the candidate's own identity and a caller-authored
+                // model may repeat it, so a `[data-…="<candidateId>"]` lookup can select
+                // a different candidate's highlight — confidently wrong, on the surface
+                // whose job is showing which span a value came from. `~=` matches one
+                // whitespace-separated token, so a mark over a shared span is found too.
+                const highlight = this.#root.querySelector(`[data-highlight-return-to~="${CSS.escape(highlightElementId)}"]`);
+                if (highlight) {
+                    highlight.focus();
+                    return;
+                }
+                // Off the current page there is nothing painted; bring the link target
+                // into view instead of leaving the reader where they were.
+                this.#root.querySelector(`#${CSS.escape(highlightElementId)}`)?.scrollIntoView({ block: "center" });
+            });
         });
     }
     /** The review queue session to display. Setting this property re-mounts the workbench. */

package/dist/src/review-workbench/review-workbench.css

@@ -199,11 +199,37 @@
 .survey-workbench-embed .inspector-pager button:disabled, .survey-workbench-embed .queue-pager button:disabled{ opacity: .45; }
 .survey-workbench-embed .inspector-candidates{ margin: 0; padding-left: 1.5rem; }
 .survey-workbench-embed .inspector-candidate{ width: 100%; display: grid; gap: .2rem; text-align: left; padding: .65rem; color: var(--k-text); background: transparent; border: 1px solid var(--k-line); }
-.survey-workbench-embed .inspector-source pre{ white-space: pre-wrap; overflow-wrap: anywhere; margin: 0; padding: 1rem; background: var(--k-sunken); border: 1px solid var(--k-line); min-height: 8rem; }
+.survey-workbench-embed .inspector-source pre{ white-space: pre-wrap; overflow-wrap: anywhere; margin: 0; padding: 1rem; background: var(--k-sunken); border: 1px solid var(--k-line); min-height: 8rem; line-height: 2.2; }
 .survey-workbench-embed .inspector-source mark{ background: var(--k-brand-wash); color: var(--k-text); outline: 1px solid var(--k-brand); }
 .survey-workbench-embed .inspector-candidate:focus{ outline: 3px solid var(--k-active); outline-offset: 2px; }
-.survey-workbench-embed .highlight-anchor{ display: inline-block; width: 1px; height: 1em; }
-.survey-workbench-embed .highlight-anchor:focus{ outline: 3px solid var(--k-active); }
+/* An inert link target, one per candidate in the model, so a host's
+   `href="#<highlightElementId>"` always resolves. It is not a control and must
+   not behave like one: no size, no tab stop, nothing painted. */
+.survey-workbench-embed .highlight-anchor{
+  display: inline;
+  width: 0;
+  height: 0;
+  overflow: hidden;
+}
+
+/* The highlight IS the return control — the only part of this surface a reader
+   can see, so it is the thing to aim at. Full phrase width, already visibly
+   marked, one tab stop per painted highlight. */
+.survey-workbench-embed .source-highlight{
+  cursor: pointer;
+  border-radius: 2px;
+  /* Vertical padding on an inline box grows the hit area without moving the
+     line box, and the prepared text's line-height below leaves room for it, so
+     the target reaches ~24px tall without lines overlapping each other. The
+     phrase itself supplies the width. */
+  padding: 5px 3px;
+  margin: 0 -3px;
+}
+
+.survey-workbench-embed .source-highlight:focus-visible{
+  outline: 3px solid var(--k-active);
+  outline-offset: 1px;
+}
 .survey-workbench-embed .source-unavailable{ color: var(--k-negative); font-weight: 700; }
 @container (max-width: 720px) { .inspector-heading, .inspector-layout { grid-template-columns: 1fr !important; } }
 
@@ -636,6 +662,22 @@
   display: none;
 }
 
+/* Why a decision was refused, next to the button that refused it. The input
+   that satisfies the precondition can be inside the collapsed audit accordion,
+   so the message cannot live only with the input (kontourai/survey#208). */
+.survey-workbench-embed .derr{
+  display: block;
+  margin-top: 6px;
+  text-align: right;
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--k-negative);
+}
+
+.survey-workbench-embed .derr[hidden]{
+  display: none;
+}
+
 /* confidence + provenance */
 
 .survey-workbench-embed .prov{
@@ -1077,14 +1119,6 @@
   text-transform: uppercase;
 }
 
-.survey-workbench-embed .preview-section.is-neutral{
-  background: var(--k-raised);
-}
-
-.survey-workbench-embed .preview-section.is-neutral h3{
-  color: var(--k-faint);
-}
-
 .survey-workbench-embed .reference-details{
   margin-top: 8px;
 }

package/dist/src/review-workbench/review-workbench.d.ts

@@ -2,7 +2,8 @@ import { type ReviewQueueSessionState, type ReviewWorkbenchDecision, type Review
 import { type ReviewSessionReplayIssue } from "./review-session-replay.js";
 import { type ReviewPresentationAdapter } from "./review-presentation.js";
 import { type ReviewCandidate, type ReviewDecision, type ReviewItem, type ReviewSession, type ReviewSessionEvent, type ReviewValueDescriptor } from "../review-resource.js";
-export { buildExtractionInspectorModel, exportExtractionInspector, filterExtractionInspectorCandidates, mountExtractionInspector, type ExtractionAlignmentState, type ArtifactUnavailableCode, type ExtractionInspectorCandidate, type ExtractionInspectorEntry, type ExtractionInspectorExportOptions, type ExtractionInspectorFilters, type ExtractionInspectorInput, type ExtractionInspectorMountOptions, type ExtractionInspectorModel, type ExtractionInspectorSource, type ResolvedExtractionArtifact, } from "./extraction-inspector.js";
+export { reviewAuditRowKeys, type ReviewAuditRowKey } from "./audit-rows.js";
+export { buildExtractionInspectorModel, exportExtractionInspector, filterExtractionInspectorCandidates, mountExtractionInspector, type ExtractionAlignmentState, type ArtifactUnavailableCode, type BuiltExtractionInspectorCandidate, type BuiltExtractionInspectorModel, type ExtractionInspectorCandidate, type ExtractionInspectorEntry, type ExtractionInspectorExportOptions, type ExtractionInspectorFilters, type ExtractionInspectorInput, type ExtractionInspectorMountOptions, type ExtractionInspectorModel, type ExtractionInspectorSource, type ResolvedExtractionArtifact, } from "./extraction-inspector.js";
 export { buildReviewSessionEvents, buildReviewSessionEvent, buildReviewSessionResource, candidateForDecision, keepActionDecision, currentReviewItem, currentReviewWorkbenchState, defaultReviewSessionName, deriveQueueRowStatus, initialReviewQueueSessionState, initialReviewWorkbenchState, nextUnresolvedItemName, replayReviewSessionEvents, reviewSessionSummary, reviewWorkbenchSessionStorageKey, selectedCandidateRole, workbenchDecisionDefinitions, type ReviewQueueRowStatus, type ReviewQueueSessionState, type ReviewSessionSummary, type ReviewWorkbenchDecision, type ReviewWorkbenchState, } from "./review-queue-session.js";
 export { buildReviewCandidatePresentation, buildReviewItemPresentation, buildReviewResultPresentation, humanizeIdentifier, type ReviewCandidatePresentation, type ReviewCandidatePresentationContext, type ReviewItemPresentation, type ReviewItemPresentationContext, type ReviewPresentationAdapter, type ReviewPresentationLink, type ReviewResultPresentation, type ReviewTracePresentationContext, type ReviewTraceRef, type ReviewValuePresentationContext, } from "./review-presentation.js";
 export { buildSurfaceProjectionPreview, type PreviewAuthorityTrace, type PreviewCandidateHistory, type PreviewClaim, type PreviewIntegrityPosture, type PreviewReviewEvent, type PreviewSourceAuthority, type PreviewSourceEvidence, type SurfaceProjectionPreview, } from "./review-surface-preview.js";