footprintjs 3.0.18 → 3.0.21

package/ai-instructions/copilot-instructions.md

@@ -1,118 +0,0 @@
-# footprint.js — Copilot Instructions
-
-This is the footprint.js library — the flowchart pattern for backend code. Self-explainable systems that AI can reason about.
-
-## Core Principle
-
-**Collect during traversal, never post-process.** All data collection happens as side effects of the single DFS traversal. Never walk the tree after execution.
-
-## Architecture
-
-```
-src/lib/
-├── memory/    → Transactional state (SharedMemory, StageContext, TransactionBuffer)
-├── schema/    → Validation (Zod optional, duck-typed)
-├── builder/   → Fluent DSL (FlowChartBuilder, flowChart())
-├── scope/     → Per-stage facades + recorders + providers
-├── reactive/  → TypedScope<T> deep Proxy (typed property access, $-methods)
-├── decide/    → decide()/select() decision evidence capture
-├── engine/    → DFS traversal + narrative + handlers
-├── runner/    → FlowChartExecutor
-└── contract/  → I/O schema + OpenAPI
-```
-
-Entry points: `footprintjs` (public) and `footprintjs/advanced` (internals).
-
-## Key API — TypedScope (Recommended)
-
-```typescript
-import { flowChart, FlowChartExecutor, decide } from 'footprintjs';
-
-interface State {
-  creditScore: number;
-  riskTier: string;
-  decision?: string;
-}
-
-const chart = flowChart<State>('Intake', async (scope) => {
-  scope.creditScore = 750;          // typed write (no setValue needed)
-  scope.riskTier = 'low';           // typed write
-}, 'intake')
-  .addDeciderFunction('Route', (scope) => {
-    return decide(scope, [
-      { when: { riskTier: { eq: 'low' } }, then: 'approved', label: 'Low risk' },
-    ], 'rejected');
-  }, 'route', 'Route based on risk')
-    .addFunctionBranch('approved', 'Approve', async (scope) => {
-      scope.decision = 'Approved';
-    })
-    .addFunctionBranch('rejected', 'Reject', async (scope) => {
-      scope.decision = 'Rejected';
-    })
-    .setDefault('rejected')
-    .end()
-  .build();
-
-const executor = new FlowChartExecutor(chart);
-await executor.run();
-executor.getNarrative();  // causal trace with decision evidence
-```
-
-### TypedScope $-methods (escape hatches)
-
-```typescript
-scope.$getArgs<T>()        // frozen readonly input
-scope.$getEnv()            // execution environment (signal, timeoutMs, traceId)
-scope.$break()             // stop pipeline
-scope.$debug(key, value)   // debug info
-scope.$metric(name, value) // metrics
-```
-
-### decide() / select()
-
-```typescript
-// Filter syntax — captures operators + thresholds
-decide(scope, [
-  { when: { creditScore: { gt: 700 }, dti: { lt: 0.43 } }, then: 'approved', label: 'Good credit' },
-], 'rejected');
-
-// Function syntax — captures which keys were read
-decide(scope, [
-  { when: (s) => s.creditScore > 700, then: 'approved' },
-], 'rejected');
-
-// select() — all matching branches (not first-match)
-select(scope, [
-  { when: { glucose: { gt: 100 } }, then: 'diabetes' },
-  { when: { bmi: { gt: 30 } }, then: 'obesity' },
-]);
-```
-
-### Executor
-
-```typescript
-const executor = new FlowChartExecutor(chart);
-await executor.run({ input, env: { traceId: 'req-123' } });
-executor.getNarrative()            // string[]
-executor.getNarrativeEntries()     // CombinedNarrativeEntry[]
-executor.getSnapshot()             // memory state
-executor.attachRecorder(recorder)  // scope observer
-executor.attachFlowRecorder(r)     // flow observer
-executor.setRedactionPolicy({ keys, patterns, fields })
-```
-
-## Observer Systems
-
-- **Scope Recorder**: fires DURING stage (`onRead`, `onWrite`, `onCommit`)
-- **FlowRecorder**: fires AFTER stage (`onStageExecuted`, `onDecision`, `onFork`, `onLoop`)
-- 8 built-in FlowRecorder strategies
-- Narrative via `executor.recorder(narrative())` at runtime
-
-## Rules
-
-- Use `flowChart<T>()` — scopeFactory is auto-embedded
-- Use `decide()` / `select()` in decider/selector functions
-- Use typed property access (not getValue/setValue)
-- Use `$getArgs()` for input, `$getEnv()` for environment
-- Never post-process the tree — use recorders
-- Use `.recorder(narrative())` at runtime for narrative setup

