Track where time is spent during worksheet page render:
- loadWorksheetSettings (DB query + getViewerId)
- generateWorksheetPreview (problem generation + Typst compilation)
- Total page render time
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add flowchart_version_history table to store snapshots after generate/refine
- Create versions API endpoint (GET list, POST restore)
- Add History tab with version list showing source, validation status, timestamp
- Implement inline preview mode to view historical versions without restoring
- Preview mode shows amber banner and updates diagram, examples, worksheet, tests
- Hide structure/input tabs (not useful currently)
- Add preview notice in refinement panel clarifying behavior
- Update React Query documentation with comprehensive patterns
- Add versionHistoryKeys to central query key factory
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Fix race condition where watch endpoint couldn't find active generation
because generate hadn't registered yet. Workshop page now triggers
/generate before connecting to /watch.
- Add polling fallback in watch endpoint (up to 3s) for edge cases where
generate route is still starting up.
- Add progress panel for regeneration - was missing because the panel
was only shown when !hasDraft.
- Add comprehensive logging throughout generation pipeline for debugging.
- Improve generation registry with subscriber management and accumulated
reasoning text for reconnection support.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Rewrite DebugMermaidDiagram edge matching to use BFS graph traversal
- Build graph from SVG edges (L_FROM_TO_INDEX format) for path finding
- Handle phase boundary disconnections with bidirectional BFS:
- Forward BFS finds all nodes reachable from start
- Backward BFS finds all nodes that can reach end
- Combines both to highlight intermediate nodes across phase gaps
- Remove complex pattern matching in favor of graph-based approach
- Auto-compute edge IDs as {nodeId}_{optionValue} in loader.ts
- Add computeEdgeId() helper to schema.ts for consistent edge ID generation
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Instead of warning about missing edge IDs in the doctor, automatically
assign computed edge IDs ({nodeId}_{optionValue}) to decision edges
that have auto-generated IDs (edge_N) during flowchart loading.
This makes edge highlighting work for legacy flowcharts without
requiring regeneration.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add computeEdgeId() helper that generates edge IDs as {nodeId}_{optionValue}
- Update loader.ts to compute edge IDs automatically from decision options
- Update parser.ts to extract edge IDs from mermaid id@--> syntax
- Add MERM-003 diagnostic in doctor.ts to detect missing edge IDs
- Update LLM schemas to document the required edge ID pattern
- Update DebugMermaidDiagram to match edges by ID (with index fallback)
Edge IDs enable reliable highlighting of decision edges during visualization.
The pattern is deterministic: for a decision node "COMPARE" with option
value "direct", the expected edge ID is "COMPARE_direct".
Mermaid content must use: COMPARE COMPARE_direct@-->|"DIRECT"| NEXT_NODE
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Phase 3 - Mermaid Highlighting:
- Add highlightedNodeId prop to DebugMermaidDiagram for trace hover highlighting
- Cyan dashed border distinguishes trace hover from walker progress (amber)
Phase 4 - Problem Trace Component:
- Create ProblemTrace.tsx displaying step-by-step computation trace
- Shows node title, transforms applied, working problem evolution
- Timeline UI with expand/collapse for each step
- Integrate into WorksheetDebugPanel expanded details
Phase 5 - Unified Answer Computation:
- Update WorksheetDebugPanel to use simulateWalk + extractAnswer
- Update worksheet-generator.ts to use unified computation path
- Update test-case-validator.ts runTestCaseWithFlowchart to use simulateWalk
- All places with full ExecutableFlowchart now use single code path
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Transform the flowchart system from "compute everything upfront" to
"walk IS the computation". This is the foundation for the new unified
computation model.
Phase 1 - Schema & Core Runtime:
- Add TransformExpression, StateSnapshot, DisplayTemplate, AnswerDefinition
- Add StructuredTestCase for primitive-based test validation
- Update FlowchartState with values, snapshots, hasError fields
- Mark variables as deprecated (optional) for transition period
- Add interpolateTemplate() for {{name}} and {{=expr}} syntax
- Add applyTransforms(), extractAnswer(), simulateWalk() to loader
- Add createContextFromValues() for transform execution
Phase 2 - Walker Integration:
- Apply transforms when entering each node during walk
- Initialize entry node transforms on state creation
- Snapshots now accumulate as nodes are visited
All existing flowcharts continue to work via backwards compatibility
with the legacy variables section.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add a flexible logging system to the llm-client package that can be
enabled/disabled without rebuilding:
- Add Logger class with configurable enable/disable and custom logger support
- Add LogLevel, LoggerFn, LoggingConfig types
- Add `debug` option to LLMStreamRequest for per-request logging override
- Add setLogging() method for runtime enable/disable
- Replace hardcoded console.log in openai-responses provider with logger
- Add ?debug=true query param to flowchart generate endpoint
Usage:
- Per-request: llm.stream({ ..., debug: true })
- Global: llm.setLogging({ enabled: true })
- Custom logger: new LLMClient({ logging: { enabled: true, logger: fn } })
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Hardcoded flowcharts are now "seeds" that can be manually populated
into the database via a debug UI. This provides a single source of
truth (database) while keeping canonical definitions in version control.
Changes:
- Add /api/flowcharts/seeds endpoint for seed management
- Add SeedManagerPanel component (visible in debug mode on /flowchart)
- Rename FLOWCHARTS -> FLOWCHART_SEEDS in definitions/index.ts
- Remove hardcoded fallbacks from getFlowchartByIdAsync/getFlowchartListAsync
- Update browse API to only load from database
- Update all dependent files to use database-only loading
- Seeds are owned by the user who initiates seeding
To use: Enable debug mode on /flowchart, use Seed Manager panel to
populate the database with built-in flowcharts.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Server components read from request headers, not response headers.
This fixes the "No valid viewer session found" error for new visitors
on pages like /practice that need guest identification on first load.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Remove legacy schema-specific formatting fallbacks in formatting.ts and example-generator.ts
- All flowcharts now require explicit display.problem and display.answer expressions
- Add DISP-003 diagnostic for missing display.problem expressions
- Update doctor to treat missing display.answer as error (was warning)
Also includes:
- Terraform: generate LiteFS config at runtime, add AUTH_TRUST_HOST, add volume mounts for vision-training and uploads data
- Terraform: add storage.tf for persistent volume claims
- Add Claude instructions for terraform directory
- Various UI component formatting updates
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add expectedAnswer field to ProblemExample schema for test validation
- Create test-case-validator.ts with functions to evaluate display.answer
and compare against expected answers
- Add TestsTab.tsx component showing test results and path coverage
- Integrate validation into generate/refine routes with SSE events
- Add coverage diagnostics to flowchart doctor (TEST-001/002/003)
- Fix LLM output normalization: strip wrapper quotes from strings
(e.g., "'+'" -> "+") and convert numeric strings to numbers
- Use formatAnswerDisplay for test evaluation (same as worksheet)
- Update LLM prompts with clearer excludeFromExampleStructure guidance
for result-formatting decisions vs problem-type decisions
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add LiteFS binary and config to Docker image for SQLite replication
- Convert k8s Deployment to StatefulSet for stable pod identities
- Pod-0 is primary (handles writes), others are replicas
- LiteFS proxy forwards write requests to primary automatically
- Add headless service for pod-to-pod communication
- Increase Node.js heap size to 4GB for Next.js build
- Exclude large Python venvs from Docker context
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Panda CSS token values in shorthand strings (e.g., `padding: '2 4'`)
silently fail. Convert all 84+ occurrences to paddingX/paddingY and
marginX/marginY properties which correctly resolve design tokens.
Affected areas:
- Flowchart pages and components
- Know Your World game components
- KidNumberInput component
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Avoid terminology confusion - "skills" refers to invokable commands
like /fix-css and /porkbun-dns. The documentation files are
step-by-step procedures, not invocable skills.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Replace sequential example generation with a proper task queue system that
correctly handles concurrent requests to the Web Worker pool.
Root cause of previous issues: Each worker stored only ONE resolve/reject
callback, so concurrent requests would overwrite each other's callbacks,
causing promises to never resolve or resolve with wrong data.
Solution:
- Add unique requestId to all worker messages for request/response matching
- Implement task queue with dispatch logic for pending work
- Track pending requests in a Map keyed by requestId
- Workers echo back requestId so responses match their originating requests
- Both /flowchart page and workshop page now generate concurrently
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
When both WorksheetDebugPanel and FlowchartExampleGrid try to generate
examples simultaneously using the shared web worker pool, the workers'
resolve/reject callbacks get overwritten, causing one request to never
complete.
This fix sequences the generation:
- WorksheetDebugPanel generates first (when worksheet tab is active)
- FlowchartExampleGrid waits until WorksheetDebugPanel signals completion
- Added onGenerationStart/onGenerationComplete callbacks to WorksheetDebugPanel
- Added waitForReady prop to FlowchartExampleGrid to defer generation
- Workshop page coordinates the sequence using isDebugPanelGenerating state
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add MERM-002 doctor diagnostic to detect when JSON node IDs don't
match mermaid node IDs
- Update loader to throw error when entry node is missing or >50% of
nodes are missing from mermaid (prevents crash loops)
- Add flowchartLoadError state and UI display in workshop page
- Improve LLM schema documentation for display.answer vs generation.target
- Add context-aware division-by-zero suggestions in doctor
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Combine published and draft example generation into single unified effect
- Fix race condition where worker pool was cancelling requests when
drafts and published flowcharts competed for the same workers
- Add draftMermaidContent to sessions API response (was missing)
- Remove redundant draftCardExamples state in favor of unified cardExamples
- Process all flowcharts sequentially to avoid worker pool cancellation
- Show animated backgrounds on healthy draft flowcharts, not just published
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The worksheet generator was hardcoding answer computation for specific
schemas (two-digit-subtraction, fractions, linear equations) and
returning "?" for any unknown schema like custom flowcharts.
Now uses the centralized formatAnswerDisplay() function which properly
handles:
- Custom display.answer expressions defined in the flowchart
- Computed variables from the flowchart definition
- Schema-specific fallback logic
- The generation.target fallback for custom schemas
This fixes PDF worksheets showing "?" answers for teacher-created
flowcharts like "math duck maker" while the debug panel showed
correct answers.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Worksheet improvements:
- Add orderByDifficulty option to sort problems easy→medium→hard
- Add typstAnswer field for proper fraction rendering in answer key
- Add WorksheetDebugPanel to preview generated examples
- Move PDF creation to modal in workshop, make worksheet tab default
- Support worksheet generation from workshop sessions
Flowchart diagnostics:
- Add doctor.ts with validation checks (DISP-002 for missing answer handlers)
- Add FlowchartDiagnostics component for displaying warnings
- Add display.answer config to fraction and linear equation flowcharts
UI refinements:
- Improve AnimatedProblemTile styling
- Enhance FlowchartCard and FlowchartModal components
- Add derived field validation tests for LLM schemas
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add AnimatedProblemTile component with MathDisplay for proper math rendering
- Add AnimatedBackgroundTiles grid component for card backgrounds
- Update FlowchartCard to accept flowchart + examples props
- Generate examples client-side for both hardcoded and database flowcharts
- Use same formatting system (formatProblemDisplay + MathDisplay) as modal
Also includes:
- Fix migration 0076 timestamp ordering issue (linkedPublishedId column)
- Add migration-timestamp-fix skill documenting common drizzle-kit issue
- Update CLAUDE.md with migration timestamp ordering guidance
- Various flowchart workshop and vision training improvements
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Previously, closing the browser while the LLM was generating a flowchart
would abort the entire operation - the work would be lost because:
1. sendEvent() would throw when writing to a closed stream
2. The exception would jump to catch and skip the DB save
3. Session state would be reset to 'initial' (error state)
Now the generate and refine routes are resilient to client disconnect:
- sendEvent() catches errors silently and sets clientConnected=false
- LLM stream processing continues regardless of client state
- DB save happens AFTER the LLM loop, not inside try-catch for client errors
- Added logging to track when saves happen with disconnected client
Result: If you start generating a flowchart and close the browser, the
server will finish processing and save to DB. When you return to the
session, your flowchart will be there waiting.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add virtualization using @tanstack/react-virtual to handle thousands
of training images without loading all at once
- Fix selection behavior: normal click now replaces selection (was toggle),
shift+click adds range to selection
- Add independent panel scrolling with minHeight: 0 for flex layout
- Use ResizeObserver to dynamically calculate items per row
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Create .claude/skills/FLOWCHART_MODIFICATIONS.md with patterns for:
- Adding checkpoint nodes (variables, edges, Mermaid content)
- Conditional skipping with skipIf and excludeSkipFromPaths
- Understanding path enumeration and grid dimension stability
- Working problem evolution
- Debugging tips and modification checklist
- Add reference in CLAUDE.md under Flowchart Walker System section
This captures lessons learned from the fraction flowchart sprint where we
split CALCULATE into separate inputs and added conditional whole number skipping.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Split STEP4 into three checkpoints: NUMERATOR, DENOMINATOR, WHOLE NUMBER
- Add skipIf/skipTo support to CheckpointNode for conditional skipping
- Add excludeSkipFromPaths option to prevent skipIf from affecting grid dimensions
- CALC_WHOLE skips automatically when no whole numbers in problem
- Update loader.ts to handle checkpoint skipIf in path complexity and enumeration
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Major layout redesign that makes the working problem the hero:
Layout changes:
- Single centered column instead of two-column with sidebar
- TimeMachineHistory displays problem evolution as 3D perspective stack
- Instructions appear above the Time Machine
- Interaction area (checkpoints, decisions) below
- Compact phase rail in top bar
- Floating hamburger menu replaces full nav during walking
Behavior changes:
- Decision nodes rendered via FlowchartDecisionGraph (moved from separate component)
- Embellishment nodes auto-advance after 800ms with pop animation
- Milestone nodes auto-advance after 500ms
- Walking mode uses distraction-free UI with FloatingHamburgerMenu
This creates a focused, problem-centered experience where the student
sees their work evolving as they progress through the flowchart.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add a `compact` prop that renders the phase rail as minimal pills:
- Shows only phase indicators: ✓ (completed), 📍 (current), ○ (upcoming)
- No expanded current phase section
- No decision graph in compact mode
- Suitable for top bar placement in focused walker views
Also integrates FlowchartDecisionGraph for inline decision rendering
when not in compact mode.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
New component that displays problem evolution as an Apple Time Machine-style
stack of cards:
- Current problem is prominent (full opacity, full scale) at the front
- Previous problems are stacked behind with perspective depth
- Each layer: translateZ, scale down, fade opacity
- Clicking past layers triggers navigation to rewind
- Smooth animation when new entries are added
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add exclusions for test files and KidNumberInput.tsx to prevent Panda CSS
from attempting to parse special patterns like {bksp} and {enter} that
confuse the parser.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
A standalone hamburger menu that floats in the corner of the screen.
Use this for distraction-free modes where you want to hide the full
app nav but still provide access to navigation, settings, and theme.
Features:
- Configurable position (top-left, top-right, bottom-left, bottom-right)
- Optional exit button with custom label
- Navigation links to main app areas
- Fullscreen toggle
- Theme toggle (light/dark)
- App info access
- Mobile: full-screen overlay
- Desktop: Radix dropdown menu
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Extract the decision graph visualization into a standalone component.
Renders a flowchart-style diamond with option buttons, showing the
decision point visually with connecting lines to choices.
Features:
- Diamond shape for decision question
- Option buttons arranged around the diamond
- SVG connecting lines between diamond and options
- Wrong answer feedback with shake animation
- Dark mode support
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Two related improvements to flowchart path analysis:
1. Embellishment node support:
- Add case handlers in getNextNode, calculatePathComplexity,
enumerateAllPaths, and getNextNodeForAnalysis
- Embellishment nodes auto-advance like milestones
2. skipIf/skipTo for decision nodes:
- Allow decisions to be automatically skipped based on a condition
- In calculatePathComplexity: evaluate skipIf and skip to target
without counting as a decision
- In enumerateAllPaths: enumerate both skip path (skipIf=true)
and option paths (skipIf=false) as alternatives
This enables conditional decision nodes like WHOLE_CHECK that only
appear when relevant (e.g., when fractions have whole numbers).
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add a new node type for showing animated emoji/celebration moments
that auto-advance. Unlike milestones (which are for success markers),
embellishments are purely decorative moments like 👍, 😎, 💪 between
substantive steps.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Thomas Hallock