---
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