`@blueforge-studio/tester-overlay`

One overlay, one instrumentation contract, one flag-group model, one feedback pipeline — the tester-facing half of the tester-overlay program (spec §6, decision D4). Peer of @blueforge-studio/app-dom; adopted the way theming and sidecars were — one call in the app shell, zero per-app feedback UI.

Adopt

import { mountTesterOverlay } from "@blueforge-studio/tester-overlay";

const overlay = await mountTesterOverlay({
  appId: "my-app",                         // matches blueforge.testing.yml id
  container: document.getElementById("root") ?? document.body,

  // §5.1 signed-in testers: resolve group membership from your auth
  // session (Better Auth claim, API-key column, …). Omit for link-only apps.
  session: async () => ({ groups: ["beta"], identity: user?.id }),

  // §5.2 virtual testers: forge-auth verifies `?tester=<token>` (D3).
  verifyEndpoint: "https://forge-auth…/v1/testing/verify",

  // §4 flag catalog — parsed blueforge.testing.yml (or a URL to it).
  flagCatalog: { flags: [...] },
  // flagCatalogUrl: "/blueforge.testing.json",
  groupFlagMap: { alpha: ["flag-x"], beta: ["flag-x", "flag-y"] },

  // §7 central feedback API (mission-control /v1/feedback, T4).
  feedbackEndpoint: "https://…/v1/feedback",
});

// later: overlay.destroy();

Returns null when the page has no activation (no session groups, no valid link token) — the app is then completely untouched.

What it does

Piece	Behavior
Activation (§5)	account path (`session`) or virtual link (`?tester=`); link wins, both fail closed; virtual identity is `virtual:tester:<jti>`
Instrumentation	`instrumentApp()` from `@blueforge-studio/app-dom` — highlight chips `none / hover / always`, mount-once per `appId`
Flags (§4/D2)	catalog defaults ∪ group sets → written to `window.__FEATURE_OVERRIDES` (the lq-core layer-0 seam) + read-only `window.__TESTER_OVERLAY__`; teardown restores both
Report form (§6)	type / category / severity / title / description / tags (comma-split), auto-captured route, element context, viewport/platform/UA, screenshot via `html-to-image` (a real dep, D6) as a multipart blob part
Click-to-report	with the feedback toggle ON, clicking an instrumented element pre-fills the form from its `data-appdom-*` attributes — no URL→screen map to rot
Persistence (gap #6)	panel open / highlight mode / feedback toggle persist per app in `localStorage` (`blueforge:tester-overlay:<appId>`)
a11y (gap #8)	labelled modal dialog, live-region status — no `alert()`, ever

Prerequisites

Instrument core pages with data-appdom-* attributes (spec §3 — data-testid / data-cy also resolve, via dom-overlay-core's family chain).
A blueforge.testing.yml flag catalog (schema: @blueforge-studio/blueforge-sidecar-schemas ≥ 0.20.0).

Security invariants (§9)

Tester tokens grant overlay capabilities only (mount, flag-set read, feedback write); they are validated at forge-auth, never locally; revocation (jti) takes effect at next init; flag sets gate UI surfaces only — server-side twins stay app config.

Develop

pnpm --filter @blueforge-studio/tester-overlay typecheck
pnpm --filter @blueforge-studio/tester-overlay test
pnpm --filter @blueforge-studio/tester-overlay build

Version	Published
0.1.2	2026-09-26
0.1.1	2026-09-26
0.1.0	2026-09-26

Version	Sig	SBOM	Att
0.1.2
0.1.1
0.1.0

@blueforge-studio/tester-overlay

Package Info

Versions

Per-version supply chain

Supply chain

Provenance

Claimed by the build

Attachments

Dependencies

README