@shubh90/app-runtime 0.3.0 → 0.4.1

package/README.md

@@ -29,11 +29,20 @@ and autosave never fights a kit-dirtied tree. Apps pin a version; a breaking
 Plaza contract change is a semver major with a deprecation window, not a flag
 day.
 
-## Publishing (GitHub Packages)
+## Publishing (npmjs, public)
 
-Built and published from the monorepo on a `app-runtime-v*` tag by
-`.github/workflows/publish-app-runtime.yml`. The registry is
-`npm.pkg.github.com`, scope `@mii`.
+Every released version (0.1.0 →) lives on the PUBLIC npm registry — that is
+where app installs resolve, with no auth to provision in any build
+environment, which is the point. Publish from a machine logged in as
+`shubh90`:
+
+```bash
+# from packages/app-runtime, after npm run check && npm run build:
+npm publish --registry=https://registry.npmjs.org
+```
+
+The `app-runtime-v*` tag workflow publishes a mirror copy to GitHub Packages;
+nothing installs from there today, so treat npmjs as the source of truth.
 
 ```bash
 # maintainers, from packages/app-runtime:

package/dist/next/index.d.ts

@@ -1,5 +1,6 @@
-/** Plaza origins allowed to frame an org app. Keep in step with the pane. */
-export declare const PLAZA_FRAME_ORIGINS: readonly ["https://plaza.miis.run", "https://miiplaza.vercel.app", "http://localhost:3000", "http://localhost:3111"];
+import { PLAZA_FRAME_ORIGINS } from "../platform/index.js";
+/** Re-exported for existing importers; the source of truth is ./platform. */
+export { PLAZA_FRAME_ORIGINS };
 type Header = {
     key: string;
     value: string;
@@ -14,4 +15,3 @@ type NextConfigLike = {
     [k: string]: unknown;
 };
 export declare function withMiiPlatform(config?: NextConfigLike): NextConfigLike;
-export {};

package/dist/next/index.js

@@ -10,23 +10,10 @@
 // Newmark SF set `frame-ancestors 'none'` + `X-Frame-Options: DENY` in its own
 // config and white-screened its pane. This makes that impossible: whatever the
 // app sets, the resulting headers frame-allow Plaza and carry no X-Frame-Options.
-/** Plaza origins allowed to frame an org app. Keep in step with the pane. */
-export const PLAZA_FRAME_ORIGINS = [
-    "https://plaza.miis.run",
-    "https://miiplaza.vercel.app",
-    "http://localhost:3000",
-    "http://localhost:3111"
-];
-const FRAME_ANCESTORS = `frame-ancestors 'self' ${PLAZA_FRAME_ORIGINS.join(" ")}`;
-/** Force `frame-ancestors` to allow Plaza in a Content-Security-Policy value. */
-function forceFrameAncestors(csp) {
-    const directives = csp
-        .split(";")
-        .map((d) => d.trim())
-        .filter((d) => d !== "" && !d.toLowerCase().startsWith("frame-ancestors"));
-    directives.push(FRAME_ANCESTORS);
-    return directives.join("; ");
-}
+import { FRAME_ANCESTORS, forceFrameAncestors as forceCsp, PLAZA_FRAME_ORIGINS } from "../platform/index.js";
+/** Re-exported for existing importers; the source of truth is ./platform. */
+export { PLAZA_FRAME_ORIGINS };
+const forceFrameAncestors = forceCsp;
 /** Rewrite one route's headers: fix any CSP's frame-ancestors, drop XFO. */
 function enforce(headers) {
     let sawCsp = false;

package/dist/platform/index.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Plaza origins allowed to frame an org app AND to drive its preview bridge.
+ * One list on purpose: who may frame the app and who may talk to it must never
+ * drift apart. localhost is here because Plaza is developed locally against
+ * real deployed org apps.
+ */
+export declare const PLAZA_FRAME_ORIGINS: readonly ["https://plaza.miis.run", "https://miiplaza.vercel.app", "http://localhost:3000", "http://localhost:3111"];
+export declare const FRAME_ANCESTORS: string;
+/** Force a Content-Security-Policy value's frame-ancestors to allow Plaza. */
+export declare function forceFrameAncestors(csp: string): string;
+/**
+ * Enforce the framing contract on one response's headers, in place: any CSP
+ * keeps its own directives but frame-allows Plaza, X-Frame-Options is dropped
+ * (it cannot allowlist; CSP governs), and a response with no CSP gains one.
+ * Wire it wherever the app touches every response once — a Start server
+ * middleware, a Node server hook — and the Newmark white-pane class of bug
+ * has no mechanism left.
+ */
+export declare function applyMiiFraming(headers: Headers): void;
+export type PlatformEnv = {
+    /** Vercel's environment name; undefined locally. */
+    readonly vercelEnv?: string;
+    /** MII_ORG_ID / VITE_MII_ORG_ID — the tag that makes telemetry attributable. */
+    readonly orgId?: string;
+};
+export type MiiErrorPolicy = {
+    readonly enabled: boolean;
+    readonly environment: string;
+    readonly tracesSampleRate: 0;
+    readonly sendDefaultPii: false;
+    readonly initialScope: {
+        readonly tags: {
+            readonly org_id: string | undefined;
+        };
+    };
+};
+/**
+ * The Sentry init options an org app must not diverge from, for any Sentry
+ * SDK (`Sentry.init({ dsn, ...miiErrorPolicy(...) })`). The Sentry project is
+ * shared across every org app, so an untagged event is un-attributable: the
+ * policy stays OFF rather than emit one. Errors are the only quota the
+ * platform pays for — tracing stays off. `force` mirrors SENTRY_FORCE_ENABLE
+ * for testing locally.
+ */
+export declare function miiErrorPolicy(env: PlatformEnv & {
+    readonly dsn?: string;
+    readonly force?: boolean;
+}): MiiErrorPolicy;
+export type MiiAnalyticsPolicy = {
+    readonly enabled: boolean;
+    /** posthog-js init options: `posthog.init("in-house", options)`. */
+    readonly options: {
+        readonly api_host: string;
+        /** posthog-js "defaults era" — a date literal its ConfigDefaults union accepts. */
+        readonly defaults: "2026-06-25";
+        readonly person_profiles: "identified_only";
+        readonly advanced_disable_flags: true;
+        readonly disable_external_dependency_loading: true;
+        readonly disable_surveys: true;
+        readonly disable_session_recording: true;
+        readonly capture_exceptions: false;
+    };
+};
+/**
+ * Analytics is in-house: posthog-js is purely the capture SDK, events go to
+ * the mii ingest endpoint and no analytics vendor is involved. Off in local
+ * dev unless forced, so clicking around locally doesn't pollute product data.
+ * Cloud-only SDK features stay off so the client never phones home.
+ */
+export declare function miiAnalyticsPolicy(env: PlatformEnv & {
+    readonly ingestHost: string;
+    readonly force?: boolean;
+}): MiiAnalyticsPolicy;
+/**
+ * Whether this browser is automation (the org's own agents, E2E runs), which
+ * analytics must keep separable from real users (`is_agent=true`).
+ * `?mii_agent=1` is the manual override and persists via localStorage;
+ * Playwright-family browsers set `navigator.webdriver`.
+ */
+export declare function isAgentBrowser(win: Window): boolean;

package/dist/platform/index.js

@@ -0,0 +1,101 @@
+// The platform policies every mii org app must agree on, framework-free and
+// dependency-free. The framing list, the error-reporting rules and the
+// analytics rules are contracts: an app that drifts on any of them breaks its
+// deal with Plaza (a pane it cannot be shown in, errors nobody can attribute,
+// events that pollute product data). Frameworks come and go around this file;
+// nothing in it may import one.
+/**
+ * Plaza origins allowed to frame an org app AND to drive its preview bridge.
+ * One list on purpose: who may frame the app and who may talk to it must never
+ * drift apart. localhost is here because Plaza is developed locally against
+ * real deployed org apps.
+ */
+export const PLAZA_FRAME_ORIGINS = [
+    "https://plaza.miis.run",
+    "https://miiplaza.vercel.app",
+    "http://localhost:3000",
+    "http://localhost:3111"
+];
+export const FRAME_ANCESTORS = `frame-ancestors 'self' ${PLAZA_FRAME_ORIGINS.join(" ")}`;
+/** Force a Content-Security-Policy value's frame-ancestors to allow Plaza. */
+export function forceFrameAncestors(csp) {
+    const directives = csp
+        .split(";")
+        .map((d) => d.trim())
+        .filter((d) => d !== "" && !d.toLowerCase().startsWith("frame-ancestors"));
+    directives.push(FRAME_ANCESTORS);
+    return directives.join("; ");
+}
+/**
+ * Enforce the framing contract on one response's headers, in place: any CSP
+ * keeps its own directives but frame-allows Plaza, X-Frame-Options is dropped
+ * (it cannot allowlist; CSP governs), and a response with no CSP gains one.
+ * Wire it wherever the app touches every response once — a Start server
+ * middleware, a Node server hook — and the Newmark white-pane class of bug
+ * has no mechanism left.
+ */
+export function applyMiiFraming(headers) {
+    headers.delete("x-frame-options");
+    const csp = headers.get("content-security-policy");
+    headers.set("content-security-policy", csp === null ? FRAME_ANCESTORS : forceFrameAncestors(csp));
+}
+const isDeployed = (env) => env.vercelEnv === "production" || env.vercelEnv === "preview";
+/**
+ * The Sentry init options an org app must not diverge from, for any Sentry
+ * SDK (`Sentry.init({ dsn, ...miiErrorPolicy(...) })`). The Sentry project is
+ * shared across every org app, so an untagged event is un-attributable: the
+ * policy stays OFF rather than emit one. Errors are the only quota the
+ * platform pays for — tracing stays off. `force` mirrors SENTRY_FORCE_ENABLE
+ * for testing locally.
+ */
+export function miiErrorPolicy(env) {
+    return {
+        enabled: Boolean(env.dsn) &&
+            Boolean(env.orgId) &&
+            (isDeployed(env) || env.force === true),
+        environment: env.vercelEnv ?? "development",
+        tracesSampleRate: 0,
+        sendDefaultPii: false,
+        initialScope: { tags: { org_id: env.orgId } }
+    };
+}
+/**
+ * Analytics is in-house: posthog-js is purely the capture SDK, events go to
+ * the mii ingest endpoint and no analytics vendor is involved. Off in local
+ * dev unless forced, so clicking around locally doesn't pollute product data.
+ * Cloud-only SDK features stay off so the client never phones home.
+ */
+export function miiAnalyticsPolicy(env) {
+    return {
+        enabled: isDeployed(env) || env.force === true,
+        options: {
+            api_host: env.ingestHost,
+            defaults: "2026-06-25",
+            person_profiles: "identified_only",
+            advanced_disable_flags: true,
+            disable_external_dependency_loading: true,
+            disable_surveys: true,
+            disable_session_recording: true,
+            capture_exceptions: false
+        }
+    };
+}
+/**
+ * Whether this browser is automation (the org's own agents, E2E runs), which
+ * analytics must keep separable from real users (`is_agent=true`).
+ * `?mii_agent=1` is the manual override and persists via localStorage;
+ * Playwright-family browsers set `navigator.webdriver`.
+ */
+export function isAgentBrowser(win) {
+    try {
+        if (new URLSearchParams(win.location.search).has("mii_agent")) {
+            win.localStorage.setItem("mii_agent", "1");
+        }
+        return (win.navigator.webdriver === true ||
+            win.localStorage.getItem("mii_agent") === "1");
+    }
+    catch {
+        // localStorage can be unavailable (privacy modes); never break the app.
+        return win.navigator.webdriver === true;
+    }
+}

package/dist/react/index.d.ts

@@ -0,0 +1 @@
+export { MiiPaneBridge } from "./pane-bridge.js";

package/dist/react/index.js

@@ -0,0 +1,4 @@
+// React pieces of the platform contract. Framework-free React: no Next, no
+// TanStack imports — route changes are observed from the History API itself,
+// so the same component is correct under any router.
+export { MiiPaneBridge } from "./pane-bridge.js";

package/dist/react/pane-bridge.d.ts

@@ -0,0 +1 @@
+export declare function MiiPaneBridge(): null;

package/dist/react/pane-bridge.js

@@ -0,0 +1,206 @@
+"use client";
+// How an org app talks to Plaza when Plaza is showing it in a pane.
+//
+// Plaza embeds the deployment in an iframe. That iframe is a different origin,
+// so the browser will not let Plaza read the route inside it, catch its
+// errors, or find an element in it — a preview with none of those is a picture
+// of an app rather than something you can work on. This posts the missing
+// facts outward and answers the two questions Plaza can ask.
+//
+// Plaza speaks first. Until an allowed origin says hello this app posts
+// nothing at all, so being framed by someone else leaks nothing: no route, no
+// errors, no DOM. That handshake is also why the parent origin is never
+// guessed from `document.referrer`, which an iframe can suppress.
+//
+// Deliberately no analytics — the ingest pipe already records what people do.
+// This is only the live channel to the pane, and it leaves no trace.
+import { useEffect, useRef } from "react";
+import { PLAZA_FRAME_ORIGINS } from "../platform/index.js";
+const PLAZA_ORIGINS = PLAZA_FRAME_ORIGINS;
+/**
+ * Route changes without a router dependency: popstate covers back/forward,
+ * and pushState/replaceState are wrapped to announce themselves, which every
+ * SPA router ultimately calls. The wrap is installed once per mount and
+ * restored on unmount.
+ */
+function onRouteChange(callback) {
+    const announce = () => queueMicrotask(callback);
+    const wrap = (method) => {
+        const original = window.history[method].bind(window.history);
+        const wrapped = (...args) => {
+            original(...args);
+            announce();
+        };
+        window.history[method] = wrapped;
+        return () => {
+            window.history[method] = original;
+        };
+    };
+    const restorePush = wrap("pushState");
+    const restoreReplace = wrap("replaceState");
+    window.addEventListener("popstate", announce);
+    return () => {
+        restorePush();
+        restoreReplace();
+        window.removeEventListener("popstate", announce);
+    };
+}
+export function MiiPaneBridge() {
+    // Set by the handshake, read by the route announcements. A ref rather than
+    // state: nothing renders from it.
+    const plazaRef = useRef(null);
+    useEffect(() => {
+        // `window.parent === window` when this app is the whole tab, which is the
+        // ordinary case — someone just using the app.
+        if (window.parent === window)
+            return;
+        const describe = () => ({
+            path: window.location.pathname + window.location.search,
+            title: document.title
+        });
+        const send = (message) => {
+            const plaza = plazaRef.current;
+            if (plaza !== null)
+                window.parent.postMessage(message, plaza);
+        };
+        // Runtime failures the pane would otherwise never hear about. Sentry gets
+        // these too, but Sentry is somewhere you go afterwards — an agent watching
+        // its own change land needs to know now.
+        const onError = (event) => send({
+            type: "mii-preview:error",
+            message: event.message,
+            source: `${event.filename}:${event.lineno}`
+        });
+        const onRejection = (event) => send({
+            type: "mii-preview:error",
+            message: String(event.reason),
+            source: "unhandled rejection"
+        });
+        // Select mode. Hovering paints one outline element — reused, never
+        // stacked — and clicking reports what was picked instead of activating
+        // it: you are pointing at a button to talk about it, not pressing it.
+        let selecting = false;
+        const outline = document.createElement("div");
+        outline.setAttribute("aria-hidden", "true");
+        // Injected imperatively and deliberately outside the design system: this
+        // paints over the app, so it must not inherit the app's own theming.
+        outline.style.cssText =
+            "position:fixed;pointer-events:none;z-index:2147483647;display:none;" +
+                "border:2px solid #4f7cff;border-radius:3px;background:rgba(79,124,255,0.12)";
+        const onMove = (event) => {
+            if (!selecting)
+                return;
+            const rect = event.target.getBoundingClientRect();
+            outline.style.display = "block";
+            outline.style.top = `${rect.top}px`;
+            outline.style.left = `${rect.left}px`;
+            outline.style.width = `${rect.width}px`;
+            outline.style.height = `${rect.height}px`;
+        };
+        const onClick = (event) => {
+            if (!selecting)
+                return;
+            event.preventDefault();
+            event.stopPropagation();
+            const target = event.target;
+            send({
+                type: "mii-preview:picked",
+                // `data-el` is the codebase's label convention — the analytics ingest
+                // reads the same attribute, so an element already named for a chart
+                // arrives here under the name it already has.
+                label: target.getAttribute("data-el") ??
+                    (target.textContent ?? "").trim().slice(0, 80),
+                selector: selectorFor(target),
+                tag: target.tagName.toLowerCase(),
+                ...describe()
+            });
+        };
+        const onMessage = (event) => {
+            if (!PLAZA_ORIGINS.includes(event.origin))
+                return;
+            plazaRef.current = event.origin;
+            const message = event.data;
+            if (message.type === "mii-preview:hello") {
+                send({ type: "mii-preview:ready", ...describe() });
+                return;
+            }
+            if (message.type === "mii-preview:select") {
+                selecting = message.on;
+                document.body.style.cursor = selecting ? "crosshair" : "";
+                if (!selecting)
+                    outline.style.display = "none";
+                return;
+            }
+            if (message.type === "mii-preview:locate") {
+                // Where is this element, right now, in this window? Plaza uses the
+                // answer to put a cursor on it. Asked by element rather than by
+                // coordinates so the answer stays right when this window is a
+                // different size than the one being replayed.
+                const found = document.querySelector(message.selector);
+                send({
+                    type: "mii-preview:located",
+                    id: message.id,
+                    rect: found === null ? null : rectOf(found)
+                });
+            }
+        };
+        // A navigation reports itself; the listener set above stays put.
+        const stopRouteWatch = onRouteChange(() => {
+            const plaza = plazaRef.current;
+            if (plaza === null)
+                return;
+            window.parent.postMessage({ type: "mii-preview:route", ...describe() }, plaza);
+        });
+        document.body.appendChild(outline);
+        window.addEventListener("error", onError);
+        window.addEventListener("unhandledrejection", onRejection);
+        window.addEventListener("message", onMessage);
+        document.addEventListener("mousemove", onMove, true);
+        document.addEventListener("click", onClick, true);
+        return () => {
+            stopRouteWatch();
+            window.removeEventListener("error", onError);
+            window.removeEventListener("unhandledrejection", onRejection);
+            window.removeEventListener("message", onMessage);
+            document.removeEventListener("mousemove", onMove, true);
+            document.removeEventListener("click", onClick, true);
+            document.body.style.cursor = "";
+            outline.remove();
+        };
+    }, []);
+    return null;
+}
+function rectOf(element) {
+    const rect = element.getBoundingClientRect();
+    return { x: rect.x, y: rect.y, width: rect.width, height: rect.height };
+}
+/**
+ * A selector that finds this element again in another window. Prefers the
+ * names that survive a re-render — an id, the `data-el` label — and only
+ * counts siblings when an element carries no name of its own.
+ */
+function selectorFor(element) {
+    const parts = [];
+    let node = element;
+    while (node !== null && node !== document.body) {
+        if (node.id !== "") {
+            parts.unshift(`#${CSS.escape(node.id)}`);
+            break;
+        }
+        const label = node.getAttribute("data-el");
+        if (label !== null) {
+            parts.unshift(`[data-el="${CSS.escape(label)}"]`);
+            break;
+        }
+        const parent = node.parentElement;
+        const tag = node.tagName.toLowerCase();
+        if (parent === null) {
+            parts.unshift(tag);
+            break;
+        }
+        const twins = [...parent.children].filter((child) => child.tagName === node?.tagName);
+        parts.unshift(twins.length === 1 ? tag : `${tag}:nth-of-type(${twins.indexOf(node) + 1})`);
+        node = parent;
+    }
+    return parts.join(" > ");
+}

