@thehammer/template-verification

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 ignores it. That is compile-time compatibility for already-built templates, whose App.vue is generated from a snippet that still passes it; it is not a feature. See src/context.ts.

detailUrl was the same story until SG-689, when gpt-manager's wiring snippet and its server-side sidecar both stopped emitting it — it is no longer part of InitVerificationConfig at all. An already-built template's source that still names it keeps building (the template build does not type-check) and keeps harmlessly passing an unread property, same as before it had a name in this interface.

Install

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, AND the positioning rule that keeps the mark out of the text flow:

import "@thehammer/template-verification/style.css"

Usage

Call initVerification() once at your App root (a function call — not a wrapping element), then drop a single <VerificationChrome/> as a sibling of the document and use <VerifiedField> anywhere:

<script setup lang="ts">
import { initVerification, VerificationChrome, VerifiedField } from "@thehammer/template-verification"

const props = defineProps<{ data: any }>()

initVerification({
  data: props.data,
  // 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>

<template>
  <article>
    <h1><VerifiedField :source="data.claimant" field="full_name" /></h1>
    <div v-for="(p, i) in data.medical_providers" :key="i">
      <VerifiedField :source="p" field="name" />
    </div>
  </article>

  <!-- Sibling of the document, placed once. -->
  <VerificationChrome />
</template>

The backing store is a module singleton — safe because each rendered template 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

{
  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 entry is a DataPointMeta:

interface DataPointMeta {
  anchor: { object_ids: (number | string)[]; field: string; field_path: string }
  candidates: {
    override?: { value; source_choice }
    extracted?: { value; confidence: number | null; state; sources_count; history_count }
    claim?: { value; claim_set_label }
  }
  discrepancy: boolean
  resolved: { value; source: "override" | "extracted" | "claim" | "none" }
}

Resolution + status

• Resolution priority: override > extracted > claim.
• Status buckets the integer confidence: null → unverifiable (gray), ≤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

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

npm test          # vitest
npm run build     # vite lib build + emitted .d.ts types