CLAUDE.md

1# workflowDocument store — Agent Guidelines
2 
3## Core pattern: apply/public method split
4 
5Every composable in this folder follows a two-layer pattern:
6 
7**Public methods** (exposed) — represent user intent. Handle normalization,
8deduplication, and preparation. Call apply methods internally.
9 
10**Apply methods** (private) — the **only** functions that mutate refs. Each
11apply method writes to the ref and fires an event hook. Never expose apply
12methods from the composable.
13 
14```
15Component → publicMethod() → normalize → applyXxx() → ref + event hook
16```
17 
18This split exists to support CRDT in the future: local user actions,
19remote CRDT sync, and undo/redo all converge on the same private apply
20methods inside the composable.
21 
22## Event hooks
23 
24Every composable exposes change notifications via `createEventHook` from
25`@vueuse/core`. Event payloads must extend `ChangeEvent` from `./types.ts`:
26 
27```typescript
28import { createEventHook } from '@vueuse/core';
29import type { ChangeEvent, ChangeAction } from './types';
30 
31type MyChangeEvent = ChangeEvent<{ /* domain-specific fields */ }>;
32const onMyChange = createEventHook<MyChangeEvent>();
33```
34 
35- Fire `void onMyChange.trigger(...)` inside every apply method
36- Expose only the `.on` subscriber: `onMyChange: onMyChange.on`
37- Use `CHANGE_ACTION.ADD | UPDATE | DELETE` for the `action` field
38 
39## Reactivity invariant: events carry reactive references
40 
41When an apply method emits a node (or any tracked entity) in its event
42payload, the payload must contain the **reactive proxy** read back from the
43ref — NOT the raw input received by the apply method.
44 
45Vue creates proxies lazily on read from a reactive container. The raw object
46passed into the apply method and the proxy returned by `nodes.value[i]` share
47underlying state but are different JS references. Subscribers that store the
48raw reference lose reactivity on subsequent property mutations: property reads
49on the raw object create no dependencies, and downstream computeds never
50invalidate when the underlying node is mutated through its proxy.
51 
52Pattern — read back from the ref after the mutation, emit the proxy:
53 
54```typescript
55function applyAddNode(node: INodeUi) {
56    nodes.value.push(node);
57    const reactiveNode = nodes.value[nodes.value.length - 1]; // proxy
58    void onChange.trigger({
59        action: CHANGE_ACTION.ADD,
60        payload: { node: reactiveNode },
61    });
62}
63```
64 
65This invariant is locked by the `addNode emits the reactive proxy from
66nodes.value` test in `useWorkflowDocumentNodes.test.ts`. Any new apply method
67that emits a tracked entity must follow the same pattern and add an
68equivalent test.
69 
70## Adding a new composable — checklist
71 
721. Create event hook with typed payload extending `ChangeEvent`
732. Write private `apply*()` methods — each mutates the ref and fires the hook
743. Write public methods — normalize input, then call apply
754. Return: readonly refs, public methods, `onXxxChange: hook.on`
765. Never return apply methods
77 
78## Anti-patterns
79 
80| Don't | Do instead |
81|-------|------------|
82| Mutate refs outside apply methods | All ref writes go through apply |
83| Expose apply methods from composable | Keep them private (not in return) |
84| Use action objects / `onChange` router | Public methods call apply directly |
85| Use `dataPinningEventBus` or global event bus | Use scoped `createEventHook` |
86| Import global stores inside composable | Inject dependencies via function params |
87 
88## Dependency injection
89 
90Composables receive external dependencies as constructor params, not via
91global store imports. This keeps them testable and makes coupling explicit:
92 
93```typescript
94export function useWorkflowDocumentFoo(deps: {
95  getNodeByName: (name: string) => INodeUi | undefined;
96}) { ... }
97```
98 
99## Reference implementation
100 
101See `useWorkflowDocumentActive.ts` — the simplest complete example of the
102apply/public pattern with event hooks.
103