package/dist/server/build-marker.d.ts

@@ -0,0 +1,10 @@
+export type BuildMarkerOptions = {
+    /** Defaults to VERCEL_DEPLOYMENT_ID / VERCEL_GIT_COMMIT_SHA, read per request. */
+    readonly deploymentId?: () => string | undefined;
+    readonly commitSha?: () => string | undefined;
+};
+/** GET + OPTIONS for /api/mii-build; mount both from one factory. */
+export declare function createBuildMarkerHandler(options?: BuildMarkerOptions): {
+    GET(request: Request): Response;
+    OPTIONS(request: Request): Response;
+};

package/dist/server/build-marker.js

@@ -0,0 +1,51 @@
+// Which build of this app is currently serving.
+//
+// Plaza's App pane is an iframe of the deployment. When an agent ships, the
+// URL does not move, so nothing tells the pane the page underneath it is now
+// stale — the pane polls this and reloads the frame when the answer changes.
+// Plaza's server asks the same question for agents (deployedCommitOf), which
+// is why this stays a route on the app: "the domain answers with this commit"
+// is a stronger claim than any deploy provider's READY, and it needs no
+// provider token to work.
+//
+// Deliberately touches nothing: no database, no imports beyond the origin
+// list. It is polled every few seconds by every open pane, so it has to be
+// the cheapest route in the app — the health check next door opens a Postgres
+// connection and would wake the database on a timer forever.
+import { PLAZA_FRAME_ORIGINS } from "../platform/index.js";
+function corsHeaders(origin) {
+    // Echo the caller's origin only when it is a Plaza we know. `*` would let
+    // any page on the internet read this; harmless today, but this is the
+    // pattern the next endpoint copies, and the next one may not be harmless.
+    return origin !== null && PLAZA_FRAME_ORIGINS.includes(origin)
+        ? {
+            "Access-Control-Allow-Origin": origin,
+            Vary: "Origin",
+            "Cache-Control": "no-store"
+        }
+        : { "Cache-Control": "no-store" };
+}
+/** GET + OPTIONS for /api/mii-build; mount both from one factory. */
+export function createBuildMarkerHandler(options = {}) {
+    const deploymentId = options.deploymentId ?? (() => process.env.VERCEL_DEPLOYMENT_ID);
+    const commitSha = options.commitSha ?? (() => process.env.VERCEL_GIT_COMMIT_SHA);
+    return {
+        GET(request) {
+            // The deployment id changes on every deploy, including a redeploy of the
+            // same commit — which is exactly the question being asked. The commit
+            // rides along because it is the half a human can act on.
+            const deployment = deploymentId() ?? null;
+            const commit = commitSha() ?? null;
+            return Response.json({ build: deployment ?? commit, commit }, { headers: corsHeaders(request.headers.get("origin")) });
+        },
+        OPTIONS(request) {
+            return new Response(null, {
+                status: 204,
+                headers: {
+                    ...corsHeaders(request.headers.get("origin")),
+                    "Access-Control-Allow-Methods": "GET, OPTIONS"
+                }
+            });
+        }
+    };
+}

