@thehammer/template-verification 0.2.9 → 0.2.11

package/README.md

@@ -1,28 +1,39 @@
 # @thehammer/template-verification
 
-A read-write **verification overlay** for rendered template apps. It overlays a
-trust layer on top of an already-rendered document template: per-data-point
-confidence pills + verified check chips, discrepancy indicators, and a
-click-through **Inspector** dialog — a hero strip (resolved value, gradient
-confidence meter, discrepancy alert) over three tabs:
-
-- **Evidence** — readonly-markdown reasoning, cited-text quote, an embedded
-  `DanxFileViewer` over the cited source pages, and per-document drill-down
-  to the FULL parent PDF in a stacked dialog.
-- **Candidates** — the resolution flow: one card per candidate
-  (override/extracted/claim) with Accept actions + custom-value entry;
-  saves toast and flip the in-document pill to a verified chip.
-- **Audit trail** — the LLM calls behind the data point (model, status,
-  timing, collapsible JSON request/response), lazy-fetched from the host's
-  token-sealed `audit_url`. Tab hidden when the host mints none.
-
-`VerificationChrome` adds a review-progress meter (X of Y human-verified),
-a needs-review jump button, and completion celebration.
-
-Render data + `__meta` arrive via a single `initVerification()` call — the
-only network the library touches is the host-supplied `saveOverride`
-transport and the optional `auditUrl` endpoint. Backend-agnostic and
-unit-testable standalone.
+The **verification overlay** a rendered template app wears, and the one signal it
+sends back out.
+
+It draws ONE mark beside every bound data value — a confidence pill, a verified
+check chip once a person has locked the value in, and a discrepancy indicator
+when candidates or source documents disagree. Clicking that mark posts a
+`data-point-activated` message to the embedding application. Nothing else
+happens inside the document.
+
+`VerificationChrome` adds the overlay's on/off toggle, a review-progress meter
+(X of Y human-verified) and a needs-review jump button, all hidden under print.
+
+Render data + `__meta` arrive via a single `initVerification()` call. **The
+library fetches nothing and saves nothing.**
+
+## What this library used to do, and deliberately no longer does
+
+Earlier versions rendered the whole review surface INSIDE the iframe: a
+90vw × 90vh **Inspector** dialog with Evidence / Candidates / History / Audit
+tabs, an embedded file viewer over the cited pages, a hover summary panel on
+every mark, and `contenteditable` editing on the value with a save transport
+behind it. All of that is **deleted**, along with `VerificationModal`,
+`CitationEvidence`, `CitationPageList`, `CitationPage`, `citationEvidence`,
+`citationSummary` and `fetchDataPointDetail`.
+
+A letter is a document, and a document that grows a second application on top of
+itself is two products fighting over one viewport — in a frame that cannot reach
+any of the viewers the embedding app already has. Reviewing a value now happens
+in that app, which opens the citation and the record beside the letter.
+
+`initVerification` still **accepts** `saveOverride` and `detailUrl` and ignores
+both. That is compile-time compatibility for already-built templates, whose
+`App.vue` is generated from a snippet that still passes them; it is not a
+feature. See `src/context.ts`.
 
 ## Install
 
@@ -33,8 +44,9 @@ npm install @thehammer/template-verification
 `vue` and `@thehammer/danx-ui` are peer dependencies (runtime externals) — the
 host template app already loads both.
 
