@directive-run/claude-plugin 1.16.0

package/skills/testing-directive-code/history.md

@@ -0,0 +1,351 @@
+# History & Snapshots
+
+> Covers `@directive-run/core` — time-travel: snapshot, undo/redo, replay, export/import, changeset grouping.
+
+Directive records fact changes as snapshots, enabling undo/redo, replay, export/import, and changeset grouping.
+
+## Decision Tree: "Should I enable history?"
+
+```
+What's the use case?
+├── Debugging during development → Yes, enable with maxSnapshots cap
+├── Production app → No, disable for performance
+├── Bug reproduction → Enable, use export() to share
+├── Testing → Usually no – use assertFact/assertDerivation instead
+└── Demo / presentation → Yes, great for showing state changes
+```
+
+## Enabling History
+
+```typescript
+import { createSystem } from "@directive-run/core";
+
+const system = createSystem({
+  module: myModule,
+  history: {
+    maxSnapshots: 100, // Cap memory usage (default: 100)
+  },
+});
+```
+
+History is disabled by default. When disabled, `system.history` is `null`. When enabled, snapshots are recorded automatically after every fact mutation.
+
+## Filtering Snapshot Events
+
+By default every event that changes facts creates a snapshot. Use `history.snapshotEvents` on your module to limit which events create snapshots — keeps undo/redo clean by excluding UI-only events like selection or timer ticks.
+
+```typescript
+const game = createModule("game", {
+  schema: gameSchema,
+
+  // Only these events appear in undo/redo history.
+  // Omit to snapshot ALL events (the default).
+  history: {
+    snapshotEvents: [
+      "inputNumber",
+      "requestHint",
+      "newGame",
+    ],
+  },
+
+  events: {
+    tick: (facts) => { /* no snapshot */ },
+    selectCell: (facts, { index }) => { /* no snapshot */ },
+    inputNumber: (facts, { value }) => { /* creates snapshot */ },
+    requestHint: (facts) => { /* creates snapshot */ },
+    newGame: (facts, { difficulty }) => { /* creates snapshot */ },
+  },
+});
+```
+
+### Filtering by Module
+
+In a multi-module system, control which modules create snapshots at the system level:
+
+```typescript
+const system = createSystem({
+  modules: { ui: uiModule, game: gameModule },
+  history: {
+    maxSnapshots: 100,
+    snapshotModules: ["game"], // Only game events create snapshots
+  },
+});
+```
+
+**Rules:**
+- `snapshotEvents` omitted → all events snapshot (per module)
+- `snapshotModules` omitted → all modules snapshot (per system)
+- Both provided → they intersect (module must be in `snapshotModules` AND event in `snapshotEvents`)
+- Direct fact mutations (`system.facts.x = 5`) always snapshot regardless of filtering
+- `snapshotEvents` entries are type-checked against schema events
+
+## Core API: `system.history` (`HistoryAPI`)
+
+```typescript
+const history = system.history; // HistoryAPI | null
+
+if (history) {
+  // Read-only state
+  history.snapshots;      // Snapshot[] — all recorded snapshots
+  history.currentIndex;   // number — position in the snapshot array
+  history.isPaused;       // boolean — whether recording is paused
+
+  // Navigation
+  history.goBack();       // Step backward one snapshot (changeset-aware)
+  history.goBack(3);      // Step backward 3 snapshots
+  history.goForward();    // Step forward one snapshot (changeset-aware)
+  history.goForward(3);   // Step forward 3 snapshots
+  history.goTo(snapshotId); // Jump to a specific snapshot by its ID
+  history.replay();       // Jump to the first snapshot
+
+  // Export / Import (JSON strings)
+  history.export();       // Serialize entire history to JSON string
+  history.import(json);   // Restore history from JSON string
+
+  // Changesets — group multiple snapshots into one undo/redo unit
+  history.beginChangeset("Move piece");
+  // ... mutations happen ...
+  history.endChangeset();
+
+  // Recording control
+  history.pause();        // Temporarily stop recording snapshots
+  history.resume();       // Resume recording
+}
+```
+
+### Snapshot Structure
+
+```typescript
+interface Snapshot {
+  id: number;                     // Auto-incrementing identifier
+  timestamp: number;              // When captured (Date.now())
+  facts: Record<string, unknown>; // Complete copy of all fact values
+  trigger: string;                // What caused this snapshot (e.g., "fact:count")
+}
+```
+
+## Framework Hook: `useHistory` (`HistoryState`)
+
+Each framework adapter provides a reactive `useHistory` hook that re-renders on snapshot changes. Returns `null` when history is disabled, otherwise a `HistoryState` object that wraps the core API with convenience properties.
+
+```typescript
+interface SnapshotMeta {
+  id: number;          // Snapshot identifier
+  timestamp: number;   // When captured
+  trigger: string;     // What caused this snapshot
+}
+
+interface HistoryState {
+  // Convenience booleans (not on core API)
+  canGoBack: boolean;    // True when currentIndex > 0
+  canGoForward: boolean; // True when currentIndex < totalSnapshots - 1
+  currentIndex: number;
+  totalSnapshots: number;
+
+  // Snapshot access (metadata only — keeps re-renders cheap)
+  snapshots: SnapshotMeta[];
+  getSnapshotFacts: (id: number) => Record<string, unknown> | null;
+
+  // Navigation
+  goTo: (snapshotId: number) => void;
+  goBack: (steps: number) => void;
+  goForward: (steps: number) => void;
+  replay: () => void;
+
+  // Session persistence
+  exportSession: () => string;     // Wraps history.export()
+  importSession: (json: string) => void; // Wraps history.import()
+
+  // Changesets
+  beginChangeset: (label: string) => void;
+  endChangeset: () => void;
+
+  // Recording control
+  isPaused: boolean;
+  pause: () => void;
+  resume: () => void;
+}
+```
+
+### React Example
+
+```tsx
+import { useHistory } from "@directive-run/react";
+
+function HistoryToolbar() {
+  const history = useHistory(system);
+  if (!history) return null;
+
+  return (
+    <div>
+      <button onClick={() => history.goBack()} disabled={!history.canGoBack}>Undo</button>
+      <button onClick={() => history.goForward()} disabled={!history.canGoForward}>Redo</button>
+      <span>{history.currentIndex + 1} / {history.totalSnapshots}</span>
+    </div>
+  );
+}
+```
+
+## Undo/Redo Pattern
+
+```typescript
+const system = createSystem({
+  module: editorModule,
+  history: { maxSnapshots: 200 },
+});
+
+system.start();
+
+// User makes changes
+system.facts.text = "Hello";
+system.facts.text = "Hello, world";
+system.facts.text = "Hello, world!";
+
+const history = system.history!;
+
+// Undo (one step back)
+history.goBack();
+console.log(system.facts.text); // "Hello, world"
+
+history.goBack();
+console.log(system.facts.text); // "Hello"
+
+// Redo (one step forward)
+history.goForward();
+console.log(system.facts.text); // "Hello, world"
+```
+
+## How Snapshots Work
+
+Snapshots are taken **once per reconciliation cycle**, not per individual fact change. All synchronous fact mutations within the same event handler batch into a single snapshot. One `goBack()` reverts all changes from that event.
+
+## Changesets: Grouping Multiple Events
+
+Changesets group snapshots from **multiple separate events** into one undo/redo unit. Useful when a single user action triggers a sequence of events.
+
+```typescript
+const history = system.history!;
+
+// Two separate events = two snapshots
+system.events.pickUp({ index: 0 });      // → snapshot 1
+system.events.place({ from: 0, to: 1 }); // → snapshot 2
+// goBack() only reverts the place — need two goBack() calls
+
+// With changeset — grouped into one undo unit
+history.beginChangeset("Move piece");
+system.events.pickUp({ index: 0 });      // → snapshot 1 ─┐
+system.events.place({ from: 0, to: 1 }); // → snapshot 2 ─┘ grouped
+history.endChangeset();
+// One goBack() reverts both events
+```
+
+Also works for direct fact mutations across separate synchronous blocks:
+
+```typescript
+history.beginChangeset("Update user");
+system.facts.firstName = "Alice";
+system.facts.lastName = "Smith";
+// These batch into one snapshot synchronously, but changeset
+// still works if an async gap separates them
+history.endChangeset();
+```
+
+Always close your changesets. If you forget `endChangeset()`, all subsequent mutations get grouped into the same changeset.
+
+## Exporting and Importing History
+
+Serialize the full snapshot history for bug reports or debugging.
+
+```typescript
+const history = system.history!;
+
+// Export — returns a JSON string
+const exported = history.export();
+localStorage.setItem("debug-session", exported);
+
+// Import — restore from a JSON string
+const saved = localStorage.getItem("debug-session");
+if (saved) {
+  history.import(saved);
+
+  // Step through the user's exact state sequence
+  history.goTo(0); // First snapshot
+  history.goTo(5); // When the bug occurred
+}
+```
+
+## Performance: maxSnapshots
+
+Every fact mutation creates a snapshot. Cap the number to control memory:
+
+```typescript
+// Low memory — keeps last 20 snapshots, discards oldest
+history: { maxSnapshots: 20 },
+
+// Development — generous cap for deep debugging
+history: { maxSnapshots: 500 },
+
+// Default if not specified
+history: true, // maxSnapshots defaults to 100
+```
+
+When the cap is reached, the oldest snapshot is discarded (ring buffer / FIFO).
+
+## Common Mistakes
+
+### Enabling history in production
+
+```typescript
+// WRONG — snapshots consume memory on every mutation
+const system = createSystem({
+  module: myModule,
+  history: true,
+});
+
+// CORRECT — gate on environment
+const system = createSystem({
+  module: myModule,
+  history: process.env.NODE_ENV === "development"
+    ? { maxSnapshots: 100 }
+    : false,
+});
+```
+
+### Forgetting to end a changeset
+
+```typescript
+// WRONG — changeset never closed, all subsequent mutations are grouped
+history.beginChangeset("update");
+system.facts.name = "Alice";
+// ... forgot endChangeset()
+system.facts.unrelated = true; // Still part of the changeset!
+
+// CORRECT — always close changesets
+history.beginChangeset("update");
+system.facts.name = "Alice";
+history.endChangeset();
+```
+
+### Accessing history when disabled
+
+```typescript
+// WRONG — history not enabled, system.history is null
+const system = createSystem({ module: myModule });
+system.history.goBack(); // TypeError!
+
+// CORRECT — check before using
+if (system.history) {
+  system.history.goBack();
+}
+
+// Or enable it
+const system = createSystem({
+  module: myModule,
+  history: true,
+});
+```
+
+## See also
+
+- [`system-api.md`](./system-api.md) — `history` config in `createSystem` + the full `system.history.*` API
+- [`testing.md`](./testing.md) — replay-driven testing patterns that pair with recorded snapshots