Duolith docs

0074. Crash reports carry the screen, breadcrumbs and frames mapped to .duo files

  • Status: Proposed
  • Date: 2026-11-14
  • Decided by: production adapters agent, pending the integrator
  • Planning item: Roadmap milestone 3, "crash adapters" (D33)

Context

A crash report is useful only if it says where the person was, what they did just before, and which line of the page they wrote failed, not which line of the generated JavaScript.

Decision

  • Captured: the window's error and unhandledrejection events, and captureError(error, context) from the app.
  • A report has the error (name, message, frames), the screen in front (route pattern and page module; path and params only when the app passes includePaths: true, since they can hold ids; never the query), up to 30 breadcrumbs (screens shown, actions settled, buttons and links pressed, named by data-crumb or aria-label and never by their text, and the app's own notes), the release, a random session id and the time. It never includes what was typed into fields.
  • Frames are mapped through source maps: a script's last //# sourceMappingURL= (an address or a data: URL) is fetched once, version 3 Base64 VLQ mappings are decoded, and each frame gains an original place, such as pages/post/[id].duo:12:5. A script without a map is reported as it ran.
  • At most ten reports a minute are sent, and only while consent grants crashes (0071).

Alternatives considered

OptionWhy not
Map stacks on a serverNeeds a server we do not have; D33 providers do it, and our transport can hand them the raw frames too
Keep the query string in the screen contextQueries often hold search terms and tokens

Consequences

  • Breadcrumbs wait for consent. They are kept only while the crashes category is granted, and refusing it drops them, so nothing recorded before a yes is ever sent. A report made right after the yes therefore has few breadcrumbs; that is the price of not recording a person who has not agreed.
  • The reporter cannot loop or break the app. The rate limit is counted before consent is read, everything inside a report is caught, and an error the transport raises while sending is neither thrown nor reported.
  • Source maps come only from the app's own origin (or allowedOrigins), and the error's message is cut from the stack before frames are read, so a message cannot point the fetch elsewhere.
  • The web emitter does not write source maps yet, so built apps report generated files until it does (an Emission change). The mapper is tested against maps written by hand and served by a real browser.