-Import the stylesheet once (it carries the `@media print` rule that hides the
-overlay chrome on print/export):
+Import the stylesheet once. It carries the `@media print` rule that hides the
+overlay chrome on print/export, AND the positioning rule that keeps the mark out
+of the text flow:
 
 ```ts
 import "@thehammer/template-verification/style.css"
@@ -52,23 +64,12 @@ import { initVerification, VerificationChrome, VerifiedField } from "@thehammer/
 
 const props = defineProps<{ data: any }>()
 
-// Host-supplied, authenticated transport. Its presence enables inline editing.
-async function saveOverride(args) {
-  const res = await fetch(`/api/workflow-inputs/${args.workflow_input_id}/data-point-overrides`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
-    body: JSON.stringify({ ...args, object_id: args.object_ids.at(-1) })
-  })
-  return res.json() // recomputed DataPointMeta
-}
-
-// Once, at root setup. Absent saveOverride ⇒ every field is read-only.
 initVerification({
   data: props.data,
-  saveOverride,
-  workflowInputId: props.data.__verification?.workflow_input_id,
-  // Token-sealed audit endpoint (optional) — enables the Inspector's Audit tab.
-  auditUrl: props.data.__verification?.audit_url ?? null
+  // Echoed on every activation message, so the embedder can tell a click on
+  // THIS render from a click on one it has already replaced.
+  workflowInputId: props.data.__verification?.workflow_input_id ?? null,
+  defaultEnabled: props.data.__verification?.default_enabled ?? false
 })
 </script>
 
@@ -89,6 +90,46 @@ The backing store is a **module singleton** — safe because each rendered templ
 runs as its own isolated Vue app inside its own iframe (one JS module instance,
 one app-wide config, no SSR). See `src/context.ts` for the invariant.
 
+## The mark occupies no space, and that is a contract
+
+The mark is absolutely positioned against its wrapper, overlaying the right-hand
+end of the value it belongs to. Turning the overlay on or off, or a field going
+from unverified to verified, must not move a single character of the document.
+
+Measured rather than asserted: `.junk/reflow-probe` in the gpt-manager repo
+mounts `VerifiedField` twice into one paragraph in a real browser, with the
+overlay on and off, and compares `getBoundingClientRect()` for the value and for
+the text after it. `src/__tests__/VerifiedField.test.ts` pins the structural
+half (happy-dom has no layout engine, so a rect assertion there would pass on
+zeroes).
+
+## The outbound message
+
+```ts
+{
+  source: "danxbot-template",        // TEMPLATE_MESSAGE_SOURCE
+  version: 1,                        // TEMPLATE_PROTOCOL_VERSION
+  type: "data-point-activated",      // DATA_POINT_ACTIVATED
+  anchor: {                          // copied VERBATIM from __meta, unreshaped
+    object_ids: [4211, 77],          // full root-to-leaf path; LAST is the record
+    field: "full_name",
+    field_path: "medical_providers.0.full_name"
+  },
+  workflowInputId: 431 | null,
+  label: "full_name" | null,
+  value: "Jane Doe" | null
+}
+```
+
+Posted to `window.parent` at the embedder's **real origin**, never `"*"`. The
+origin is resolved from `location.ancestorOrigins[0]`, falling back to
+`document.referrer`'s origin; when neither resolves, **nothing is posted**. See
+`src/lib/hostBridge.ts`.
+
+A receiver must check `event.origin` before it looks at the payload. A payload
+check is not a security check: anyone can post a well-formed message, and only
+the bundle can post from the bundle's origin.
+
 ## The `__meta` contract
 
 Each rendered object node carries a `__meta` map keyed by leaf field name. Each
@@ -99,7 +140,7 @@ interface DataPointMeta {
   anchor: { object_ids: (number | string)[]; field: string; field_path: string }
   candidates: {
     override?: { value; source_choice }
-    extracted?: { value; confidence: number | null; reasoning; cited_text; cited_text_verified; sources[] }
+    extracted?: { value; confidence: number | null; state; sources_count; history_count }
     claim?: { value; claim_set_label }
   }
   discrepancy: boolean
@@ -111,15 +152,16 @@ interface DataPointMeta {
 
 - **Resolution priority:** `override > extracted > claim`.
 - **Status** buckets the **integer** confidence: `null → unverifiable (gray)`,
-  `≤2 → low (red)`, `==3 → medium (yellow)`, `≥4 → high (green)`.
+  `≤2 → low (red)`, `==3 → medium (yellow)`, `≥4 → high (green)`. A `failed`
+  extraction state is its own bucket, not a confidence.
 - **Discrepancy** is orthogonal to confidence — a high-confidence field can still
   disagree with a differing claim/override.
 
 ## Activation
 
-Fully self-contained: a fixed bottom-right settings button toggles the overlay,
-persisted to `localStorage`. No URL flags, no postMessage, no host activation prop.
-All library chrome is hidden under print/export media.
+The overlay's own toggle is a fixed bottom-right settings button, persisted to
+`localStorage`. No URL flags and no host activation prop. All library chrome is
+hidden under print/export media.
 
 ## Develop
 

package/dist/components/VerifiedField.vue.d.ts

@@ -4,12 +4,36 @@ import type { MetaCarrier } from "../types";
  * `source` object at `field` (`source.__meta[field]`), renders the RESOLVED value
  * (override > extracted > claim) with a HARD fallback to the host's raw value —
  * the document must never lose data because provenance is thin. When the overlay
- * is enabled via `useVerification()` it overlays a confidence pill (or, for
- * provenance-less points, a subtle dotted underline), a discrepancy indicator,
- * and click-through to the Inspector dialog. Inline contenteditable editing is
- * available whenever a `saveOverride` transport was passed to `initVerification`;
- * absent it, read-only. With no meta/source it degrades to a bare value — and
- * with no `initVerification` call at all it still renders and never throws.
+ * is enabled via `useVerification()` it draws ONE mark beside the value, and
+ * clicking that mark tells the embedding app which data point was activated
+ * ({@link notifyDataPointActivated}). With no meta/source it degrades to a bare
+ * value — and with no `initVerification` call at all it still renders and never
+ * throws.
+ *
+ * ==== THE MARK IS THE WHOLE SURFACE. THERE IS NOTHING ELSE ====
+ *
+ * What used to be here as well: a 90vw x 90vh tabbed Inspector dialog, a hover
+ * panel summarising confidence and citation counts, and `contenteditable` on
+ * the value with a save transport behind it. All three are deleted, not
+ * disabled. A letter is a document. Reviewing a value — reading its citations,
+ * seeing the record it belongs to, correcting it — is the embedding app's job,
+ * and that app already does all three better than a dialog squeezed into an
+ * iframe ever could. Everything a reader can do from here is: click the mark.
+ *
+ * The mark's own summary now lives in its ACCESSIBLE NAME rather than in a
+ * hover panel, so the same sentence reaches a screen reader and a mouse
+ * hovering the glyph, and neither costs a second piece of chrome in the page.
+ *
+ * ==== THE MARK IS OUT OF FLOW, AND THAT IS A HARD REQUIREMENT ====
+ *
+ * It is absolutely positioned against the wrapper (see the `<style>` block at
+ * the foot of this file), overlaying the right-hand end of the value it belongs
+ * to. It therefore occupies ZERO inline space: turning the overlay on or off,
+ * or toggling a field from "unverified" to "verified", must not move a single
+ * character of the letter. The previous layout was an `inline-flex` row with a
+ * gap, so every mark pushed the rest of its line along — which reflowed the
+ * document the moment the overlay was switched on, in a product whose entire
+ * point is that the document is the deliverable.
  */
 type __VLS_Props = {
     source?: MetaCarrier;

package/dist/context.d.ts

@@ -22,17 +22,33 @@ import type { SaveOverrideFn } from "./types";
 export interface InitVerificationConfig {
     /** The bound data tree (carries per-node `__meta`). */
     data: Record<string, unknown>;
-    /** Host transport; absent ⇒ all fields read-only. */
+    /**
+     * ACCEPTED AND IGNORED. Nothing in this library saves anything any more.
+     *
+     * The in-letter review surface this fed — the Inspector dialog and the
+     * `contenteditable` value — is gone; correcting a value is the embedding
+     * app's job now. The field stays in this interface for exactly one reason:
+     * every already-built template's `App.vue` passes it (the wiring snippet
+     * that generates them lives in gpt-manager's `SchemaBuilderContextBuilder`),
+     * and removing it here turns every one of those into a TypeScript excess-
+     * property error the next time it is rebuilt — for a library that cannot
+     * rebuild them. It goes when that snippet stops emitting it.
+     */
     saveOverride?: SaveOverrideFn;
-    /** Opaque workflow input id echoed back in saves. */
+    /**
+     * The workflow input this render is for. Echoed on the outbound activation
+     * message so an embedder can tell a click on the CURRENT render from a
+     * click on a render it has already replaced — see
+     * {@link ../lib/hostBridge.DataPointActivatedMessage}.
+     */
     workflowInputId?: number | string | null;
     /**
-     * Token-sealed per-field detail endpoint base (`__verification.detail_url` from
-     * the host). Present ⇒ the Inspector dialog lazy-loads a data point's full
-     * citation sources, extraction history, and LLM-call audit trace from
-     * `{detailUrl}?object_id=&field=` the instant it opens for that field (SG-392).
-     * Absent ⇒ the Audit tab is hidden, and the base render's light `extracted`
-     * candidate (see `types.ts`) is all any tab ever shows.
+     * ACCEPTED AND IGNORED, for the same reason as `saveOverride` above.
+     *
+     * This was the Inspector dialog's lazy per-field detail endpoint. The
+     * Inspector is gone, and the embedder fetches a data point's citations and
+     * history against its own authenticated session rather than against a
+     * token-sealed url handed into an iframe.
      */
     detailUrl?: string | null;
     /** Seeds the overlay toggle ONLY when localStorage holds no prior value. */
@@ -53,12 +69,8 @@ export interface Verification {
     enabled: Ref<boolean>;
     /** The bound data tree (carries per-node `__meta`). */
     data: Record<string, unknown>;
-    /** Host transport; absent ⇒ all fields read-only. */
-    saveOverride?: SaveOverrideFn;
-    /** Opaque workflow input id echoed back in saves. */
+    /** The workflow input this render is for; echoed on activation messages. */
     workflowInputId?: number | string | null;
-    /** Token-sealed per-field detail endpoint base; null/absent hides the Audit tab. */
-    detailUrl?: string | null;
     /** True while the host is fetching a new data source; see {@link InitVerificationConfig.loading}. */
     loading: boolean;
 }
@@ -69,8 +81,8 @@ export interface Verification {
  */
 export declare function initVerification(config: InitVerificationConfig): void;
 /**
- * Consume the live verification state. Returns a default (empty data, disabled,
- * no transport) when {@link initVerification} was never called, so a
+ * Consume the live verification state. Returns a default (empty data, disabled)
+ * when {@link initVerification} was never called, so a
  * `<VerifiedField>` used standalone degrades to a bare value instead of throwing.
  * Consumed internally by `VerifiedField` + `VerificationChrome`; exported for
  * advanced hosts.

package/dist/index.d.ts

@@ -1,13 +1,29 @@
 /**
- * @thehammer/template-verification — read-write verification overlay for rendered
- * template apps. Consumes the host's `__meta` sidecar (override > extracted >
- * claim resolution + discrepancy), overlays confidence/status icons, and a
- * click-through Inspector dialog with inline + modal-driven override editing.
- * The host calls `initVerification` once with `data` and an optional
- * `saveOverride` transport. SG-392: the base `__meta` is LIGHT (no citation
- * sources/history — only their `*_count`); the ONE thing this library fetches
- * on its own is that full per-field detail, via `detailUrl`, the instant the
- * Inspector dialog opens for a field (see `fetchDataPointDetail`).
+ * @thehammer/template-verification — the verification overlay a rendered
+ * template app wears, and the one signal it sends back out.
+ *
+ * Consumes the host's `__meta` sidecar (override > extracted > claim resolution
+ * + discrepancy) and draws ONE mark beside each bound value. Clicking a mark
+ * posts {@link DataPointActivatedMessage} to the embedding app; that app opens
+ * the citation and the record. The host calls `initVerification` once with
+ * `data`.
+ *
+ * ==== WHAT THIS LIBRARY DELIBERATELY NO LONGER DOES ====
+ *
+ * It used to render the entire review surface inside the iframe — a tabbed
+ * Inspector dialog (citations, extraction history, LLM audit trace), a hover
+ * summary panel on every mark, and `contenteditable` editing with a save
+ * transport behind it — and it fetched per-field detail from a token-sealed
+ * endpoint to fill them. All of that is deleted. It fetches nothing, saves
+ * nothing, and opens nothing. A letter is a document; the review happens in the
+ * application framing it, which already owns a citation viewer, a page viewer
+ * and a record editor.
+ *
+ * Removed exports, for anyone chasing an import that no longer resolves:
+ * `VerificationModal`, `CitationEvidence`, `CitationPageList`, `CitationPage`,
+ * `citationEvidence`, `citationSummary`, `fetchDataPointDetail`, and the
+ * `CitationPageModel` / `CitationEvidenceModel` / `AuditLlmCall` /
+ * `DataPointDetail` types.
  */
 import "./styles.css";
 export { initVerification, useVerification } from "./context";
@@ -15,20 +31,14 @@ export type { InitVerificationConfig, Verification } from "./context";
 export { default as VerifiedField } from "./components/VerifiedField.vue";
 export { default as VerificationChrome } from "./components/VerificationChrome.vue";
 export { default as ConfidenceIcon } from "./components/ConfidenceIcon.vue";
-export { default as VerificationModal } from "./components/VerificationModal.vue";
-export { default as CitationEvidence } from "./components/CitationEvidence.vue";
-export { default as CitationPageList } from "./components/CitationPageList.vue";
-export { default as CitationPage } from "./components/CitationPage.vue";
+export { TEMPLATE_MESSAGE_SOURCE, TEMPLATE_PROTOCOL_VERSION, DATA_POINT_ACTIVATED, embedderOrigin, notifyDataPointActivated, } from "./lib/hostBridge";
+export type { DataPointActivatedMessage, DataPointActivation, } from "./lib/hostBridge";
 export { bucketConfidence, STATUS_COLORS, STATUS_LABELS, } from "./lib/confidence";
-export { resolveDataPoint, resolveCandidates, reasoningOf, RESOLUTION_PRIORITY, } from "./lib/resolveDataPoint";
+export { resolveDataPoint, resolveCandidates, RESOLUTION_PRIORITY, } from "./lib/resolveDataPoint";
 export { hasDiscrepancy, candidatesDisagree } from "./lib/discrepancy";
 export { walkDataPoints } from "./lib/walk";
 export type { WalkedDataPoint } from "./lib/walk";
-export { citationEvidence, citationSummary } from "./lib/citations";
-export type { CitationPage as CitationPageModel, CitationEvidence as CitationEvidenceModel } from "./lib/citations";
 export { computeProgress } from "./lib/progress";
 export type { VerificationProgress } from "./lib/progress";
-export { fetchDataPointDetail } from "./lib/dataPointDetail";
-export type { AuditLlmCall, DataPointDetail } from "./lib/dataPointDetail";
 export { CHROME_CLASS, ENABLED_STORAGE_KEY } from "./constants";
 export type { VerificationStatus, ResolvedSource, SourceChoice, VerificationSource, ExtractedCandidate, OverrideCandidate, ClaimCandidate, CandidateSet, DataPointAnchor, ResolvedValue, DataPointMeta, MetaCarrier, SaveOverrideArgs, SaveOverrideFn, } from "./types";

package/dist/lib/discrepancy.d.ts

@@ -12,3 +12,11 @@ import type { CandidateSet, DataPointMeta } from "../types";
 export declare function hasDiscrepancy(meta?: DataPointMeta | null): boolean;
 /** True when >=2 present candidates hold differing values. */
 export declare function candidatesDisagree(candidates?: CandidateSet | null): boolean;
+/**
+ * True when a data point's discrepancy (if any) comes from a SOURCE-DOCUMENT conflict the
+ * host already reconciled (SG-217), rather than — or in addition to — two candidates
+ * disagreeing. Distinguishes the two kinds for copy/icon purposes; both share the same
+ * `discrepancy` flag and the same indicator in `VerifiedField.vue` — this only decides
+ * which wording the mark's accessible name carries.
+ */
+export declare function isSourceDiscrepancy(meta?: DataPointMeta | null): boolean;

package/dist/lib/hostBridge.d.ts

@@ -1,25 +1,127 @@
 /**
- * Outbound signal to the embedding consumer (gpt-manager's `TemplatePreview.vue`)
- * telling it a nested pan/zoom surface — the Evidence tab's `DanxFileViewer` — is
- * currently visible and wants exclusive ownership of Ctrl/Cmd+drag.
- *
- * Why this exists: the consumer's own preview canvas ALSO binds Ctrl/Cmd+drag to
- * pan the whole rendered document, and it activates that gesture the instant it
- * sees a relayed Ctrl/Cmd keydown from anywhere inside this iframe (the danxbot
- * host-bridge relays raw keyboard events regardless of what's focused inside).
- * Its pan overlay is a transparent `position: absolute; inset: 0` div stacked
- * ABOVE the iframe in the PARENT's own DOM — once it renders, every subsequent
- * mouse event over the iframe's whole bounding box (including this dialog's
- * nested file viewer) is captured by that parent-level div instead of reaching
- * anything inside the iframe. The nested viewer's own Ctrl+drag-to-pan-the-image
- * gesture then never receives its mousedown at all. Posting this message lets
- * the consumer gate its overlay off while a nested viewer wants the gesture,
- * without either side needing to know the other's internal DOM structure.
- *
- * Message type is namespaced under the same `source: "danxbot-template"`
- * envelope the danxbot host-bridge already uses for keyboard/wheel relays (see
- * danxbot's `scaffold.ts` → `buildHostBridgeScript`), sent directly via
- * `window.top.postMessage` — this call runs as ordinary Vue code already
- * executing inside the iframe, so it needs no relay of its own.
+ * The one outbound channel from a rendered template to the app embedding it.
+ *
+ * ==== WHY THE LETTER NO LONGER REVIEWS ANYTHING ITSELF ====
+ *
+ * This library used to render the whole review surface INSIDE the iframe: a
+ * 90vw x 90vh dialog with tabs for citations, extraction history and the LLM
+ * audit trace, a hover panel on every badge, and contenteditable editing on the
+ * value itself. All of it is gone. A letter is a document; a document that
+ * grows a second application on top of itself is two products fighting for one
+ * viewport, and the embedding app already owns a citation viewer, a record
+ * editor and a page viewer that are better than the ones in here ever were.
+ *
+ * What is left in the letter is the MARK and nothing else. Clicking it posts
+ * this message; everything that happens next happens in the embedder.
+ *
+ * ==== THE TARGET ORIGIN IS RESOLVED, NEVER "*" ====
+ *
+ * The message names the record and field a reader is looking at, which is this
+ * team's data. Posting it to `"*"` hands it to whatever happens to be framing
+ * the document, which on a mis-served preview is not the app that asked for it.
+ *
+ * The embedder's origin is not readable through `window.parent` — that is the
+ * whole point of a cross-origin frame — so it is resolved from the two places a
+ * browser DOES publish it, in order:
+ *
+ *   1. `location.ancestorOrigins[0]` — the embedder's origin, stated directly.
+ *      Chromium and WebKit only.
+ *   2. `document.referrer`'s origin — the document that framed this one. Under
+ *      the default `strict-origin-when-cross-origin` referrer policy a
+ *      cross-origin embed still sends the ORIGIN, which is exactly and only
+ *      what is needed here.
+ *
+ * If neither resolves, NOTHING IS POSTED. A mark that does nothing is a bug
+ * worth reporting; a token-shaped payload broadcast to an unknown origin is a
+ * leak, and the two are not comparable.
+ */
+import type { DataPointAnchor } from "../types";
+/**
+ * The envelope every message out of a rendered template carries.
+ *
+ * Deliberately the SAME `source` the danxbot host-bridge scaffold already uses
+ * for its `ready` handshake and its keyboard/wheel relays. An embedder filters
+ * on `source` once and then switches on `type`; a second envelope would mean a
+ * second listener and a second thing to keep in step.
+ */
+export declare const TEMPLATE_MESSAGE_SOURCE = "danxbot-template";
+/**
+ * The protocol version, matching the one the embedder stamps on its own
+ * outbound settings messages. It is on the wire so a receiver can refuse a
+ * shape it does not know rather than half-reading it; today every receiver
+ * accepts 1.
+ */
+export declare const TEMPLATE_PROTOCOL_VERSION = 1;
+/** A reader clicked the verification mark on a rendered value. */
+export declare const DATA_POINT_ACTIVATED = "data-point-activated";
+/**
+ * The activation message.
+ *
+ * ==== THE ANCHOR IS COPIED VERBATIM, NEVER RESHAPED ====
+ *
+ * `anchor` carries the host's own three fields under the host's own names —
+ * `object_ids` (the FULL root-to-leaf path), `field`, `field_path` — because
+ * the receiver's citation endpoint and record lookup both key off exactly
+ * those. Renaming them into JS-side camelCase here would put a translation
+ * between the two halves of one protocol, and a translation is a place to get
+ * it wrong for no gain. `object_ids` is shallow-copied rather than passed by
+ * reference only because the source array is a Vue reactive proxy and the
+ * structured-clone algorithm has no business being handed one.
+ *
+ * `object_ids.at(-1)` is the record the field lives on; `object_ids[0]` is the
+ * demand itself. That distinction is load-bearing on the receiving side and is
+ * the reason the whole path travels rather than one id.
+ *
+ * ==== WHY `workflowInputId` IS ON THE MESSAGE ====
+ *
+ * An embedder does not remount the frame when it switches which record it is
+ * showing — it posts new data into the frame it already has. So a click can in
+ * principle arrive from a render of the PREVIOUS record, and the receiver has
+ * no other way to notice. Echoing the id the letter was initialised with lets
+ * it be checked in one comparison. Null when the host never supplied one.
+ *
+ * ==== WHY `value` TRAVELS AND `confidence` DOES NOT ====
+ *
+ * `value` is what the reader is looking at, so a panel can name the thing that
+ * was clicked before it has resolved anything, and a divergence between the
+ * letter and the record is visible rather than silent. Everything else about
+ * the data point — confidence, candidates, citations, history — the receiver
+ * already holds or can fetch against the anchor, and shipping a second copy
+ * would create two sources for one fact.
+ */
+export interface DataPointActivatedMessage {
+    source: typeof TEMPLATE_MESSAGE_SOURCE;
+    version: number;
+    type: typeof DATA_POINT_ACTIVATED;
+    anchor: DataPointAnchor;
+    /** The workflow input this render was initialised for. Null when unknown. */
+    workflowInputId: number | string | null;
+    /** The field name the template bound, for a panel heading. Null when unbound. */
+    label: string | null;
+    /** The resolved text currently rendered in the letter. */
+    value: string | null;
+}
+/** What {@link notifyDataPointActivated} needs in order to name a data point. */
+export interface DataPointActivation {
+    anchor: DataPointAnchor;
+    workflowInputId?: number | string | null;
+    label?: string | null;
+    value?: string | null;
+}
+/**
+ * The origin of the document framing this one, or null when it cannot be known.
+ *
+ * Exported because it is the security property of this module and a test that
+ * cannot reach it can only assert it indirectly.
+ */
+export declare function embedderOrigin(): string | null;
+/**
+ * Tell the embedder a reader activated one data point.
+ *
+ * Returns whether anything was actually posted, so a caller (or a test) can
+ * tell "the embedder was told" from "there was nobody to tell" without reaching
+ * inside. Silent no-op — not a throw — in all three cases where there is no
+ * legitimate recipient: no window at all, not framed, or an unresolvable
+ * embedder origin.
  */
-export declare function notifyNestedViewerActive(active: boolean): void;
+export declare function notifyDataPointActivated(activation: DataPointActivation): boolean;

package/dist/lib/resolveDataPoint.d.ts

@@ -17,8 +17,3 @@ export declare const RESOLUTION_PRIORITY: Array<keyof CandidateSet>;
 export declare function resolveDataPoint(meta?: DataPointMeta | null): ResolvedValue;
 /** Derive the winning resolution purely from a candidate set, by priority. */
 export declare function resolveCandidates(candidates?: CandidateSet | null): ResolvedValue;
-/**
- * The extracted candidate's reasoning, normalized to a non-empty string or null.
- * Reasoning is frequently `""`/null — callers render a quiet empty state, never throw.
- */
-export declare function reasoningOf(meta?: DataPointMeta | null): string | null;