Elide Crank internals from error stack traces

[brainkim]

Problem

When an error is thrown in a Crank component, the stack trace includes Crank's internal execution frames mixed with user code:

Error: Cannot read property 'name' of undefined
    at UserProfile (UserProfile.js:12)
    at runComponent (crank.js:482)
    at diffChildren (crank.js:312)
    at commitHost (crank.js:198)
    at UserCard (UserCard.js:8)
    at runComponent (crank.js:482)
    ...

Ideally it would show only the component chain:

Error: Cannot read property 'name' of undefined
    at UserProfile (UserProfile.js:12)
    at UserCard (UserCard.js:8)
    at App (App.js:5)

Constraints

• Use platform APIs, avoid runtime overhead
• Only incur cost when errors are thrown
• Cross-browser would be nice, but V8-only (Error.prepareStackTrace) is acceptable

Research

• V8's Error.prepareStackTrace allows filtering frames, but only works in Chrome/Node
• Error.captureStackTrace can hide frames above a function reference
• Safari has issues with rethrowing errors losing stack info
• React maintains a separate componentStack string rather than eliding the JS stack

Possible approaches

1. Use Error.prepareStackTrace to filter frames containing Crank internals (V8 only)
2. Use Error.captureStackTrace at strategic points to truncate internal frames
3. Post-hoc string parsing of error.stack (cross-browser but fragile)
4. Hybrid: platform APIs where available, graceful degradation elsewhere

[brainkim]

Research Notes

Generated by Claude Code based on codebase analysis and discussion with @brainkim

Internal call stack analysis

When an error is thrown in a user component, there are typically 8-15 internal frames between component boundaries. The key functions that appear in every error stack:

• runComponent() — where component execution happens (lines 2737+)
• enqueueComponent() — async queuing
• diffComponentChildren() / diffChildren() — recursive child processing
• diffComponent() — component-specific diffing
• handleChildError() / propagateError() — error boundary and bubbling logic
• Various promise .then/.catch handlers

Error propagation path

Errors are caught at runComponent() (where the user's component function is called), then rethrown synchronously. They bubble up through handleChildError() → propagateError(), which walks ctx.parent recursively until either an error boundary handles it or it escapes at the root.

Prior art

Framework	Approach	Mutates native stack?
React	Walks fiber tree to build componentStack string, passed to error boundaries via errorInfo	No
Preact	Debug mode (import 'preact/debug') walks vnode tree, logs component stack via console.error	No
Vue	onErrorCaptured receives component instance + info string; no component stack	No
Solid	ErrorBoundary catches errors; no component stack at all	No

Nobody mutates the native JS stack. They either walk an existing tree lazily at error time, or don't provide component stacks.

Recommended approach: post-hoc stack filtering

The cleanest DX would be filtering internal frames from error.stack directly — users see a clean component chain in the console without needing to know about special properties.

Implementation: In propagateError(), right before the final throw err (when no parent is left), string-filter err.stack to remove lines matching known internal function names. This would:

• Have zero cost on the happy path — only runs when an error is already being thrown
• Be cross-browser — error.stack string parsing works everywhere (unlike V8-only Error.prepareStackTrace)
• Work with unminified function names since Crank is distributed as source/ESM

Risk: If a bug exists in Crank's internals (e.g., bad props/context causing user code to throw), the filtered stack would hide internal frames that might help diagnose the root cause. In practice, those internal frames rarely help diagnose such issues anyway — you'd need to debug Crank's diffing logic directly.

The ctx.parent chain is already available for walking at error time (analogous to React's fiber tree), so building a componentStack string as a fallback/complement is also feasible with no happy-path cost.