Debug Pattern

Use Skill("ct") for ct CLI documentation if debugging deployment or piece issues.

Read First

• docs/development/debugging/workflow.md - 5-step debugging process
• docs/development/debugging/README.md - Error reference matrix

Process

1. Check TypeScript errors:

   bash
   1deno task ct check pattern.tsx --no-run

2. Match error to documentation:

   • Read the error message carefully
   • Check docs/development/debugging/README.md for matching errors

3. Check gotchas:

   • docs/development/debugging/gotchas/handler-inside-pattern.md
   • docs/development/debugging/gotchas/filter-map-find-not-a-function.md
   • docs/development/debugging/gotchas/onclick-inside-computed.md

4. Simplify to minimal reproduction:

   • Comment out code until error disappears
   • Add back piece by piece to find root cause

5. Fix and verify:

   • Apply fix
   • Run tests to confirm

Common Issues

Handler defined inside pattern body:

• Move handler() to module scope
• Only bind it inside pattern: onClick={myHandler({ state })}

Type errors with Writable/Default:

• Check if field needs write access → use Writable<>
• Check if field could be undefined → use Default<T, value>

Action not triggering:

• Ensure Output type includes action as Stream<void>
• Use .send() not .get() to trigger

computed() wrapping JSX — conditional rendering broken:

• Inside computed() body, ternaries are plain JS (Writable objects always truthy)
• Cell bindings ($value, $checked) inside derive() may get positionally mis-resolved
• Fix: use bare JSX ternaries, hoist computed() for data only
• See docs/common/concepts/computed/computed.md

Runtime Debugging (browser)

When the pattern compiles but behaves wrong at runtime, use the browser console utilities. Full reference: docs/development/debugging/console-commands.md.

With agent-browser (for automated testing):

bash
1# Read piece cell values
2agent-browser eval "(async () => {
3  const v = await commontools.readCell();
4  return JSON.stringify(v).slice(0, 500);
5})()"
6
7# Inspect VDOM tree
8agent-browser eval "(async () => {
9  await commontools.vdom.dump();
10  return 'dumped';
11})()"
12
13# Detect non-idempotent computations (UI churning)
14agent-browser eval "(async () => {
15  const r = await commontools.detectNonIdempotent(5000);
16  return JSON.stringify({ nonIdempotent: r.nonIdempotent.length, cycles: r.cycles.length });
17})()"
18
19# Check for action schema mismatches (handlers doing nothing)
20agent-browser eval "JSON.stringify(commontools.getLoggerFlagsBreakdown())"

In browser console (for interactive debugging):

javascript
1// Read cell values
2await commontools.readCell()
3await commontools.readArgumentCell({ path: ["items"] })
4
5// Watch values change during interaction
6const cancel = commontools.subscribeToCell()
7// ... interact ... then cancel()
8
9// VDOM tree
10await commontools.vdom.dump()
11commontools.vdom.stats()
12
13// Logger counts and timing
14commontools.getLoggerCountsBreakdown()
15commontools.getTimingStatsBreakdown()
16
17// Non-idempotent detection
18await commontools.detectNonIdempotent()

Done When

• Root cause identified
• Error fixed
• Tests pass again