scritch-react

Your application already knows why it failed. Your user doesn't.

Report a blocked user, get back one sentence they can act on — in their words, not a stack trace and not "something went wrong".

import { RecoveryProvider, useRecoverableTask, useGuidance } from "scritch-react";

// Once, near your root. The key stays on your server; this gets a short-lived token.
<RecoveryProvider config={{ appId: "acme", environment: "production", getToken }}>

// Where a failure happens.
const { incident, run } = useRecoverableTask({ code: "upload.rejected", surface: "inline" });
const guidance = useGuidance(incident);

await run(() => api.upload(file), {
  form: { id: "cv", fields: [{ path: "cv", state: "invalid", ruleCodes: ["accepts_pdf_txt_only"] }] },
});

// Your UI, your styling. The hook returns text and a verdict, never a component.
{guidance.message && <InlineError>{guidance.message}</InlineError>}

guidance.userCanFix is the field worth building around: it separates advice a person can act on from a failure they can only wait out.

What leaves the browser

Field states and rule codes, never values, unless you allowlist a path. Passwords, tokens, keys and card fields are refused even then. With consent.diagnostics, two coarse device facts as well — which of seven platforms, and whether the browser was online — and never the user-agent string.

envelope.ts is the whole privacy story and is small enough to read in one sitting.

Server

scritch-react/server carries the handler you mount and the read-only connectors the agent may call — your error monitoring, your status page, your auth provider, your repository. Each runs where you mount it, with your credentials.

Unstable while it finds its shape; expect breaking changes before 1.0.