package/dist/server/db-retry.d.ts

@@ -0,0 +1,9 @@
+export declare const DB_RETRY_ATTEMPTS = 4;
+export declare function isTransientConnectionError(error: unknown): boolean;
+export type DbRetryOptions = {
+    readonly attempts?: number;
+    readonly baseDelayMs?: number;
+    /** Injected by tests so they do not spend real seconds sleeping. */
+    readonly sleep?: (ms: number) => Promise<void>;
+};
+export declare function withDbRetry<T>(operation: () => Promise<T>, options?: DbRetryOptions): Promise<T>;

package/dist/server/db-retry.js

@@ -0,0 +1,54 @@
+// Ported from the Next template's src/lib/db-retry.ts, where it earned its
+// shape in production (transient EAI_AGAIN across several orgs, 2026-08-22):
+// postgres.js connects lazily, so a resolver blip surfaces on the first query
+// and nothing underneath tries again. Retry the connect, and only the connect
+// — a wrong password or a missing table must still fail on attempt one.
+const TRANSIENT_CODES = new Set([
+    "EAI_AGAIN",
+    "ENOTFOUND",
+    "ETIMEDOUT",
+    "ECONNRESET",
+    "ECONNREFUSED",
+    "ENETUNREACH",
+    "EHOSTUNREACH",
+    "CONNECT_TIMEOUT"
+]);
+export const DB_RETRY_ATTEMPTS = 4;
+const BASE_DELAY_MS = 250;
+function errorCode(error) {
+    let current = error;
+    for (let depth = 0; current !== null && current !== undefined && depth < 5; depth += 1) {
+        const code = current.code;
+        if (typeof code === "string")
+            return code;
+        current = current.cause;
+    }
+    return undefined;
+}
+export function isTransientConnectionError(error) {
+    const code = errorCode(error);
+    return code !== undefined && TRANSIENT_CODES.has(code);
+}
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export async function withDbRetry(operation, options = {}) {
+    const attempts = options.attempts ?? DB_RETRY_ATTEMPTS;
+    const baseDelayMs = options.baseDelayMs ?? BASE_DELAY_MS;
+    const sleep = options.sleep ?? wait;
+    let lastError;
+    for (let attempt = 1; attempt <= attempts; attempt += 1) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            if (!isTransientConnectionError(error))
+                throw error;
+            lastError = error;
+            if (attempt < attempts)
+                await sleep(baseDelayMs * 2 ** (attempt - 1));
+        }
+    }
+    throw new Error(`Could not reach the database after ${attempts} attempts ` +
+        `(${errorCode(lastError) ?? "unknown"}). The host did not resolve or ` +
+        `accept a connection. This is a transient network fault, not a ` +
+        `credential, schema or permission problem — run the command again.`, { cause: lastError });
+}