package/ai-instructions/cursor/footprint.md

@@ -1,118 +0,0 @@
-# footprint.js — Cursor Rules
-
-This is the footprint.js library — the flowchart pattern for backend code. Self-explainable systems that AI can reason about.
-
-## Core Principle
-
-**Collect during traversal, never post-process.** All data collection happens as side effects of the single DFS traversal. Never walk the tree after execution.
-
-## Architecture
-
-```
-src/lib/
-├── memory/    → Transactional state (SharedMemory, StageContext, TransactionBuffer)
-├── schema/    → Validation (Zod optional, duck-typed)
-├── builder/   → Fluent DSL (FlowChartBuilder, flowChart())
-├── scope/     → Per-stage facades + recorders + providers
-├── reactive/  → TypedScope<T> deep Proxy (typed property access, $-methods)
-├── decide/    → decide()/select() decision evidence capture
-├── engine/    → DFS traversal + narrative + handlers
-├── runner/    → FlowChartExecutor
-└── contract/  → I/O schema + OpenAPI
-```
-
-Entry points: `footprintjs` (public) and `footprintjs/advanced` (internals).
-
-## Key API — TypedScope (Recommended)
-
-```typescript
-import { flowChart, FlowChartExecutor, decide } from 'footprintjs';
-
-interface State {
-  creditScore: number;
-  riskTier: string;
-  decision?: string;
-}
-
-const chart = flowChart<State>('Intake', async (scope) => {
-  scope.creditScore = 750;          // typed write (no setValue needed)
-  scope.riskTier = 'low';           // typed write
-}, 'intake')
-  .addDeciderFunction('Route', (scope) => {
-    return decide(scope, [
-      { when: { riskTier: { eq: 'low' } }, then: 'approved', label: 'Low risk' },
-    ], 'rejected');
-  }, 'route', 'Route based on risk')
-    .addFunctionBranch('approved', 'Approve', async (scope) => {
-      scope.decision = 'Approved';
-    })
-    .addFunctionBranch('rejected', 'Reject', async (scope) => {
-      scope.decision = 'Rejected';
-    })
-    .setDefault('rejected')
-    .end()
-  .build();
-
-const executor = new FlowChartExecutor(chart);
-await executor.run();
-executor.getNarrative();  // causal trace with decision evidence
-```
-
-### TypedScope $-methods (escape hatches)
-
-```typescript
-scope.$getArgs<T>()        // frozen readonly input
-scope.$getEnv()            // execution environment (signal, timeoutMs, traceId)
-scope.$break()             // stop pipeline
-scope.$debug(key, value)   // debug info
-scope.$metric(name, value) // metrics
-```
-
-### decide() / select()
-
-```typescript
-// Filter syntax — captures operators + thresholds
-decide(scope, [
-  { when: { creditScore: { gt: 700 }, dti: { lt: 0.43 } }, then: 'approved', label: 'Good credit' },
-], 'rejected');
-
-// Function syntax — captures which keys were read
-decide(scope, [
-  { when: (s) => s.creditScore > 700, then: 'approved' },
-], 'rejected');
-
-// select() — all matching branches (not first-match)
-select(scope, [
-  { when: { glucose: { gt: 100 } }, then: 'diabetes' },
-  { when: { bmi: { gt: 30 } }, then: 'obesity' },
-]);
-```
-
-### Executor
-
-```typescript
-const executor = new FlowChartExecutor(chart);
-await executor.run({ input, env: { traceId: 'req-123' } });
-executor.getNarrative()            // string[]
-executor.getNarrativeEntries()     // CombinedNarrativeEntry[]
-executor.getSnapshot()             // memory state
-executor.attachRecorder(recorder)  // scope observer
-executor.attachFlowRecorder(r)     // flow observer
-executor.setRedactionPolicy({ keys, patterns, fields })
-```
-
-## Observer Systems
-
-- **Scope Recorder**: fires DURING stage (`onRead`, `onWrite`, `onCommit`)
-- **FlowRecorder**: fires AFTER stage (`onStageExecuted`, `onDecision`, `onFork`, `onLoop`)
-- 8 built-in FlowRecorder strategies
-- Narrative via `executor.recorder(narrative())` at runtime
-
-## Rules
-
-- Use `flowChart<T>()` — scopeFactory is auto-embedded
-- Use `decide()` / `select()` in decider/selector functions
-- Use typed property access (not getValue/setValue)
-- Use `$getArgs()` for input, `$getEnv()` for environment
-- Never post-process the tree — use recorders
-- Use `.recorder(narrative())` at runtime for narrative setup

