{"owner":"metacraft-labs","repo":"codetracer","hasSkills":true,"totalSkillsCount":9,"totalTokensCount":11123,"categories":["anthropic-skill","root-instruction"],"hasMcp":false,"mcpConfig":null,"found":["tools/visual-review/mature-karax-visual-delta-20260505.md","tools/visual-review/project-visual-brief.md","tools/screen-briefs.md","docs/system.md","AGENTS.md","tools/visual-review/briefs/storybook-build-panel.md","tools/visual-review/briefs/storybook-default-layout.md","tools/visual-review/briefs/storybook-terminal-output.md","tools/visual-review/reference-coverage.md"],"skills":{"tools/visual-review/mature-karax-visual-delta-20260505.md":"# Mature Karax Visual Delta Report - 2026-05-05\n\n\n\nBranch: `codetracer-viewmodel`\n\n## Method\n\n- Storybook was rebuilt with\n `nix shell nixpkgs#nodejs --command bash -lc 'just storybook-build'`.\n- Current Storybook stories were captured with\n `tools/visual-review/capture-storybook.mjs`.\n- `wide` (`1920x1080`) was used for Karax references captured at `1920x1080`.\n- `laptop` (`1440x900`) was used for the older full-page Karax references\n captured as `2161x3766`; those metrics are useful for trend tracking but are\n dominated by viewport/full-page framing.\n- Screenshot metrics were generated with `tools/visual-review/compare-screenshots.sh`,\n which resizes the reference image to the current capture before computing RMSE/MAE.\n- Generated captures, dumps, and diff images remain ignored under\n `tools/visual-review/{screenshots,reports,compare,dumps}`.\n\n## Summary\n\nThe mature Karax states now have matching capturable Storybook stories. The\nclosest comparisons are the `1920x1080` default Noir layout variants: their\nlargest remaining deltas are mostly intentional richer IsoNim content, not empty\nor broken rendering. The older full-page references and panel-only current\nstories are documented separately because their RMSE/MAE numbers are dominated\nby app-frame and viewport mismatch.\n\nNo small shell/chrome/CSS fix was applied in this pass; the visible differences\nthat remain would require either new full-layout stories for panel-only states or\ndeliberate content downgrades, which this audit avoided.\n\n## Per-Surface Results\n\n| Surface | Current story | Viewport | RMSE | MAE | Status |\n| --- | --- | --- | ---: | ---: | --- |\n| Default layout | `default-layout` | laptop | 0.148885 | 0.056060 | Framing-dominated; current shell is populated and richer. |\n| Terminal | `terminal-output` | laptop | 0.098892 | 0.028241 | Panel story vs full-layout Karax terminal state; metric is directional only. |\n| Scratchpad | `scratchpad` | laptop | 0.098082 | 0.029454 | Panel story vs full-layout Karax scratchpad state; metric is directional only. |\n| Filesystem active | `noir-filesystem-active` | wide | 0.100905 | 0.025215 | Good app-frame match; richer editor/calltrace/event rows dominate. |\n| State active | `noir-state-active` | wide | 0.100905 | 0.025215 | Same base Karax/current pixels as filesystem active; focus change is not visibly distinct. |\n| Calltrace active | `noir-calltrace-active` | wide | 0.100905 | 0.025215 | Same base Karax/current pixels as filesystem active; richer calltrace text dominates. |\n| Calltrace search/status | `noir-calltrace-search-status-report` | wide | 0.106128 | 0.026938 | Good app-frame match; current calltrace/search content is denser. |\n| Menu open | `noir-menu-view-open` | wide | 0.074298 | 0.018578 | Good app-frame match; menu/status shell differences are localized. |\n| Status expanded | `noir-status-expanded` | wide | 0.072659 | 0.018013 | Best layout match in this batch; status and agent panel richness remain. |\n| Fixed search | `noir-fixed-search-visible` | laptop | 0.168908 | 0.057116 | Full-page reference mismatch; current search shell is richer. |\n| Search results | `noir-search-results-populated` | laptop | 0.170998 | 0.060999 | Full-page reference mismatch plus richer current search result content. |\n| Command palette | `noir-command-palette-open` | laptop | 0.094881 | 0.058993 | Full-page reference mismatch; overlay shape/content comparable. |\n| Build | `noir-build-open` | laptop | 0.134460 | 0.048930 | Full-page reference mismatch; current build output behavior is richer. |\n| Trace log | `noir-trace-log-open` | laptop | 0.123995 | 0.041831 | Full-page reference mismatch; table density/content differs intentionally. |\n| Debug controls/header | `noir-debug-controls-header` | laptop | 0.148460 | 0.055652 | Full-page reference mismatch; header chrome is comparable. |\n| Shell | `shell` | wide | 0.079896 | 0.037638 | Panel story vs full-layout Karax shell state; metric is not a parity signal. |\n| REPL | `repl` | laptop | 0.073845 | 0.032278 | Panel story vs full-layout Karax REPL state; metric is directional only. |\n| Low-level code | `low-level-code` | laptop | 0.073199 | 0.030190 | Panel story vs full-layout Karax low-level state; metric is directional only. |\n| No source | `no-source` | laptop | 0.092624 | 0.020209 | Panel story vs full-layout Karax no-source state; metric is directional only. |\n| Welcome | `welcome` | wide | 0.067437 | 0.011610 | Good standalone match; remaining delta is mostly typography/spacing. |\n| Step list | `step-list` | wide | 0.088317 | 0.037435 | Panel story vs full-layout Karax step-list state; metric is directional only. |\n\n## Top Remaining Deltas\n\n1. Several Karax references are full-page `2161x3766` captures while current\n Storybook is viewport-framed. These need either custom-size capture support or\n new reference captures before RMSE/MAE can be treated as parity gates.\n2. Shell, REPL, low-level, no-source, and step-list currently compare panel\n stories against full-layout Karax states. Full-layout Storybook variants would\n make these measurable in the same way as the Noir default variants.\n3. The current IsoNim default layout intentionally shows richer editor syntax,\n calltrace rows, terminal/event-log rows, and populated panel behavior. These\n content differences should not be patched back to the older Karax state.\n4. The remaining meaningful layout deltas are small chrome differences in tabs,\n status/menu treatment, scroll positions, and text wrapping rather than missing\n surfaces.\n","tools/visual-review/project-visual-brief.md":"# CodeTracer Storybook Visual Brief\n\nCodeTracer is a debugging and replay UI for inspecting recorded program\nexecution. The Storybook surfaces must render the production IsoNim DOM with\nthe same CSS and shell context as the Electron app, so isolated panel review can\ncatch visual regressions before full GUI tests.\n\nThe important rule is that Storybook may mock ViewModel data, but it must not\nmock or reimplement component DOM. Storybook stories should call the real\nIsoNim ViewModel constructors and `src/frontend/viewmodel/views/*.nim` render\nor mount functions.\n\n## Shared Design Goals\n\n- Match the dark CodeTracer Electron UI from `src/frontend/index.html`.\n- Use the app CSS from `frontend/styles/default_dark_theme_electron.css`.\n- Preserve the app shell context: `#root-container`, `#auto-hide-layout-row`,\n `#ROOT`, `.session-container`, and `#main`.\n- Panels should look like CodeTracer work surfaces, not generic Storybook\n cards.\n- Text should be legible, clipped content should be intentional, and images or\n icons should not be broken.\n\n## What Must Not Happen\n\n- Missing app CSS links in the Storybook iframe.\n- Bare unstyled HTML controls.\n- Storybook-local colors/fonts overriding CodeTracer CSS.\n- DOM mounted outside the app shell when the production selector depends on\n app-shell ancestors.\n- Broken asset URLs under `/public/resources` or `/public/third_party`.\n","tools/screen-briefs.md":"# Per-Screen Design Briefs for Visual Audit\n\nEach section describes exactly what must be visible, what data should be shown,\nand how to evaluate the screenshot against the CodeTracer design spec.\n\n---\n\n## Screen 1: Normal CodeTracer Layout (reference baseline)\n\n**Purpose**: Establish the reference baseline that all other screens are compared against.\n\n**Expected content**:\n\n- Toolbar: debugger step controls (forward, backward, continue icons)\n- Left: FILESYSTEM panel with file tree showing `source folders > codetracer > test-programs > py_console_logs > main.py`\n- Center: Editor tab `py_console_logs/main.py` with Python source code visible, line numbers, syntax highlighting (keywords in purple/blue, strings in green/orange)\n- Center-right: STATE panel showing \"Enter a watch expression\" input, SCRATCHPAD tab\n- Right: CALLTRACE panel with expandable call tree showing function names, AGENT ACTIVITY tab\n- Bottom-left: EVENT LOG panel with event rows (step index, line number, event text)\n- Bottom-right: TERMINAL OUTPUT panel with stdout/stderr output\n- Footer: Status bar with `Python(db) | UTF-8 | stable: ready | ` on the right, **BUILD | PROBLEMS | SEARCH RESULTS** labels on the right as auto-hide pane triggers\n- NO session tab bar (single trace)\n- NO gray empty areas — panels fill full window width\n\n**Evaluation**: This must look like a professional IDE. Compare against VS Code's dark theme for consistency.\n\n---\n\n## Screen 2: BUILD Auto-Hide Pane — Successful Build (happy path)\n\n**Purpose**: Show the BUILD pane expanded from the bottom with successful build output.\n\n**How to trigger**: Click the \"BUILD\" label in the status bar footer. The BUILD pane slides up as an overlay from the bottom.\n\n**Expected data to inject**:\n\n```\n$ nim c --sourcemap:on main.nim\nHint: used 42 lines of code\nHint: operation successful (0.8s)\nHint: [SuccessX]\n```\n\n**Expected appearance**:\n\n- BUILD overlay visible at bottom, full-width, ~30% window height\n- Overlay header: \"Build succeeded\" in GREEN text, with header controls (stop, clear, auto-scroll, duration \"0.8s\")\n- Build output lines in monospace font with ANSI colors rendered (green \"Hint:\" text)\n- \"Unpin\" button at top-right of overlay\n- The GL layout area above is still visible behind/above the overlay\n- Status bar \"BUILD\" label is highlighted (active state)\n\n---\n\n## Screen 3: BUILD Auto-Hide Pane — Failed Build (unhappy path)\n\n**Purpose**: Show BUILD pane with compiler errors, demonstrating error parsing and color coding.\n\n**Expected data to inject**:\n\n```\n$ cargo build\nerror[E0308]: mismatched types\n --> src/main.rs:42:5\n |\n42 | let x: bool = 42;\n | ^^ expected `bool`, found integer\n\nwarning: unused variable: `y`\n --> src/main.rs:10:9\n\nerror: aborting due to previous error\n```\n\n**Expected appearance**:\n\n- Overlay header: \"Build failed (exit code 1)\" in RED text\n- Error lines: red text (#f85149), clickable (underline on hover)\n- Warning lines: yellow text (#d29922)\n- File locations (`src/main.rs:42:5`) underlined and clickable\n- ANSI colors rendered — \"error\" in red, \"warning\" in yellow, \"-->\" in blue\n- Arrow indicators and code snippets visible in monospace\n\n---\n\n## Screen 4: PROBLEMS Auto-Hide Pane with Parsed Errors\n\n**Purpose**: Show the PROBLEMS pane with structured error list from the failed build.\n\n**Expected data**: 2 errors + 1 warning:\n\n- ERROR: src/main.rs:42:5 — \"mismatched types: expected `bool`, found integer\"\n- ERROR: src/main.rs:55:12 — \"cannot find value `undefined_var` in this scope\"\n- WARNING: src/main.rs:10:9 — \"unused variable: `y`\"\n\n**Expected appearance**:\n\n- Overlay header: \"3 problems (2 errors, 1 warning)\" with filter buttons [All] [Errors] [Warnings]\n- Error rows: red circle icon (●), file path in dim color, line:col, error message\n- Warning row: yellow triangle icon (▲), same format\n- Rows clickable with pointer cursor\n- Grouped by file if \"Group by File\" is toggled\n\n---\n\n## Screen 5: SEARCH RESULTS Auto-Hide Pane with Results\n\n**Purpose**: Show search results grouped by file with match highlighting.\n\n**Expected data**: Search for \"print\" with 4 results across 2 files:\n\n- src/main.py:10 — `def print_to_stdout() -> None:`\n- src/main.py:15 — `print(\"hello world\")`\n- src/main.py:51 — `print(\"1. print using print('text')\")`\n- src/utils.py:3 — `from io import print_function`\n\n**Expected appearance**:\n\n- Overlay header: \"4 results for 'print'\"\n- Results grouped by file: `src/main.py (3)` header, then 3 match rows\n- Then `src/utils.py (1)` header, 1 match row\n- Each row: line number on left, text with \"print\" highlighted in amber/yellow\n- Clickable rows for navigation\n\n---\n\n## Screen 6: Auto-Hide Left — FILESYSTEM Pinned with Overlay Open\n\n**Purpose**: Show left auto-hide strip with FILESYSTEM panel overlay.\n\n**Expected appearance**:\n\n- Thin vertical strip (~28px) on the left edge with vertical text \"FILESYSTEM\"\n- Strip is TILED beside GL (not overlaying) — GL content starts after the strip\n- Overlay panel slides in from left showing the FILESYSTEM file tree\n- File tree shows `source folders > codetracer > test-programs > py_console_logs > main.py`\n- \"Unpin\" button at top-right of overlay\n- Overlay content is LIVE (real file tree, not placeholder)\n\n---\n\n## Screen 7: Multi-Tab Mode — Two Traces Loaded\n\n**Purpose**: Show the session tab bar with multiple traces.\n\n**Expected appearance**:\n\n- Session tab bar visible ABOVE the GL panels (between toolbar and GL)\n- Two tabs: first trace name (e.g., \"py_console_logs/main.py\"), second tab (e.g., \"Trace 2\")\n- Active tab highlighted with different background\n- \"+\" button at the right end to add new trace\n- GL layout below shows the active trace's panels\n- All panels show data from the ACTIVE trace\n\n---\n\n## Screen 8: DeepReview Standard Layout\n\n**Purpose**: Show DeepReview mode using the standard CodeTracer GL layout with changed files.\n\n**Expected appearance (per DeepReview-GUI.md spec)**:\n\n- FILESYSTEM panel shows changed files with diff badges: M main.rs (+8/-3), A utils.rs (+8/-0), D config.rs (+0/-7)\n- Colors: M=orange, A=green, D=red\n- Editor area shows the first file's content with diff decorations (green lines for additions)\n- All standard panels present: STATE, CALLTRACE, EVENT LOG, etc.\n- **Must look like the normal CodeTracer layout** (Screen 1) with only the FILESYSTEM content changed and diff decorations in the editor\n- NO separate \"DeepReview\" panel or monolithic component\n\n**Comparison**: The reviewer should compare this against Screen 1 (normal layout) and verify that ONLY the FILESYSTEM content and editor decorations changed — everything else is identical.\n\n---\n\n## Evaluation Criteria (applied to ALL screens)\n\n1. **Full-width**: Panels must fill the entire window width. NO gray empty areas.\n2. **Dark theme**: Background #1e1e1e, panels #252526, borders #3c3c3c, text #cccccc\n3. **Font consistency**: Monospace for code/output, system sans-serif for UI labels\n4. **Professional polish**: Looks like VS Code / JetBrains, not a prototype\n5. **Auto-hide overlays**: Flush with window edge, full-width for bottom, full-height for sides\n6. **Status bar**: Always visible at bottom with auto-hide labels (BUILD, PROBLEMS, SEARCH RESULTS)\n7. **No broken elements**: No overlapping text, no clipped content, no invisible elements\n\n**Rating scale**: 1-3 broken, 4-5 rough, 6-7 good, 8-9 near-shipping, 10 perfect\n**Target**: All screens must reach 7/10 minimum.\n","docs/system.md":"\n\n## system\n\nUI\n==\n\nUI is important.\n\nWe have most of our code in `ui/`.\n`ui_js.nim` is the main file.\nWe define the root view.\n\nMost of the components are defined in their own modules:\n\n* `calltrace` the calltrace, expanding and collapse\n* `chronology` the chronology and input\n* `colors` some constants\n* `debug` the debug toolbar\n* `editor` the main editor, uses Monaco\n* `events` support coloring the output code as in terminal\n* `flow` the preload ui\n* `history` the history ui which reuses the value ui\n* `inline_editor` uses monaco, the editor open for traces\n* `layout` the overall layout\n* `loading` the loading screen\n* `start` would be useful as default screen\n* `state` the state view with changing variables\n* `trace` the trace view: now we show traces inline, so maybe remove\n* `ui_imports` exports most dependencies for ui\n* `value` reused by views that show values or expand them\n\nImportant stuff:\n\n* Use direct style helpers for generated DOM and stylus for css files\n* You can watch debug output in the console\n* Monaco, datatables and charts have a custom DOM integration\n* Layouts can be loaded from files: look at `config.nim`, we have to fix this\n* We have themes: defined by variables in name_theme.styl\n* Redraw needs to be manual sometimes, especially after IPC listeners or direct DOM integrations\n* A lot of the helper code is in `types.nim`(types) or `lib.nim` (signatures for third party or our helpers)\n* We use `view` in the name of views to easily spot them, normal functions don't need it\n* When we're changing css, it's best to change the current code: remove literals and define them in defaults and theme styles, we might get the designer to color pick better colors and new themes\n* We use vex-js for dialogs\n* Please check id-s and classes if you remove them: we might need them for ui testing\n* test_base includes most of the logic for ui testing, we use spectron\n\nEvents\n\nYou define a callback in renderer and you update state.\nMost of our state is in the `data` global. It can certainly be optimized.\nWe maintain our panel in `sys`.\n\nWhen you need to talk with the server, you send a message using `ipc.send`.\nWe apply the \"CODETRACER::\" namespace. In a browser this is a socket message, in\nElectron we send it to the main process.\nThe main process responds, and usually you register a listener with ipcConfigure.\n\nYou can also define an async function which makes a promise which is resolved after a listener is called.\n\n\n\nTesting\n\n==\n\nWe have to fix the tests.\n\nHowever let's look at the three main sets:\n\n```bash\nexample-based/ nim.cfg programs/ quicktests/ README.md reproductions/ run/ Tupfile\n```\n\nIn `example-based` we have normal tests.\n\nIn `quicktests` we have property tests. Their results are sometimes added to `reproductions`.\n\nIn `run` we store the compiled tests.\n\nIn `programs` we have the example programs.\n\nWe also have tests for python commands: but I must find them, probably git.\n\nThis is an old note:\n\n```\ntests/quicktests/\n reproductions/\n quicktest_basename/\n repr_id.json\n\n failing tests that we eventually fixed\n random subset of succeeding tests\n\n make sure that stuff that worked before, still works\n and that stuff that is fixed is still fixed\n```\n\nEach test folder has lang tests. They are often similar, so I am not sure if we need to parametrize them.\nWe define most of the main logic in test_base.\n\nWe also have `nim-ui` in `example-based` and `quicktests`.\nThey are based on Spectron.\n\nThey use a dsl, so you don't need to always access elements manually.\nIf you need to, please write a helper which can be reused.\n\n==\n\nDebugger\n\n==\n\nWe are working with rr here. RR provides most of our low level functionality.\n\nWe use gdb-js, a custom fork of the original repo with minor differences: several helpers.\n\nMost of the code is in `debugger/`\n\nThe base types are either in `types` and `core` usually.\n\nWe have a `Pool` which is currently only one.\nA `Pool` has a list of `Process` which are currently rr instances.\nBy default, we have a `stable` process which runs most of the usual steps.\nA `trace` process which runs trace debug, a `history` process which runs history search.\nA `preload` process which preloads future values and `args_preload` which preloads args.\nWe also have `prestart` process which starts in the beginning and loads chronology: mostly writes and reads for now.\n\nLet's take a look:\n\n* `args_preloader` defines `loadCallTraceArgs` which loads args\n* `core` contains shared logic and types for the debugger\n* `debugger` is the central module\n* `flow_preloader` defines the preloading code\n* `history` defines the history code\n* `move` runs most of the jumps\n* `process_gdb` is where most of our helpers and other shortcuts live\n* `py_command` is a wrapper around our python commands giving a type safe API\n* `scheduler` was an experiment in mirroring stable steps in preload\n* `sync_preload` is used to sync the preload process to the stable process\n\nWe also have `cgdb` which should eventually deal with gdb as a pure nim solution and give as a way to rewrite debugger with the C backend.\n\nBasically we define a pool in the beginning and the server sends initial data to it.\nAfter that the server starts the pre-start process which loads info while running the program\nand starts the other needed processes.\n\nThe stable process jumps to main and calls back the server so the ui can show the main program.\n\nWe have a listener for gdb events and use a system of JavaScript promises to await actions.\nThe problem is that an action usually ends before the info of the new location arrives, so we have our own\nhelpers in process_gdb which we should use.\n\nThe other bizarre part is the export api: it defines with a macro the debugger interface and generates export code for it. We expose a type to other modules, so they can call our functions in a type safe way.\nThe debugger module can be used directly (import) or in a different process. The second thing is usually better, as\nit can crash or block the main process.\n\nIt communicates using helpers and ipc send. This is also complicated internally as on desktop it uses electron, and on server `node-ipc` mapping the calls (probably).\n\nWe have some helpers to report errors and to load stuff from the server.\nA lot of the moves are basically taking arguments from the server , invoking typed functions which implement the logic\nand call python commands as primitives. Some actions periodically update the server , e.g. preloading.\n\nArgs preloading is a bit hard to optimize for bigger programs, so we have to work a bit on it: it visits all the call children of the current call and logs the args.\n\nFlow preloading can be slow: most of the logic is in Python commands. We try to limit the number of steps taken there\nand repeatedly call it , sending updates to the server until we are stopped by a new preloading context or finished.\n\nWe cache a lot of stuff like preload results, AST etc. Some of the caches are on function-level, some on filename-level etc.\n\nA lot of the logic is in Python commands: usually if something needs to use a series of gdb commands or to analyze in a more powerful way the program , we create a command, it's best if it is general enough to be reused in many actions.\n\nParsing the modules is good for preloading: we load the labels for each line.\n\nOverall\n==\n\n\nElectron:\n\nWe have several components.\n\nThe backend, the archive runner, the archive server, the shell support, codetracer, plugins, the commands, language forks, the server, the renderer and the debugger.\n\n\nCodetracer calls the server, a local database and Redis.\n\nThe server is the main Electron process which dispatches tasks and messages to the renderer and the debugger.\n\nIt also maintains a running plugin for the current language and communicates on stdout with json.\nIt communicates on the stdout with `nimsuggest` when in a Nim project too: we have to test if this is working now.\n\nThe plugins can parse expressions and modules: expressions are parsed as QueryNode which can be interpreted by our debugger, the modules as a language-unified AST.\n\nThe QueryNode-s are interpreted with the class Loader. We visit the nodes and map each one to a gdb expression, which most of the time accesses some kind of variable or a call which can start a rr fork.\n\nThe server currently assumes it has only one renderer. We have to parametrize it.\n\nNow, we map the messages to ipc on desktop and sockets in browser.\n\nThe renderer just talks with the server in all scenarios, for now we assume it's always a single project in a renderer.\n\nThe debugger also connects to the server for additional functionality: e.g. plugin call.\nIt maintains a sequence of RR debuggers with sockets and communicates with them using gdb-js either directly or with commands.\n\nThe python commands are loaded when the debugger starts: we also reuse the CPython gdb commands for Python.\nThey are executed only in a single RR process.\n\nThe telemetry is used for logging by me most of the time: it logs to the screen and in a file. In most of the code you can log using `event` or other shortcuts in `telemetry`. You can turn it off or on in `.config.yaml`, you can eventually share a structured log in `telemetry.log`. We probably can use nim-chronicles, but it has to be flexible enough and work on the JavaScript backend.\n\n\nPlugin communicator\n==\n\nPlugins are supposed to analyze language-specific things using the language tools.\nFor Nim, we just import the compiler.\nFor C++, currently we parse clang's dump output: we have to write a plugin in C++ which actually analyzes the AST, but I had some problems with the parser API: TODO.\n","AGENTS.md":"# Instructions for Codex\n\n## Where a checkout — or a worktree — has to live\n\n**A checkout of this repo must sit DIRECTLY under the workspace root, beside its\nsibling repos.** A `git worktree` is a checkout and this rule is not relaxed for\nit: put worktrees at `/`, never at `/.agent-wt/`\nor in any other subdirectory, and never outside the workspace.\n\n```\n/path/to/workspace/ # the workspace root\n codetracer/ # the main checkout\n my-feature/ # CORRECT — a worktree, beside the siblings\n isonim/ runquota/ nim-agents/ codetracer-trace-format/ ...\n .agent-wt/\n my-feature/ # WRONG — its parent is `.agent-wt`, which has no siblings\n```\n\nThe reason is that **the parent directory of the checkout IS the workspace root,\nby definition**, for four independent resolvers that reach siblings by the\nrelative path `../`:\n\n| resolver | where | how it fails from the wrong place |\n| --- | --- | --- |\n| Nim | `config.nims` (`repoRoot.parentDir()`), `src/Tuprules.tup` (`$(ROOT)/../…`) | `--path` to a missing dir is silently ignored → `cannot open file: runquota_process`, minutes in |\n| Cargo | `src/db-backend/Cargo.toml` (`path = \"../../../codetracer-trace-format/…\"`) | `failed to load manifest` |\n| cc | `src/db-backend/build.rs` (`../../../codetracer-native-recorder/ct_emulator`) | 81 undefined `mcr*` symbols at link |\n| Repro/Nix | `repro.nim` and native workspace input overrides (`../io-mon`, `../reprobuild`, …) | sibling overrides cannot be resolved |\n\nNone of the four can be pointed elsewhere per-worktree, so relocating the\ncheckout is the only fix. In particular **`runquota` has no override at all** by\ndesign — see the tier notes in `scripts/require-siblings.sh` — so no environment\nvariable can paper over a badly-placed worktree.\n\nCreate one like this, from the main checkout:\n\n```bash\ngit -C /path/to/workspace/codetracer worktree add /path/to/workspace/ \n```\n\nand move a misplaced one like this:\n\n```bash\ngit worktree move /path/to/workspace/.agent-wt/ /path/to/workspace/\n```\n\n`scripts/require-siblings.sh` runs before every build (`just build-once`,\n`just build`, `just test-gui`, …) and refuses a badly-placed checkout by name.\n**Do not answer it with `CODETRACER_SKIP_SIBLING_CHECK=1`**: that escape hatch is\nfor genuinely different layouts (vendored trees, Nix builds that pre-stage the\npaths). Used here it only removes the message — the build still cannot see the\nsiblings and dies later naming a *module* instead of the real problem.\n\n## Building the full frontend (Nim + Electron)\n\nTo rebuild the full CodeTracer frontend (Nim backend CLI, Nim renderer JS, webpack bundles):\n\n```\njust build-once\n```\n\nThis runs tup (incremental build) and webpack. Use this after modifying any `.nim` files in\n`src/ct/`, `src/frontend/`, or `src/common/`.\n\n## Building the db-backend\n\n```\n# inside src/db-backend\ncargo build\n```\n\n## Running tests\n\n```\n# inside src/db-backend\ncargo test\n```\n\n## Running the linter\n\n```\n# inside src/db-backend\ncargo clippy\n```\n\nDon't disable the lint: try to fix the code instead first!\n\n## Running Playwright e2e tests\n\n```\n# From the repo root (needs Xvfb or a display)\njust test-e2e\n```\n\nThe Playwright tests live in `tsc-ui-tests/`. They launch the real Electron app via the `ct`\nbinary at `src/build-debug/bin/ct`. If you modify frontend Nim code, run `just build-once`\nfirst to rebuild the frontend before running the tests.\n\n## Running the cross-language ct_test provider tests\n\n```\n# From inside the dev shell (provides nim + the gtest/catch2/cmake/ninja\n# toolchain and the CMAKE_PREFIX_PATH / CT_TEST_C{C,XX} the C/C++ providers need)\njust test-ct-providers\n```\n\nThis runs the cross-language `ct_test` provider suites (C/C++ GoogleTest/Catch2/CTest, M11\nnative, M12 fallback, JavaScript, Ruby) plus the framework gate tests. It first builds the\nnative (`ct-mcr`), JavaScript and Ruby recorder siblings in their own pinned dev shells\n(`repro exec -- just build`, via `scripts/build-siblings.sh`) so the recording tests run\nagainst real recorders; a missing or failed required sibling fails loudly rather than skipping\n(per `codetracer-specs/Working-with-the-CodeTracer-Repos.md` Part 2). Useful overrides:\n\n- `CT_PROVIDERS_SKIP_SIBLINGS=1` — reuse already-built recorders, skip the sibling build step.\n- `CT_PROVIDERS_ALLOW_MISSING=1` — run the suites even if a required recorder sibling is\n missing/unbuildable (the recording tests then fail honestly instead of aborting up front).\n\nThe recorder binaries are discovered via PATH / the documented env vars\n(`CODETRACER_CT_MCR_CMD`, `CODETRACER_JS_RECORDER_PATH`, `CODETRACER_RUBY_RECORDER_PATH`) by\n`scripts/detect-siblings.sh`. See `ci/test/ct-providers.sh`.\n\n## Windows local setup (non-Nix)\n\nFor Windows development (both x64 and ARM64), use the DIY bootstrap:\n\n### Activate environment (auto-installs tools on first run)\n```bash\n# Git Bash / MSYS2\nsource env.sh\n\n# PowerShell\n. .\\env.ps1\n```\n\n### Optional skip flags\nComponents can be skipped via environment variables (e.g. for satellite repos\nthat only need a subset):\n- `WINDOWS_DIY_SKIP_NARGO=1` — skip Noir compiler\n- `WINDOWS_DIY_SKIP_CT_REMOTE=1` — skip ct-remote desktop client\n- `WINDOWS_DIY_ENSURE_TTD=0` — skip TTD/WinDbg validation\n\n### Build commands (Windows)\n```bash\n# Rust components\ncd src/db-backend && cargo build && cargo test && cargo clippy\ncd src/tui && cargo build && cargo test\ncd src/backend-manager && cargo build\n\n# Full frontend (Nim + Tup)\ncd src/build-debug && source ../../env.sh && tup upd\n```\n\n### Version pins\nPinned tool versions are tracked in:\n```\nnon-nix-build/windows/toolchain-versions.env\n```\n\nFor detailed Windows porting progress, see `windows-porting-initiative-status.md`.\n\n## Nix dev shell and local flake overrides\n\nThe Repro shell hook activates the flake through `repro.nim`. Run `repro allow`\nonce for this checkout, then enter it with the hook installed. For an explicit\ncommand, use `repro exec /path/to/codetracer -- `.\n\nRepro resolves declared workspace siblings as native flake input overrides.\nKeep direnv denied; `.envrc` and the old override plugin are not required for\nthis activation path. Changes to the recipe require renewed Repro authorization.\n\n### Blockchain recorder tools (circom, forc)\n\nThe Nix dev shell supplies the toolchains declared by the CodeTracer flake.\nBuild recorder siblings through `scripts/build-siblings.sh`; each recorder's\n`repro.nim` activates its own pinned environment. See the helper's per-repository\nlogs when a required tool or sibling build fails.\n\n### Inspecting a Nix environment directly\n\nTo diagnose an individual flake input independently of shell activation, use an\nexplicit Nix invocation without changing direnv trust:\n\n```bash\nnix develop '.?submodules=1' --override-input nix-blockchain-development path:../nix-blockchain-development -c bash\n```\n\n### Cadence Go helper\n\nThe `detect-siblings.sh` script auto-builds `cadence-trace-helper` from\n`codetracer-flow-recorder/go-helper/` when the flow recorder sibling is\npresent and `go` is available. The built binary is exported via\n`CADENCE_HELPER_BIN` and added to PATH.\n\n# Keeping notes\n\nIn the `.agents/codebase-insights.txt` file, we try to maintain useful tips that may help\nyou in your development tasks. When you discover something important or surprising about\nthe codebase, add a remark in a comment near the relevant code or in the codebase-insights\nfile. ALWAYS remove older remarks if they are no longer true.\n\nYou can consult this file before starting your coding tasks.\n\n# Code quality guidelines\n\n- ALWAYS strive to achieve high code quality.\n- ALWAYS write secure code.\n- ALWAYS make sure the code is well tested and edge cases are covered. Design the code for testability and be extremely thorough.\n- ALWAYS write defensive code and make sure all potential errors are handled.\n- ALWAYS strive to write highly reusable code with routines that have high fan in and low fan out.\n- ALWAYS keep the code DRY.\n- Aim for low coupling and high cohesion. Encapsulate and hide implementation details.\n- When creating executable, ALWAYS make sure the functionality can also be used as a library.\n To achieve this, avoid global variables, raise/return errors instead of terminating the program, and think whether the use case of the library requires more control over logging\n and metrics from the application that integrates the library.\n\n# Code commenting guidelines\n\n- Document public APIs and complex modules using standard code documentation conventions.\n- Comment the intention behind your code extensively. Omit comments only for very obvious\n facts that almost any developer would know.\n- Maintain the comments together with the code to keep them meaningful and current.\n- When the code is based on specific formats, standards or well-specified behavior of\n other software, always make sure to include relevant links (URLs) that provide the\n necessary technical details.\n\n# Writing git commit messages\n\n- You MUST use multiline git commit messages.\n- Use the conventional commits style for the first line of the commit message.\n- Use the summary section of your final response as the remaining lines in the commit message.\n","tools/visual-review/briefs/storybook-build-panel.md":"# Build Panel Story Visual Brief\n\n## What You're Reviewing\n\nThis is the CodeTracer Build panel rendered in Storybook through the real\nIsoNim Build view.\n\nShared project brief: `../project-visual-brief.md`\n\n## Screen\n\n- Route: Storybook iframe story `codetracer-panels--build`\n- Capture id: `storybook-build-panel`\n- Viewport: laptop, 1440x900\n\n## Seeded State\n\nThe fixture shows a failed `nargo test` build with stdout, stderr, and parsed\nproblem rows.\n\n## Expected Visible Content\n\n- Dark CodeTracer app background and app font styling.\n- Build header/status controls styled like the app.\n- Compiler output lines with error/warning colors.\n- Clickable source-location styling for `src/combat.nr:42`.\n\n## Must Not Show\n\n- Unstyled default buttons or form controls.\n- Missing CodeTracer color palette.\n- Text overlapping the header controls.\n- A bare list of lines with no panel structure.\n\n## What to Evaluate\n\nFocus on whether the app CSS is matching the real DOM, and whether the panel\nlooks like a real CodeTracer bottom/side panel rather than a mock.\n\n## How to Report\n\nKeep under 200 words. Lead with an overall impression, list specific visual\nissues, then give the top two fixes. Include a 1-10 rating.\n","tools/visual-review/briefs/storybook-default-layout.md":"# Default Layout Story Visual Brief\n\n## What You're Reviewing\n\nThis is the Storybook default IsoNim app-shell layout story. It exercises\nmultiple real panel views together in the standalone IsoNim shell.\n\nShared project brief: `../project-visual-brief.md`\n\n## Screen\n\n- Route: Storybook iframe story `codetracer-layouts--default-debug`\n- Capture id: `storybook-default-layout`\n- Viewport: laptop, 1440x900\n\n## Seeded State\n\nThe fixture includes a Karax-reference-shaped Golden Layout debugging workspace\nwith Filesystem, Editor, State/Scratchpad, Calltrace/Agent Activity, and Event\nLog/Terminal Output stacks. Visible panels are real IsoNim views; inactive tabs\nshould remain present in the DOM but hidden like the Karax reference.\n\n## Expected Visible Content\n\n- Dark CodeTracer app styling loaded in the iframe.\n- Golden Layout panel headers, grouped tabs, splitters, and content cells should\n be visible.\n- Multiple real IsoNim panels should look like CodeTracer surfaces, not browser defaults.\n- The layout should use the Karax shell framing: dark body, top-offset\n root-container, `#ROOT`, empty `#main`, and GoldenLayout immediately under\n `#ROOT`.\n\n## Must Not Show\n\n- Blank screen.\n- White background or generic Storybook styling dominating the view.\n- Panels clipped to unusably small fragments.\n- Missing CSS resources or broken image icons.\n\n## What to Evaluate\n\nEvaluate shell context, spacing, panel sizing, typography, color, and whether\nthe surface is useful for visual parity work.\n\n## How to Report\n\nKeep under 200 words. Lead with an overall impression, list specific visual\nissues, then give the top two fixes. Include a 1-10 rating.\n","tools/visual-review/briefs/storybook-terminal-output.md":"# Terminal Output Story Visual Brief\n\n## What You're Reviewing\n\nThis is the CodeTracer Terminal Output panel rendered in Storybook through the\nreal IsoNim Terminal Output view.\n\nShared project brief: `../project-visual-brief.md`\n\n## Screen\n\n- Route: Storybook iframe story `codetracer-panels--terminal-output`\n- Capture id: `storybook-terminal-output`\n- Viewport: laptop, 1440x900\n\n## Seeded State\n\nThe fixture shows the Noir space-ship replay terminal transcript from the\nKarax terminal-visible reference. All lines are ahead of the current replay\nposition, matching the reference state.\n\n## Expected Visible Content\n\n- Dark CodeTracer app background and app font styling.\n- Terminal output panel with CodeTracer terminal row styling.\n- Dense terminal output including \"Positive Test Case\", shield status rows,\n and the final \"shields will not hold as expected\" line.\n- Future terminal fragments should use the same dimmed terminal row styling as\n the Karax reference.\n\n## Must Not Show\n\n- Generic browser serif fonts.\n- White Storybook or Bootstrap default panel background.\n- A tiny unstyled text block floating in empty space.\n- Missing app CSS or broken icon/resource requests.\n\n## What to Evaluate\n\nCheck whether app styles are actually applied, whether the panel sits in a\nCodeTracer-like shell context, and whether spacing, typography, contrast, and\nvisual hierarchy look like the real app.\n\n## How to Report\n\nKeep under 200 words. Lead with an overall impression, list specific visual\nissues, then give the top two fixes. Include a 1-10 rating.\n","tools/visual-review/reference-coverage.md":"# Storybook Reference Coverage\n\n\n\n\nThis file tracks Karax reference captures used for IsoNim visual parity work.\nGenerated screenshots, HTML dumps, and computed-style dumps are intentionally\nkept out of this repository; the rows below point to the local reference\nworktree artifacts that agents should compare against.\n\nPaths are given relative to the reference-dump root, written below as\n`$CT_REFERENCE_DUMPS`. It defaults to `ui-tests/reference-dumps/` inside the\ncheckout and can be pointed at a local capture worktree instead — the same\nvariable `src/tests/gui/tests/session-chrome/new-trace-caption-chrome.spec.ts`\nreads. The captures themselves are not distributed with the repository, so an\nunset root simply means the reference-fact diagnostics stay empty.\n\n## Reference Sets\n\n- Full default/scratchpad/terminal baseline:\n `$CT_REFERENCE_DUMPS/isonim-karax-reference-20260504T155511Z/`\n- Expanded panel baseline:\n `$CT_REFERENCE_DUMPS/isonim-karax-reference-20260504T220906Z/`\n- Expanded panel baseline with isolated layout config:\n `$CT_REFERENCE_DUMPS/isonim-karax-reference-20260504T222307Z/`\n\nSome old Karax panels were less developed than current IsoNim surfaces. Use\nthese references for mature shell, Golden Layout, design-system class, and\nspacing contracts. Do not downgrade richer current IsoNim behavior to match an\nold empty, blocked, or partial Karax state.\n\n## Current Storybook Audit\n\nLast audited: 2026-05-05 on `codetracer-viewmodel`.\n\nCurrent Storybook views are discovered with:\n\n```sh\nnix shell nixpkgs#nodejs --command node tools/visual-review/capture-storybook.mjs --list-views --no-build\n```\n\nThe generated list includes all real IsoNim panel stories exported through\n`mountCodeTracerStory`, plus structure stories for session tabs, menu/status\nshells, debug shell, auto-hide controls, and default/app-shell layouts. The\ncapture tool also exposes source-slug aliases for `deepreview` and\n`agent-activity-deepreview`, in addition to Storybook's display-name slugs\n`deep-review` and `agent-activity-deep-review`; `status` aliases the\n`status-shell` component story.\n\nRepresentative partial/missing-reference surfaces were captured successfully at\n`laptop` size on 2026-05-05:\n\n| Surface | Current Storybook view | Current status |\n| --- | --- | --- |\n| Point list | `point-list` | confirmed current IsoNim panel, `tools/visual-review/reports/point-list-laptop.json` |\n| Timeline | `timeline` | confirmed current IsoNim panel, `tools/visual-review/reports/timeline-laptop.json` |\n| Flow | `flow` | confirmed current IsoNim panel with populated steps, `tools/visual-review/reports/flow-laptop.json` |\n| VCS | `vcs` | confirmed current IsoNim panel, `tools/visual-review/reports/vcs-laptop.json` |\n| Request panel | `request-panel` | confirmed current IsoNim panel, `tools/visual-review/reports/request-panel-laptop.json` |\n| Build errors | `errors` | confirmed current IsoNim problems/build-errors panel, `tools/visual-review/reports/errors-laptop.json`; `noir-build-open` also confirms the panel tab in a default layout |\n| Deep review panel | `deepreview` | confirmed current IsoNim panel, `tools/visual-review/reports/deepreview-laptop.json` |\n| Agent activity deep review | `agent-activity-deepreview` | confirmed current IsoNim panel, `tools/visual-review/reports/agent-activity-deepreview-laptop.json` |\n| Auto-hide bottom strip | `auto-hide-bottom-strip` | confirmed current IsoNim component, `tools/visual-review/reports/auto-hide-bottom-strip-laptop.json` |\n| Auto-hide collapsed icons | `auto-hide-collapsed-icons` | confirmed current IsoNim component, `tools/visual-review/reports/auto-hide-collapsed-icons-laptop.json` |\n| Auto-hide overlay tabs | `auto-hide-overlay-tabs` | confirmed current IsoNim component, `tools/visual-review/reports/auto-hide-overlay-tabs-laptop.json` |\n| Auto-hide side strip | `auto-hide-side-strip` and `auto-hide-side-strip-collapsed` | confirmed populated and collapsed current IsoNim variants |\n| Session tabs | `session-tabs` | confirmed current IsoNim component, `tools/visual-review/reports/session-tabs-laptop.json` |\n| Default layout variants | `default-layout`, `standalone-app-shell`, `noir-filesystem-active`, `noir-state-active`, `noir-calltrace-active`, `noir-calltrace-search-status-report`, `noir-menu-view-open`, `noir-status-expanded` | confirmed current layout stories; use a non-default `--port` if another static server is already bound to `6106` |\n\nCurrent confirmation does not change the old reference status below. Rows marked\n`blocked`, `partial`, or `missing` still mean the old Karax reference capture is\nblocked, partial, or absent; the current IsoNim story can still be valid and\ncapturable.\n\nLatest mature-state screenshot delta report:\n`tools/visual-review/mature-karax-visual-delta-20260505.md`.\n\n## Coverage Matrix\n\n| Surface | Reference status | Reference capture |\n| --- | --- | --- |\n| Default layout | captured | `20260504T160311Z_noir-electron-rendered` |\n| Scratchpad visible | captured | `20260504T160414Z_noir-scratchpad-visible` |\n| Terminal visible | captured | `20260504T160434Z_noir-terminal-visible` |\n| Filesystem active | captured | `20260504T220916Z_noir-filesystem-active` |\n| State active | captured | `20260504T220918Z_noir-state-active` |\n| Calltrace active | captured | `20260504T220919Z_noir-calltrace-active` |\n| Calltrace search status | captured | `20260504T220922Z_noir-calltrace-search-status-report` |\n| Agent activity active | captured | `20260504T220923Z_noir-agent-activity-active` |\n| Menu open | captured | `20260504T220925Z_noir-menu-view-open` |\n| Status expanded | captured | `20260504T220927Z_noir-status-expanded` |\n| Search results | captured | `20260504T222338Z_noir-search-results-karax-populated`; preserve newer IsoNim functionality if richer |\n| Fixed search | captured | `20260504T222336Z_noir-fixed-search-karax-visible` |\n| Point list | blocked | `20260504T220950Z_noir-point-list-open`; Karax raised unexpected `PointList` content |\n| Step list | captured | `20260504T220952Z_noir-step-list-open` |\n| Timeline | blocked | `20260504T222349Z_noir-timeline-blocked-no-factory`; Karax lacked a usable component factory |\n| Trace log | captured | `20260504T222329Z_noir-trace-log-karax-open` |\n| Build | captured | `20260504T222317Z_noir-build-karax-open`; preserve newer IsoNim output behavior if richer |\n| Build errors | partial | `20260504T222538Z_noir-build-errors-karax-open-attached` and `20260504T222734Z_noir-build-errors-karax-direct-id0`; Karax content stayed empty |\n| Shell | captured | `20260504T221002Z_noir-shell-open` |\n| REPL | captured | `20260504T222331Z_noir-repl-karax-open` |\n| Low-level code | captured | `20260504T222333Z_noir-low-level-code-karax-open` |\n| No source | captured | `20260504T222334Z_noir-no-source-karax-open` |\n| Command palette | captured | `20260504T222339Z_noir-command-palette-karax-open` |\n| Debug controls/header | captured | `20260504T222314Z_noir-debug-controls-header` |\n| Agent workspace | captured | `20260504T222341Z_noir-agent-workspace-karax-open`; preserve newer IsoNim behavior if richer |\n| Agent activity deep review | captured | `20260504T222342Z_noir-agent-activity-deepreview-karax-open`; preserve newer IsoNim behavior if richer |\n| Deep review panel | partial | `20260504T222344Z_noir-deepreview-panel-karax-open-empty` and `20260504T222427Z_deepreview-standalone-karax-sample`; old Karax state was underdeveloped |\n| Flow | partial | `20260504T222348Z_noir-flow-select-attempt`; old frontend raised missing `ct/load-flow` response-kind handling |\n| VCS | missing | No old panel implementation found |\n| Request panel | missing | No old panel implementation found |\n| Welcome screen | captured | `20260504T221201Z_welcome-screen` |\n\n## Current Workflow\n\n1. Capture current Storybook for a matching story with\n `tools/visual-review/capture-storybook.mjs --view --size laptop`.\n Use repeated `--view` flags or `--views a,b,c` for batch captures. If the\n default port is occupied, pass `--port `.\n2. Compare HTML and computed-style dumps against the reference capture with the\n same surface name.\n3. Compare screenshots with `tools/visual-review/compare-screenshots.sh` when\n the reference capture is marked `captured`.\n4. Patch the real IsoNim view/style/story shell, not a parallel mock.\n5. Update this matrix when new reference captures become available.\n"},"files":{"tools/visual-review/mature-karax-visual-delta-20260505.md":"# Mature Karax Visual Delta Report - 2026-05-05\n\n\n\nBranch: `codetracer-viewmodel`\n\n## Method\n\n- Storybook was rebuilt with\n `nix shell nixpkgs#nodejs --command bash -lc 'just storybook-build'`.\n- Current Storybook stories were captured with\n `tools/visual-review/capture-storybook.mjs`.\n- `wide` (`1920x1080`) was used for Karax references captured at `1920x1080`.\n- `laptop` (`1440x900`) was used for the older full-page Karax references\n captured as `2161x3766`; those metrics are useful for trend tracking but are\n dominated by viewport/full-page framing.\n- Screenshot metrics were generated with `tools/visual-review/compare-screenshots.sh`,\n which resizes the reference image to the current capture before computing RMSE/MAE.\n- Generated captures, dumps, and diff images remain ignored under\n `tools/visual-review/{screenshots,reports,compare,dumps}`.\n\n## Summary\n\nThe mature Karax states now have matching capturable Storybook stories. The\nclosest comparisons are the `1920x1080` default Noir layout variants: their\nlargest remaining deltas are mostly intentional richer IsoNim content, not empty\nor broken rendering. The older full-page references and panel-only current\nstories are documented separately because their RMSE/MAE numbers are dominated\nby app-frame and viewport mismatch.\n\nNo small shell/chrome/CSS fix was applied in this pass; the visible differences\nthat remain would require either new full-layout stories for panel-only states or\ndeliberate content downgrades, which this audit avoided.\n\n## Per-Surface Results\n\n| Surface | Current story | Viewport | RMSE | MAE | Status |\n| --- | --- | --- | ---: | ---: | --- |\n| Default layout | `default-layout` | laptop | 0.148885 | 0.056060 | Framing-dominated; current shell is populated and richer. |\n| Terminal | `terminal-output` | laptop | 0.098892 | 0.028241 | Panel story vs full-layout Karax terminal state; metric is directional only. |\n| Scratchpad | `scratchpad` | laptop | 0.098082 | 0.029454 | Panel story vs full-layout Karax scratchpad state; metric is directional only. |\n| Filesystem active | `noir-filesystem-active` | wide | 0.100905 | 0.025215 | Good app-frame match; richer editor/calltrace/event rows dominate. |\n| State active | `noir-state-active` | wide | 0.100905 | 0.025215 | Same base Karax/current pixels as filesystem active; focus change is not visibly distinct. |\n| Calltrace active | `noir-calltrace-active` | wide | 0.100905 | 0.025215 | Same base Karax/current pixels as filesystem active; richer calltrace text dominates. |\n| Calltrace search/status | `noir-calltrace-search-status-report` | wide | 0.106128 | 0.026938 | Good app-frame match; current calltrace/search content is denser. |\n| Menu open | `noir-menu-view-open` | wide | 0.074298 | 0.018578 | Good app-frame match; menu/status shell differences are localized. |\n| Status expanded | `noir-status-expanded` | wide | 0.072659 | 0.018013 | Best layout match in this batch; status and agent panel richness remain. |\n| Fixed search | `noir-fixed-search-visible` | laptop | 0.168908 | 0.057116 | Full-page reference mismatch; current search shell is richer. |\n| Search results | `noir-search-results-populated` | laptop | 0.170998 | 0.060999 | Full-page reference mismatch plus richer current search result content. |\n| Command palette | `noir-command-palette-open` | laptop | 0.094881 | 0.058993 | Full-page reference mismatch; overlay shape/content comparable. |\n| Build | `noir-build-open` | laptop | 0.134460 | 0.048930 | Full-page reference mismatch; current build output behavior is richer. |\n| Trace log | `noir-trace-log-open` | laptop | 0.123995 | 0.041831 | Full-page reference mismatch; table density/content differs intentionally. |\n| Debug controls/header | `noir-debug-controls-header` | laptop | 0.148460 | 0.055652 | Full-page reference mismatch; header chrome is comparable. |\n| Shell | `shell` | wide | 0.079896 | 0.037638 | Panel story vs full-layout Karax shell state; metric is not a parity signal. |\n| REPL | `repl` | laptop | 0.073845 | 0.032278 | Panel story vs full-layout Karax REPL state; metric is directional only. |\n| Low-level code | `low-level-code` | laptop | 0.073199 | 0.030190 | Panel story vs full-layout Karax low-level state; metric is directional only. |\n| No source | `no-source` | laptop | 0.092624 | 0.020209 | Panel story vs full-layout Karax no-source state; metric is directional only. |\n| Welcome | `welcome` | wide | 0.067437 | 0.011610 | Good standalone match; remaining delta is mostly typography/spacing. |\n| Step list | `step-list` | wide | 0.088317 | 0.037435 | Panel story vs full-layout Karax step-list state; metric is directional only. |\n\n## Top Remaining Deltas\n\n1. Several Karax references are full-page `2161x3766` captures while current\n Storybook is viewport-framed. These need either custom-size capture support or\n new reference captures before RMSE/MAE can be treated as parity gates.\n2. Shell, REPL, low-level, no-source, and step-list currently compare panel\n stories against full-layout Karax states. Full-layout Storybook variants would\n make these measurable in the same way as the Noir default variants.\n3. The current IsoNim default layout intentionally shows richer editor syntax,\n calltrace rows, terminal/event-log rows, and populated panel behavior. These\n content differences should not be patched back to the older Karax state.\n4. The remaining meaningful layout deltas are small chrome differences in tabs,\n status/menu treatment, scroll positions, and text wrapping rather than missing\n surfaces.\n","tools/visual-review/project-visual-brief.md":"# CodeTracer Storybook Visual Brief\n\nCodeTracer is a debugging and replay UI for inspecting recorded program\nexecution. The Storybook surfaces must render the production IsoNim DOM with\nthe same CSS and shell context as the Electron app, so isolated panel review can\ncatch visual regressions before full GUI tests.\n\nThe important rule is that Storybook may mock ViewModel data, but it must not\nmock or reimplement component DOM. Storybook stories should call the real\nIsoNim ViewModel constructors and `src/frontend/viewmodel/views/*.nim` render\nor mount functions.\n\n## Shared Design Goals\n\n- Match the dark CodeTracer Electron UI from `src/frontend/index.html`.\n- Use the app CSS from `frontend/styles/default_dark_theme_electron.css`.\n- Preserve the app shell context: `#root-container`, `#auto-hide-layout-row`,\n `#ROOT`, `.session-container`, and `#main`.\n- Panels should look like CodeTracer work surfaces, not generic Storybook\n cards.\n- Text should be legible, clipped content should be intentional, and images or\n icons should not be broken.\n\n## What Must Not Happen\n\n- Missing app CSS links in the Storybook iframe.\n- Bare unstyled HTML controls.\n- Storybook-local colors/fonts overriding CodeTracer CSS.\n- DOM mounted outside the app shell when the production selector depends on\n app-shell ancestors.\n- Broken asset URLs under `/public/resources` or `/public/third_party`.\n","tools/screen-briefs.md":"# Per-Screen Design Briefs for Visual Audit\n\nEach section describes exactly what must be visible, what data should be shown,\nand how to evaluate the screenshot against the CodeTracer design spec.\n\n---\n\n## Screen 1: Normal CodeTracer Layout (reference baseline)\n\n**Purpose**: Establish the reference baseline that all other screens are compared against.\n\n**Expected content**:\n\n- Toolbar: debugger step controls (forward, backward, continue icons)\n- Left: FILESYSTEM panel with file tree showing `source folders > codetracer > test-programs > py_console_logs > main.py`\n- Center: Editor tab `py_console_logs/main.py` with Python source code visible, line numbers, syntax highlighting (keywords in purple/blue, strings in green/orange)\n- Center-right: STATE panel showing \"Enter a watch expression\" input, SCRATCHPAD tab\n- Right: CALLTRACE panel with expandable call tree showing function names, AGENT ACTIVITY tab\n- Bottom-left: EVENT LOG panel with event rows (step index, line number, event text)\n- Bottom-right: TERMINAL OUTPUT panel with stdout/stderr output\n- Footer: Status bar with `Python(db) | UTF-8 | stable: ready | ` on the right, **BUILD | PROBLEMS | SEARCH RESULTS** labels on the right as auto-hide pane triggers\n- NO session tab bar (single trace)\n- NO gray empty areas — panels fill full window width\n\n**Evaluation**: This must look like a professional IDE. Compare against VS Code's dark theme for consistency.\n\n---\n\n## Screen 2: BUILD Auto-Hide Pane — Successful Build (happy path)\n\n**Purpose**: Show the BUILD pane expanded from the bottom with successful build output.\n\n**How to trigger**: Click the \"BUILD\" label in the status bar footer. The BUILD pane slides up as an overlay from the bottom.\n\n**Expected data to inject**:\n\n```\n$ nim c --sourcemap:on main.nim\nHint: used 42 lines of code\nHint: operation successful (0.8s)\nHint: [SuccessX]\n```\n\n**Expected appearance**:\n\n- BUILD overlay visible at bottom, full-width, ~30% window height\n- Overlay header: \"Build succeeded\" in GREEN text, with header controls (stop, clear, auto-scroll, duration \"0.8s\")\n- Build output lines in monospace font with ANSI colors rendered (green \"Hint:\" text)\n- \"Unpin\" button at top-right of overlay\n- The GL layout area above is still visible behind/above the overlay\n- Status bar \"BUILD\" label is highlighted (active state)\n\n---\n\n## Screen 3: BUILD Auto-Hide Pane — Failed Build (unhappy path)\n\n**Purpose**: Show BUILD pane with compiler errors, demonstrating error parsing and color coding.\n\n**Expected data to inject**:\n\n```\n$ cargo build\nerror[E0308]: mismatched types\n --> src/main.rs:42:5\n |\n42 | let x: bool = 42;\n | ^^ expected `bool`, found integer\n\nwarning: unused variable: `y`\n --> src/main.rs:10:9\n\nerror: aborting due to previous error\n```\n\n**Expected appearance**:\n\n- Overlay header: \"Build failed (exit code 1)\" in RED text\n- Error lines: red text (#f85149), clickable (underline on hover)\n- Warning lines: yellow text (#d29922)\n- File locations (`src/main.rs:42:5`) underlined and clickable\n- ANSI colors rendered — \"error\" in red, \"warning\" in yellow, \"-->\" in blue\n- Arrow indicators and code snippets visible in monospace\n\n---\n\n## Screen 4: PROBLEMS Auto-Hide Pane with Parsed Errors\n\n**Purpose**: Show the PROBLEMS pane with structured error list from the failed build.\n\n**Expected data**: 2 errors + 1 warning:\n\n- ERROR: src/main.rs:42:5 — \"mismatched types: expected `bool`, found integer\"\n- ERROR: src/main.rs:55:12 — \"cannot find value `undefined_var` in this scope\"\n- WARNING: src/main.rs:10:9 — \"unused variable: `y`\"\n\n**Expected appearance**:\n\n- Overlay header: \"3 problems (2 errors, 1 warning)\" with filter buttons [All] [Errors] [Warnings]\n- Error rows: red circle icon (●), file path in dim color, line:col, error message\n- Warning row: yellow triangle icon (▲), same format\n- Rows clickable with pointer cursor\n- Grouped by file if \"Group by File\" is toggled\n\n---\n\n## Screen 5: SEARCH RESULTS Auto-Hide Pane with Results\n\n**Purpose**: Show search results grouped by file with match highlighting.\n\n**Expected data**: Search for \"print\" with 4 results across 2 files:\n\n- src/main.py:10 — `def print_to_stdout() -> None:`\n- src/main.py:15 — `print(\"hello world\")`\n- src/main.py:51 — `print(\"1. print using print('text')\")`\n- src/utils.py:3 — `from io import print_function`\n\n**Expected appearance**:\n\n- Overlay header: \"4 results for 'print'\"\n- Results grouped by file: `src/main.py (3)` header, then 3 match rows\n- Then `src/utils.py (1)` header, 1 match row\n- Each row: line number on left, text with \"print\" highlighted in amber/yellow\n- Clickable rows for navigation\n\n---\n\n## Screen 6: Auto-Hide Left — FILESYSTEM Pinned with Overlay Open\n\n**Purpose**: Show left auto-hide strip with FILESYSTEM panel overlay.\n\n**Expected appearance**:\n\n- Thin vertical strip (~28px) on the left edge with vertical text \"FILESYSTEM\"\n- Strip is TILED beside GL (not overlaying) — GL content starts after the strip\n- Overlay panel slides in from left showing the FILESYSTEM file tree\n- File tree shows `source folders > codetracer > test-programs > py_console_logs > main.py`\n- \"Unpin\" button at top-right of overlay\n- Overlay content is LIVE (real file tree, not placeholder)\n\n---\n\n## Screen 7: Multi-Tab Mode — Two Traces Loaded\n\n**Purpose**: Show the session tab bar with multiple traces.\n\n**Expected appearance**:\n\n- Session tab bar visible ABOVE the GL panels (between toolbar and GL)\n- Two tabs: first trace name (e.g., \"py_console_logs/main.py\"), second tab (e.g., \"Trace 2\")\n- Active tab highlighted with different background\n- \"+\" button at the right end to add new trace\n- GL layout below shows the active trace's panels\n- All panels show data from the ACTIVE trace\n\n---\n\n## Screen 8: DeepReview Standard Layout\n\n**Purpose**: Show DeepReview mode using the standard CodeTracer GL layout with changed files.\n\n**Expected appearance (per DeepReview-GUI.md spec)**:\n\n- FILESYSTEM panel shows changed files with diff badges: M main.rs (+8/-3), A utils.rs (+8/-0), D config.rs (+0/-7)\n- Colors: M=orange, A=green, D=red\n- Editor area shows the first file's content with diff decorations (green lines for additions)\n- All standard panels present: STATE, CALLTRACE, EVENT LOG, etc.\n- **Must look like the normal CodeTracer layout** (Screen 1) with only the FILESYSTEM content changed and diff decorations in the editor\n- NO separate \"DeepReview\" panel or monolithic component\n\n**Comparison**: The reviewer should compare this against Screen 1 (normal layout) and verify that ONLY the FILESYSTEM content and editor decorations changed — everything else is identical.\n\n---\n\n## Evaluation Criteria (applied to ALL screens)\n\n1. **Full-width**: Panels must fill the entire window width. NO gray empty areas.\n2. **Dark theme**: Background #1e1e1e, panels #252526, borders #3c3c3c, text #cccccc\n3. **Font consistency**: Monospace for code/output, system sans-serif for UI labels\n4. **Professional polish**: Looks like VS Code / JetBrains, not a prototype\n5. **Auto-hide overlays**: Flush with window edge, full-width for bottom, full-height for sides\n6. **Status bar**: Always visible at bottom with auto-hide labels (BUILD, PROBLEMS, SEARCH RESULTS)\n7. **No broken elements**: No overlapping text, no clipped content, no invisible elements\n\n**Rating scale**: 1-3 broken, 4-5 rough, 6-7 good, 8-9 near-shipping, 10 perfect\n**Target**: All screens must reach 7/10 minimum.\n","docs/system.md":"\n\n## system\n\nUI\n==\n\nUI is important.\n\nWe have most of our code in `ui/`.\n`ui_js.nim` is the main file.\nWe define the root view.\n\nMost of the components are defined in their own modules:\n\n* `calltrace` the calltrace, expanding and collapse\n* `chronology` the chronology and input\n* `colors` some constants\n* `debug` the debug toolbar\n* `editor` the main editor, uses Monaco\n* `events` support coloring the output code as in terminal\n* `flow` the preload ui\n* `history` the history ui which reuses the value ui\n* `inline_editor` uses monaco, the editor open for traces\n* `layout` the overall layout\n* `loading` the loading screen\n* `start` would be useful as default screen\n* `state` the state view with changing variables\n* `trace` the trace view: now we show traces inline, so maybe remove\n* `ui_imports` exports most dependencies for ui\n* `value` reused by views that show values or expand them\n\nImportant stuff:\n\n* Use direct style helpers for generated DOM and stylus for css files\n* You can watch debug output in the console\n* Monaco, datatables and charts have a custom DOM integration\n* Layouts can be loaded from files: look at `config.nim`, we have to fix this\n* We have themes: defined by variables in name_theme.styl\n* Redraw needs to be manual sometimes, especially after IPC listeners or direct DOM integrations\n* A lot of the helper code is in `types.nim`(types) or `lib.nim` (signatures for third party or our helpers)\n* We use `view` in the name of views to easily spot them, normal functions don't need it\n* When we're changing css, it's best to change the current code: remove literals and define them in defaults and theme styles, we might get the designer to color pick better colors and new themes\n* We use vex-js for dialogs\n* Please check id-s and classes if you remove them: we might need them for ui testing\n* test_base includes most of the logic for ui testing, we use spectron\n\nEvents\n\nYou define a callback in renderer and you update state.\nMost of our state is in the `data` global. It can certainly be optimized.\nWe maintain our panel in `sys`.\n\nWhen you need to talk with the server, you send a message using `ipc.send`.\nWe apply the \"CODETRACER::\" namespace. In a browser this is a socket message, in\nElectron we send it to the main process.\nThe main process responds, and usually you register a listener with ipcConfigure.\n\nYou can also define an async function which makes a promise which is resolved after a listener is called.\n\n\n\nTesting\n\n==\n\nWe have to fix the tests.\n\nHowever let's look at the three main sets:\n\n```bash\nexample-based/ nim.cfg programs/ quicktests/ README.md reproductions/ run/ Tupfile\n```\n\nIn `example-based` we have normal tests.\n\nIn `quicktests` we have property tests. Their results are sometimes added to `reproductions`.\n\nIn `run` we store the compiled tests.\n\nIn `programs` we have the example programs.\n\nWe also have tests for python commands: but I must find them, probably git.\n\nThis is an old note:\n\n```\ntests/quicktests/\n reproductions/\n quicktest_basename/\n repr_id.json\n\n failing tests that we eventually fixed\n random subset of succeeding tests\n\n make sure that stuff that worked before, still works\n and that stuff that is fixed is still fixed\n```\n\nEach test folder has lang tests. They are often similar, so I am not sure if we need to parametrize them.\nWe define most of the main logic in test_base.\n\nWe also have `nim-ui` in `example-based` and `quicktests`.\nThey are based on Spectron.\n\nThey use a dsl, so you don't need to always access elements manually.\nIf you need to, please write a helper which can be reused.\n\n==\n\nDebugger\n\n==\n\nWe are working with rr here. RR provides most of our low level functionality.\n\nWe use gdb-js, a custom fork of the original repo with minor differences: several helpers.\n\nMost of the code is in `debugger/`\n\nThe base types are either in `types` and `core` usually.\n\nWe have a `Pool` which is currently only one.\nA `Pool` has a list of `Process` which are currently rr instances.\nBy default, we have a `stable` process which runs most of the usual steps.\nA `trace` process which runs trace debug, a `history` process which runs history search.\nA `preload` process which preloads future values and `args_preload` which preloads args.\nWe also have `prestart` process which starts in the beginning and loads chronology: mostly writes and reads for now.\n\nLet's take a look:\n\n* `args_preloader` defines `loadCallTraceArgs` which loads args\n* `core` contains shared logic and types for the debugger\n* `debugger` is the central module\n* `flow_preloader` defines the preloading code\n* `history` defines the history code\n* `move` runs most of the jumps\n* `process_gdb` is where most of our helpers and other shortcuts live\n* `py_command` is a wrapper around our python commands giving a type safe API\n* `scheduler` was an experiment in mirroring stable steps in preload\n* `sync_preload` is used to sync the preload process to the stable process\n\nWe also have `cgdb` which should eventually deal with gdb as a pure nim solution and give as a way to rewrite debugger with the C backend.\n\nBasically we define a pool in the beginning and the server sends initial data to it.\nAfter that the server starts the pre-start process which loads info while running the program\nand starts the other needed processes.\n\nThe stable process jumps to main and calls back the server so the ui can show the main program.\n\nWe have a listener for gdb events and use a system of JavaScript promises to await actions.\nThe problem is that an action usually ends before the info of the new location arrives, so we have our own\nhelpers in process_gdb which we should use.\n\nThe other bizarre part is the export api: it defines with a macro the debugger interface and generates export code for it. We expose a type to other modules, so they can call our functions in a type safe way.\nThe debugger module can be used directly (import) or in a different process. The second thing is usually better, as\nit can crash or block the main process.\n\nIt communicates using helpers and ipc send. This is also complicated internally as on desktop it uses electron, and on server `node-ipc` mapping the calls (probably).\n\nWe have some helpers to report errors and to load stuff from the server.\nA lot of the moves are basically taking arguments from the server , invoking typed functions which implement the logic\nand call python commands as primitives. Some actions periodically update the server , e.g. preloading.\n\nArgs preloading is a bit hard to optimize for bigger programs, so we have to work a bit on it: it visits all the call children of the current call and logs the args.\n\nFlow preloading can be slow: most of the logic is in Python commands. We try to limit the number of steps taken there\nand repeatedly call it , sending updates to the server until we are stopped by a new preloading context or finished.\n\nWe cache a lot of stuff like preload results, AST etc. Some of the caches are on function-level, some on filename-level etc.\n\nA lot of the logic is in Python commands: usually if something needs to use a series of gdb commands or to analyze in a more powerful way the program , we create a command, it's best if it is general enough to be reused in many actions.\n\nParsing the modules is good for preloading: we load the labels for each line.\n\nOverall\n==\n\n\nElectron:\n\nWe have several components.\n\nThe backend, the archive runner, the archive server, the shell support, codetracer, plugins, the commands, language forks, the server, the renderer and the debugger.\n\n\nCodetracer calls the server, a local database and Redis.\n\nThe server is the main Electron process which dispatches tasks and messages to the renderer and the debugger.\n\nIt also maintains a running plugin for the current language and communicates on stdout with json.\nIt communicates on the stdout with `nimsuggest` when in a Nim project too: we have to test if this is working now.\n\nThe plugins can parse expressions and modules: expressions are parsed as QueryNode which can be interpreted by our debugger, the modules as a language-unified AST.\n\nThe QueryNode-s are interpreted with the class Loader. We visit the nodes and map each one to a gdb expression, which most of the time accesses some kind of variable or a call which can start a rr fork.\n\nThe server currently assumes it has only one renderer. We have to parametrize it.\n\nNow, we map the messages to ipc on desktop and sockets in browser.\n\nThe renderer just talks with the server in all scenarios, for now we assume it's always a single project in a renderer.\n\nThe debugger also connects to the server for additional functionality: e.g. plugin call.\nIt maintains a sequence of RR debuggers with sockets and communicates with them using gdb-js either directly or with commands.\n\nThe python commands are loaded when the debugger starts: we also reuse the CPython gdb commands for Python.\nThey are executed only in a single RR process.\n\nThe telemetry is used for logging by me most of the time: it logs to the screen and in a file. In most of the code you can log using `event` or other shortcuts in `telemetry`. You can turn it off or on in `.config.yaml`, you can eventually share a structured log in `telemetry.log`. We probably can use nim-chronicles, but it has to be flexible enough and work on the JavaScript backend.\n\n\nPlugin communicator\n==\n\nPlugins are supposed to analyze language-specific things using the language tools.\nFor Nim, we just import the compiler.\nFor C++, currently we parse clang's dump output: we have to write a plugin in C++ which actually analyzes the AST, but I had some problems with the parser API: TODO.\n","AGENTS.md":"# Instructions for Codex\n\n## Where a checkout — or a worktree — has to live\n\n**A checkout of this repo must sit DIRECTLY under the workspace root, beside its\nsibling repos.** A `git worktree` is a checkout and this rule is not relaxed for\nit: put worktrees at `/`, never at `/.agent-wt/`\nor in any other subdirectory, and never outside the workspace.\n\n```\n/path/to/workspace/ # the workspace root\n codetracer/ # the main checkout\n my-feature/ # CORRECT — a worktree, beside the siblings\n isonim/ runquota/ nim-agents/ codetracer-trace-format/ ...\n .agent-wt/\n my-feature/ # WRONG — its parent is `.agent-wt`, which has no siblings\n```\n\nThe reason is that **the parent directory of the checkout IS the workspace root,\nby definition**, for four independent resolvers that reach siblings by the\nrelative path `../`:\n\n| resolver | where | how it fails from the wrong place |\n| --- | --- | --- |\n| Nim | `config.nims` (`repoRoot.parentDir()`), `src/Tuprules.tup` (`$(ROOT)/../…`) | `--path` to a missing dir is silently ignored → `cannot open file: runquota_process`, minutes in |\n| Cargo | `src/db-backend/Cargo.toml` (`path = \"../../../codetracer-trace-format/…\"`) | `failed to load manifest` |\n| cc | `src/db-backend/build.rs` (`../../../codetracer-native-recorder/ct_emulator`) | 81 undefined `mcr*` symbols at link |\n| Repro/Nix | `repro.nim` and native workspace input overrides (`../io-mon`, `../reprobuild`, …) | sibling overrides cannot be resolved |\n\nNone of the four can be pointed elsewhere per-worktree, so relocating the\ncheckout is the only fix. In particular **`runquota` has no override at all** by\ndesign — see the tier notes in `scripts/require-siblings.sh` — so no environment\nvariable can paper over a badly-placed worktree.\n\nCreate one like this, from the main checkout:\n\n```bash\ngit -C /path/to/workspace/codetracer worktree add /path/to/workspace/ \n```\n\nand move a misplaced one like this:\n\n```bash\ngit worktree move /path/to/workspace/.agent-wt/ /path/to/workspace/\n```\n\n`scripts/require-siblings.sh` runs before every build (`just build-once`,\n`just build`, `just test-gui`, …) and refuses a badly-placed checkout by name.\n**Do not answer it with `CODETRACER_SKIP_SIBLING_CHECK=1`**: that escape hatch is\nfor genuinely different layouts (vendored trees, Nix builds that pre-stage the\npaths). Used here it only removes the message — the build still cannot see the\nsiblings and dies later naming a *module* instead of the real problem.\n\n## Building the full frontend (Nim + Electron)\n\nTo rebuild the full CodeTracer frontend (Nim backend CLI, Nim renderer JS, webpack bundles):\n\n```\njust build-once\n```\n\nThis runs tup (incremental build) and webpack. Use this after modifying any `.nim` files in\n`src/ct/`, `src/frontend/`, or `src/common/`.\n\n## Building the db-backend\n\n```\n# inside src/db-backend\ncargo build\n```\n\n## Running tests\n\n```\n# inside src/db-backend\ncargo test\n```\n\n## Running the linter\n\n```\n# inside src/db-backend\ncargo clippy\n```\n\nDon't disable the lint: try to fix the code instead first!\n\n## Running Playwright e2e tests\n\n```\n# From the repo root (needs Xvfb or a display)\njust test-e2e\n```\n\nThe Playwright tests live in `tsc-ui-tests/`. They launch the real Electron app via the `ct`\nbinary at `src/build-debug/bin/ct`. If you modify frontend Nim code, run `just build-once`\nfirst to rebuild the frontend before running the tests.\n\n## Running the cross-language ct_test provider tests\n\n```\n# From inside the dev shell (provides nim + the gtest/catch2/cmake/ninja\n# toolchain and the CMAKE_PREFIX_PATH / CT_TEST_C{C,XX} the C/C++ providers need)\njust test-ct-providers\n```\n\nThis runs the cross-language `ct_test` provider suites (C/C++ GoogleTest/Catch2/CTest, M11\nnative, M12 fallback, JavaScript, Ruby) plus the framework gate tests. It first builds the\nnative (`ct-mcr`), JavaScript and Ruby recorder siblings in their own pinned dev shells\n(`repro exec -- just build`, via `scripts/build-siblings.sh`) so the recording tests run\nagainst real recorders; a missing or failed required sibling fails loudly rather than skipping\n(per `codetracer-specs/Working-with-the-CodeTracer-Repos.md` Part 2). Useful overrides:\n\n- `CT_PROVIDERS_SKIP_SIBLINGS=1` — reuse already-built recorders, skip the sibling build step.\n- `CT_PROVIDERS_ALLOW_MISSING=1` — run the suites even if a required recorder sibling is\n missing/unbuildable (the recording tests then fail honestly instead of aborting up front).\n\nThe recorder binaries are discovered via PATH / the documented env vars\n(`CODETRACER_CT_MCR_CMD`, `CODETRACER_JS_RECORDER_PATH`, `CODETRACER_RUBY_RECORDER_PATH`) by\n`scripts/detect-siblings.sh`. See `ci/test/ct-providers.sh`.\n\n## Windows local setup (non-Nix)\n\nFor Windows development (both x64 and ARM64), use the DIY bootstrap:\n\n### Activate environment (auto-installs tools on first run)\n```bash\n# Git Bash / MSYS2\nsource env.sh\n\n# PowerShell\n. .\\env.ps1\n```\n\n### Optional skip flags\nComponents can be skipped via environment variables (e.g. for satellite repos\nthat only need a subset):\n- `WINDOWS_DIY_SKIP_NARGO=1` — skip Noir compiler\n- `WINDOWS_DIY_SKIP_CT_REMOTE=1` — skip ct-remote desktop client\n- `WINDOWS_DIY_ENSURE_TTD=0` — skip TTD/WinDbg validation\n\n### Build commands (Windows)\n```bash\n# Rust components\ncd src/db-backend && cargo build && cargo test && cargo clippy\ncd src/tui && cargo build && cargo test\ncd src/backend-manager && cargo build\n\n# Full frontend (Nim + Tup)\ncd src/build-debug && source ../../env.sh && tup upd\n```\n\n### Version pins\nPinned tool versions are tracked in:\n```\nnon-nix-build/windows/toolchain-versions.env\n```\n\nFor detailed Windows porting progress, see `windows-porting-initiative-status.md`.\n\n## Nix dev shell and local flake overrides\n\nThe Repro shell hook activates the flake through `repro.nim`. Run `repro allow`\nonce for this checkout, then enter it with the hook installed. For an explicit\ncommand, use `repro exec /path/to/codetracer -- `.\n\nRepro resolves declared workspace siblings as native flake input overrides.\nKeep direnv denied; `.envrc` and the old override plugin are not required for\nthis activation path. Changes to the recipe require renewed Repro authorization.\n\n### Blockchain recorder tools (circom, forc)\n\nThe Nix dev shell supplies the toolchains declared by the CodeTracer flake.\nBuild recorder siblings through `scripts/build-siblings.sh`; each recorder's\n`repro.nim` activates its own pinned environment. See the helper's per-repository\nlogs when a required tool or sibling build fails.\n\n### Inspecting a Nix environment directly\n\nTo diagnose an individual flake input independently of shell activation, use an\nexplicit Nix invocation without changing direnv trust:\n\n```bash\nnix develop '.?submodules=1' --override-input nix-blockchain-development path:../nix-blockchain-development -c bash\n```\n\n### Cadence Go helper\n\nThe `detect-siblings.sh` script auto-builds `cadence-trace-helper` from\n`codetracer-flow-recorder/go-helper/` when the flow recorder sibling is\npresent and `go` is available. The built binary is exported via\n`CADENCE_HELPER_BIN` and added to PATH.\n\n# Keeping notes\n\nIn the `.agents/codebase-insights.txt` file, we try to maintain useful tips that may help\nyou in your development tasks. When you discover something important or surprising about\nthe codebase, add a remark in a comment near the relevant code or in the codebase-insights\nfile. ALWAYS remove older remarks if they are no longer true.\n\nYou can consult this file before starting your coding tasks.\n\n# Code quality guidelines\n\n- ALWAYS strive to achieve high code quality.\n- ALWAYS write secure code.\n- ALWAYS make sure the code is well tested and edge cases are covered. Design the code for testability and be extremely thorough.\n- ALWAYS write defensive code and make sure all potential errors are handled.\n- ALWAYS strive to write highly reusable code with routines that have high fan in and low fan out.\n- ALWAYS keep the code DRY.\n- Aim for low coupling and high cohesion. Encapsulate and hide implementation details.\n- When creating executable, ALWAYS make sure the functionality can also be used as a library.\n To achieve this, avoid global variables, raise/return errors instead of terminating the program, and think whether the use case of the library requires more control over logging\n and metrics from the application that integrates the library.\n\n# Code commenting guidelines\n\n- Document public APIs and complex modules using standard code documentation conventions.\n- Comment the intention behind your code extensively. Omit comments only for very obvious\n facts that almost any developer would know.\n- Maintain the comments together with the code to keep them meaningful and current.\n- When the code is based on specific formats, standards or well-specified behavior of\n other software, always make sure to include relevant links (URLs) that provide the\n necessary technical details.\n\n# Writing git commit messages\n\n- You MUST use multiline git commit messages.\n- Use the conventional commits style for the first line of the commit message.\n- Use the summary section of your final response as the remaining lines in the commit message.\n","tools/visual-review/briefs/storybook-build-panel.md":"# Build Panel Story Visual Brief\n\n## What You're Reviewing\n\nThis is the CodeTracer Build panel rendered in Storybook through the real\nIsoNim Build view.\n\nShared project brief: `../project-visual-brief.md`\n\n## Screen\n\n- Route: Storybook iframe story `codetracer-panels--build`\n- Capture id: `storybook-build-panel`\n- Viewport: laptop, 1440x900\n\n## Seeded State\n\nThe fixture shows a failed `nargo test` build with stdout, stderr, and parsed\nproblem rows.\n\n## Expected Visible Content\n\n- Dark CodeTracer app background and app font styling.\n- Build header/status controls styled like the app.\n- Compiler output lines with error/warning colors.\n- Clickable source-location styling for `src/combat.nr:42`.\n\n## Must Not Show\n\n- Unstyled default buttons or form controls.\n- Missing CodeTracer color palette.\n- Text overlapping the header controls.\n- A bare list of lines with no panel structure.\n\n## What to Evaluate\n\nFocus on whether the app CSS is matching the real DOM, and whether the panel\nlooks like a real CodeTracer bottom/side panel rather than a mock.\n\n## How to Report\n\nKeep under 200 words. Lead with an overall impression, list specific visual\nissues, then give the top two fixes. Include a 1-10 rating.\n","tools/visual-review/briefs/storybook-default-layout.md":"# Default Layout Story Visual Brief\n\n## What You're Reviewing\n\nThis is the Storybook default IsoNim app-shell layout story. It exercises\nmultiple real panel views together in the standalone IsoNim shell.\n\nShared project brief: `../project-visual-brief.md`\n\n## Screen\n\n- Route: Storybook iframe story `codetracer-layouts--default-debug`\n- Capture id: `storybook-default-layout`\n- Viewport: laptop, 1440x900\n\n## Seeded State\n\nThe fixture includes a Karax-reference-shaped Golden Layout debugging workspace\nwith Filesystem, Editor, State/Scratchpad, Calltrace/Agent Activity, and Event\nLog/Terminal Output stacks. Visible panels are real IsoNim views; inactive tabs\nshould remain present in the DOM but hidden like the Karax reference.\n\n## Expected Visible Content\n\n- Dark CodeTracer app styling loaded in the iframe.\n- Golden Layout panel headers, grouped tabs, splitters, and content cells should\n be visible.\n- Multiple real IsoNim panels should look like CodeTracer surfaces, not browser defaults.\n- The layout should use the Karax shell framing: dark body, top-offset\n root-container, `#ROOT`, empty `#main`, and GoldenLayout immediately under\n `#ROOT`.\n\n## Must Not Show\n\n- Blank screen.\n- White background or generic Storybook styling dominating the view.\n- Panels clipped to unusably small fragments.\n- Missing CSS resources or broken image icons.\n\n## What to Evaluate\n\nEvaluate shell context, spacing, panel sizing, typography, color, and whether\nthe surface is useful for visual parity work.\n\n## How to Report\n\nKeep under 200 words. Lead with an overall impression, list specific visual\nissues, then give the top two fixes. Include a 1-10 rating.\n","tools/visual-review/briefs/storybook-terminal-output.md":"# Terminal Output Story Visual Brief\n\n## What You're Reviewing\n\nThis is the CodeTracer Terminal Output panel rendered in Storybook through the\nreal IsoNim Terminal Output view.\n\nShared project brief: `../project-visual-brief.md`\n\n## Screen\n\n- Route: Storybook iframe story `codetracer-panels--terminal-output`\n- Capture id: `storybook-terminal-output`\n- Viewport: laptop, 1440x900\n\n## Seeded State\n\nThe fixture shows the Noir space-ship replay terminal transcript from the\nKarax terminal-visible reference. All lines are ahead of the current replay\nposition, matching the reference state.\n\n## Expected Visible Content\n\n- Dark CodeTracer app background and app font styling.\n- Terminal output panel with CodeTracer terminal row styling.\n- Dense terminal output including \"Positive Test Case\", shield status rows,\n and the final \"shields will not hold as expected\" line.\n- Future terminal fragments should use the same dimmed terminal row styling as\n the Karax reference.\n\n## Must Not Show\n\n- Generic browser serif fonts.\n- White Storybook or Bootstrap default panel background.\n- A tiny unstyled text block floating in empty space.\n- Missing app CSS or broken icon/resource requests.\n\n## What to Evaluate\n\nCheck whether app styles are actually applied, whether the panel sits in a\nCodeTracer-like shell context, and whether spacing, typography, contrast, and\nvisual hierarchy look like the real app.\n\n## How to Report\n\nKeep under 200 words. Lead with an overall impression, list specific visual\nissues, then give the top two fixes. Include a 1-10 rating.\n","tools/visual-review/reference-coverage.md":"# Storybook Reference Coverage\n\n\n\n\nThis file tracks Karax reference captures used for IsoNim visual parity work.\nGenerated screenshots, HTML dumps, and computed-style dumps are intentionally\nkept out of this repository; the rows below point to the local reference\nworktree artifacts that agents should compare against.\n\nPaths are given relative to the reference-dump root, written below as\n`$CT_REFERENCE_DUMPS`. It defaults to `ui-tests/reference-dumps/` inside the\ncheckout and can be pointed at a local capture worktree instead — the same\nvariable `src/tests/gui/tests/session-chrome/new-trace-caption-chrome.spec.ts`\nreads. The captures themselves are not distributed with the repository, so an\nunset root simply means the reference-fact diagnostics stay empty.\n\n## Reference Sets\n\n- Full default/scratchpad/terminal baseline:\n `$CT_REFERENCE_DUMPS/isonim-karax-reference-20260504T155511Z/`\n- Expanded panel baseline:\n `$CT_REFERENCE_DUMPS/isonim-karax-reference-20260504T220906Z/`\n- Expanded panel baseline with isolated layout config:\n `$CT_REFERENCE_DUMPS/isonim-karax-reference-20260504T222307Z/`\n\nSome old Karax panels were less developed than current IsoNim surfaces. Use\nthese references for mature shell, Golden Layout, design-system class, and\nspacing contracts. Do not downgrade richer current IsoNim behavior to match an\nold empty, blocked, or partial Karax state.\n\n## Current Storybook Audit\n\nLast audited: 2026-05-05 on `codetracer-viewmodel`.\n\nCurrent Storybook views are discovered with:\n\n```sh\nnix shell nixpkgs#nodejs --command node tools/visual-review/capture-storybook.mjs --list-views --no-build\n```\n\nThe generated list includes all real IsoNim panel stories exported through\n`mountCodeTracerStory`, plus structure stories for session tabs, menu/status\nshells, debug shell, auto-hide controls, and default/app-shell layouts. The\ncapture tool also exposes source-slug aliases for `deepreview` and\n`agent-activity-deepreview`, in addition to Storybook's display-name slugs\n`deep-review` and `agent-activity-deep-review`; `status` aliases the\n`status-shell` component story.\n\nRepresentative partial/missing-reference surfaces were captured successfully at\n`laptop` size on 2026-05-05:\n\n| Surface | Current Storybook view | Current status |\n| --- | --- | --- |\n| Point list | `point-list` | confirmed current IsoNim panel, `tools/visual-review/reports/point-list-laptop.json` |\n| Timeline | `timeline` | confirmed current IsoNim panel, `tools/visual-review/reports/timeline-laptop.json` |\n| Flow | `flow` | confirmed current IsoNim panel with populated steps, `tools/visual-review/reports/flow-laptop.json` |\n| VCS | `vcs` | confirmed current IsoNim panel, `tools/visual-review/reports/vcs-laptop.json` |\n| Request panel | `request-panel` | confirmed current IsoNim panel, `tools/visual-review/reports/request-panel-laptop.json` |\n| Build errors | `errors` | confirmed current IsoNim problems/build-errors panel, `tools/visual-review/reports/errors-laptop.json`; `noir-build-open` also confirms the panel tab in a default layout |\n| Deep review panel | `deepreview` | confirmed current IsoNim panel, `tools/visual-review/reports/deepreview-laptop.json` |\n| Agent activity deep review | `agent-activity-deepreview` | confirmed current IsoNim panel, `tools/visual-review/reports/agent-activity-deepreview-laptop.json` |\n| Auto-hide bottom strip | `auto-hide-bottom-strip` | confirmed current IsoNim component, `tools/visual-review/reports/auto-hide-bottom-strip-laptop.json` |\n| Auto-hide collapsed icons | `auto-hide-collapsed-icons` | confirmed current IsoNim component, `tools/visual-review/reports/auto-hide-collapsed-icons-laptop.json` |\n| Auto-hide overlay tabs | `auto-hide-overlay-tabs` | confirmed current IsoNim component, `tools/visual-review/reports/auto-hide-overlay-tabs-laptop.json` |\n| Auto-hide side strip | `auto-hide-side-strip` and `auto-hide-side-strip-collapsed` | confirmed populated and collapsed current IsoNim variants |\n| Session tabs | `session-tabs` | confirmed current IsoNim component, `tools/visual-review/reports/session-tabs-laptop.json` |\n| Default layout variants | `default-layout`, `standalone-app-shell`, `noir-filesystem-active`, `noir-state-active`, `noir-calltrace-active`, `noir-calltrace-search-status-report`, `noir-menu-view-open`, `noir-status-expanded` | confirmed current layout stories; use a non-default `--port` if another static server is already bound to `6106` |\n\nCurrent confirmation does not change the old reference status below. Rows marked\n`blocked`, `partial`, or `missing` still mean the old Karax reference capture is\nblocked, partial, or absent; the current IsoNim story can still be valid and\ncapturable.\n\nLatest mature-state screenshot delta report:\n`tools/visual-review/mature-karax-visual-delta-20260505.md`.\n\n## Coverage Matrix\n\n| Surface | Reference status | Reference capture |\n| --- | --- | --- |\n| Default layout | captured | `20260504T160311Z_noir-electron-rendered` |\n| Scratchpad visible | captured | `20260504T160414Z_noir-scratchpad-visible` |\n| Terminal visible | captured | `20260504T160434Z_noir-terminal-visible` |\n| Filesystem active | captured | `20260504T220916Z_noir-filesystem-active` |\n| State active | captured | `20260504T220918Z_noir-state-active` |\n| Calltrace active | captured | `20260504T220919Z_noir-calltrace-active` |\n| Calltrace search status | captured | `20260504T220922Z_noir-calltrace-search-status-report` |\n| Agent activity active | captured | `20260504T220923Z_noir-agent-activity-active` |\n| Menu open | captured | `20260504T220925Z_noir-menu-view-open` |\n| Status expanded | captured | `20260504T220927Z_noir-status-expanded` |\n| Search results | captured | `20260504T222338Z_noir-search-results-karax-populated`; preserve newer IsoNim functionality if richer |\n| Fixed search | captured | `20260504T222336Z_noir-fixed-search-karax-visible` |\n| Point list | blocked | `20260504T220950Z_noir-point-list-open`; Karax raised unexpected `PointList` content |\n| Step list | captured | `20260504T220952Z_noir-step-list-open` |\n| Timeline | blocked | `20260504T222349Z_noir-timeline-blocked-no-factory`; Karax lacked a usable component factory |\n| Trace log | captured | `20260504T222329Z_noir-trace-log-karax-open` |\n| Build | captured | `20260504T222317Z_noir-build-karax-open`; preserve newer IsoNim output behavior if richer |\n| Build errors | partial | `20260504T222538Z_noir-build-errors-karax-open-attached` and `20260504T222734Z_noir-build-errors-karax-direct-id0`; Karax content stayed empty |\n| Shell | captured | `20260504T221002Z_noir-shell-open` |\n| REPL | captured | `20260504T222331Z_noir-repl-karax-open` |\n| Low-level code | captured | `20260504T222333Z_noir-low-level-code-karax-open` |\n| No source | captured | `20260504T222334Z_noir-no-source-karax-open` |\n| Command palette | captured | `20260504T222339Z_noir-command-palette-karax-open` |\n| Debug controls/header | captured | `20260504T222314Z_noir-debug-controls-header` |\n| Agent workspace | captured | `20260504T222341Z_noir-agent-workspace-karax-open`; preserve newer IsoNim behavior if richer |\n| Agent activity deep review | captured | `20260504T222342Z_noir-agent-activity-deepreview-karax-open`; preserve newer IsoNim behavior if richer |\n| Deep review panel | partial | `20260504T222344Z_noir-deepreview-panel-karax-open-empty` and `20260504T222427Z_deepreview-standalone-karax-sample`; old Karax state was underdeveloped |\n| Flow | partial | `20260504T222348Z_noir-flow-select-attempt`; old frontend raised missing `ct/load-flow` response-kind handling |\n| VCS | missing | No old panel implementation found |\n| Request panel | missing | No old panel implementation found |\n| Welcome screen | captured | `20260504T221201Z_welcome-screen` |\n\n## Current Workflow\n\n1. Capture current Storybook for a matching story with\n `tools/visual-review/capture-storybook.mjs --view --size laptop`.\n Use repeated `--view` flags or `--views a,b,c` for batch captures. If the\n default port is occupied, pass `--port `.\n2. Compare HTML and computed-style dumps against the reference capture with the\n same surface name.\n3. Compare screenshots with `tools/visual-review/compare-screenshots.sh` when\n the reference capture is marked `captured`.\n4. Patch the real IsoNim view/style/story shell, not a parallel mock.\n5. Update this matrix when new reference captures become available.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","rawUrl":"https://raw.githubusercontent.com/metacraft-labs/codetracer/HEAD/AGENTS.md","title":"AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# Instructions for Codex\n\n## Where a checkout — or a worktree — has to live\n\n**A checkout of this repo must sit DIRECTLY under the workspace root, beside its\nsibling repos.** A `git worktree` is a checkout and this rule is not relaxed for\nit: put worktrees at `/`, never at `/.agent-wt/`\nor in any other subdirectory, and never outside the workspace.\n\n```\n/path/to/workspace/ # the workspace root\n codetracer/ # the main checkout\n my-feature/ # CORRECT — a worktree, beside the siblings\n isonim/ runquota/ nim-agents/ codetracer-trace-format/ ...\n .agent-wt/\n my-feature/ # WRONG — its parent is `.agent-wt`, which has no siblings\n```\n\nThe reason is that **the parent directory of the checkout IS the workspace root,\nby definition**, for four independent resolvers that reach siblings by the\nrelative path `../`:\n\n| resolver | where | how it fails from the wrong place |\n| --- | --- | --- |\n| Nim | `config.nims` (`repoRoot.parentDir()`), `src/Tuprules.tup` (`$(ROOT)/../…`) | `--path` to a missing dir is silently ignored → `cannot open file: runquota_process`, minutes in |\n| Cargo | `src/db-backend/Cargo.toml` (`path = \"../../../codetracer-trace-format/…\"`) | `failed to load manifest` |\n| cc | `src/db-backend/build.rs` (`../../../codetracer-native-recorder/ct_emulator`) | 81 undefined `mcr*` symbols at link |\n| Repro/Nix | `repro.nim` and native workspace input overrides (`../io-mon`, `../reprobuild`, …) | sibling overrides cannot be resolved |\n\nNone of the four can be pointed elsewhere per-worktree, so relocating the\ncheckout is the only fix. In particular **`runquota` has no override at all** by\ndesign — see the tier notes in `scripts/require-siblings.sh` — so no environment\nvariable can paper over a badly-placed worktree.\n\nCreate one like this, from the main checkout:\n\n```bash\ngit -C /path/to/workspace/codetracer worktree add /path/to/workspace/ \n```\n\nand move a misplaced one like this:\n\n```bash\ngit worktree move /path/to/workspace/.agent-wt/ /path/to/workspace/\n```\n\n`scripts/require-siblings.sh` runs before every build (`just build-once`,\n`just build`, `just test-gui`, …) and refuses a badly-placed checkout by name.\n**Do not answer it with `CODETRACER_SKIP_SIBLING_CHECK=1`**: that escape hatch is\nfor genuinely different layouts (vendored trees, Nix builds that pre-stage the\npaths). Used here it only removes the message — the build still cannot see the\nsiblings and dies later naming a *module* instead of the real problem.\n\n## Building the full frontend (Nim + Electron)\n\nTo rebuild the full CodeTracer frontend (Nim backend CLI, Nim renderer JS, webpack bundles):\n\n```\njust build-once\n```\n\nThis runs tup (incremental build) and webpack. Use this after modifying any `.nim` files in\n`src/ct/`, `src/frontend/`, or `src/common/`.\n\n## Building the db-backend\n\n```\n# inside src/db-backend\ncargo build\n```\n\n## Running tests\n\n```\n# inside src/db-backend\ncargo test\n```\n\n## Running the linter\n\n```\n# inside src/db-backend\ncargo clippy\n```\n\nDon't disable the lint: try to fix the code instead first!\n\n## Running Playwright e2e tests\n\n```\n# From the repo root (needs Xvfb or a display)\njust test-e2e\n```\n\nThe Playwright tests live in `tsc-ui-tests/`. They launch the real Electron app via the `ct`\nbinary at `src/build-debug/bin/ct`. If you modify frontend Nim code, run `just build-once`\nfirst to rebuild the frontend before running the tests.\n\n## Running the cross-language ct_test provider tests\n\n```\n# From inside the dev shell (provides nim + the gtest/catch2/cmake/ninja\n# toolchain and the CMAKE_PREFIX_PATH / CT_TEST_C{C,XX} the C/C++ providers need)\njust test-ct-providers\n```\n\nThis runs the cross-language `ct_test` provider suites (C/C++ GoogleTest/Catch2/CTest, M11\nnative, M12 fallback, JavaScript, Ruby) plus the framework gate tests. It first builds the\nnative (`ct-mcr`), JavaScript and Ruby recorder siblings in their own pinned dev shells\n(`repro exec -- just build`, via `scripts/build-siblings.sh`) so the recording tests run\nagainst real recorders; a missing or failed required sibling fails loudly rather than skipping\n(per `codetracer-specs/Working-with-the-CodeTracer-Repos.md` Part 2). Useful overrides:\n\n- `CT_PROVIDERS_SKIP_SIBLINGS=1` — reuse already-built recorders, skip the sibling build step.\n- `CT_PROVIDERS_ALLOW_MISSING=1` — run the suites even if a required recorder sibling is\n missing/unbuildable (the recording tests then fail honestly instead of aborting up front).\n\nThe recorder binaries are discovered via PATH / the documented env vars\n(`CODETRACER_CT_MCR_CMD`, `CODETRACER_JS_RECORDER_PATH`, `CODETRACER_RUBY_RECORDER_PATH`) by\n`scripts/detect-siblings.sh`. See `ci/test/ct-providers.sh`.\n\n## Windows local setup (non-Nix)\n\nFor Windows development (both x64 and ARM64), use the DIY bootstrap:\n\n### Activate environment (auto-installs tools on first run)\n```bash\n# Git Bash / MSYS2\nsource env.sh\n\n# PowerShell\n. .\\env.ps1\n```\n\n### Optional skip flags\nComponents can be skipped via environment variables (e.g. for satellite repos\nthat only need a subset):\n- `WINDOWS_DIY_SKIP_NARGO=1` — skip Noir compiler\n- `WINDOWS_DIY_SKIP_CT_REMOTE=1` — skip ct-remote desktop client\n- `WINDOWS_DIY_ENSURE_TTD=0` — skip TTD/WinDbg validation\n\n### Build commands (Windows)\n```bash\n# Rust components\ncd src/db-backend && cargo build && cargo test && cargo clippy\ncd src/tui && cargo build && cargo test\ncd src/backend-manager && cargo build\n\n# Full frontend (Nim + Tup)\ncd src/build-debug && source ../../env.sh && tup upd\n```\n\n### Version pins\nPinned tool versions are tracked in:\n```\nnon-nix-build/windows/toolchain-versions.env\n```\n\nFor detailed Windows porting progress, see `windows-porting-initiative-status.md`.\n\n## Nix dev shell and local flake overrides\n\nThe Repro shell hook activates the flake through `repro.nim`. Run `repro allow`\nonce for this checkout, then enter it with the hook installed. For an explicit\ncommand, use `repro exec /path/to/codetracer -- `.\n\nRepro resolves declared workspace siblings as native flake input overrides.\nKeep direnv denied; `.envrc` and the old override plugin are not required for\nthis activation path. Changes to the recipe require renewed Repro authorization.\n\n### Blockchain recorder tools (circom, forc)\n\nThe Nix dev shell supplies the toolchains declared by the CodeTracer flake.\nBuild recorder siblings through `scripts/build-siblings.sh`; each recorder's\n`repro.nim` activates its own pinned environment. See the helper's per-repository\nlogs when a required tool or sibling build fails.\n\n### Inspecting a Nix environment directly\n\nTo diagnose an individual flake input independently of shell activation, use an\nexplicit Nix invocation without changing direnv trust:\n\n```bash\nnix develop '.?submodules=1' --override-input nix-blockchain-development path:../nix-blockchain-development -c bash\n```\n\n### Cadence Go helper\n\nThe `detect-siblings.sh` script auto-builds `cadence-trace-helper` from\n`codetracer-flow-recorder/go-helper/` when the flow recorder sibling is\npresent and `go` is available. The built binary is exported via\n`CADENCE_HELPER_BIN` and added to PATH.\n\n# Keeping notes\n\nIn the `.agents/codebase-insights.txt` file, we try to maintain useful tips that may help\nyou in your development tasks. When you discover something important or surprising about\nthe codebase, add a remark in a comment near the relevant code or in the codebase-insights\nfile. ALWAYS remove older remarks if they are no longer true.\n\nYou can consult this file before starting your coding tasks.\n\n# Code quality guidelines\n\n- ALWAYS strive to achieve high code quality.\n- ALWAYS write secure code.\n- ALWAYS make sure the code is well tested and edge cases are covered. Design the code for testability and be extremely thorough.\n- ALWAYS write defensive code and make sure all potential errors are handled.\n- ALWAYS strive to write highly reusable code with routines that have high fan in and low fan out.\n- ALWAYS keep the code DRY.\n- Aim for low coupling and high cohesion. Encapsulate and hide implementation details.\n- When creating executable, ALWAYS make sure the functionality can also be used as a library.\n To achieve this, avoid global variables, raise/return errors instead of terminating the program, and think whether the use case of the library requires more control over logging\n and metrics from the application that integrates the library.\n\n# Code commenting guidelines\n\n- Document public APIs and complex modules using standard code documentation conventions.\n- Comment the intention behind your code extensively. Omit comments only for very obvious\n facts that almost any developer would know.\n- Maintain the comments together with the code to keep them meaningful and current.\n- When the code is based on specific formats, standards or well-specified behavior of\n other software, always make sure to include relevant links (URLs) that provide the\n necessary technical details.\n\n# Writing git commit messages\n\n- You MUST use multiline git commit messages.\n- Use the conventional commits style for the first line of the commit message.\n- Use the summary section of your final response as the remaining lines in the commit message.\n","isInternal":false,"tokens":2235,"sizeBytes":9325},{"name":"system.md","path":"docs/system.md","rawUrl":"https://raw.githubusercontent.com/metacraft-labs/codetracer/HEAD/docs/system.md","title":"docs - System Architecture & Agent Directives","category":"root-instruction","format":"markdown","content":"\n\n## system\n\nUI\n==\n\nUI is important.\n\nWe have most of our code in `ui/`.\n`ui_js.nim` is the main file.\nWe define the root view.\n\nMost of the components are defined in their own modules:\n\n* `calltrace` the calltrace, expanding and collapse\n* `chronology` the chronology and input\n* `colors` some constants\n* `debug` the debug toolbar\n* `editor` the main editor, uses Monaco\n* `events` support coloring the output code as in terminal\n* `flow` the preload ui\n* `history` the history ui which reuses the value ui\n* `inline_editor` uses monaco, the editor open for traces\n* `layout` the overall layout\n* `loading` the loading screen\n* `start` would be useful as default screen\n* `state` the state view with changing variables\n* `trace` the trace view: now we show traces inline, so maybe remove\n* `ui_imports` exports most dependencies for ui\n* `value` reused by views that show values or expand them\n\nImportant stuff:\n\n* Use direct style helpers for generated DOM and stylus for css files\n* You can watch debug output in the console\n* Monaco, datatables and charts have a custom DOM integration\n* Layouts can be loaded from files: look at `config.nim`, we have to fix this\n* We have themes: defined by variables in name_theme.styl\n* Redraw needs to be manual sometimes, especially after IPC listeners or direct DOM integrations\n* A lot of the helper code is in `types.nim`(types) or `lib.nim` (signatures for third party or our helpers)\n* We use `view` in the name of views to easily spot them, normal functions don't need it\n* When we're changing css, it's best to change the current code: remove literals and define them in defaults and theme styles, we might get the designer to color pick better colors and new themes\n* We use vex-js for dialogs\n* Please check id-s and classes if you remove them: we might need them for ui testing\n* test_base includes most of the logic for ui testing, we use spectron\n\nEvents\n\nYou define a callback in renderer and you update state.\nMost of our state is in the `data` global. It can certainly be optimized.\nWe maintain our panel in `sys`.\n\nWhen you need to talk with the server, you send a message using `ipc.send`.\nWe apply the \"CODETRACER::\" namespace. In a browser this is a socket message, in\nElectron we send it to the main process.\nThe main process responds, and usually you register a listener with ipcConfigure.\n\nYou can also define an async function which makes a promise which is resolved after a listener is called.\n\n\n\nTesting\n\n==\n\nWe have to fix the tests.\n\nHowever let's look at the three main sets:\n\n```bash\nexample-based/ nim.cfg programs/ quicktests/ README.md reproductions/ run/ Tupfile\n```\n\nIn `example-based` we have normal tests.\n\nIn `quicktests` we have property tests. Their results are sometimes added to `reproductions`.\n\nIn `run` we store the compiled tests.\n\nIn `programs` we have the example programs.\n\nWe also have tests for python commands: but I must find them, probably git.\n\nThis is an old note:\n\n```\ntests/quicktests/\n reproductions/\n quicktest_basename/\n repr_id.json\n\n failing tests that we eventually fixed\n random subset of succeeding tests\n\n make sure that stuff that worked before, still works\n and that stuff that is fixed is still fixed\n```\n\nEach test folder has lang tests. They are often similar, so I am not sure if we need to parametrize them.\nWe define most of the main logic in test_base.\n\nWe also have `nim-ui` in `example-based` and `quicktests`.\nThey are based on Spectron.\n\nThey use a dsl, so you don't need to always access elements manually.\nIf you need to, please write a helper which can be reused.\n\n==\n\nDebugger\n\n==\n\nWe are working with rr here. RR provides most of our low level functionality.\n\nWe use gdb-js, a custom fork of the original repo with minor differences: several helpers.\n\nMost of the code is in `debugger/`\n\nThe base types are either in `types` and `core` usually.\n\nWe have a `Pool` which is currently only one.\nA `Pool` has a list of `Process` which are currently rr instances.\nBy default, we have a `stable` process which runs most of the usual steps.\nA `trace` process which runs trace debug, a `history` process which runs history search.\nA `preload` process which preloads future values and `args_preload` which preloads args.\nWe also have `prestart` process which starts in the beginning and loads chronology: mostly writes and reads for now.\n\nLet's take a look:\n\n* `args_preloader` defines `loadCallTraceArgs` which loads args\n* `core` contains shared logic and types for the debugger\n* `debugger` is the central module\n* `flow_preloader` defines the preloading code\n* `history` defines the history code\n* `move` runs most of the jumps\n* `process_gdb` is where most of our helpers and other shortcuts live\n* `py_command` is a wrapper around our python commands giving a type safe API\n* `scheduler` was an experiment in mirroring stable steps in preload\n* `sync_preload` is used to sync the preload process to the stable process\n\nWe also have `cgdb` which should eventually deal with gdb as a pure nim solution and give as a way to rewrite debugger with the C backend.\n\nBasically we define a pool in the beginning and the server sends initial data to it.\nAfter that the server starts the pre-start process which loads info while running the program\nand starts the other needed processes.\n\nThe stable process jumps to main and calls back the server so the ui can show the main program.\n\nWe have a listener for gdb events and use a system of JavaScript promises to await actions.\nThe problem is that an action usually ends before the info of the new location arrives, so we have our own\nhelpers in process_gdb which we should use.\n\nThe other bizarre part is the export api: it defines with a macro the debugger interface and generates export code for it. We expose a type to other modules, so they can call our functions in a type safe way.\nThe debugger module can be used directly (import) or in a different process. The second thing is usually better, as\nit can crash or block the main process.\n\nIt communicates using helpers and ipc send. This is also complicated internally as on desktop it uses electron, and on server `node-ipc` mapping the calls (probably).\n\nWe have some helpers to report errors and to load stuff from the server.\nA lot of the moves are basically taking arguments from the server , invoking typed functions which implement the logic\nand call python commands as primitives. Some actions periodically update the server , e.g. preloading.\n\nArgs preloading is a bit hard to optimize for bigger programs, so we have to work a bit on it: it visits all the call children of the current call and logs the args.\n\nFlow preloading can be slow: most of the logic is in Python commands. We try to limit the number of steps taken there\nand repeatedly call it , sending updates to the server until we are stopped by a new preloading context or finished.\n\nWe cache a lot of stuff like preload results, AST etc. Some of the caches are on function-level, some on filename-level etc.\n\nA lot of the logic is in Python commands: usually if something needs to use a series of gdb commands or to analyze in a more powerful way the program , we create a command, it's best if it is general enough to be reused in many actions.\n\nParsing the modules is good for preloading: we load the labels for each line.\n\nOverall\n==\n\n\nElectron:\n\nWe have several components.\n\nThe backend, the archive runner, the archive server, the shell support, codetracer, plugins, the commands, language forks, the server, the renderer and the debugger.\n\n\nCodetracer calls the server, a local database and Redis.\n\nThe server is the main Electron process which dispatches tasks and messages to the renderer and the debugger.\n\nIt also maintains a running plugin for the current language and communicates on stdout with json.\nIt communicates on the stdout with `nimsuggest` when in a Nim project too: we have to test if this is working now.\n\nThe plugins can parse expressions and modules: expressions are parsed as QueryNode which can be interpreted by our debugger, the modules as a language-unified AST.\n\nThe QueryNode-s are interpreted with the class Loader. We visit the nodes and map each one to a gdb expression, which most of the time accesses some kind of variable or a call which can start a rr fork.\n\nThe server currently assumes it has only one renderer. We have to parametrize it.\n\nNow, we map the messages to ipc on desktop and sockets in browser.\n\nThe renderer just talks with the server in all scenarios, for now we assume it's always a single project in a renderer.\n\nThe debugger also connects to the server for additional functionality: e.g. plugin call.\nIt maintains a sequence of RR debuggers with sockets and communicates with them using gdb-js either directly or with commands.\n\nThe python commands are loaded when the debugger starts: we also reuse the CPython gdb commands for Python.\nThey are executed only in a single RR process.\n\nThe telemetry is used for logging by me most of the time: it logs to the screen and in a file. In most of the code you can log using `event` or other shortcuts in `telemetry`. You can turn it off or on in `.config.yaml`, you can eventually share a structured log in `telemetry.log`. We probably can use nim-chronicles, but it has to be flexible enough and work on the JavaScript backend.\n\n\nPlugin communicator\n==\n\nPlugins are supposed to analyze language-specific things using the language tools.\nFor Nim, we just import the compiler.\nFor C++, currently we parse clang's dump output: we have to write a plugin in C++ which actually analyzes the AST, but I had some problems with the parser API: TODO.\n","isInternal":false,"tokens":2180,"sizeBytes":9667},{"name":"screen-briefs.md","path":"tools/screen-briefs.md","rawUrl":"https://raw.githubusercontent.com/metacraft-labs/codetracer/HEAD/tools/screen-briefs.md","title":"Tools Skill","category":"anthropic-skill","format":"markdown","content":"# Per-Screen Design Briefs for Visual Audit\n\nEach section describes exactly what must be visible, what data should be shown,\nand how to evaluate the screenshot against the CodeTracer design spec.\n\n---\n\n## Screen 1: Normal CodeTracer Layout (reference baseline)\n\n**Purpose**: Establish the reference baseline that all other screens are compared against.\n\n**Expected content**:\n\n- Toolbar: debugger step controls (forward, backward, continue icons)\n- Left: FILESYSTEM panel with file tree showing `source folders > codetracer > test-programs > py_console_logs > main.py`\n- Center: Editor tab `py_console_logs/main.py` with Python source code visible, line numbers, syntax highlighting (keywords in purple/blue, strings in green/orange)\n- Center-right: STATE panel showing \"Enter a watch expression\" input, SCRATCHPAD tab\n- Right: CALLTRACE panel with expandable call tree showing function names, AGENT ACTIVITY tab\n- Bottom-left: EVENT LOG panel with event rows (step index, line number, event text)\n- Bottom-right: TERMINAL OUTPUT panel with stdout/stderr output\n- Footer: Status bar with `Python(db) | UTF-8 | stable: ready | ` on the right, **BUILD | PROBLEMS | SEARCH RESULTS** labels on the right as auto-hide pane triggers\n- NO session tab bar (single trace)\n- NO gray empty areas — panels fill full window width\n\n**Evaluation**: This must look like a professional IDE. Compare against VS Code's dark theme for consistency.\n\n---\n\n## Screen 2: BUILD Auto-Hide Pane — Successful Build (happy path)\n\n**Purpose**: Show the BUILD pane expanded from the bottom with successful build output.\n\n**How to trigger**: Click the \"BUILD\" label in the status bar footer. The BUILD pane slides up as an overlay from the bottom.\n\n**Expected data to inject**:\n\n```\n$ nim c --sourcemap:on main.nim\nHint: used 42 lines of code\nHint: operation successful (0.8s)\nHint: [SuccessX]\n```\n\n**Expected appearance**:\n\n- BUILD overlay visible at bottom, full-width, ~30% window height\n- Overlay header: \"Build succeeded\" in GREEN text, with header controls (stop, clear, auto-scroll, duration \"0.8s\")\n- Build output lines in monospace font with ANSI colors rendered (green \"Hint:\" text)\n- \"Unpin\" button at top-right of overlay\n- The GL layout area above is still visible behind/above the overlay\n- Status bar \"BUILD\" label is highlighted (active state)\n\n---\n\n## Screen 3: BUILD Auto-Hide Pane — Failed Build (unhappy path)\n\n**Purpose**: Show BUILD pane with compiler errors, demonstrating error parsing and color coding.\n\n**Expected data to inject**:\n\n```\n$ cargo build\nerror[E0308]: mismatched types\n --> src/main.rs:42:5\n |\n42 | let x: bool = 42;\n | ^^ expected `bool`, found integer\n\nwarning: unused variable: `y`\n --> src/main.rs:10:9\n\nerror: aborting due to previous error\n```\n\n**Expected appearance**:\n\n- Overlay header: \"Build failed (exit code 1)\" in RED text\n- Error lines: red text (#f85149), clickable (underline on hover)\n- Warning lines: yellow text (#d29922)\n- File locations (`src/main.rs:42:5`) underlined and clickable\n- ANSI colors rendered — \"error\" in red, \"warning\" in yellow, \"-->\" in blue\n- Arrow indicators and code snippets visible in monospace\n\n---\n\n## Screen 4: PROBLEMS Auto-Hide Pane with Parsed Errors\n\n**Purpose**: Show the PROBLEMS pane with structured error list from the failed build.\n\n**Expected data**: 2 errors + 1 warning:\n\n- ERROR: src/main.rs:42:5 — \"mismatched types: expected `bool`, found integer\"\n- ERROR: src/main.rs:55:12 — \"cannot find value `undefined_var` in this scope\"\n- WARNING: src/main.rs:10:9 — \"unused variable: `y`\"\n\n**Expected appearance**:\n\n- Overlay header: \"3 problems (2 errors, 1 warning)\" with filter buttons [All] [Errors] [Warnings]\n- Error rows: red circle icon (●), file path in dim color, line:col, error message\n- Warning row: yellow triangle icon (▲), same format\n- Rows clickable with pointer cursor\n- Grouped by file if \"Group by File\" is toggled\n\n---\n\n## Screen 5: SEARCH RESULTS Auto-Hide Pane with Results\n\n**Purpose**: Show search results grouped by file with match highlighting.\n\n**Expected data**: Search for \"print\" with 4 results across 2 files:\n\n- src/main.py:10 — `def print_to_stdout() -> None:`\n- src/main.py:15 — `print(\"hello world\")`\n- src/main.py:51 — `print(\"1. print using print('text')\")`\n- src/utils.py:3 — `from io import print_function`\n\n**Expected appearance**:\n\n- Overlay header: \"4 results for 'print'\"\n- Results grouped by file: `src/main.py (3)` header, then 3 match rows\n- Then `src/utils.py (1)` header, 1 match row\n- Each row: line number on left, text with \"print\" highlighted in amber/yellow\n- Clickable rows for navigation\n\n---\n\n## Screen 6: Auto-Hide Left — FILESYSTEM Pinned with Overlay Open\n\n**Purpose**: Show left auto-hide strip with FILESYSTEM panel overlay.\n\n**Expected appearance**:\n\n- Thin vertical strip (~28px) on the left edge with vertical text \"FILESYSTEM\"\n- Strip is TILED beside GL (not overlaying) — GL content starts after the strip\n- Overlay panel slides in from left showing the FILESYSTEM file tree\n- File tree shows `source folders > codetracer > test-programs > py_console_logs > main.py`\n- \"Unpin\" button at top-right of overlay\n- Overlay content is LIVE (real file tree, not placeholder)\n\n---\n\n## Screen 7: Multi-Tab Mode — Two Traces Loaded\n\n**Purpose**: Show the session tab bar with multiple traces.\n\n**Expected appearance**:\n\n- Session tab bar visible ABOVE the GL panels (between toolbar and GL)\n- Two tabs: first trace name (e.g., \"py_console_logs/main.py\"), second tab (e.g., \"Trace 2\")\n- Active tab highlighted with different background\n- \"+\" button at the right end to add new trace\n- GL layout below shows the active trace's panels\n- All panels show data from the ACTIVE trace\n\n---\n\n## Screen 8: DeepReview Standard Layout\n\n**Purpose**: Show DeepReview mode using the standard CodeTracer GL layout with changed files.\n\n**Expected appearance (per DeepReview-GUI.md spec)**:\n\n- FILESYSTEM panel shows changed files with diff badges: M main.rs (+8/-3), A utils.rs (+8/-0), D config.rs (+0/-7)\n- Colors: M=orange, A=green, D=red\n- Editor area shows the first file's content with diff decorations (green lines for additions)\n- All standard panels present: STATE, CALLTRACE, EVENT LOG, etc.\n- **Must look like the normal CodeTracer layout** (Screen 1) with only the FILESYSTEM content changed and diff decorations in the editor\n- NO separate \"DeepReview\" panel or monolithic component\n\n**Comparison**: The reviewer should compare this against Screen 1 (normal layout) and verify that ONLY the FILESYSTEM content and editor decorations changed — everything else is identical.\n\n---\n\n## Evaluation Criteria (applied to ALL screens)\n\n1. **Full-width**: Panels must fill the entire window width. NO gray empty areas.\n2. **Dark theme**: Background #1e1e1e, panels #252526, borders #3c3c3c, text #cccccc\n3. **Font consistency**: Monospace for code/output, system sans-serif for UI labels\n4. **Professional polish**: Looks like VS Code / JetBrains, not a prototype\n5. **Auto-hide overlays**: Flush with window edge, full-width for bottom, full-height for sides\n6. **Status bar**: Always visible at bottom with auto-hide labels (BUILD, PROBLEMS, SEARCH RESULTS)\n7. **No broken elements**: No overlapping text, no clipped content, no invisible elements\n\n**Rating scale**: 1-3 broken, 4-5 rough, 6-7 good, 8-9 near-shipping, 10 perfect\n**Target**: All screens must reach 7/10 minimum.\n","isInternal":false,"tokens":1828,"sizeBytes":7454},{"name":"storybook-build-panel.md","path":"tools/visual-review/briefs/storybook-build-panel.md","rawUrl":"https://raw.githubusercontent.com/metacraft-labs/codetracer/HEAD/tools/visual-review/briefs/storybook-build-panel.md","title":"Briefs Skill","category":"anthropic-skill","format":"markdown","content":"# Build Panel Story Visual Brief\n\n## What You're Reviewing\n\nThis is the CodeTracer Build panel rendered in Storybook through the real\nIsoNim Build view.\n\nShared project brief: `../project-visual-brief.md`\n\n## Screen\n\n- Route: Storybook iframe story `codetracer-panels--build`\n- Capture id: `storybook-build-panel`\n- Viewport: laptop, 1440x900\n\n## Seeded State\n\nThe fixture shows a failed `nargo test` build with stdout, stderr, and parsed\nproblem rows.\n\n## Expected Visible Content\n\n- Dark CodeTracer app background and app font styling.\n- Build header/status controls styled like the app.\n- Compiler output lines with error/warning colors.\n- Clickable source-location styling for `src/combat.nr:42`.\n\n## Must Not Show\n\n- Unstyled default buttons or form controls.\n- Missing CodeTracer color palette.\n- Text overlapping the header controls.\n- A bare list of lines with no panel structure.\n\n## What to Evaluate\n\nFocus on whether the app CSS is matching the real DOM, and whether the panel\nlooks like a real CodeTracer bottom/side panel rather than a mock.\n\n## How to Report\n\nKeep under 200 words. Lead with an overall impression, list specific visual\nissues, then give the top two fixes. Include a 1-10 rating.\n","isInternal":false,"tokens":284,"sizeBytes":1210},{"name":"storybook-default-layout.md","path":"tools/visual-review/briefs/storybook-default-layout.md","rawUrl":"https://raw.githubusercontent.com/metacraft-labs/codetracer/HEAD/tools/visual-review/briefs/storybook-default-layout.md","title":"Briefs Skill","category":"anthropic-skill","format":"markdown","content":"# Default Layout Story Visual Brief\n\n## What You're Reviewing\n\nThis is the Storybook default IsoNim app-shell layout story. It exercises\nmultiple real panel views together in the standalone IsoNim shell.\n\nShared project brief: `../project-visual-brief.md`\n\n## Screen\n\n- Route: Storybook iframe story `codetracer-layouts--default-debug`\n- Capture id: `storybook-default-layout`\n- Viewport: laptop, 1440x900\n\n## Seeded State\n\nThe fixture includes a Karax-reference-shaped Golden Layout debugging workspace\nwith Filesystem, Editor, State/Scratchpad, Calltrace/Agent Activity, and Event\nLog/Terminal Output stacks. Visible panels are real IsoNim views; inactive tabs\nshould remain present in the DOM but hidden like the Karax reference.\n\n## Expected Visible Content\n\n- Dark CodeTracer app styling loaded in the iframe.\n- Golden Layout panel headers, grouped tabs, splitters, and content cells should\n be visible.\n- Multiple real IsoNim panels should look like CodeTracer surfaces, not browser defaults.\n- The layout should use the Karax shell framing: dark body, top-offset\n root-container, `#ROOT`, empty `#main`, and GoldenLayout immediately under\n `#ROOT`.\n\n## Must Not Show\n\n- Blank screen.\n- White background or generic Storybook styling dominating the view.\n- Panels clipped to unusably small fragments.\n- Missing CSS resources or broken image icons.\n\n## What to Evaluate\n\nEvaluate shell context, spacing, panel sizing, typography, color, and whether\nthe surface is useful for visual parity work.\n\n## How to Report\n\nKeep under 200 words. Lead with an overall impression, list specific visual\nissues, then give the top two fixes. Include a 1-10 rating.\n","isInternal":false,"tokens":375,"sizeBytes":1657},{"name":"storybook-terminal-output.md","path":"tools/visual-review/briefs/storybook-terminal-output.md","rawUrl":"https://raw.githubusercontent.com/metacraft-labs/codetracer/HEAD/tools/visual-review/briefs/storybook-terminal-output.md","title":"Briefs Skill","category":"anthropic-skill","format":"markdown","content":"# Terminal Output Story Visual Brief\n\n## What You're Reviewing\n\nThis is the CodeTracer Terminal Output panel rendered in Storybook through the\nreal IsoNim Terminal Output view.\n\nShared project brief: `../project-visual-brief.md`\n\n## Screen\n\n- Route: Storybook iframe story `codetracer-panels--terminal-output`\n- Capture id: `storybook-terminal-output`\n- Viewport: laptop, 1440x900\n\n## Seeded State\n\nThe fixture shows the Noir space-ship replay terminal transcript from the\nKarax terminal-visible reference. All lines are ahead of the current replay\nposition, matching the reference state.\n\n## Expected Visible Content\n\n- Dark CodeTracer app background and app font styling.\n- Terminal output panel with CodeTracer terminal row styling.\n- Dense terminal output including \"Positive Test Case\", shield status rows,\n and the final \"shields will not hold as expected\" line.\n- Future terminal fragments should use the same dimmed terminal row styling as\n the Karax reference.\n\n## Must Not Show\n\n- Generic browser serif fonts.\n- White Storybook or Bootstrap default panel background.\n- A tiny unstyled text block floating in empty space.\n- Missing app CSS or broken icon/resource requests.\n\n## What to Evaluate\n\nCheck whether app styles are actually applied, whether the panel sits in a\nCodeTracer-like shell context, and whether spacing, typography, contrast, and\nvisual hierarchy look like the real app.\n\n## How to Report\n\nKeep under 200 words. Lead with an overall impression, list specific visual\nissues, then give the top two fixes. Include a 1-10 rating.\n","isInternal":false,"tokens":338,"sizeBytes":1556},{"name":"mature-karax-visual-delta-20260505.md","path":"tools/visual-review/mature-karax-visual-delta-20260505.md","rawUrl":"https://raw.githubusercontent.com/metacraft-labs/codetracer/HEAD/tools/visual-review/mature-karax-visual-delta-20260505.md","title":"Visual-review Skill","category":"anthropic-skill","format":"markdown","content":"# Mature Karax Visual Delta Report - 2026-05-05\n\n\n\nBranch: `codetracer-viewmodel`\n\n## Method\n\n- Storybook was rebuilt with\n `nix shell nixpkgs#nodejs --command bash -lc 'just storybook-build'`.\n- Current Storybook stories were captured with\n `tools/visual-review/capture-storybook.mjs`.\n- `wide` (`1920x1080`) was used for Karax references captured at `1920x1080`.\n- `laptop` (`1440x900`) was used for the older full-page Karax references\n captured as `2161x3766`; those metrics are useful for trend tracking but are\n dominated by viewport/full-page framing.\n- Screenshot metrics were generated with `tools/visual-review/compare-screenshots.sh`,\n which resizes the reference image to the current capture before computing RMSE/MAE.\n- Generated captures, dumps, and diff images remain ignored under\n `tools/visual-review/{screenshots,reports,compare,dumps}`.\n\n## Summary\n\nThe mature Karax states now have matching capturable Storybook stories. The\nclosest comparisons are the `1920x1080` default Noir layout variants: their\nlargest remaining deltas are mostly intentional richer IsoNim content, not empty\nor broken rendering. The older full-page references and panel-only current\nstories are documented separately because their RMSE/MAE numbers are dominated\nby app-frame and viewport mismatch.\n\nNo small shell/chrome/CSS fix was applied in this pass; the visible differences\nthat remain would require either new full-layout stories for panel-only states or\ndeliberate content downgrades, which this audit avoided.\n\n## Per-Surface Results\n\n| Surface | Current story | Viewport | RMSE | MAE | Status |\n| --- | --- | --- | ---: | ---: | --- |\n| Default layout | `default-layout` | laptop | 0.148885 | 0.056060 | Framing-dominated; current shell is populated and richer. |\n| Terminal | `terminal-output` | laptop | 0.098892 | 0.028241 | Panel story vs full-layout Karax terminal state; metric is directional only. |\n| Scratchpad | `scratchpad` | laptop | 0.098082 | 0.029454 | Panel story vs full-layout Karax scratchpad state; metric is directional only. |\n| Filesystem active | `noir-filesystem-active` | wide | 0.100905 | 0.025215 | Good app-frame match; richer editor/calltrace/event rows dominate. |\n| State active | `noir-state-active` | wide | 0.100905 | 0.025215 | Same base Karax/current pixels as filesystem active; focus change is not visibly distinct. |\n| Calltrace active | `noir-calltrace-active` | wide | 0.100905 | 0.025215 | Same base Karax/current pixels as filesystem active; richer calltrace text dominates. |\n| Calltrace search/status | `noir-calltrace-search-status-report` | wide | 0.106128 | 0.026938 | Good app-frame match; current calltrace/search content is denser. |\n| Menu open | `noir-menu-view-open` | wide | 0.074298 | 0.018578 | Good app-frame match; menu/status shell differences are localized. |\n| Status expanded | `noir-status-expanded` | wide | 0.072659 | 0.018013 | Best layout match in this batch; status and agent panel richness remain. |\n| Fixed search | `noir-fixed-search-visible` | laptop | 0.168908 | 0.057116 | Full-page reference mismatch; current search shell is richer. |\n| Search results | `noir-search-results-populated` | laptop | 0.170998 | 0.060999 | Full-page reference mismatch plus richer current search result content. |\n| Command palette | `noir-command-palette-open` | laptop | 0.094881 | 0.058993 | Full-page reference mismatch; overlay shape/content comparable. |\n| Build | `noir-build-open` | laptop | 0.134460 | 0.048930 | Full-page reference mismatch; current build output behavior is richer. |\n| Trace log | `noir-trace-log-open` | laptop | 0.123995 | 0.041831 | Full-page reference mismatch; table density/content differs intentionally. |\n| Debug controls/header | `noir-debug-controls-header` | laptop | 0.148460 | 0.055652 | Full-page reference mismatch; header chrome is comparable. |\n| Shell | `shell` | wide | 0.079896 | 0.037638 | Panel story vs full-layout Karax shell state; metric is not a parity signal. |\n| REPL | `repl` | laptop | 0.073845 | 0.032278 | Panel story vs full-layout Karax REPL state; metric is directional only. |\n| Low-level code | `low-level-code` | laptop | 0.073199 | 0.030190 | Panel story vs full-layout Karax low-level state; metric is directional only. |\n| No source | `no-source` | laptop | 0.092624 | 0.020209 | Panel story vs full-layout Karax no-source state; metric is directional only. |\n| Welcome | `welcome` | wide | 0.067437 | 0.011610 | Good standalone match; remaining delta is mostly typography/spacing. |\n| Step list | `step-list` | wide | 0.088317 | 0.037435 | Panel story vs full-layout Karax step-list state; metric is directional only. |\n\n## Top Remaining Deltas\n\n1. Several Karax references are full-page `2161x3766` captures while current\n Storybook is viewport-framed. These need either custom-size capture support or\n new reference captures before RMSE/MAE can be treated as parity gates.\n2. Shell, REPL, low-level, no-source, and step-list currently compare panel\n stories against full-layout Karax states. Full-layout Storybook variants would\n make these measurable in the same way as the Noir default variants.\n3. The current IsoNim default layout intentionally shows richer editor syntax,\n calltrace rows, terminal/event-log rows, and populated panel behavior. These\n content differences should not be patched back to the older Karax state.\n4. The remaining meaningful layout deltas are small chrome differences in tabs,\n status/menu treatment, scroll positions, and text wrapping rather than missing\n surfaces.\n","isInternal":false,"tokens":1427,"sizeBytes":5610},{"name":"project-visual-brief.md","path":"tools/visual-review/project-visual-brief.md","rawUrl":"https://raw.githubusercontent.com/metacraft-labs/codetracer/HEAD/tools/visual-review/project-visual-brief.md","title":"Visual-review Skill","category":"anthropic-skill","format":"markdown","content":"# CodeTracer Storybook Visual Brief\n\nCodeTracer is a debugging and replay UI for inspecting recorded program\nexecution. The Storybook surfaces must render the production IsoNim DOM with\nthe same CSS and shell context as the Electron app, so isolated panel review can\ncatch visual regressions before full GUI tests.\n\nThe important rule is that Storybook may mock ViewModel data, but it must not\nmock or reimplement component DOM. Storybook stories should call the real\nIsoNim ViewModel constructors and `src/frontend/viewmodel/views/*.nim` render\nor mount functions.\n\n## Shared Design Goals\n\n- Match the dark CodeTracer Electron UI from `src/frontend/index.html`.\n- Use the app CSS from `frontend/styles/default_dark_theme_electron.css`.\n- Preserve the app shell context: `#root-container`, `#auto-hide-layout-row`,\n `#ROOT`, `.session-container`, and `#main`.\n- Panels should look like CodeTracer work surfaces, not generic Storybook\n cards.\n- Text should be legible, clipped content should be intentional, and images or\n icons should not be broken.\n\n## What Must Not Happen\n\n- Missing app CSS links in the Storybook iframe.\n- Bare unstyled HTML controls.\n- Storybook-local colors/fonts overriding CodeTracer CSS.\n- DOM mounted outside the app shell when the production selector depends on\n app-shell ancestors.\n- Broken asset URLs under `/public/resources` or `/public/third_party`.\n","isInternal":false,"tokens":304,"sizeBytes":1388},{"name":"reference-coverage.md","path":"tools/visual-review/reference-coverage.md","rawUrl":"https://raw.githubusercontent.com/metacraft-labs/codetracer/HEAD/tools/visual-review/reference-coverage.md","title":"Visual-review Skill","category":"anthropic-skill","format":"markdown","content":"# Storybook Reference Coverage\n\n\n\n\nThis file tracks Karax reference captures used for IsoNim visual parity work.\nGenerated screenshots, HTML dumps, and computed-style dumps are intentionally\nkept out of this repository; the rows below point to the local reference\nworktree artifacts that agents should compare against.\n\nPaths are given relative to the reference-dump root, written below as\n`$CT_REFERENCE_DUMPS`. It defaults to `ui-tests/reference-dumps/` inside the\ncheckout and can be pointed at a local capture worktree instead — the same\nvariable `src/tests/gui/tests/session-chrome/new-trace-caption-chrome.spec.ts`\nreads. The captures themselves are not distributed with the repository, so an\nunset root simply means the reference-fact diagnostics stay empty.\n\n## Reference Sets\n\n- Full default/scratchpad/terminal baseline:\n `$CT_REFERENCE_DUMPS/isonim-karax-reference-20260504T155511Z/`\n- Expanded panel baseline:\n `$CT_REFERENCE_DUMPS/isonim-karax-reference-20260504T220906Z/`\n- Expanded panel baseline with isolated layout config:\n `$CT_REFERENCE_DUMPS/isonim-karax-reference-20260504T222307Z/`\n\nSome old Karax panels were less developed than current IsoNim surfaces. Use\nthese references for mature shell, Golden Layout, design-system class, and\nspacing contracts. Do not downgrade richer current IsoNim behavior to match an\nold empty, blocked, or partial Karax state.\n\n## Current Storybook Audit\n\nLast audited: 2026-05-05 on `codetracer-viewmodel`.\n\nCurrent Storybook views are discovered with:\n\n```sh\nnix shell nixpkgs#nodejs --command node tools/visual-review/capture-storybook.mjs --list-views --no-build\n```\n\nThe generated list includes all real IsoNim panel stories exported through\n`mountCodeTracerStory`, plus structure stories for session tabs, menu/status\nshells, debug shell, auto-hide controls, and default/app-shell layouts. The\ncapture tool also exposes source-slug aliases for `deepreview` and\n`agent-activity-deepreview`, in addition to Storybook's display-name slugs\n`deep-review` and `agent-activity-deep-review`; `status` aliases the\n`status-shell` component story.\n\nRepresentative partial/missing-reference surfaces were captured successfully at\n`laptop` size on 2026-05-05:\n\n| Surface | Current Storybook view | Current status |\n| --- | --- | --- |\n| Point list | `point-list` | confirmed current IsoNim panel, `tools/visual-review/reports/point-list-laptop.json` |\n| Timeline | `timeline` | confirmed current IsoNim panel, `tools/visual-review/reports/timeline-laptop.json` |\n| Flow | `flow` | confirmed current IsoNim panel with populated steps, `tools/visual-review/reports/flow-laptop.json` |\n| VCS | `vcs` | confirmed current IsoNim panel, `tools/visual-review/reports/vcs-laptop.json` |\n| Request panel | `request-panel` | confirmed current IsoNim panel, `tools/visual-review/reports/request-panel-laptop.json` |\n| Build errors | `errors` | confirmed current IsoNim problems/build-errors panel, `tools/visual-review/reports/errors-laptop.json`; `noir-build-open` also confirms the panel tab in a default layout |\n| Deep review panel | `deepreview` | confirmed current IsoNim panel, `tools/visual-review/reports/deepreview-laptop.json` |\n| Agent activity deep review | `agent-activity-deepreview` | confirmed current IsoNim panel, `tools/visual-review/reports/agent-activity-deepreview-laptop.json` |\n| Auto-hide bottom strip | `auto-hide-bottom-strip` | confirmed current IsoNim component, `tools/visual-review/reports/auto-hide-bottom-strip-laptop.json` |\n| Auto-hide collapsed icons | `auto-hide-collapsed-icons` | confirmed current IsoNim component, `tools/visual-review/reports/auto-hide-collapsed-icons-laptop.json` |\n| Auto-hide overlay tabs | `auto-hide-overlay-tabs` | confirmed current IsoNim component, `tools/visual-review/reports/auto-hide-overlay-tabs-laptop.json` |\n| Auto-hide side strip | `auto-hide-side-strip` and `auto-hide-side-strip-collapsed` | confirmed populated and collapsed current IsoNim variants |\n| Session tabs | `session-tabs` | confirmed current IsoNim component, `tools/visual-review/reports/session-tabs-laptop.json` |\n| Default layout variants | `default-layout`, `standalone-app-shell`, `noir-filesystem-active`, `noir-state-active`, `noir-calltrace-active`, `noir-calltrace-search-status-report`, `noir-menu-view-open`, `noir-status-expanded` | confirmed current layout stories; use a non-default `--port` if another static server is already bound to `6106` |\n\nCurrent confirmation does not change the old reference status below. Rows marked\n`blocked`, `partial`, or `missing` still mean the old Karax reference capture is\nblocked, partial, or absent; the current IsoNim story can still be valid and\ncapturable.\n\nLatest mature-state screenshot delta report:\n`tools/visual-review/mature-karax-visual-delta-20260505.md`.\n\n## Coverage Matrix\n\n| Surface | Reference status | Reference capture |\n| --- | --- | --- |\n| Default layout | captured | `20260504T160311Z_noir-electron-rendered` |\n| Scratchpad visible | captured | `20260504T160414Z_noir-scratchpad-visible` |\n| Terminal visible | captured | `20260504T160434Z_noir-terminal-visible` |\n| Filesystem active | captured | `20260504T220916Z_noir-filesystem-active` |\n| State active | captured | `20260504T220918Z_noir-state-active` |\n| Calltrace active | captured | `20260504T220919Z_noir-calltrace-active` |\n| Calltrace search status | captured | `20260504T220922Z_noir-calltrace-search-status-report` |\n| Agent activity active | captured | `20260504T220923Z_noir-agent-activity-active` |\n| Menu open | captured | `20260504T220925Z_noir-menu-view-open` |\n| Status expanded | captured | `20260504T220927Z_noir-status-expanded` |\n| Search results | captured | `20260504T222338Z_noir-search-results-karax-populated`; preserve newer IsoNim functionality if richer |\n| Fixed search | captured | `20260504T222336Z_noir-fixed-search-karax-visible` |\n| Point list | blocked | `20260504T220950Z_noir-point-list-open`; Karax raised unexpected `PointList` content |\n| Step list | captured | `20260504T220952Z_noir-step-list-open` |\n| Timeline | blocked | `20260504T222349Z_noir-timeline-blocked-no-factory`; Karax lacked a usable component factory |\n| Trace log | captured | `20260504T222329Z_noir-trace-log-karax-open` |\n| Build | captured | `20260504T222317Z_noir-build-karax-open`; preserve newer IsoNim output behavior if richer |\n| Build errors | partial | `20260504T222538Z_noir-build-errors-karax-open-attached` and `20260504T222734Z_noir-build-errors-karax-direct-id0`; Karax content stayed empty |\n| Shell | captured | `20260504T221002Z_noir-shell-open` |\n| REPL | captured | `20260504T222331Z_noir-repl-karax-open` |\n| Low-level code | captured | `20260504T222333Z_noir-low-level-code-karax-open` |\n| No source | captured | `20260504T222334Z_noir-no-source-karax-open` |\n| Command palette | captured | `20260504T222339Z_noir-command-palette-karax-open` |\n| Debug controls/header | captured | `20260504T222314Z_noir-debug-controls-header` |\n| Agent workspace | captured | `20260504T222341Z_noir-agent-workspace-karax-open`; preserve newer IsoNim behavior if richer |\n| Agent activity deep review | captured | `20260504T222342Z_noir-agent-activity-deepreview-karax-open`; preserve newer IsoNim behavior if richer |\n| Deep review panel | partial | `20260504T222344Z_noir-deepreview-panel-karax-open-empty` and `20260504T222427Z_deepreview-standalone-karax-sample`; old Karax state was underdeveloped |\n| Flow | partial | `20260504T222348Z_noir-flow-select-attempt`; old frontend raised missing `ct/load-flow` response-kind handling |\n| VCS | missing | No old panel implementation found |\n| Request panel | missing | No old panel implementation found |\n| Welcome screen | captured | `20260504T221201Z_welcome-screen` |\n\n## Current Workflow\n\n1. Capture current Storybook for a matching story with\n `tools/visual-review/capture-storybook.mjs --view --size laptop`.\n Use repeated `--view` flags or `--views a,b,c` for batch captures. If the\n default port is occupied, pass `--port `.\n2. Compare HTML and computed-style dumps against the reference capture with the\n same surface name.\n3. Compare screenshots with `tools/visual-review/compare-screenshots.sh` when\n the reference capture is marked `captured`.\n4. Patch the real IsoNim view/style/story shell, not a parallel mock.\n5. Update this matrix when new reference captures become available.\n","isInternal":false,"tokens":2152,"sizeBytes":8500}],"systemPromptSnippet":"\n\n# Instructions for Codex\n\n## Where a checkout — or a worktree — has to live\n\n**A checkout of this repo must sit DIRECTLY under the workspace root, beside its\nsibling repos.** A `git worktree` is a checkout and this rule is not relaxed for\nit: put worktrees at `/`, never at `/.agent-wt/`\nor in any other subdirectory, and never outside the workspace.\n\n```\n/path/to/workspace/ # the workspace root\n codetracer/ # the main checkout\n my-feature/ # CORRECT — a worktree, beside the siblings\n isonim/ runquota/ nim-agents/ codetracer-trace-format/ ...\n .agent-wt/\n my-feature/ # WRONG — its parent is `.agent-wt`, which has no siblings\n```\n\nThe reason is that **the parent directory of the checkout IS the workspace root,\nby definition**, for four independent resolvers that reach siblings by the\nrelative path `../`:\n\n| resolver | where | how it fails from the wrong place |\n| --- | --- | --- |\n| Nim | `config.nims` (`repoRoot.parentDir()`), `src/Tuprules.tup` (`$(ROOT)/../…`) | `--path` to a missing dir is silently ignored → `cannot open file: runquota_process`, minutes in |\n| Cargo | `src/db-backend/Cargo.toml` (`path = \"../../../codetracer-trace-format/…\"`) | `failed to load manifest` |\n| cc | `src/db-backend/build.rs` (`../../../codetracer-native-recorder/ct_emulator`) | 81 undefined `mcr*` symbols at link |\n| Repro/Nix | `repro.nim` and native workspace input overrides (`../io-mon`, `../reprobuild`, …) | sibling overrides cannot be resolved |\n\nNone of the four can be pointed elsewhere per-worktree, so relocating the\ncheckout is the only fix. In particular **`runquota` has no override at all** by\ndesign — see the tier notes in `scripts/require-siblings.sh` — so no environment\nvariable can paper over a badly-placed worktree.\n\nCreate one like this, from the main checkout:\n\n```bash\ngit -C /path/to/workspace/codetracer worktree add /path/to/workspace/ \n```\n\nand move a misplaced one like this:\n\n```bash\ngit worktree move /path/to/workspace/.agent-wt/ /path/to/workspace/\n```\n\n`scripts/require-siblings.sh` runs before every build (`just build-once`,\n`just build`, `just test-gui`, …) and refuses a badly-placed checkout by name.\n**Do not answer it with `CODETRACER_SKIP_SIBLING_CHECK=1`**: that escape hatch is\nfor genuinely different layouts (vendored trees, Nix builds that pre-stage the\npaths). Used here it only removes the message — the build still cannot see the\nsiblings and dies later naming a *module* instead of the real problem.\n\n## Building the full frontend (Nim + Electron)\n\nTo rebuild the full CodeTracer frontend (Nim backend CLI, Nim renderer JS, webpack bundles):\n\n```\njust build-once\n```\n\nThis runs tup (incremental build) and webpack. Use this after modifying any `.nim` files in\n`src/ct/`, `src/frontend/`, or `src/common/`.\n\n## Building the db-backend\n\n```\n# inside src/db-backend\ncargo build\n```\n\n## Running tests\n\n```\n# inside src/db-backend\ncargo test\n```\n\n## Running the linter\n\n```\n# inside src/db-backend\ncargo clippy\n```\n\nDon't disable the lint: try to fix the code instead first!\n\n## Running Playwright e2e tests\n\n```\n# From the repo root (needs Xvfb or a display)\njust test-e2e\n```\n\nThe Playwright tests live in `tsc-ui-tests/`. They launch the real Electron app via the `ct`\nbinary at `src/build-debug/bin/ct`. If you modify frontend Nim code, run `just build-once`\nfirst to rebuild the frontend before running the tests.\n\n## Running the cross-language ct_test provider tests\n\n```\n# From inside the dev shell (provides nim + the gtest/catch2/cmake/ninja\n# toolchain and the CMAKE_PREFIX_PATH / CT_TEST_C{C,XX} the C/C++ providers need)\njust test-ct-providers\n```\n\nThis runs the cross-language `ct_test` provider suites (C/C++ GoogleTest/Catch2/CTest, M11\nnative, M12 fallback, JavaScript, Ruby) plus the framework gate tests. It first builds the\nnative (`ct-mcr`), JavaScript and Ruby recorder siblings in their own pinned dev shells\n(`repro exec -- just build`, via `scripts/build-siblings.sh`) so the recording tests run\nagainst real recorders; a missing or failed required sibling fails loudly rather than skipping\n(per `codetracer-specs/Working-with-the-CodeTracer-Repos.md` Part 2). Useful overrides:\n\n- `CT_PROVIDERS_SKIP_SIBLINGS=1` — reuse already-built recorders, skip the sibling build step.\n- `CT_PROVIDERS_ALLOW_MISSING=1` — run the suites even if a required recorder sibling is\n missing/unbuildable (the recording tests then fail honestly instead of aborting up front).\n\nThe recorder binaries are discovered via PATH / the documented env vars\n(`CODETRACER_CT_MCR_CMD`, `CODETRACER_JS_RECORDER_PATH`, `CODETRACER_RUBY_RECORDER_PATH`) by\n`scripts/detect-siblings.sh`. See `ci/test/ct-providers.sh`.\n\n## Windows local setup (non-Nix)\n\nFor Windows development (both x64 and ARM64), use the DIY bootstrap:\n\n### Activate environment (auto-installs tools on first run)\n```bash\n# Git Bash / MSYS2\nsource env.sh\n\n# PowerShell\n. .\\env.ps1\n```\n\n### Optional skip flags\nComponents can be skipped via environment variables (e.g. for satellite repos\nthat only need a subset):\n- `WINDOWS_DIY_SKIP_NARGO=1` — skip Noir compiler\n- `WINDOWS_DIY_SKIP_CT_REMOTE=1` — skip ct-remote desktop client\n- `WINDOWS_DIY_ENSURE_TTD=0` — skip TTD/WinDbg validation\n\n### Build commands (Windows)\n```bash\n# Rust components\ncd src/db-backend && cargo build && cargo test && cargo clippy\ncd src/tui && cargo build && cargo test\ncd src/backend-manager && cargo build\n\n# Full frontend (Nim + Tup)\ncd src/build-debug && source ../../env.sh && tup upd\n```\n\n### Version pins\nPinned tool versions are tracked in:\n```\nnon-nix-build/windows/toolchain-versions.env\n```\n\nFor detailed Windows porting progress, see `windows-porting-initiative-status.md`.\n\n## Nix dev shell and local flake overrides\n\nThe Repro shell hook activates the flake through `repro.nim`. Run `repro allow`\nonce for this checkout, then enter it with the hook installed. For an explicit\ncommand, use `repro exec /path/to/codetracer -- `.\n\nRepro resolves declared workspace siblings as native flake input overrides.\nKeep direnv denied; `.envrc` and the old override plugin are not required for\nthis activation path. Changes to the recipe require renewed Repro authorization.\n\n### Blockchain recorder tools (circom, forc)\n\nThe Nix dev shell supplies the toolchains declared by the CodeTracer flake.\nBuild recorder siblings through `scripts/build-siblings.sh`; each recorder's\n`repro.nim` activates its own pinned environment. See the helper's per-repository\nlogs when a required tool or sibling build fails.\n\n### Inspecting a Nix environment directly\n\nTo diagnose an individual flake input independently of shell activation, use an\nexplicit Nix invocation without changing direnv trust:\n\n```bash\nnix develop '.?submodules=1' --override-input nix-blockchain-development path:../nix-blockchain-development -c bash\n```\n\n### Cadence Go helper\n\nThe `detect-siblings.sh` script auto-builds `cadence-trace-helper` from\n`codetracer-flow-recorder/go-helper/` when the flow recorder sibling is\npresent and `go` is available. The built binary is exported via\n`CADENCE_HELPER_BIN` and added to PATH.\n\n# Keeping notes\n\nIn the `.agents/codebase-insights.txt` file, we try to maintain useful tips that may help\nyou in your development tasks. When you discover something important or surprising about\nthe codebase, add a remark in a comment near the relevant code or in the codebase-insights\nfile. ALWAYS remove older remarks if they are no longer true.\n\nYou can consult this file before starting your coding tasks.\n\n# Code quality guidelines\n\n- ALWAYS strive to achieve high code quality.\n- ALWAYS write secure code.\n- ALWAYS make sure the code is well tested and edge cases are covered. Design the code for testability and be extremely thorough.\n- ALWAYS write defensive code and make sure all potential errors are handled.\n- ALWAYS strive to write highly reusable code with routines that have high fan in and low fan out.\n- ALWAYS keep the code DRY.\n- Aim for low coupling and high cohesion. Encapsulate and hide implementation details.\n- When creating executable, ALWAYS make sure the functionality can also be used as a library.\n To achieve this, avoid global variables, raise/return errors instead of terminating the program, and think whether the use case of the library requires more control over logging\n and metrics from the application that integrates the library.\n\n# Code commenting guidelines\n\n- Document public APIs and complex modules using standard code documentation conventions.\n- Comment the intention behind your code extensively. Omit comments only for very obvious\n facts that almost any developer would know.\n- Maintain the comments together with the code to keep them meaningful and current.\n- When the code is based on specific formats, standards or well-specified behavior of\n other software, always make sure to include relevant links (URLs) that provide the\n necessary technical details.\n\n# Writing git commit messages\n\n- You MUST use multiline git commit messages.\n- Use the conventional commits style for the first line of the commit message.\n- Use the summary section of your final response as the remaining lines in the commit message.\n\n\n## system\n\nUI\n==\n\nUI is important.\n\nWe have most of our code in `ui/`.\n`ui_js.nim` is the main file.\nWe define the root view.\n\nMost of the components are defined in their own modules:\n\n* `calltrace` the calltrace, expanding and collapse\n* `chronology` the chronology and input\n* `colors` some constants\n* `debug` the debug toolbar\n* `editor` the main editor, uses Monaco\n* `events` support coloring the output code as in terminal\n* `flow` the preload ui\n* `history` the history ui which reuses the value ui\n* `inline_editor` uses monaco, the editor open for traces\n* `layout` the overall layout\n* `loading` the loading screen\n* `start` would be useful as default screen\n* `state` the state view with changing variables\n* `trace` the trace view: now we show traces inline, so maybe remove\n* `ui_imports` exports most dependencies for ui\n* `value` reused by views that show values or expand them\n\nImportant stuff:\n\n* Use direct style helpers for generated DOM and stylus for css files\n* You can watch debug output in the console\n* Monaco, datatables and charts have a custom DOM integration\n* Layouts can be loaded from files: look at `config.nim`, we have to fix this\n* We have themes: defined by variables in name_theme.styl\n* Redraw needs to be manual sometimes, especially after IPC listeners or direct DOM integrations\n* A lot of the helper code is in `types.nim`(types) or `lib.nim` (signatures for third party or our helpers)\n* We use `view` in the name of views to easily spot them, normal functions don't need it\n* When we're changing css, it's best to change the current code: remove literals and define them in defaults and theme styles, we might get the designer to color pick better colors and new themes\n* We use vex-js for dialogs\n* Please check id-s and classes if you remove them: we might need them for ui testing\n* test_base includes most of the logic for ui testing, we use spectron\n\nEvents\n\nYou define a callback in renderer and you update state.\nMost of our state is in the `data` global. It can certainly be optimized.\nWe maintain our panel in `sys`.\n\nWhen you need to talk with the server, you send a message using `ipc.send`.\nWe apply the \"CODETRACER::\" namespace. In a browser this is a socket message, in\nElectron we send it to the main process.\nThe main process responds, and usually you register a listener with ipcConfigure.\n\nYou can also define an async function which makes a promise which is resolved after a listener is called.\n\n\n\nTesting\n\n==\n\nWe have to fix the tests.\n\nHowever let's look at the three main sets:\n\n```bash\nexample-based/ nim.cfg programs/ quicktests/ README.md reproductions/ run/ Tupfile\n```\n\nIn `example-based` we have normal tests.\n\nIn `quicktests` we have property tests. Their results are sometimes added to `reproductions`.\n\nIn `run` we store the compiled tests.\n\nIn `programs` we have the example programs.\n\nWe also have tests for python commands: but I must find them, probably git.\n\nThis is an old note:\n\n```\ntests/quicktests/\n reproductions/\n quicktest_basename/\n repr_id.json\n\n failing tests that we eventually fixed\n random subset of succeeding tests\n\n make sure that stuff that worked before, still works\n and that stuff that is fixed is still fixed\n```\n\nEach test folder has lang tests. They are often similar, so I am not sure if we need to parametrize them.\nWe define most of the main logic in test_base.\n\nWe also have `nim-ui` in `example-based` and `quicktests`.\nThey are based on Spectron.\n\nThey use a dsl, so you don't need to always access elements manually.\nIf you need to, please write a helper which can be reused.\n\n==\n\nDebugger\n\n==\n\nWe are working with rr here. RR provides most of our low level functionality.\n\nWe use gdb-js, a custom fork of the original repo with minor differences: several helpers.\n\nMost of the code is in `debugger/`\n\nThe base types are either in `types` and `core` usually.\n\nWe have a `Pool` which is currently only one.\nA `Pool` has a list of `Process` which are currently rr instances.\nBy default, we have a `stable` process which runs most of the usual steps.\nA `trace` process which runs trace debug, a `history` process which runs history search.\nA `preload` process which preloads future values and `args_preload` which preloads args.\nWe also have `prestart` process which starts in the beginning and loads chronology: mostly writes and reads for now.\n\nLet's take a look:\n\n* `args_preloader` defines `loadCallTraceArgs` which loads args\n* `core` contains shared logic and types for the debugger\n* `debugger` is the central module\n* `flow_preloader` defines the preloading code\n* `history` defines the history code\n* `move` runs most of the jumps\n* `process_gdb` is where most of our helpers and other shortcuts live\n* `py_command` is a wrapper around our python commands giving a type safe API\n* `scheduler` was an experiment in mirroring stable steps in preload\n* `sync_preload` is used to sync the preload process to the stable process\n\nWe also have `cgdb` which should eventually deal with gdb as a pure nim solution and give as a way to rewrite debugger with the C backend.\n\nBasically we define a pool in the beginning and the server sends initial data to it.\nAfter that the server starts the pre-start process which loads info while running the program\nand starts the other needed processes.\n\nThe stable process jumps to main and calls back the server so the ui can show the main program.\n\nWe have a listener for gdb events and use a system of JavaScript promises to await actions.\nThe problem is that an action usually ends before the info of the new location arrives, so we have our own\nhelpers in process_gdb which we should use.\n\nThe other bizarre part is the export api: it defines with a macro the debugger interface and generates export code for it. We expose a type to other modules, so they can call our functions in a type safe way.\nThe debugger module can be used directly (import) or in a different process. The second thing is usually better, as\nit can crash or block the main process.\n\nIt communicates using helpers and ipc send. This is also complicated internally as on desktop it uses electron, and on server `node-ipc` mapping the calls (probably).\n\nWe have some helpers to report errors and to load stuff from the server.\nA lot of the moves are basically taking arguments from the server , invoking typed functions which implement the logic\nand call python commands as primitives. Some actions periodically update the server , e.g. preloading.\n\nArgs preloading is a bit hard to optimize for bigger programs, so we have to work a bit on it: it visits all the call children of the current call and logs the args.\n\nFlow preloading can be slow: most of the logic is in Python commands. We try to limit the number of steps taken there\nand repeatedly call it , sending updates to the server until we are stopped by a new preloading context or finished.\n\nWe cache a lot of stuff like preload results, AST etc. Some of the caches are on function-level, some on filename-level etc.\n\nA lot of the logic is in Python commands: usually if something needs to use a series of gdb commands or to analyze in a more powerful way the program , we create a command, it's best if it is general enough to be reused in many actions.\n\nParsing the modules is good for preloading: we load the labels for each line.\n\nOverall\n==\n\n\nElectron:\n\nWe have several components.\n\nThe backend, the archive runner, the archive server, the shell support, codetracer, plugins, the commands, language forks, the server, the renderer and the debugger.\n\n\nCodetracer calls the server, a local database and Redis.\n\nThe server is the main Electron process which dispatches tasks and messages to the renderer and the debugger.\n\nIt also maintains a running plugin for the current language and communicates on stdout with json.\nIt communicates on the stdout with `nimsuggest` when in a Nim project too: we have to test if this is working now.\n\nThe plugins can parse expressions and modules: expressions are parsed as QueryNode which can be interpreted by our debugger, the modules as a language-unified AST.\n\nThe QueryNode-s are interpreted with the class Loader. We visit the nodes and map each one to a gdb expression, which most of the time accesses some kind of variable or a call which can start a rr fork.\n\nThe server currently assumes it has only one renderer. We have to parametrize it.\n\nNow, we map the messages to ipc on desktop and sockets in browser.\n\nThe renderer just talks with the server in all scenarios, for now we assume it's always a single project in a renderer.\n\nThe debugger also connects to the server for additional functionality: e.g. plugin call.\nIt maintains a sequence of RR debuggers with sockets and communicates with them using gdb-js either directly or with commands.\n\nThe python commands are loaded when the debugger starts: we also reuse the CPython gdb commands for Python.\nThey are executed only in a single RR process.\n\nThe telemetry is used for logging by me most of the time: it logs to the screen and in a file. In most of the code you can log using `event` or other shortcuts in `telemetry`. You can turn it off or on in `.config.yaml`, you can eventually share a structured log in `telemetry.log`. We probably can use nim-chronicles, but it has to be flexible enough and work on the JavaScript backend.\n\n\nPlugin communicator\n==\n\nPlugins are supposed to analyze language-specific things using the language tools.\nFor Nim, we just import the compiler.\nFor C++, currently we parse clang's dump output: we have to write a plugin in C++ which actually analyzes the AST, but I had some problems with the parser API: TODO.\n\n\n# Per-Screen Design Briefs for Visual Audit\n\nEach section describes exactly what must be visible, what data should be shown,\nand how to evaluate the screenshot against the CodeTracer design spec.\n\n---\n\n## Screen 1: Normal CodeTracer Layout (reference baseline)\n\n**Purpose**: Establish the reference baseline that all other screens are compared against.\n\n**Expected content**:\n\n- Toolbar: debugger step controls (forward, backward, continue icons)\n- Left: FILESYSTEM panel with file tree showing `source folders > codetracer > test-programs > py_console_logs > main.py`\n- Center: Editor tab `py_console_logs/main.py` with Python source code visible, line numbers, syntax highlighting (keywords in purple/blue, strings in green/orange)\n- Center-right: STATE panel showing \"Enter a watch expression\" input, SCRATCHPAD tab\n- Right: CALLTRACE panel with expandable call tree showing function names, AGENT ACTIVITY tab\n- Bottom-left: EVENT LOG panel with event rows (step index, line number, event text)\n- Bottom-right: TERMINAL OUTPUT panel with stdout/stderr output\n- Footer: Status bar with `Python(db) | UTF-8 | stable: ready | ` on the right, **BUILD | PROBLEMS | SEARCH RESULTS** labels on the right as auto-hide pane triggers\n- NO session tab bar (single trace)\n- NO gray empty areas — panels fill full window width\n\n**Evaluation**: This must look like a professional IDE. Compare against VS Code's dark theme for consistency.\n\n---\n\n## Screen 2: BUILD Auto-Hide Pane — Successful Build (happy path)\n\n**Purpose**: Show the BUILD pane expanded from the bottom with successful build output.\n\n**How to trigger**: Click the \"BUILD\" label in the status bar footer. The BUILD pane slides up as an overlay from the bottom.\n\n**Expected data to inject**:\n\n```\n$ nim c --sourcemap:on main.nim\nHint: used 42 lines of code\nHint: operation successful (0.8s)\nHint: [SuccessX]\n```\n\n**Expected appearance**:\n\n- BUILD overlay visible at bottom, full-width, ~30% window height\n- Overlay header: \"Build succeeded\" in GREEN text, with header controls (stop, clear, auto-scroll, duration \"0.8s\")\n- Build output lines in monospace font with ANSI colors rendered (green \"Hint:\" text)\n- \"Unpin\" button at top-right of overlay\n- The GL layout area above is still visible behind/above the overlay\n- Status bar \"BUILD\" label is highlighted (active state)\n\n---\n\n## Screen 3: BUILD Auto-Hide Pane — Failed Build (unhappy path)\n\n**Purpose**: Show BUILD pane with compiler errors, demonstrating error parsing and color coding.\n\n**Expected data to inject**:\n\n```\n$ cargo build\nerror[E0308]: mismatched types\n --> src/main.rs:42:5\n |\n42 | let x: bool = 42;\n | ^^ expected `bool`, found integer\n\nwarning: unused variable: `y`\n --> src/main.rs:10:9\n\nerror: aborting due to previous error\n```\n\n**Expected appearance**:\n\n- Overlay header: \"Build failed (exit code 1)\" in RED text\n- Error lines: red text (#f85149), clickable (underline on hover)\n- Warning lines: yellow text (#d29922)\n- File locations (`src/main.rs:42:5`) underlined and clickable\n- ANSI colors rendered — \"error\" in red, \"warning\" in yellow, \"-->\" in blue\n- Arrow indicators and code snippets visible in monospace\n\n---\n\n## Screen 4: PROBLEMS Auto-Hide Pane with Parsed Errors\n\n**Purpose**: Show the PROBLEMS pane with structured error list from the failed build.\n\n**Expected data**: 2 errors + 1 warning:\n\n- ERROR: src/main.rs:42:5 — \"mismatched types: expected `bool`, found integer\"\n- ERROR: src/main.rs:55:12 — \"cannot find value `undefined_var` in this scope\"\n- WARNING: src/main.rs:10:9 — \"unused variable: `y`\"\n\n**Expected appearance**:\n\n- Overlay header: \"3 problems (2 errors, 1 warning)\" with filter buttons [All] [Errors] [Warnings]\n- Error rows: red circle icon (●), file path in dim color, line:col, error message\n- Warning row: yellow triangle icon (▲), same format\n- Rows clickable with pointer cursor\n- Grouped by file if \"Group by File\" is toggled\n\n---\n\n## Screen 5: SEARCH RESULTS Auto-Hide Pane with Results\n\n**Purpose**: Show search results grouped by file with match highlighting.\n\n**Expected data**: Search for \"print\" with 4 results across 2 files:\n\n- src/main.py:10 — `def print_to_stdout() -> None:`\n- src/main.py:15 — `print(\"hello world\")`\n- src/main.py:51 — `print(\"1. print using print('text')\")`\n- src/utils.py:3 — `from io import print_function`\n\n**Expected appearance**:\n\n- Overlay header: \"4 results for 'print'\"\n- Results grouped by file: `src/main.py (3)` header, then 3 match rows\n- Then `src/utils.py (1)` header, 1 match row\n- Each row: line number on left, text with \"print\" highlighted in amber/yellow\n- Clickable rows for navigation\n\n---\n\n## Screen 6: Auto-Hide Left — FILESYSTEM Pinned with Overlay Open\n\n**Purpose**: Show left auto-hide strip with FILESYSTEM panel overlay.\n\n**Expected appearance**:\n\n- Thin vertical strip (~28px) on the left edge with vertical text \"FILESYSTEM\"\n- Strip is TILED beside GL (not overlaying) — GL content starts after the strip\n- Overlay panel slides in from left showing the FILESYSTEM file tree\n- File tree shows `source folders > codetracer > test-programs > py_console_logs > main.py`\n- \"Unpin\" button at top-right of overlay\n- Overlay content is LIVE (real file tree, not placeholder)\n\n---\n\n## Screen 7: Multi-Tab Mode — Two Traces Loaded\n\n**Purpose**: Show the session tab bar with multiple traces.\n\n**Expected appearance**:\n\n- Session tab bar visible ABOVE the GL panels (between toolbar and GL)\n- Two tabs: first trace name (e.g., \"py_console_logs/main.py\"), second tab (e.g., \"Trace 2\")\n- Active tab highlighted with different background\n- \"+\" button at the right end to add new trace\n- GL layout below shows the active trace's panels\n- All panels show data from the ACTIVE trace\n\n---\n\n## Screen 8: DeepReview Standard Layout\n\n**Purpose**: Show DeepReview mode using the standard CodeTracer GL layout with changed files.\n\n**Expected appearance (per DeepReview-GUI.md spec)**:\n\n- FILESYSTEM panel shows changed files with diff badges: M main.rs (+8/-3), A utils.rs (+8/-0), D config.rs (+0/-7)\n- Colors: M=orange, A=green, D=red\n- Editor area shows the first file's content with diff decorations (green lines for additions)\n- All standard panels present: STATE, CALLTRACE, EVENT LOG, etc.\n- **Must look like the normal CodeTracer layout** (Screen 1) with only the FILESYSTEM content changed and diff decorations in the editor\n- NO separate \"DeepReview\" panel or monolithic component\n\n**Comparison**: The reviewer should compare this against Screen 1 (normal layout) and verify that ONLY the FILESYSTEM content and editor decorations changed — everything else is identical.\n\n---\n\n## Evaluation Criteria (applied to ALL screens)\n\n1. **Full-width**: Panels must fill the entire window width. NO gray empty areas.\n2. **Dark theme**: Background #1e1e1e, panels #252526, borders #3c3c3c, text #cccccc\n3. **Font consistency**: Monospace for code/output, system sans-serif for UI labels\n4. **Professional polish**: Looks like VS Code / JetBrains, not a prototype\n5. **Auto-hide overlays**: Flush with window edge, full-width for bottom, full-height for sides\n6. **Status bar**: Always visible at bottom with auto-hide labels (BUILD, PROBLEMS, SEARCH RESULTS)\n7. **No broken elements**: No overlapping text, no clipped content, no invisible elements\n\n**Rating scale**: 1-3 broken, 4-5 rough, 6-7 good, 8-9 near-shipping, 10 perfect\n**Target**: All screens must reach 7/10 minimum.\n\n\n# Build Panel Story Visual Brief\n\n## What You're Reviewing\n\nThis is the CodeTracer Build panel rendered in Storybook through the real\nIsoNim Build view.\n\nShared project brief: `../project-visual-brief.md`\n\n## Screen\n\n- Route: Storybook iframe story `codetracer-panels--build`\n- Capture id: `storybook-build-panel`\n- Viewport: laptop, 1440x900\n\n## Seeded State\n\nThe fixture shows a failed `nargo test` build with stdout, stderr, and parsed\nproblem rows.\n\n## Expected Visible Content\n\n- Dark CodeTracer app background and app font styling.\n- Build header/status controls styled like the app.\n- Compiler output lines with error/warning colors.\n- Clickable source-location styling for `src/combat.nr:42`.\n\n## Must Not Show\n\n- Unstyled default buttons or form controls.\n- Missing CodeTracer color palette.\n- Text overlapping the header controls.\n- A bare list of lines with no panel structure.\n\n## What to Evaluate\n\nFocus on whether the app CSS is matching the real DOM, and whether the panel\nlooks like a real CodeTracer bottom/side panel rather than a mock.\n\n## How to Report\n\nKeep under 200 words. Lead with an overall impression, list specific visual\nissues, then give the top two fixes. Include a 1-10 rating.\n\n\n# Default Layout Story Visual Brief\n\n## What You're Reviewing\n\nThis is the Storybook default IsoNim app-shell layout story. It exercises\nmultiple real panel views together in the standalone IsoNim shell.\n\nShared project brief: `../project-visual-brief.md`\n\n## Screen\n\n- Route: Storybook iframe story `codetracer-layouts--default-debug`\n- Capture id: `storybook-default-layout`\n- Viewport: laptop, 1440x900\n\n## Seeded State\n\nThe fixture includes a Karax-reference-shaped Golden Layout debugging workspace\nwith Filesystem, Editor, State/Scratchpad, Calltrace/Agent Activity, and Event\nLog/Terminal Output stacks. Visible panels are real IsoNim views; inactive tabs\nshould remain present in the DOM but hidden like the Karax reference.\n\n## Expected Visible Content\n\n- Dark CodeTracer app styling loaded in the iframe.\n- Golden Layout panel headers, grouped tabs, splitters, and content cells should\n be visible.\n- Multiple real IsoNim panels should look like CodeTracer surfaces, not browser defaults.\n- The layout should use the Karax shell framing: dark body, top-offset\n root-container, `#ROOT`, empty `#main`, and GoldenLayout immediately under\n `#ROOT`.\n\n## Must Not Show\n\n- Blank screen.\n- White background or generic Storybook styling dominating the view.\n- Panels clipped to unusably small fragments.\n- Missing CSS resources or broken image icons.\n\n## What to Evaluate\n\nEvaluate shell context, spacing, panel sizing, typography, color, and whether\nthe surface is useful for visual parity work.\n\n## How to Report\n\nKeep under 200 words. Lead with an overall impression, list specific visual\nissues, then give the top two fixes. Include a 1-10 rating.\n\n\n# Terminal Output Story Visual Brief\n\n## What You're Reviewing\n\nThis is the CodeTracer Terminal Output panel rendered in Storybook through the\nreal IsoNim Terminal Output view.\n\nShared project brief: `../project-visual-brief.md`\n\n## Screen\n\n- Route: Storybook iframe story `codetracer-panels--terminal-output`\n- Capture id: `storybook-terminal-output`\n- Viewport: laptop, 1440x900\n\n## Seeded State\n\nThe fixture shows the Noir space-ship replay terminal transcript from the\nKarax terminal-visible reference. All lines are ahead of the current replay\nposition, matching the reference state.\n\n## Expected Visible Content\n\n- Dark CodeTracer app background and app font styling.\n- Terminal output panel with CodeTracer terminal row styling.\n- Dense terminal output including \"Positive Test Case\", shield status rows,\n and the final \"shields will not hold as expected\" line.\n- Future terminal fragments should use the same dimmed terminal row styling as\n the Karax reference.\n\n## Must Not Show\n\n- Generic browser serif fonts.\n- White Storybook or Bootstrap default panel background.\n- A tiny unstyled text block floating in empty space.\n- Missing app CSS or broken icon/resource requests.\n\n## What to Evaluate\n\nCheck whether app styles are actually applied, whether the panel sits in a\nCodeTracer-like shell context, and whether spacing, typography, contrast, and\nvisual hierarchy look like the real app.\n\n## How to Report\n\nKeep under 200 words. Lead with an overall impression, list specific visual\nissues, then give the top two fixes. Include a 1-10 rating.\n\n\n# Mature Karax Visual Delta Report - 2026-05-05\n\n\n\nBranch: `codetracer-viewmodel`\n\n## Method\n\n- Storybook was rebuilt with\n `nix shell nixpkgs#nodejs --command bash -lc 'just storybook-build'`.\n- Current Storybook stories were captured with\n `tools/visual-review/capture-storybook.mjs`.\n- `wide` (`1920x1080`) was used for Karax references captured at `1920x1080`.\n- `laptop` (`1440x900`) was used for the older full-page Karax references\n captured as `2161x3766`; those metrics are useful for trend tracking but are\n dominated by viewport/full-page framing.\n- Screenshot metrics were generated with `tools/visual-review/compare-screenshots.sh`,\n which resizes the reference image to the current capture before computing RMSE/MAE.\n- Generated captures, dumps, and diff images remain ignored under\n `tools/visual-review/{screenshots,reports,compare,dumps}`.\n\n## Summary\n\nThe mature Karax states now have matching capturable Storybook stories. The\nclosest comparisons are the `1920x1080` default Noir layout variants: their\nlargest remaining deltas are mostly intentional richer IsoNim content, not empty\nor broken rendering. The older full-page references and panel-only current\nstories are documented separately because their RMSE/MAE numbers are dominated\nby app-frame and viewport mismatch.\n\nNo small shell/chrome/CSS fix was applied in this pass; the visible differences\nthat remain would require either new full-layout stories for panel-only states or\ndeliberate content downgrades, which this audit avoided.\n\n## Per-Surface Results\n\n| Surface | Current story | Viewport | RMSE | MAE | Status |\n| --- | --- | --- | ---: | ---: | --- |\n| Default layout | `default-layout` | laptop | 0.148885 | 0.056060 | Framing-dominated; current shell is populated and richer. |\n| Terminal | `terminal-output` | laptop | 0.098892 | 0.028241 | Panel story vs full-layout Karax terminal state; metric is directional only. |\n| Scratchpad | `scratchpad` | laptop | 0.098082 | 0.029454 | Panel story vs full-layout Karax scratchpad state; metric is directional only. |\n| Filesystem active | `noir-filesystem-active` | wide | 0.100905 | 0.025215 | Good app-frame match; richer editor/calltrace/event rows dominate. |\n| State active | `noir-state-active` | wide | 0.100905 | 0.025215 | Same base Karax/current pixels as filesystem active; focus change is not visibly distinct. |\n| Calltrace active | `noir-calltrace-active` | wide | 0.100905 | 0.025215 | Same base Karax/current pixels as filesystem active; richer calltrace text dominates. |\n| Calltrace search/status | `noir-calltrace-search-status-report` | wide | 0.106128 | 0.026938 | Good app-frame match; current calltrace/search content is denser. |\n| Menu open | `noir-menu-view-open` | wide | 0.074298 | 0.018578 | Good app-frame match; menu/status shell differences are localized. |\n| Status expanded | `noir-status-expanded` | wide | 0.072659 | 0.018013 | Best layout match in this batch; status and agent panel richness remain. |\n| Fixed search | `noir-fixed-search-visible` | laptop | 0.168908 | 0.057116 | Full-page reference mismatch; current search shell is richer. |\n| Search results | `noir-search-results-populated` | laptop | 0.170998 | 0.060999 | Full-page reference mismatch plus richer current search result content. |\n| Command palette | `noir-command-palette-open` | laptop | 0.094881 | 0.058993 | Full-page reference mismatch; overlay shape/content comparable. |\n| Build | `noir-build-open` | laptop | 0.134460 | 0.048930 | Full-page reference mismatch; current build output behavior is richer. |\n| Trace log | `noir-trace-log-open` | laptop | 0.123995 | 0.041831 | Full-page reference mismatch; table density/content differs intentionally. |\n| Debug controls/header | `noir-debug-controls-header` | laptop | 0.148460 | 0.055652 | Full-page reference mismatch; header chrome is comparable. |\n| Shell | `shell` | wide | 0.079896 | 0.037638 | Panel story vs full-layout Karax shell state; metric is not a parity signal. |\n| REPL | `repl` | laptop | 0.073845 | 0.032278 | Panel story vs full-layout Karax REPL state; metric is directional only. |\n| Low-level code | `low-level-code` | laptop | 0.073199 | 0.030190 | Panel story vs full-layout Karax low-level state; metric is directional only. |\n| No source | `no-source` | laptop | 0.092624 | 0.020209 | Panel story vs full-layout Karax no-source state; metric is directional only. |\n| Welcome | `welcome` | wide | 0.067437 | 0.011610 | Good standalone match; remaining delta is mostly typography/spacing. |\n| Step list | `step-list` | wide | 0.088317 | 0.037435 | Panel story vs full-layout Karax step-list state; metric is directional only. |\n\n## Top Remaining Deltas\n\n1. Several Karax references are full-page `2161x3766` captures while current\n Storybook is viewport-framed. These need either custom-size capture support or\n new reference captures before RMSE/MAE can be treated as parity gates.\n2. Shell, REPL, low-level, no-source, and step-list currently compare panel\n stories against full-layout Karax states. Full-layout Storybook variants would\n make these measurable in the same way as the Noir default variants.\n3. The current IsoNim default layout intentionally shows richer editor syntax,\n calltrace rows, terminal/event-log rows, and populated panel behavior. These\n content differences should not be patched back to the older Karax state.\n4. The remaining meaningful layout deltas are small chrome differences in tabs,\n status/menu treatment, scroll positions, and text wrapping rather than missing\n surfaces.\n\n\n# CodeTracer Storybook Visual Brief\n\nCodeTracer is a debugging and replay UI for inspecting recorded program\nexecution. The Storybook surfaces must render the production IsoNim DOM with\nthe same CSS and shell context as the Electron app, so isolated panel review can\ncatch visual regressions before full GUI tests.\n\nThe important rule is that Storybook may mock ViewModel data, but it must not\nmock or reimplement component DOM. Storybook stories should call the real\nIsoNim ViewModel constructors and `src/frontend/viewmodel/views/*.nim` render\nor mount functions.\n\n## Shared Design Goals\n\n- Match the dark CodeTracer Electron UI from `src/frontend/index.html`.\n- Use the app CSS from `frontend/styles/default_dark_theme_electron.css`.\n- Preserve the app shell context: `#root-container`, `#auto-hide-layout-row`,\n `#ROOT`, `.session-container`, and `#main`.\n- Panels should look like CodeTracer work surfaces, not generic Storybook\n cards.\n- Text should be legible, clipped content should be intentional, and images or\n icons should not be broken.\n\n## What Must Not Happen\n\n- Missing app CSS links in the Storybook iframe.\n- Bare unstyled HTML controls.\n- Storybook-local colors/fonts overriding CodeTracer CSS.\n- DOM mounted outside the app shell when the production selector depends on\n app-shell ancestors.\n- Broken asset URLs under `/public/resources` or `/public/third_party`.\n\n\n# Storybook Reference Coverage\n\n\n\n\nThis file tracks Karax reference captures used for IsoNim visual parity work.\nGenerated screenshots, HTML dumps, and computed-style dumps are intentionally\nkept out of this repository; the rows below point to the local reference\nworktree artifacts that agents should compare against.\n\nPaths are given relative to the reference-dump root, written below as\n`$CT_REFERENCE_DUMPS`. It defaults to `ui-tests/reference-dumps/` inside the\ncheckout and can be pointed at a local capture worktree instead — the same\nvariable `src/tests/gui/tests/session-chrome/new-trace-caption-chrome.spec.ts`\nreads. The captures themselves are not distributed with the repository, so an\nunset root simply means the reference-fact diagnostics stay empty.\n\n## Reference Sets\n\n- Full default/scratchpad/terminal baseline:\n `$CT_REFERENCE_DUMPS/isonim-karax-reference-20260504T155511Z/`\n- Expanded panel baseline:\n `$CT_REFERENCE_DUMPS/isonim-karax-reference-20260504T220906Z/`\n- Expanded panel baseline with isolated layout config:\n `$CT_REFERENCE_DUMPS/isonim-karax-reference-20260504T222307Z/`\n\nSome old Karax panels were less developed than current IsoNim surfaces. Use\nthese references for mature shell, Golden Layout, design-system class, and\nspacing contracts. Do not downgrade richer current IsoNim behavior to match an\nold empty, blocked, or partial Karax state.\n\n## Current Storybook Audit\n\nLast audited: 2026-05-05 on `codetracer-viewmodel`.\n\nCurrent Storybook views are discovered with:\n\n```sh\nnix shell nixpkgs#nodejs --command node tools/visual-review/capture-storybook.mjs --list-views --no-build\n```\n\nThe generated list includes all real IsoNim panel stories exported through\n`mountCodeTracerStory`, plus structure stories for session tabs, menu/status\nshells, debug shell, auto-hide controls, and default/app-shell layouts. The\ncapture tool also exposes source-slug aliases for `deepreview` and\n`agent-activity-deepreview`, in addition to Storybook's display-name slugs\n`deep-review` and `agent-activity-deep-review`; `status` aliases the\n`status-shell` component story.\n\nRepresentative partial/missing-reference surfaces were captured successfully at\n`laptop` size on 2026-05-05:\n\n| Surface | Current Storybook view | Current status |\n| --- | --- | --- |\n| Point list | `point-list` | confirmed current IsoNim panel, `tools/visual-review/reports/point-list-laptop.json` |\n| Timeline | `timeline` | confirmed current IsoNim panel, `tools/visual-review/reports/timeline-laptop.json` |\n| Flow | `flow` | confirmed current IsoNim panel with populated steps, `tools/visual-review/reports/flow-laptop.json` |\n| VCS | `vcs` | confirmed current IsoNim panel, `tools/visual-review/reports/vcs-laptop.json` |\n| Request panel | `request-panel` | confirmed current IsoNim panel, `tools/visual-review/reports/request-panel-laptop.json` |\n| Build errors | `errors` | confirmed current IsoNim problems/build-errors panel, `tools/visual-review/reports/errors-laptop.json`; `noir-build-open` also confirms the panel tab in a default layout |\n| Deep review panel | `deepreview` | confirmed current IsoNim panel, `tools/visual-review/reports/deepreview-laptop.json` |\n| Agent activity deep review | `agent-activity-deepreview` | confirmed current IsoNim panel, `tools/visual-review/reports/agent-activity-deepreview-laptop.json` |\n| Auto-hide bottom strip | `auto-hide-bottom-strip` | confirmed current IsoNim component, `tools/visual-review/reports/auto-hide-bottom-strip-laptop.json` |\n| Auto-hide collapsed icons | `auto-hide-collapsed-icons` | confirmed current IsoNim component, `tools/visual-review/reports/auto-hide-collapsed-icons-laptop.json` |\n| Auto-hide overlay tabs | `auto-hide-overlay-tabs` | confirmed current IsoNim component, `tools/visual-review/reports/auto-hide-overlay-tabs-laptop.json` |\n| Auto-hide side strip | `auto-hide-side-strip` and `auto-hide-side-strip-collapsed` | confirmed populated and collapsed current IsoNim variants |\n| Session tabs | `session-tabs` | confirmed current IsoNim component, `tools/visual-review/reports/session-tabs-laptop.json` |\n| Default layout variants | `default-layout`, `standalone-app-shell`, `noir-filesystem-active`, `noir-state-active`, `noir-calltrace-active`, `noir-calltrace-search-status-report`, `noir-menu-view-open`, `noir-status-expanded` | confirmed current layout stories; use a non-default `--port` if another static server is already bound to `6106` |\n\nCurrent confirmation does not change the old reference status below. Rows marked\n`blocked`, `partial`, or `missing` still mean the old Karax reference capture is\nblocked, partial, or absent; the current IsoNim story can still be valid and\ncapturable.\n\nLatest mature-state screenshot delta report:\n`tools/visual-review/mature-karax-visual-delta-20260505.md`.\n\n## Coverage Matrix\n\n| Surface | Reference status | Reference capture |\n| --- | --- | --- |\n| Default layout | captured | `20260504T160311Z_noir-electron-rendered` |\n| Scratchpad visible | captured | `20260504T160414Z_noir-scratchpad-visible` |\n| Terminal visible | captured | `20260504T160434Z_noir-terminal-visible` |\n| Filesystem active | captured | `20260504T220916Z_noir-filesystem-active` |\n| State active | captured | `20260504T220918Z_noir-state-active` |\n| Calltrace active | captured | `20260504T220919Z_noir-calltrace-active` |\n| Calltrace search status | captured | `20260504T220922Z_noir-calltrace-search-status-report` |\n| Agent activity active | captured | `20260504T220923Z_noir-agent-activity-active` |\n| Menu open | captured | `20260504T220925Z_noir-menu-view-open` |\n| Status expanded | captured | `20260504T220927Z_noir-status-expanded` |\n| Search results | captured | `20260504T222338Z_noir-search-results-karax-populated`; preserve newer IsoNim functionality if richer |\n| Fixed search | captured | `20260504T222336Z_noir-fixed-search-karax-visible` |\n| Point list | blocked | `20260504T220950Z_noir-point-list-open`; Karax raised unexpected `PointList` content |\n| Step list | captured | `20260504T220952Z_noir-step-list-open` |\n| Timeline | blocked | `20260504T222349Z_noir-timeline-blocked-no-factory`; Karax lacked a usable component factory |\n| Trace log | captured | `20260504T222329Z_noir-trace-log-karax-open` |\n| Build | captured | `20260504T222317Z_noir-build-karax-open`; preserve newer IsoNim output behavior if richer |\n| Build errors | partial | `20260504T222538Z_noir-build-errors-karax-open-attached` and `20260504T222734Z_noir-build-errors-karax-direct-id0`; Karax content stayed empty |\n| Shell | captured | `20260504T221002Z_noir-shell-open` |\n| REPL | captured | `20260504T222331Z_noir-repl-karax-open` |\n| Low-level code | captured | `20260504T222333Z_noir-low-level-code-karax-open` |\n| No source | captured | `20260504T222334Z_noir-no-source-karax-open` |\n| Command palette | captured | `20260504T222339Z_noir-command-palette-karax-open` |\n| Debug controls/header | captured | `20260504T222314Z_noir-debug-controls-header` |\n| Agent workspace | captured | `20260504T222341Z_noir-agent-workspace-karax-open`; preserve newer IsoNim behavior if richer |\n| Agent activity deep review | captured | `20260504T222342Z_noir-agent-activity-deepreview-karax-open`; preserve newer IsoNim behavior if richer |\n| Deep review panel | partial | `20260504T222344Z_noir-deepreview-panel-karax-open-empty` and `20260504T222427Z_deepreview-standalone-karax-sample`; old Karax state was underdeveloped |\n| Flow | partial | `20260504T222348Z_noir-flow-select-attempt`; old frontend raised missing `ct/load-flow` response-kind handling |\n| VCS | missing | No old panel implementation found |\n| Request panel | missing | No old panel implementation found |\n| Welcome screen | captured | `20260504T221201Z_welcome-screen` |\n\n## Current Workflow\n\n1. Capture current Storybook for a matching story with\n `tools/visual-review/capture-storybook.mjs --view --size laptop`.\n Use repeated `--view` flags or `--views a,b,c` for batch captures. If the\n default port is occupied, pass `--port `.\n2. Compare HTML and computed-style dumps against the reference capture with the\n same surface name.\n3. Compare screenshots with `tools/visual-review/compare-screenshots.sh` when\n the reference capture is marked `captured`.\n4. Patch the real IsoNim view/style/story shell, not a parallel mock.\n5. Update this matrix when new reference captures become available.\n"}