package/dist/server/index.d.ts

@@ -0,0 +1,21 @@
+import { type DbRetryOptions } from "./db-retry.js";
+export { withDbRetry, isTransientConnectionError, DB_RETRY_ATTEMPTS } from "./db-retry.js";
+export type { DbRetryOptions } from "./db-retry.js";
+export { createBuildMarkerHandler, type BuildMarkerOptions } from "./build-marker.js";
+export { createSentryTunnelHandler, type SentryTunnelOptions } from "./sentry-tunnel.js";
+export type HealthHandlerOptions = {
+    /** Defaults to process.env.DATABASE_URL, read per request. */
+    readonly databaseUrl?: () => string | undefined;
+    /** Defaults to process.env.MII_ORG_ID. */
+    readonly orgId?: () => string | undefined;
+    /** Test hook: shrink attempts/delays so failure paths don't spend seconds. */
+    readonly retry?: DbRetryOptions;
+};
+/**
+ * GET /api/health — the readiness gate. The sandbox refuses to report an
+ * instance as up, and Plaza refuses to wake one, until this answers ok. It
+ * proves the one dependency that page loads actually need: the database
+ * answers a query. A transient DNS fault must not read as an unhealthy app,
+ * hence the connect retry.
+ */
+export declare function createHealthHandler(options?: HealthHandlerOptions): () => Promise<Response>;

