@fabrika/app 0.4.2 → 0.4.4

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/app",
-	"version": "0.4.2",
+	"version": "0.4.4",
 	"type": "module",
 	"license": "MIT",
 	"repository": {
@@ -93,13 +93,13 @@
 		"test": "bun test --path-ignore-patterns='src/react/**' && bun test --isolate src/react"
 	},
 	"dependencies": {
-		"@fabrika/auth": "^0.4.2",
-		"@fabrika/auth-core": "^0.4.2",
-		"@fabrika/db": "^0.4.2",
-		"@fabrika/jwks": "^0.4.2",
-		"@fabrika/platform": "^0.4.2",
-		"@fabrika/platform-node": "^0.4.2",
-		"@fabrika/proxy-core": "^0.4.2",
+		"@fabrika/auth": "^0.4.4",
+		"@fabrika/auth-core": "^0.4.4",
+		"@fabrika/db": "^0.4.4",
+		"@fabrika/jwks": "^0.4.4",
+		"@fabrika/platform": "^0.4.4",
+		"@fabrika/platform-node": "^0.4.4",
+		"@fabrika/proxy-core": "^0.4.4",
 		"jose": "^5.9.0"
 	},
 	"peerDependencies": {

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fabrika-app
-version: 0.4.2
+version: 0.4.4
 description: >
   How to write and change a Fabrika application: src/vocabulary.ts, db/migrations/, src/db/tables.ts, the
   slices' endpoints.ts with their handlers, fabrika.contract.ts, jobs, files, webhooks, share links, connectors

package/skill/references/app-setup.md

@@ -19,21 +19,20 @@ the SPA is added with it.
 		"test": "bun test --isolate"
 	},
 	"dependencies": {
-		"@fabrika/app": "^0.4.2",
-		"@fabrika/db": "^0.4.2",
-		"@fabrika/provider-zerops": "^0.4.2",
-		"@fabrika/proxy-core": "^0.4.2",
-		"@fabrika/ui": "^0.4.2",
-		"@sentry/browser": "10.69.0",
+		"@fabrika/app": "^0.4.4",
+		"@fabrika/db": "^0.4.4",
+		"@fabrika/provider-zerops": "^0.4.4",
+		"@fabrika/proxy-core": "^0.4.4",
+		"@fabrika/ui": "^0.4.4",
 		"kysely": "0.29.6",
 		"react": "^19.0.0",
 		"react-dom": "^19.0.0",
 		"zod": "^3.25.76"
 	},
 	"devDependencies": {
-		"@fabrika/check": "^0.4.2",
-		"@fabrika/cli": "^0.4.2",
-		"@fabrika/platform": "^0.4.2",
+		"@fabrika/check": "^0.4.4",
+		"@fabrika/cli": "^0.4.4",
+		"@fabrika/platform": "^0.4.4",
 		"@happy-dom/global-registrator": "^20.11.2",
 		"@types/bun": "latest",
 		"@types/react": "^19.0.0",
@@ -48,8 +47,9 @@ the SPA is added with it.
   Bun still links the workspace copies.
 - `build:web` builds the SPA: add it, `build-web.ts`, `web/`, the contract's `site` mount and the `bun run build:web`
   line of `zerops.yaml` when the application gets an SPA, and not before.
-- `kysely` is there for the generated schema's types. `@sentry/browser` reports the SPA's errors to Operations, from
-  the DSN and release the framework serves at `<prefix>/__fabrika-config.json`. The same file carries
+- `kysely` is there for the generated schema's types. The SPA reports its errors to Operations by itself:
+  `FabrikaProvider` reads the DSN, release and environment the framework serves at `<prefix>/__fabrika-config.json`
+  and sends every uncaught error and unhandled rejection there; add no error-reporting SDK. The same file carries
   `public: { <VARIABLE>: <value> }`: each form challenge's `siteKey`, and the variables the SPA mount lists in
   `c.spa(prefix, { …, public: ['SIGNUP_URL'] })`. A page reads a per-environment public value (a site key, a link
   target) there, never as a build-time constant; it holds no other variable, and the contract refuses a secret in it.
@@ -338,6 +338,7 @@ const built = await Bun.build({
 	outdir,
 	target: 'browser',
 	define: { 'process.env.NODE_ENV': JSON.stringify('production') },
+	sourcemap: 'external',
 	plugins: [shellSlicePlugin({ root: import.meta.dir })],
 })
 if (!built.success) {
@@ -357,6 +358,12 @@ await Bun.write(
   the rows are passed in.
 - The last step points the page's assets at the SPA's prefix (`/`): the mount answers `index.html` for every path
   under it, so a deep link such as `/tasks/<id>` renders. `define` gives React's production build.
+- `sourcemap: 'external'` writes each script's map beside it, and the page names none. The platform build uploads the
+  maps to Operations for the release the page reports, so an error's frames show the original source; the mount
+  never serves a `.map` file (404). Keep the maps external: `inline` would ship the source to every visitor.
+- **Errors.** `FabrikaProvider` reports the page's uncaught errors and unhandled rejections to Operations, with the
+  release and the environment, through the DSN the mount serves; without a DSN (local development, a test) it reports
+  nothing. An application that must not report passes `reportErrors={false}`.
 - Set text through JSX, never `dangerouslySetInnerHTML` or `innerHTML`. Same-origin calls carry the session cookie.
 - **Who is signed in.** Every member SPA serves `<prefix>/__fabrika-me.json` to the person it admitted:
   `{ label, email, actions: { app, scopes } }`. `useCaller()` (`@fabrika/app/react`) answers `{ label, email,

package/skill/references/spa.md

@@ -96,7 +96,8 @@ if (root !== null) {
 - `FabrikaProvider` holds the clients of the mounts the page calls. A hook takes a procedure of a client
   (`api.tasks.get`) as the typed name of the call and runs it on the provider's client of that mount; a test hands the
   provider a client over the test kit instead (below). An SPA mounted under a prefix passes it: `spa="/app"`. Its bare
-  prefix (`/app`) redirects to `/app/`, so a link may name either.
+  prefix (`/app`) redirects to `/app/`, so a link may name either. It also reports the page's uncaught errors to
+  Operations (`reportErrors={false}` turns that off); never add an error-reporting SDK.
 - `createRouter` answers typed paths: `href('task', { id })`, `navigate('project', { orgId, projectId })`, `<Link
   to="task" params={{ id }}>`, and `useRoute()`, the match or `null`. `<Router>` makes every plain `<a href>` under the
   SPA navigate without a reload: the kit's components render links that way. Pass `{ base: '/app' }` for a prefix.

package/src/client/error-reporting.ts

@@ -0,0 +1,209 @@
+// Browser error reporting on the paved road. `FabrikaProvider` reads the SPA mount's browser config and, when it names
+// an Operations DSN, sends every uncaught error and unhandled rejection of the page to that ingest as one Sentry error
+// event. Operations ingests error events only, so nothing else of the page leaves it.
+
+import { z } from 'zod/v4'
+import type { RpcFetch } from './transport'
+
+const BrowserConfigSchema = z.object({
+	dsn: z.string().nullable(),
+	release: z.string().nullable(),
+	environment: z.string().nullable(),
+})
+
+/** One stack frame in Sentry's shape, the file a script URL. */
+export interface BrowserFrame {
+	readonly filename: string
+	readonly function?: string
+	readonly lineno: number
+	readonly colno: number
+	/** A frame of a script of the page's own origin. */
+	readonly in_app: boolean
+}
+
+/** Where the page reports, read from its browser config. */
+export interface ReportingTarget {
+	/** The ingest's envelope endpoint, authenticated by the DSN's public key in its query, as the Sentry SDK sends it. */
+	readonly envelopeUrl: string
+	readonly release: string | null
+	readonly environment: string | null
+}
+
+/** What the reporter listens on and reads the page's address from: `window` in a page. */
+export interface ReportingPage {
+	addEventListener(type: 'error' | 'unhandledrejection', listener: (event: Event) => void): void
+	removeEventListener(type: 'error' | 'unhandledrejection', listener: (event: Event) => void): void
+	readonly location: { readonly origin: string; readonly pathname: string }
+}
+
+const PUBLIC_KEY = /^[0-9a-f]{32}$/
+const PROJECT_ID = /^[1-9][0-9]{0,18}$/
+/** A page that keeps failing stops reporting here; Operations rate-limits the whole source, not one page. */
+export const MAX_REPORTS_PER_PAGE = 20
+const MAX_FRAMES = 50
+const MAX_TEXT = 2_048
+const TYPE_NAME = /^[A-Za-z_$][\w$.]{0,127}$/
+
+/**
+ * The envelope endpoint of an ingest DSN `https://<key>@<host>/<project>`, or `null` for any other value. The server's
+ * reporter parses the same DSN (`jobs/report.ts`); it is server code, so a page does not import it.
+ */
+export function envelopeUrlOf(dsn: string): string | null {
+	let url: URL
+	try {
+		url = new URL(dsn.trim())
+	} catch {
+		return null
+	}
+	const project = url.pathname.slice(1)
+	if ((url.protocol !== 'https:' && url.protocol !== 'http:') || !PUBLIC_KEY.test(url.username) || url.password !== '' || !PROJECT_ID.test(project)) {
+		return null
+	}
+	return `${url.origin}/api/${project}/envelope/?sentry_key=${url.username}&sentry_version=7`
+}
+
+/** The reporting target the browser config names, or `null` when it names no usable DSN. */
+export function reportingTargetOf(config: unknown): ReportingTarget | null {
+	const parsed = BrowserConfigSchema.safeParse(config)
+	if (!parsed.success || parsed.data.dsn === null) return null
+	const envelopeUrl = envelopeUrlOf(parsed.data.dsn)
+	return envelopeUrl === null ? null : { envelopeUrl, release: parsed.data.release, environment: parsed.data.environment }
+}
+
+const cut = (text: string): string => text.length <= MAX_TEXT ? text : `${text.slice(0, MAX_TEXT)}…`
+
+const V8_FRAME = /^\s*at (?:(.+?) \()?(.+?):(\d+):(\d+)\)?$/
+const GECKO_FRAME = /^(?:(.*?)@)?(.+?):(\d+):(\d+)$/
+
+function parseFrame(line: string, origin: string): BrowserFrame | null {
+	const match = /^\s*at /.test(line) ? V8_FRAME.exec(line) : GECKO_FRAME.exec(line)
+	const filename = match?.[2]
+	if (match === null || filename === undefined || !URL.canParse(filename)) return null
+	const name = match[1]?.replace(/^(?:async|new) /, '').trim()
+	return {
+		filename: cut(filename),
+		...(name === undefined || name === '' ? {} : { function: cut(name) }),
+		lineno: Number(match[3]),
+		colno: Number(match[4]),
+		in_app: filename.startsWith(`${origin}/`),
+	}
+}
+
+/**
+ * The frames of a V8, SpiderMonkey or JavaScriptCore `stack`, oldest call first as Sentry orders them, the
+ * `MAX_FRAMES` nearest the throw kept. A frame whose file is no URL (an `eval`, a native function) is left out.
+ */
+export function parseBrowserStack(stack: string, origin: string): BrowserFrame[] {
+	const frames: BrowserFrame[] = []
+	for (const line of stack.split('\n')) {
+		const frame = parseFrame(line, origin)
+		if (frame !== null) frames.push(frame)
+		if (frames.length === MAX_FRAMES) break
+	}
+	return frames.reverse()
+}
+
+type Mechanism = 'onerror' | 'onunhandledrejection'
+
+interface ReportedException {
+	readonly type: string
+	readonly value: string
+	readonly mechanism: { readonly type: Mechanism; readonly handled: false }
+	readonly stacktrace?: { readonly frames: readonly BrowserFrame[] }
+}
+
+function exceptionOf(thrown: unknown, message: string, mechanism: Mechanism, origin: string): ReportedException {
+	if (thrown instanceof Error) {
+		const frames = typeof thrown.stack === 'string' ? parseBrowserStack(thrown.stack, origin) : []
+		return {
+			type: TYPE_NAME.test(thrown.name) ? thrown.name : 'Error',
+			value: cut(thrown.message),
+			mechanism: { type: mechanism, handled: false },
+			...(frames.length === 0 ? {} : { stacktrace: { frames } }),
+		}
+	}
+	const value = typeof thrown === 'string' ? thrown : message !== '' ? message : `a ${typeof thrown} was thrown`
+	return { type: mechanism === 'onerror' ? 'Error' : 'UnhandledRejection', value: cut(value), mechanism: { type: mechanism, handled: false } }
+}
+
+const hexId = (): string => crypto.randomUUID().replaceAll('-', '')
+
+/** The envelope of one error event. The page's address goes without its query and fragment, which may carry a key. */
+export function browserEnvelope(
+	exception: ReportedException,
+	target: ReportingTarget,
+	page: ReportingPage['location'],
+	now: Date,
+): string {
+	const eventId = hexId()
+	const event = {
+		event_id: eventId,
+		timestamp: now.toISOString(),
+		level: 'error',
+		platform: 'javascript',
+		logger: 'fabrika.browser',
+		request: { url: `${page.origin}${page.pathname}` },
+		exception: { values: [exception] },
+		...(target.release === null ? {} : { release: target.release }),
+		...(target.environment === null ? {} : { environment: target.environment }),
+	}
+	return [JSON.stringify({ event_id: eventId, sent_at: now.toISOString() }), JSON.stringify({ type: 'event' }), JSON.stringify(event), ''].join('\n')
+}
+
+const signatureOf = (exception: ReportedException): string =>
+	JSON.stringify([exception.type, exception.value, exception.stacktrace?.frames.at(-1) ?? null])
+
+/**
+ * Listen for the page's uncaught errors and unhandled rejections and send each to `target`; answers the uninstall.
+ * An error equal to the one just sent is not sent again, and the page sends at most `MAX_REPORTS_PER_PAGE`. A failed
+ * delivery is dropped: reporting never throws into the page.
+ */
+export function installErrorReporting(page: ReportingPage, target: ReportingTarget, send: RpcFetch): () => void {
+	let sent = 0
+	let previous = ''
+	const report = (exception: ReportedException): void => {
+		const signature = signatureOf(exception)
+		if (sent >= MAX_REPORTS_PER_PAGE || signature === previous) return
+		sent++
+		previous = signature
+		// A simple request (no custom header, a text body) needs no CORS preflight; `keepalive` outlives a navigation.
+		void send(target.envelopeUrl, {
+			method: 'POST',
+			headers: { 'content-type': 'text/plain;charset=UTF-8' },
+			body: browserEnvelope(exception, target, page.location, new Date()),
+			credentials: 'omit',
+			keepalive: true,
+		}).then((response) => response.body?.cancel(), () => {})
+	}
+	// Read by name: an `ErrorEvent`'s `error` and `message`, a `PromiseRejectionEvent`'s `reason`, whichever class made them.
+	const onError = (event: Event): void => {
+		const error: unknown = Reflect.get(event, 'error')
+		const message: unknown = Reflect.get(event, 'message')
+		report(exceptionOf(error, typeof message === 'string' ? message : '', 'onerror', page.location.origin))
+	}
+	const onRejection = (event: Event): void => {
+		const reason: unknown = Reflect.get(event, 'reason')
+		report(exceptionOf(reason, '', 'onunhandledrejection', page.location.origin))
+	}
+	page.addEventListener('error', onError)
+	page.addEventListener('unhandledrejection', onRejection)
+	return () => {
+		page.removeEventListener('error', onError)
+		page.removeEventListener('unhandledrejection', onRejection)
+	}
+}
+
+/**
+ * Read the browser config at `configUrl` and install reporting when it names a DSN; answers the uninstall, or `null`
+ * when nothing was installed. A missing, refused or unreadable config (local development, a test) installs nothing.
+ */
+export async function startErrorReporting(configUrl: string, fetch: RpcFetch, page: ReportingPage): Promise<(() => void) | null> {
+	let target: ReportingTarget | null
+	try {
+		const response = await fetch(configUrl, { credentials: 'same-origin' })
+		target = response.ok ? reportingTargetOf(await response.json()) : null
+	} catch {
+		return null
+	}
+	return target === null ? null : installErrorReporting(page, target, fetch)
+}

package/src/implement/browser-config.ts

@@ -1,5 +1,5 @@
-// What an SPA mount answers at `<prefix>/__fabrika-config.json`: the browser's Operations settings and the public
-// values the contract names, and nothing else of the environment.
+// What an SPA mount answers at `<prefix>/__fabrika-config.json`: the browser's Operations settings (DSN, release and
+// environment) and the public values the contract names, and nothing else of the environment.
 
 import type { ContractArtifact } from '@fabrika/auth-core'
 import type { CapturedEnvironment } from './environment'
@@ -8,9 +8,11 @@ export interface BrowserConfig {
 	/** The Operations ingest DSN (a public key), or `null` without one. */
 	readonly dsn: string | null
 	readonly release: string | null
+	/** `FABRIKA_ENVIRONMENT`, which the page's error reports carry, or `null` when unset. */
+	readonly environment: string | null
 	/**
 	 * Every form challenge's site key, and the variables the mount lists in `public`, by variable name. Absent when
-	 * there is none, so the file of an application without them holds the two Operations values only.
+	 * there is none, so the file of an application without them holds the three Operations values only.
 	 */
 	readonly public?: Readonly<Record<string, string>>
 }
@@ -48,7 +50,8 @@ export function browserConfigs(
 			else own[variable] = value
 		}
 		const served = { ...siteKeys, ...own }
-		configs.set(name, Object.freeze(Object.keys(served).length === 0 ? { ...operations } : { ...operations, public: Object.freeze(served) }))
+		const reporting = { ...operations, environment: environment.framework['FABRIKA_ENVIRONMENT']?.trim() || null }
+		configs.set(name, Object.freeze(Object.keys(served).length === 0 ? reporting : { ...reporting, public: Object.freeze(served) }))
 	}
 	return configs
 }

package/src/implement/dispatch.ts

@@ -300,7 +300,7 @@ export class ContractRuntime {
 					if (rawRequestTarget(request.url).pathname === bootstrapPath(served.prefix)) {
 						return bootstrapResponse()
 					}
-					return await withBootstrap(await this.#assets().serve({ prefix: served.prefix, dir: served.dir }, request), served.prefix)
+					return await withBootstrap(await this.#asset(served, request), served.prefix)
 				case 'procedure':
 					return await this.#procedure(served, request)
 				case 'file':
@@ -345,6 +345,14 @@ export class ContractRuntime {
 			}
 			return jsonResponse(pageCallerOf(caller.principal, caller.perms, this.#parts.actions), 200)
 		}
+		return await this.#asset(served, request)
+	}
+
+	/** A file of the mount's directory. A source map goes to Operations at build and is never served: it holds the source. */
+	async #asset(served: { readonly prefix: string; readonly dir: string }, request: Request): Promise<Response> {
+		if (rawRequestTarget(request.url).pathname.endsWith('.map')) {
+			throw new NotFoundError('A source map is not served')
+		}
 		return await this.#assets().serve({ prefix: served.prefix, dir: served.dir }, request)
 	}
 

package/src/react/provider.tsx

@@ -1,13 +1,15 @@
-// `FabrikaProvider`: the page's clients, the cache of their answers, and the caller document of the SPA mount. The
-// hooks take a procedure of a client as the typed name of a call; the provider runs it on the client it holds for
-// that mount, so a test hands in a client over the test kit and the page's own module-level client stays as it is.
+// `FabrikaProvider`: the page's clients, the cache of their answers, the caller document of the SPA mount, and the
+// page's error reporting. The hooks take a procedure of a client as the typed name of a call; the provider runs it on
+// the client it holds for that mount, so a test hands in a client over the test kit and the page's own module-level
+// client stays as it is.
 
-import { createContext, type ReactNode, useContext, useState } from 'react'
+import { createContext, type ReactNode, useContext, useEffect, useState } from 'react'
 import { z } from 'zod/v4'
 import { type PageCaller, parsePageCaller } from '../client/caller'
 import { attachmentAt, type ClientNode, clientNodeOf, downloadFile } from '../client/contract'
+import { startErrorReporting } from '../client/error-reporting'
 import { RpcError, type RpcFetch } from '../client/transport'
-import { joinPath, PAGE_CALLER_FILE } from '../contract/defaults'
+import { BROWSER_CONFIG_FILE, joinPath, PAGE_CALLER_FILE } from '../contract/defaults'
 import { type FabrikaError, toFabrikaError } from './errors'
 import { QueryStore, type StoreTarget } from './store'
 
@@ -149,13 +151,35 @@ export interface FabrikaProviderProps {
 	readonly clients: readonly object[]
 	/** The prefix of the SPA mount the page is served from: the caller document is `<spa>/__fabrika-me.json`. */
 	readonly spa?: string
-	/** What the caller document is fetched with; the global `fetch` by default (a test passes the kit's). */
+	/**
+	 * What the caller document, the browser config and the error reports are fetched with; the global `fetch` by default
+	 * (a test passes the kit's).
+	 */
 	readonly fetch?: RpcFetch
+	/**
+	 * Report the page's uncaught errors and unhandled rejections to Operations, through the DSN and release the mount
+	 * serves at `<spa>/__fabrika-config.json`; `true` by default. Without a DSN nothing is reported.
+	 */
+	readonly reportErrors?: boolean
 	readonly children?: ReactNode
 }
 
-export function FabrikaProvider({ clients, spa = '/', fetch: fetchCaller, children }: FabrikaProviderProps): ReactNode {
-	const [value] = useState(() => fabrika(clients, spa, fetchCaller ?? ((input, init) => fetch(input, init))))
+export function FabrikaProvider({ clients, spa = '/', fetch: fetchGiven, reportErrors = true, children }: FabrikaProviderProps): ReactNode {
+	const [send] = useState<RpcFetch>(() => fetchGiven ?? ((input, init) => fetch(input, init)))
+	const [value] = useState(() => fabrika(clients, spa, send))
+	useEffect(() => {
+		if (!reportErrors || typeof window === 'undefined') return
+		let stopped = false
+		let uninstall: (() => void) | null = null
+		void startErrorReporting(joinPath(spa, BROWSER_CONFIG_FILE), send, window).then((installed) => {
+			if (stopped) installed?.()
+			else uninstall = installed
+		})
+		return () => {
+			stopped = true
+			uninstall?.()
+		}
+	}, [reportErrors, spa, send])
 	return <FabrikaContext.Provider value={value}>{children}</FabrikaContext.Provider>
 }