feat(runner): Sentry error monitoring for the authoring app + API worker (DEV-2134)

[demtario]

Adds Sentry error reporting to the two runner surfaces: the authoring app and the API worker. Errors only — no tracing, no session replay, no profiling.

DEV-2134: https://app.clickup.com/t/86cax9zfa

Why

The runner had no error reporting at all. DEV-2129 (Babel 6.26 parse failure across 8 examples), DEV-2130 (blank React demo from a jsx/tsx entry mismatch) and the Tier-2 5-slot container exhaustion were all found by a human clicking around or by the link-sweep script, days after they started failing. Workers Logs gives raw lines with short retention, no grouping and no alerting.

Build settings — in place

Where	Name	Value
repo secret	SENTRY_AUTH_TOKEN	Sentry Organization Auth Token (sntrys_…), fixed org:ci scope
repo variable	SENTRY_ORG	handsoncode
repo variable	SENTRY_PROJECT	demos

All three are set, and deploy-runner-authoring.yml reads them from those exact places. vite.config.ts enables source-map upload only when all three are present, so a partial or broken setup is a clean no-op rather than a broken deploy.

Worth knowing for later: a failed upload (rotated token, wrong slug) does not fail the build — sentry-cli errors and vite still exits 0. Verified with fake credentials. The symptom is unreadable minified traces in Sentry, not a red deploy, so check the deploy log for [sentry-vite-plugin] Error if prod traces ever stop resolving.

apps/authoring

• @sentry/react initialised from a dedicated src/sentry.ts, imported first in main.tsx so a throw during module evaluation is still caught. Callsites report through a reportError helper instead of importing the SDK, which keeps the production gate (below) authoritative in one place.
• Sentry.ErrorBoundary at the app root. An editor-shell render crash previously left a blank page and no record of why.
• Reporting added at the callsites that swallowed a failure whole: saved-demo load, docs-example load and switch (tagged by which step failed — the DEV-2130 shape), versions fetch, broker /broker/userinfo, and demo save / fork / embed / share / revoke. The writeFile/deleteFile "not mounted" catches are deliberately left alone; that is expected control flow, not a fault.
• @sentry/vite-plugin uploads source maps and tags the release with github.sha. build.sourcemap follows whether upload is enabled, so a build without the credentials neither emits nor publishes .map files (~12 MB otherwise).

workers/api

• withSentry() on the fetch handler; instrumentDurableObjectWithSentry on both Sandbox and BuilderSandbox. Tier-2 session orchestration and the share-build snapshotter run inside the DOs, so their failures never reach the handler's error path.
• The export name Sandbox is load-bearing — proxyToSandbox resolves the live-preview namespace by that literal name — so the wrapper is assigned to it rather than aliased. The as unknown as casts dodge TS2589 on the Sandbox SDK's recursive RPC generic, mirroring the existing proxyToSandbox cast a few lines below.
• The outer try/catch converts every unexpected throw into a 500 body, so withSentry() alone would never observe one. captureException is called there, plus at the two npm-registry probes that silently degrade version pinning. InvalidFilePathError stays unreported — it is input validation returning a 400, not a fault.
• observability.enabled stays on; this is additive.

Decisions worth a reviewer's attention

The Worker's DSN var is ERROR_REPORTING_DSN, not SENTRY_DSN. This looks like a naming quirk and is not. @sentry/cloudflare's getFinalOptions does dsn: userOptions.dsn ?? getEnvVar(env, "SENTRY_DSN") — it reads that exact key straight off env whenever the options object omits a dsn. Under that name the SDK initialises from raw env and silently bypasses the production gate below. Commented at both the definition and the use site so it does not get "fixed" later.

Nothing is reported outside production, and that needed a gate rather than an absent DSN. .env.production is committed, so it is loaded by ci.yml's authoring build — and playwright.config.ts serves that exact build at localhost:4173. Without a gate, every PR run and every local vite preview would file events against the production project. The browser gates on window.location.hostname; the Worker gates on PREVIEW_HOST, the prod-vs-local switch the Tier-2 preview URLs already rely on and which .dev.vars already overrides.

Preview failures are classified by error class, not dropped wholesale. The preview iframe runs arbitrary authored and imported example code, so a compile error or a mid-keystroke typo is product output, not an application fault — reporting those would bury the signal under one issue per syntax error. But DemoRuntime.onError is a mixed channel:

Emitter	Error	Action
sandpack.ts	compile error in the code being edited	drop — product output
container.ts	"The session was closed."	drop — normal teardown
container.ts	ContainerBootFailure	report
container.ts	dev-server / WS error	report
mount() rejection	SessionStartError (has .status)	report unless 410

SessionStartError is the Tier-2 pool refusing a session — the exhaustion class behind #87, and one of the things this PR exists to surface. reportRuntimeError in App.tsx does the classification, next to the existing describeRuntimeError. Both container cases are fingerprinted by class so per-example boot-log text doesn't shard one problem into hundreds of issues.

Note that the beforeSend foreign-frame filter is a weak backstop, not the guarantee. A genuinely cross-origin iframe error arrives as "Script error." with no stack frames, so it would pass the filter. What actually protects the quota is the engine !== "container" early return.