package/ai-instructions/kiro/footprint.md

@@ -1,118 +0,0 @@
-# footprint.js — Kiro Rules
-
-This is the footprint.js library — the flowchart pattern for backend code. Self-explainable systems that AI can reason about.
-
-## Core Principle
-
-**Collect during traversal, never post-process.** All data collection happens as side effects of the single DFS traversal. Never walk the tree after execution.
-
-## Architecture
-
-```
-src/lib/
-├── memory/    → Transactional state (SharedMemory, StageContext, TransactionBuffer)
-├── schema/    → Validation (Zod optional, duck-typed)
-├── builder/   → Fluent DSL (FlowChartBuilder, flowChart())
-├── scope/     → Per-stage facades + recorders + providers
-├── reactive/  → TypedScope<T> deep Proxy (typed property access, $-methods)
-├── decide/    → decide()/select() decision evidence capture
-├── engine/    → DFS traversal + narrative + handlers
-├── runner/    → FlowChartExecutor
-└── contract/  → I/O schema + OpenAPI
-```
-
-Entry points: `footprintjs` (public) and `footprintjs/advanced` (internals).
-
-## Key API — TypedScope (Recommended)
-
-```typescript
-import { flowChart, FlowChartExecutor, decide } from 'footprintjs';
-
-interface State {
-  creditScore: number;
-  riskTier: string;
-  decision?: string;
-}
-
-const chart = flowChart<State>('Intake', async (scope) => {
-  scope.creditScore = 750;          // typed write (no setValue needed)
-  scope.riskTier = 'low';           // typed write
-}, 'intake')
-  .addDeciderFunction('Route', (scope) => {
-    return decide(scope, [
-      { when: { riskTier: { eq: 'low' } }, then: 'approved', label: 'Low risk' },
-    ], 'rejected');
-  }, 'route', 'Route based on risk')
-    .addFunctionBranch('approved', 'Approve', async (scope) => {
-      scope.decision = 'Approved';
-    })
-    .addFunctionBranch('rejected', 'Reject', async (scope) => {
-      scope.decision = 'Rejected';
-    })
-    .setDefault('rejected')
-    .end()
-  .build();
-
-const executor = new FlowChartExecutor(chart);
-await executor.run();
-executor.getNarrative();  // causal trace with decision evidence
-```
-
-### TypedScope $-methods (escape hatches)
-
-```typescript
-scope.$getArgs<T>()        // frozen readonly input
-scope.$getEnv()            // execution environment (signal, timeoutMs, traceId)
-scope.$break()             // stop pipeline
-scope.$debug(key, value)   // debug info
-scope.$metric(name, value) // metrics
-```
-
-### decide() / select()
-
-```typescript
-// Filter syntax — captures operators + thresholds
-decide(scope, [
-  { when: { creditScore: { gt: 700 }, dti: { lt: 0.43 } }, then: 'approved', label: 'Good credit' },
-], 'rejected');
-
-// Function syntax — captures which keys were read
-decide(scope, [
-  { when: (s) => s.creditScore > 700, then: 'approved' },
-], 'rejected');
-
-// select() — all matching branches (not first-match)
-select(scope, [
-  { when: { glucose: { gt: 100 } }, then: 'diabetes' },
-  { when: { bmi: { gt: 30 } }, then: 'obesity' },
-]);
-```
-
-### Executor
-
-```typescript
-const executor = new FlowChartExecutor(chart);
-await executor.run({ input, env: { traceId: 'req-123' } });
-executor.getNarrative()            // string[]
-executor.getNarrativeEntries()     // CombinedNarrativeEntry[]
-executor.getSnapshot()             // memory state
-executor.attachRecorder(recorder)  // scope observer
-executor.attachFlowRecorder(r)     // flow observer
-executor.setRedactionPolicy({ keys, patterns, fields })
-```
-
-## Observer Systems
-
-- **Scope Recorder**: fires DURING stage (`onRead`, `onWrite`, `onCommit`)
-- **FlowRecorder**: fires AFTER stage (`onStageExecuted`, `onDecision`, `onFork`, `onLoop`)
-- 8 built-in FlowRecorder strategies
-- Narrative via `executor.recorder(narrative())` at runtime
-
-## Rules
-
-- Use `flowChart<T>()` — scopeFactory is auto-embedded
-- Use `decide()` / `select()` in decider/selector functions
-- Use typed property access (not getValue/setValue)
-- Use `$getArgs()` for input, `$getEnv()` for environment
-- Never post-process the tree — use recorders
-- Use `.recorder(narrative())` at runtime for narrative setup