package/dist/server/index.js

@@ -0,0 +1,45 @@
+// Web-standard server handlers (Request → Response) for the routes the
+// platform itself calls on every org app. Framework-free: a TanStack Start
+// server route, a Next route handler, or a bare Node server can mount these
+// verbatim — which is the point, because the platform's probes must behave
+// identically on every stack.
+import postgres from "postgres";
+import { withDbRetry } from "./db-retry.js";
+export { withDbRetry, isTransientConnectionError, DB_RETRY_ATTEMPTS } from "./db-retry.js";
+export { createBuildMarkerHandler } from "./build-marker.js";
+export { createSentryTunnelHandler } from "./sentry-tunnel.js";
+/**
+ * GET /api/health — the readiness gate. The sandbox refuses to report an
+ * instance as up, and Plaza refuses to wake one, until this answers ok. It
+ * proves the one dependency that page loads actually need: the database
+ * answers a query. A transient DNS fault must not read as an unhealthy app,
+ * hence the connect retry.
+ */
+export function createHealthHandler(options = {}) {
+    const databaseUrl = options.databaseUrl ?? (() => process.env.DATABASE_URL);
+    const orgId = options.orgId ?? (() => process.env.MII_ORG_ID);
+    return async function health() {
+        const url = databaseUrl();
+        if (!url) {
+            return Response.json({ ok: false, error: "DATABASE_URL is not configured" }, { status: 503 });
+        }
+        const sql = postgres(url, { max: 1, prepare: false, connect_timeout: 10 });
+        try {
+            const [result] = await withDbRetry(() => sql `
+          select current_database() as database, now()::text as now
+        `, options.retry);
+            return Response.json({
+                ok: true,
+                orgId: orgId() ?? null,
+                database: result?.database ?? null,
+                databaseTime: result?.now ?? null
+            });
+        }
+        catch (err) {
+            return Response.json({ ok: false, error: err instanceof Error ? err.message : "Unknown error" }, { status: 503 });
+        }
+        finally {
+            await sql.end();
+        }
+    };
+}

