coulomb/evidence-binder
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
evidence-binder/docs/adr/ADR-0001-reference-ui-surface.md
tegwick a10f080f12
All checks were successful
CI Smoke / host-smoke (push) Successful in 0s
Details
CI Smoke / container-smoke (push) Successful in 2s
Details
Extract binder package from citation-evidence (EBIND-WP-0001) 
Extracts citation-evidence/src/binder/ into this repo as the standalone
@citation-evidence/evidence-binder package: headless binding service +
in-memory link repo, active-state machine, the SharedContracts §7
rect-registry contract (registry, change pumps, hooks, SVG overlay), and
the target-neutral reference FormRenderer.

- toolchain mirrors sibling extracted repos (pnpm/tsc/vitest/eslint);
  imports rewritten from @shared/@engine aliases to the engine's
  @citation-evidence/engine package specifiers
- dependency boundary (engine + anchor only; no source/work/umbrella)
  enforced via eslint no-restricted-imports
- docs: extraction inventory + contract deltas, ADR-0001 (reference UI
  kept as supported exports), refreshed README/SCOPE/INTENT, populated
  capabilities index
- typecheck + lint green, 37 tests passing

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-09 01:36:33 +02:00

2.2 KiB
Raw Blame History

ADR-0001 — Binder-owned reference UI surface

  • Status: accepted
  • Date: 2026-07-08
  • Workplan: EBIND-WP-0001 (T05)

Context

The extracted binder slice includes two small React components:

  • FormRenderer.tsx — renders a FormSchema as an evidence-backed form. Each field registers itself with the rect registry under kind="field", focuses a target via the active-state machine, and shows a link-count chip. This is the component that produces the field leg of the visual-guide triple.
  • FieldDefinitionForm.tsx — a shared label/type editor used by FormRenderer's add-field and edit-field flows.

The architectural rule is that the binder is form-friendly but target-neutral: it must not depend on citation-work and must not assume any particular host application.

Decision

Keep both components as supported binder exports.

  • FormRenderer is contractual: it is the reference implementation of the "form field publishes a field rect and drives active-target focus" half of the rect-registry contract (SharedContracts §7). Demoting it to an example would leave the §7 field-side contract without an in-repo reference.
  • FieldDefinitionForm is retained as a supporting export because FormRenderer depends on it directly; splitting them across the package/example boundary would break that import.

Both remain target-neutral: they operate purely on FormSchema / EvidenceTarget and the binder's own hooks. They take no dependency on citation-work, evidence-source, or the umbrella. The umbrella owns the composition (wiring FormRenderer to persistence, sidebars, and the viewer) in citation-evidence/src/app/**; the binder owns only the renderer itself.

Consequences

  • src/index.ts continues to export FormRenderer (and its FormSchema / FormFieldSchema / FormRendererProps types); the umbrella imports them unchanged after cutover.
  • The package surface stays "headless core + rect-registry contract + one reference form renderer" rather than a broad UI kit. Future richer UI belongs in host apps, not here.
  • If a later workplan needs a genuinely illustrative demo, it goes under an examples/ tree, not the package root, so the subsystem boundary stays sharp.