package/ai-instructions/setup.sh

@@ -1,140 +0,0 @@
-#!/usr/bin/env bash
-# footprint.js — AI coding tool setup
-# Installs instruction files for your preferred AI coding assistant.
-#
-# Usage:
-#   npx footprintjs-setup          (after npm install footprintjs)
-#   bash node_modules/footprintjs/ai-instructions/setup.sh
-
-set -euo pipefail
-
-PKG_DIR="$(cd "$(dirname "$0")" && pwd)"
-PROJECT_DIR="$(pwd)"
-
-echo ""
-echo "  footprint.js — AI Coding Tool Setup"
-echo "  ──────────────────────────────────────"
-echo ""
-echo "  This will copy instruction files so your AI coding"
-echo "  assistant understands the footprint.js API."
-echo ""
-
-install_claude_code() {
-  mkdir -p "$PROJECT_DIR/.claude/skills/footprint"
-  cp "$PKG_DIR/claude-code/SKILL.md" "$PROJECT_DIR/.claude/skills/footprint/SKILL.md"
-  # Also copy CLAUDE.md to project root if not present
-  if [ ! -f "$PROJECT_DIR/CLAUDE.md" ]; then
-    cp "$PKG_DIR/../CLAUDE.md" "$PROJECT_DIR/CLAUDE.md" 2>/dev/null || true
-  fi
-  echo "  [ok] Claude Code — .claude/skills/footprint/SKILL.md"
-}
-
-install_codex() {
-  if [ ! -f "$PROJECT_DIR/AGENTS.md" ]; then
-    cp "$PKG_DIR/../AGENTS.md" "$PROJECT_DIR/AGENTS.md" 2>/dev/null || true
-    echo "  [ok] OpenAI Codex — AGENTS.md"
-  else
-    echo "  [skip] AGENTS.md already exists"
-  fi
-}
-
-install_copilot() {
-  mkdir -p "$PROJECT_DIR/.github"
-  if [ ! -f "$PROJECT_DIR/.github/copilot-instructions.md" ]; then
-    cp "$PKG_DIR/copilot-instructions.md" "$PROJECT_DIR/.github/copilot-instructions.md"
-    echo "  [ok] GitHub Copilot — .github/copilot-instructions.md"
-  else
-    echo "  [skip] .github/copilot-instructions.md already exists"
-  fi
-}
-
-install_cursor() {
-  mkdir -p "$PROJECT_DIR/.cursor/rules"
-  cp "$PKG_DIR/cursor/footprint.md" "$PROJECT_DIR/.cursor/rules/footprint.md"
-  echo "  [ok] Cursor — .cursor/rules/footprint.md"
-}
-
-install_windsurf() {
-  if [ ! -f "$PROJECT_DIR/.windsurfrules" ]; then
-    cp "$PKG_DIR/windsurfrules" "$PROJECT_DIR/.windsurfrules"
-    echo "  [ok] Windsurf — .windsurfrules"
-  else
-    # Append footprint rules to existing file
-    echo "" >> "$PROJECT_DIR/.windsurfrules"
-    cat "$PKG_DIR/windsurfrules" >> "$PROJECT_DIR/.windsurfrules"
-    echo "  [ok] Windsurf — appended to .windsurfrules"
-  fi
-}
-
-install_cline() {
-  if [ ! -f "$PROJECT_DIR/.clinerules" ]; then
-    cp "$PKG_DIR/clinerules" "$PROJECT_DIR/.clinerules"
-    echo "  [ok] Cline — .clinerules"
-  else
-    echo "" >> "$PROJECT_DIR/.clinerules"
-    cat "$PKG_DIR/clinerules" >> "$PROJECT_DIR/.clinerules"
-    echo "  [ok] Cline — appended to .clinerules"
-  fi
-}
-
-install_kiro() {
-  mkdir -p "$PROJECT_DIR/.kiro/rules"
-  cp "$PKG_DIR/kiro/footprint.md" "$PROJECT_DIR/.kiro/rules/footprint.md"
-  echo "  [ok] Kiro — .kiro/rules/footprint.md"
-}
-
-install_all() {
-  install_claude_code
-  install_codex
-  install_copilot
-  install_cursor
-  install_windsurf
-  install_cline
-  install_kiro
-}
-
-# Interactive menu
-echo "  Which tool(s) do you use?"
-echo ""
-echo "    1) Claude Code"
-echo "    2) OpenAI Codex"
-echo "    3) GitHub Copilot"
-echo "    4) Cursor"
-echo "    5) Windsurf"
-echo "    6) Cline"
-echo "    7) Kiro"
-echo "    a) All of the above"
-echo "    q) Quit"
-echo ""
-read -rp "  Choose (e.g. 1,4 or a): " choice
-
-echo ""
-
-if [[ "$choice" == "q" ]]; then
-  echo "  Cancelled."
-  exit 0
-fi
-
-if [[ "$choice" == "a" || "$choice" == "A" ]]; then
-  install_all
-else
-  IFS=',' read -ra selections <<< "$choice"
-  for sel in "${selections[@]}"; do
-    sel="$(echo "$sel" | tr -d ' ')"
-    case "$sel" in
-      1) install_claude_code ;;
-      2) install_codex ;;
-      3) install_copilot ;;
-      4) install_cursor ;;
-      5) install_windsurf ;;
-      6) install_cline ;;
-      7) install_kiro ;;
-      *) echo "  [?] Unknown option: $sel" ;;
-    esac
-  done
-fi
-
-echo ""
-echo "  Done! Your AI assistant now knows the footprint.js API."
-echo "  Add the generated files to .gitignore if you don't want them in version control."
-echo ""

