Implement CE-WP-0003 T01-T08: form binding + visual guide overlay

T01 EvidenceLink/EvidenceSet types
  - src/shared/evidence-link.ts: status (§2.4), relation (§2.5), target
  - src/shared/evidence-set.ts: ordered group + activeEvidenceItemId
  - enum-conformance test parses SharedContracts.md and asserts the
    runtime lists match exactly

T02 Binding service + in-memory link repo + active-state machine
  - src/binder/repos/in-memory-links.ts: Map-backed EvidenceLinkRepository
  - src/binder/services/bindings.ts: link/unlink/list/update/setActive
    emitting §4 EvidenceLinkCreated / EvidenceLinkUpdated /
    EvidenceItemActivated
  - src/binder/state/active.ts: (target, evidence, annotation) reducer
    + ActiveStateProvider + useActiveState hook
  - extended engine/events/types.ts with EvidenceLinkCreated,
    EvidenceLinkUpdated, FormFieldActivated payloads

T03 Rect registry (SharedContracts §7 — contract FROZEN)
  - src/binder/visual-guide/rect-registry.ts: register/getRect/subscribe
    + invalidate + getVersion for useSyncExternalStore
  - events.ts: scroll/resize/focus pumps via window + ResizeObserver +
    IntersectionObserver, rAF-throttled
  - react-hooks.ts: RectRegistryProvider, useRegisterRect(kind,id,ref),
    useRectRegistryVersion

T04 Form schema + renderer
  - src/app/forms/demo-schema.ts: text/textarea/date minimal schema
  - src/binder/FormRenderer.tsx: renders schema, each field registers
    as rect kind="field"; active field gets aria-current="true"
  - placed in binder/ (not work/) because work cannot import binder per
    DependencyMap.md §2 and the renderer needs the rect-registry hook;
    workplan T04 was amended in-place to document this

T05 Side-by-side Forms layout + click-to-link
  - src/app/forms/FormsApp.tsx + src/app/App.tsx top-bar router with
    hash route #/forms/demo
  - BinderProvider mounted at app root so links survive tab switching
  - stage-evidence-then-click-field linking interaction with banner
    + per-field link-count chip

T06 Active-evidence cycling
  - src/app/forms/ActiveEvidenceChips.tsx: chips per active target,
    Tab cycles natively, first chip auto-activates on field focus,
    each chip registers as rect kind="evidence-card"
  - ScrollBridge in FormsApp wires activeAnnotationId to viewer scroll
  - EvidenceSidebar + EvidenceStrip highlight the active item via the
    new useLastActivatedEvidence hook in work/EngineContext

T07 SVG visual-guide overlay
  - src/binder/visual-guide/Overlay.tsx: single fixed-positioned SVG,
    draws field→card and card→highlight bezier curves for the active
    triple, rAF-throttled via the registry
  - src/anchor exposes getHighlightClientRects(annotationId); the
    spike viewer wraps highlights in [data-highlight-id] so the helper
    can locate them
  - src/app/forms/HighlightRectBridge.tsx: registers the active
    annotation's rect via that helper

T08 End-to-end test (PRD scenario steps 5-9)
  - tests/integration/forms-overlay-e2e.dom.test.tsx: full path from
    Review-mode capture through Forms-mode link to active triple +
    aria-current assertions + 2 SVG paths in the overlay
  - additional integration coverage: forms-link-flow + forms-active-cycling

Gates: typecheck ✓ · lint ✓ · build ✓ · 152/152 tests across 21 files.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
2026-05-25 15:53:17 +02:00
parent d54daf2e61
commit 8607c252c4
40 changed files with 3321 additions and 41 deletions

View File

@@ -0,0 +1,97 @@
/**
* BinderProvider — composition root for the binder subsystem.
*
* Wires the four binder concerns (rect registry, binding service, link
* repo, active state machine) into one provider so a single mount inside
* the EngineProvider gives every binder consumer (FormRenderer, evidence
* picker, SVG overlay) what it needs.
*
* The provider is split out from the engine because in a future
* subsystem-extraction these will live in separate packages — the engine
* will publish only the event bus and the engine services, while
* `evidence-binder` will export this provider.
*/
import {
createContext,
useContext,
useEffect,
useMemo,
type ReactNode,
} from "react";
import type { EventBus } from "@engine/events";
import {
ActiveStateProvider,
useActiveState,
} from "./state/active";
import {
createInMemoryLinkRepo,
type EvidenceLinkRepository,
} from "./repos/in-memory-links";
import {
createBindingService,
type BindingService,
} from "./services/bindings";
import {
RectRegistryProvider,
createRectRegistryContextValue,
type RectRegistryContextValue,
} from "./visual-guide/react-hooks";
export interface BinderServices {
readonly links: EvidenceLinkRepository;
readonly bindings: BindingService;
readonly rect: RectRegistryContextValue;
}
const BinderServicesContext = createContext<BinderServices | null>(null);
export function useBinder(): BinderServices {
const ctx = useContext(BinderServicesContext);
if (!ctx) throw new Error("useBinder: missing <BinderProvider />");
return ctx;
}
export interface BinderProviderProps {
readonly children: ReactNode;
/**
* The engine's event bus, threaded in by the composition root so the
* binder can emit §4 events without importing work/EngineContext
* (work cannot be a dependency of binder — see DependencyMap §2).
*/
readonly bus: EventBus;
/**
* Tests can inject a pre-built service set; production constructs a
* fresh one. The rect registry is *always* fresh per provider mount
* because its observers attach to the current `window`.
*/
readonly services?: Omit<BinderServices, "rect">;
}
export function BinderProvider({ children, bus, services }: BinderProviderProps) {
const built = useMemo<BinderServices>(() => {
const links = services?.links ?? createInMemoryLinkRepo();
const bindings = services?.bindings ?? createBindingService(links, bus);
const rect = createRectRegistryContextValue();
return { links, bindings, rect };
}, [bus, services]);
// Disconnect rect observers + listeners on unmount.
useEffect(() => {
return () => {
built.rect.observer.disconnect();
};
}, [built.rect]);
return (
<BinderServicesContext.Provider value={built}>
<RectRegistryProvider value={built.rect}>
<ActiveStateProvider bus={bus}>{children}</ActiveStateProvider>
</RectRegistryProvider>
</BinderServicesContext.Provider>
);
}
export { useActiveState };