The Worker release comes from the version_metadata binding. Cloudflare's own per-deploy version id, so deploy-runner-api.yml needs no change at all — no SHA plumbing, and nothing that has to interact with the four --routes flags already in the deploy script.

The DSN is committed, in two places, on purpose. A DSN is a write-only ingest endpoint and ships inside the JS bundle by construction, so hiding it buys nothing — and keeping it out of wrangler secret means changing it needs no Cloudflare access. Abuse is bounded Sentry-side (allowed domains, inbound filters, spike protection). It sits beside VITE_API_BASE in .env.production and beside LOGIN_BROKER_URL in the wrangler.jsonc vars block, both already labelled as public non-secret config.

packages/runtime and packages/editor-shell stay uninstrumented. They are libraries; they keep surfacing errors through their existing interfaces and the classifier lives in the app.

Verification

Local, pre-deploy:

• pnpm typecheck clean · 67/67 unit tests · pnpm e2e 10 passed / 85 skipped.
• Gate closed: real production bundle served at localhost:4173 — no Sentry client is created, and an unhandled error produces zero ingest requests (checked in a real browser, network panel).
• Send path open: with the gate temporarily pointed at localhost, the envelope POST returns 200 — DSN and project confirmed valid.
• Worker: gate closed → SDK logs "No DSN provided, client will not send events"; gate open → client initialises and captures.
• DO wrapping is safe at runtime. This was the real risk in the Worker half: Sentry's Proxy hands the SDK an Object.create(ctx) stand-in for DurableObjectState. Booted a real Tier-2 session and proxied its preview URL through the wrapped Sandbox DO — neither the Sandbox SDK nor proxyToSandbox name resolution breaks.
• Preview errors are not reported — both paths checked. Full stack running locally (API worker + authoring dev server), gate temporarily open. A deliberate app error produced exactly one envelope (HTTP 200), proving the client was live and sending. Then, in src/index.tsx of the React starter: (a) a syntax error produced no event and no UI error, because pushUpdate() catches the transpile failure at sandpack.ts:248 and keeps the last good sandbox — it never reaches the bundler; (b) an unresolvable import — valid syntax, fails at bundle time — did surface Error: Setup failed in the UI through show-error → emitError → onError, and still produced no event. Envelope count stayed at 1 across both.
• Mount churn does not flood issues. reportRuntimeError fires even when the mount effect was cancelled, on the grounds that a refused session still failed — which makes rapid example/version switching the obvious volume risk. Raced POST /api/session against an immediate DELETE three times: 410 every time, which the classifier drops.
• A partial SENTRY_* setup builds clean, and a failed upload still runs the post-upload cleanup, so .map files are never published.

Gaps — need prod to close

• Source-map-resolved stack trace in prod — the first deploy will tell us whether the upload wiring is right.
• Real events on both surfaces tagged with the Cloudflare release id.
• Sentry project settings still to configure: spike protection, allowed domains = demos.handsontable.com, default browser inbound filters.
• One real event ("DEV-2134 authoring smoke error (local verify)") is already in the project from the send-path test above.

Out of scope

• Public /d/:id viewer and /embed/:id — instrumenting the embed means a Sentry script running on handsontable.com docs pages (consent/PII surface, third-party script in docs, client-environment noise we can't act on).
• containers/live + containers/builder Node-side instrumentation — needs the Node SDK baked into both images and container-level DSN plumbing. Follow-up; see DEV-2030.
• Worker source-map upload, tracing, replay, and any alert-routing policy beyond Sentry's default "new issue" mail.

🤖 Generated with Claude Code

---

Note

Medium Risk
Touches production observability and worker/DO wrappers on session and sharing paths, but does not change auth or business logic; main risks are mis-gated events or DO instrumentation regressions, which the PR documents and tests locally.

Overview
Adds Sentry error reporting (errors only, no tracing/replay) to the demo runner’s authoring SPA and API Worker, with strict production-only gates so CI, vite preview, and wrangler dev do not pollute the prod project.

Authoring: New sentry.ts initializes @sentry/react only on demos.handsontable.com; reportError centralizes tagged captures at previously silent failures (demo load/save/fork/embed/share, docs loads, versions fetch, broker userinfo). A root ErrorBoundary replaces blank-page crashes. Container preview faults (SessionStartError, ContainerBootFailure) are reported with fingerprints; Sandpack user-code errors are not. Deploy builds pass SENTRY_* + GITHUB_SHA so @sentry/vite-plugin uploads source maps and strips .map from dist/.

API Worker: withSentry wraps the fetch handler; Sandbox and BuilderSandbox DOs are instrumented. DSN is ERROR_REPORTING_DSN (avoids SDK auto-init via SENTRY_DSN); reporting is on when PREVIEW_HOST matches prod. Unexpected handler errors and npm registry probe failures are captured. Release uses CF_VERSION_METADATA.

Docs cover tokens, variables, and operational notes (failed map upload does not fail the build).

^{Reviewed by Cursor Bugbot for commit 797cb9b. Bugbot is set up for automated code reviews on this repo. Configure here.}

[demtario]

@qunabu In https://handsoncode.sentry.io/settings/projects/demos/ -> Project security, you need to set allowed domain to demos.handsontable.com. I dont have permissions to do that

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 94e54f8. Configure here.}