package/ai-instructions/windsurfrules

@@ -1,119 +0,0 @@
-# footprint.js
-
-This is the footprint.js library — the flowchart pattern for backend code. Self-explainable systems that AI can reason about.
-
-## Core Principle
-
-**Collect during traversal, never post-process.** All data collection happens as side effects of the single DFS traversal. Never walk the tree after execution.
-
-## Architecture
-
-```
-src/lib/
-├── memory/    → Transactional state (SharedMemory, StageContext, TransactionBuffer)
-├── schema/    → Validation (Zod optional, duck-typed)
-├── builder/   → Fluent DSL (FlowChartBuilder, flowChart(), typedFlowChart())
-├── scope/     → Per-stage facades + recorders + providers
-├── reactive/  → TypedScope<T> deep Proxy (typed property access, $-methods)
-├── decide/    → decide()/select() decision evidence capture
-├── engine/    → DFS traversal + narrative + handlers
-├── runner/    → FlowChartExecutor
-└── contract/  → I/O schema + OpenAPI
-```
-
-Entry points: `footprintjs` (public) and `footprintjs/advanced` (internals).
-
-## Key API — TypedScope (Recommended)
-
-```typescript
-import { typedFlowChart, FlowChartExecutor, decide } from 'footprintjs';
-
-interface State {
-  creditScore: number;
-  riskTier: string;
-  decision?: string;
-}
-
-const chart = typedFlowChart<State>('Intake', async (scope) => {
-  scope.creditScore = 750;          // typed write (no setValue needed)
-  scope.riskTier = 'low';           // typed write
-}, 'intake')
-  .setEnableNarrative()
-  .addDeciderFunction('Route', (scope) => {
-    return decide(scope, [
-      { when: { riskTier: { eq: 'low' } }, then: 'approved', label: 'Low risk' },
-    ], 'rejected');
-  }, 'route', 'Route based on risk')
-    .addFunctionBranch('approved', 'Approve', async (scope) => {
-      scope.decision = 'Approved';
-    })
-    .addFunctionBranch('rejected', 'Reject', async (scope) => {
-      scope.decision = 'Rejected';
-    })
-    .setDefault('rejected')
-    .end()
-  .build();
-
-const executor = new FlowChartExecutor(chart<State>());
-await executor.run();
-executor.getNarrative();  // causal trace with decision evidence
-```
-
-### TypedScope $-methods (escape hatches)
-
-```typescript
-scope.$getArgs<T>()        // frozen readonly input
-scope.$getEnv()            // execution environment (signal, timeoutMs, traceId)
-scope.$break()             // stop pipeline
-scope.$debug(key, value)   // debug info
-scope.$metric(name, value) // metrics
-```
-
-### decide() / select()
-
-```typescript
-// Filter syntax — captures operators + thresholds
-decide(scope, [
-  { when: { creditScore: { gt: 700 }, dti: { lt: 0.43 } }, then: 'approved', label: 'Good credit' },
-], 'rejected');
-
-// Function syntax — captures which keys were read
-decide(scope, [
-  { when: (s) => s.creditScore > 700, then: 'approved' },
-], 'rejected');
-
-// select() — all matching branches (not first-match)
-select(scope, [
-  { when: { glucose: { gt: 100 } }, then: 'diabetes' },
-  { when: { bmi: { gt: 30 } }, then: 'obesity' },
-]);
-```
-
-### Executor
-
-```typescript
-const executor = new FlowChartExecutor(chart<State>());
-await executor.run({ input, env: { traceId: 'req-123' } });
-executor.getNarrative()            // string[]
-executor.getNarrativeEntries()     // CombinedNarrativeEntry[]
-executor.getSnapshot()             // memory state
-executor.attachRecorder(recorder)  // scope observer
-executor.attachFlowRecorder(r)     // flow observer
-executor.setRedactionPolicy({ keys, patterns, fields })
-```
-
-## Observer Systems
-
-- **Scope Recorder**: fires DURING stage (`onRead`, `onWrite`, `onCommit`)
-- **FlowRecorder**: fires AFTER stage (`onStageExecuted`, `onDecision`, `onFork`, `onLoop`)
-- 8 built-in FlowRecorder strategies
-- `setEnableNarrative()` auto-attaches `CombinedNarrativeRecorder`
-
-## Rules
-
-- Use `typedFlowChart<T>()` — scopeFactory is auto-embedded, no `createTypedScopeFactory` needed
-- Use `decide()` / `select()` in decider/selector functions
-- Use typed property access (not getValue/setValue)
-- Use `$getArgs()` for input, `$getEnv()` for environment
-- Never post-process the tree — use recorders
-- `setEnableNarrative()` is all you need for narrative setup