Reference

Mounting the signal

The light is most useful where the numbers live: on the dashboard itself. Everything here re-verifies the chain in the viewer's own browser using Web Crypto, with no build step, no framework requirement, and no server state. The UI is two things, always shipped together: the light (a small pill in the header, the lightest touch) and the room (the one robust surface behind it, where the light's "view receipts" link lands).

One light, one room

Compat shims (2.x): tamper-signal/table and tamper-signal/console keep their old signatures and now render the room's table and console presets. tamper-signal/badge's renderReceiptBadge is deprecated (removed in 3.0).

The inline status light

A dark, monospace pill that shows the traffic light and expands to a popover: a per-stage table when green, the caveat list when yellow, the broken link and totals delta when red.

<!-- serve receipts/ statically, then mount in the header -->
<script type="module">
  import { mountTamperSignal } from "/badge/light.js";
  mountTamperSignal(document.querySelector("header"), "/receipts/chain.json");
</script>

With a bundler it is the same call from the package:

import { mountTamperSignal } from "tamper-signal/light";

Options

React and web component

// React
import { TamperSignal } from "tamper-signal/react";
<TamperSignal chain="/receipts/chain.json" />

// Plain HTML, via tamper-signal/element
<tamper-signal chain="/receipts/chain.json"></tamper-signal>

The room

The one surface behind the light. The attested table is the landing plane (re-hashed in the viewer's browser against the final receipt, so its VERIFIED means the rows on screen are byte for byte the attested data), with the chain as a provenance rail above it, the break exhibit in business numbers when the chain is red, and the receipt inspector, CLI-mirror event log, and chain-of-custody timeline one drawer away. Green earns silence; the layout leads with whatever the verdict demands.

# 1. export the canonical table as the last pipeline step (Python or Node)
tamper-signal export receipts/chain.json --data dashboard.xlsx

# 2. mount it
<script type="module">
  import { mountSignalRoom } from "/badge/room.js";
  mountSignalRoom(document.querySelector("#data-tab"), "/receipts/chain.json");
</script>

Or the web component (works from React JSX too: importing tamper-signal/room registers it and ships the JSX typing):

<script type="module" src="/badge/room.js"></script>
<tamper-signal-room chain="/receipts/chain.json"></tamper-signal-room>

Attributes: chain (required), table, timeline, pub-key, watch, warn-drift, strict, max-rows, focus, preset (room | table | console), density (embedded | page). After each verification the room fires a bubbling tamper-signal:state event carrying { state, attested, strict }; the documented host gate is strict && (state === "red" || !attested). Skipping the export step degrades honestly: no table.json shows a grey "no attested table published" slab, a stale one reads NOT THE ATTESTED DATA with the re-run command.

Every attach helper serves the room automatically at /tamper-signal/receipts and points the light's "view receipts" link there with ?focus=auto, so a red chain opens scrolled to the break. /tamper-signal/console stays reachable, serving the room with its rail open.

One-call framework helpers

Each attach helper serves three things from one call (your receipts/ directory, the verifier assets, and the room page) and returns a ready-to-drop snippet with the light's receiptsHref pre-wired to the room, so you do not wire paths by hand. You structurally cannot ship the light without a live room behind it. (room=False / { room: false } opts out; not recommended: the light will link to raw JSON.)

# Flask
from tamper_signal.flask_ext import attach
signal = attach(app, receipts_dir="receipts/")   # {{ signal.snippet | safe }}

# FastAPI
from tamper_signal.fastapi_ext import attach
signal = attach(app, receipts_dir="receipts/")

// Express
import { tamperSignal } from "tamper-signal/express";
const signal = tamperSignal(app, { receiptsDir: "receipts/" });
// render signal.snippet once in your layout

Flag a broken metric in place

The signal can reach into the page and outline the exact numbers that no longer descend from the source. Add data-receipt-column to any element that displays a metric, naming the column it comes from. When the chain breaks at a link where that column moved, the signal outlines the element and tags it tamper signal: unverified value.

<div class="kpi" data-receipt-column="spend_(usd)">
  $98,441.02
</div>

Column names are the normalized keys from the receipts' control totals: lowercased, spaces turned to underscores. Read them from numeric_sums and null_counts in the receipt files.

Verify your wiring

• The pill reads VERIFIED · chain intact; click it for the per-stage popover.
• The pill's "view receipts →" link lands in the room, not on raw chain.json. If it opens unstyled JSON, receiptsHref was never wired (the attach helpers do it for you).
• The room's table plane shows the attested rows with the signed control-totals row. If it shows the grey "no attested table published" slab, the export step is missing from the pipeline run.
• Point it at examples/chains/intact/ for green and examples/chains/tampered/ for red, as a negative test.
• If it reads UNVERIFIED · could not load chain, the receipts directory is not being served at that URL (usually CORS). That state is a capability fallback, not a verdict about your data.
• If it reads verification unsupported in this browser, the browser lacks Web Crypto Ed25519; verify from the CLI instead.