package/dist/server/sentry-tunnel.d.ts

@@ -0,0 +1,6 @@
+export type SentryTunnelOptions = {
+    /** Test hook; defaults to global fetch. */
+    readonly fetch?: typeof fetch;
+};
+/** POST for /monitoring: forward the envelope, answer what Sentry answered. */
+export declare function createSentryTunnelHandler(options?: SentryTunnelOptions): (request: Request) => Promise<Response>;

package/dist/server/sentry-tunnel.js

@@ -0,0 +1,43 @@
+// The Sentry tunnel: browsers post error envelopes to this app's own
+// /monitoring route, which forwards them to Sentry — because ad-blockers
+// block *.sentry.io from the browser, and a platform whose error reporting
+// dies to a browser extension is blind exactly where it matters.
+//
+// The envelope's own header names the DSN, so the route needs no
+// configuration; it forwards only to hosts that are plainly Sentry's, so an
+// app cannot be turned into an open relay by a crafted envelope.
+const ALLOWED_HOST = /(^|\.)(sentry\.io|ingest\.sentry\.io|ingest\.[a-z0-9-]+\.sentry\.io)$/;
+/** POST for /monitoring: forward the envelope, answer what Sentry answered. */
+export function createSentryTunnelHandler(options = {}) {
+    const doFetch = options.fetch ?? fetch;
+    return async function tunnel(request) {
+        const envelope = await request.text();
+        const newline = envelope.indexOf("\n");
+        const headerLine = newline === -1 ? envelope : envelope.slice(0, newline);
+        let dsn;
+        try {
+            const header = JSON.parse(headerLine);
+            if (typeof header.dsn !== "string") {
+                return Response.json({ error: "Envelope names no DSN." }, { status: 400 });
+            }
+            dsn = new URL(header.dsn);
+        }
+        catch {
+            return Response.json({ error: "Not a Sentry envelope." }, { status: 400 });
+        }
+        if (!ALLOWED_HOST.test(dsn.hostname)) {
+            // A DSN pointing anywhere else would make this route an open relay.
+            return Response.json({ error: "DSN host is not Sentry." }, { status: 400 });
+        }
+        const projectId = dsn.pathname.replace(/^\/+/, "");
+        if (!/^\d+$/.test(projectId)) {
+            return Response.json({ error: "DSN names no project." }, { status: 400 });
+        }
+        const upstream = await doFetch(`https://${dsn.hostname}/api/${projectId}/envelope/`, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-sentry-envelope" },
+            body: envelope
+        });
+        return new Response(null, { status: upstream.status });
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shubh90/app-runtime",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "The platform contract every mii org app depends on — sign-in, and the Next.js config an app must not diverge from. A versioned package, not files copied into each repo.",
   "license": "UNLICENSED",
   "type": "module",
@@ -27,6 +27,18 @@
     "./next": {
       "types": "./dist/next/index.d.ts",
       "import": "./dist/next/index.js"
+    },
+    "./platform": {
+      "types": "./dist/platform/index.d.ts",
+      "import": "./dist/platform/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js"
     }
   },
   "scripts": {
@@ -37,17 +49,23 @@
   },
   "peerDependencies": {
     "next": ">=15",
-    "postgres": ">=3"
+    "postgres": ">=3",
+    "react": ">=18"
   },
   "peerDependenciesMeta": {
     "next": {
       "optional": true
+    },
+    "react": {
+      "optional": "true"
     }
   },
   "devDependencies": {
     "@types/node": "^22",
+    "@types/react": "^19",
     "next": "^15",
     "postgres": "^3.4.9",
+    "react": "^19",
     "tsx": "^4",
     "typescript": "^5.6"
   }