Repair capability federation index

registry/capabilities/capability.evidence.rect-registry.md

@@ -0,0 +1,184 @@
+---
+id: capability.evidence.rect-registry
+name: Visual-Guide Rect Registry
+summary: >-
+  Coordinates field, evidence-card, and highlight rectangles from independent
+  renderers so an SVG overlay can draw the active visual guide without polling.
+owner: evidence-binder
+status: draft
+domain: infotech
+tags:
+  - rect-registry
+  - visual-guide
+  - overlay
+  - active-state
+  - citation-evidence
+
+maturity:
+  discovery:
+    current: D3
+    target: D5
+    confidence: high
+    rationale: >-
+      SharedContracts section 7, SCOPE.md, the extraction inventory, and the
+      reference-UI ADR define the cross-renderer contract, ownership boundary,
+      invalidation model, and coupling risk. Systematic use-case and alternative
+      research beyond the citation workspace has not been recorded.
+  availability:
+    current: A2
+    target: A2
+    confidence: high
+    rationale: >-
+      The TypeScript package exports the rect registry, event pump, React hooks,
+      and SVG overlay as source modules consumed by the citation-evidence
+      umbrella. The capability is naturally a library rather than a CLI or
+      service.
+
+external_evidence:
+  completeness:
+    level: C3
+    confidence: medium
+    basis: scope_vs_intent_and_consumer_expectations
+    satisfied_expectations:
+      - register and resolve field, evidence-card, and highlight rectangles
+      - notify consumers on registration, removal, and explicit invalidation
+      - throttle viewport change pumps with requestAnimationFrame
+      - draw the active field-to-card-to-highlight guide through the SVG overlay
+    broken_expectations:
+      - broader renderer and layout variants have not been exercised outside the umbrella workspace
+    out_of_scope_expectations:
+      - document highlight resolution
+      - evidence-card and viewer rendering ownership
+      - polling-based geometry ownership inside the overlay
+  reliability:
+    level: R3
+    confidence: medium
+    basis: consumer_quality_signals
+    evidence:
+      tests:
+        suites:
+          - src/visual-guide/rect-registry.test.ts
+          - src/visual-guide/react-hooks.dom.test.tsx
+          - src/visual-guide/Overlay.dom.test.tsx
+      integration:
+        consumer: citation-evidence
+        mode: form, evidence-card, and highlight bridges
+    known_reliability_risks:
+      - reliability evidence comes from one browser application and its automated DOM tests
+      - unusual transforms and multi-window layouts are not represented in current evidence
+
+discovery:
+  intent: >-
+    Decouple independently rendered fields, evidence cards, and document
+    highlights by giving them one invalidation-aware geometry registry for the
+    active visual guide.
+  includes:
+    - rectangle registration and lookup for the three canonical rect kinds
+    - change subscriptions and explicit invalidation
+    - viewport event pumps and React registration hooks
+    - SVG overlay rendering for the active triple
+  excludes:
+    - source selector resolution and scrolling
+    - ownership of evidence-card or viewer components
+    - application-level active-state persistence
+  assumptions:
+    - each renderer can supply a current DOMRect through a callback
+    - the host mounts one registry shared by participating renderers
+    - the host drives active target, evidence, and annotation state
+  use_cases:
+    - connect an active form field to its evidence card and source highlight
+    - redraw guide geometry after scroll, resize, focus, or explicit invalidation
+    - let renderer bridges publish geometry without importing each other
+  research_memos: []
+
+availability:
+  current_level: A2
+  target_level: A2
+  current_artifacts:
+    - src/visual-guide/rect-registry.ts
+    - src/visual-guide/events.ts
+    - src/visual-guide/react-hooks.ts
+    - src/visual-guide/Overlay.tsx
+  target_artifacts: []
+  consumption_modes:
+    - source module
+    - React hook
+    - React component
+
+relations:
+  depends_on: []
+  supports: []
+  related_to:
+    - capability.evidence.binding
+
+evidence:
+  documentation:
+    - README.md
+    - SCOPE.md
+    - docs/extraction-inventory.md
+    - docs/adr/ADR-0001-reference-ui-surface.md
+    - ../citation-evidence/wiki/SharedContracts.md
+  tests:
+    - src/visual-guide/rect-registry.test.ts
+    - src/visual-guide/react-hooks.dom.test.tsx
+    - src/visual-guide/Overlay.dom.test.tsx
+  consumer_feedback:
+    - citation-evidence composes field, evidence-card, and highlight bridges through this registry
+  bug_reports: []
+  incidents: []
+
+consumer_guidance:
+  recommended_for:
+    - React applications drawing active relationships across independently rendered panes
+    - citation-evidence consumers using the canonical field, evidence-card, and highlight rect kinds
+  not_recommended_for:
+    - non-DOM renderers without a DOMRect-compatible adapter
+    - applications expecting the registry to resolve selectors or own scrolling
+  known_limitations:
+    - evidence is limited to one internal browser application
+    - transformed and multi-window layout behavior is not explicitly tested
+
+promotion_history: []
+---
+
+# Visual-Guide Rect Registry
+
+## Overview
+
+This capability provides the shared geometry contract for the visual guide.
+Independent field, evidence-card, and highlight renderers publish callbacks into
+one registry; hooks and event pumps invalidate it, and the overlay draws the
+active relationship without owning those renderers or polling their geometry.
+
+## Assessment notes
+
+### Discovery
+
+The contract and the coupling problem it solves are explicit and implemented,
+supporting D3. Promotion to D5 requires a broader, prioritized use-case and
+layout-variant catalogue.
+
+### Availability
+
+The registry, hooks, and overlay are directly consumable TypeScript and React
+source modules. A2 is the natural target for this embedded UI capability.
+
+### Completeness
+
+The canonical three-leg visual-guide path works and has focused coverage. The
+assessment remains C3 because only the umbrella layout and browser context have
+supplied consumer evidence.
+
+### Reliability
+
+Registry, event-pump, hook, and overlay tests plus the umbrella integration
+support R3 for normal internal use. Confidence remains medium until independent
+consumers or broader layout evidence exist.
+
+## Promotion checklist
+
+- [x] ID follows the capability identifier pattern
+- [x] Maturity enums match the capability maturity standard
+- [x] External evidence is separate from internal maturity
+- [x] Relations reference an indexed capability ID
+- [x] Index entry points to this file