184 lines
6.4 KiB
Markdown
184 lines
6.4 KiB
Markdown
---
|
|
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
|