@shubh90/app-runtime 0.2.2 → 0.4.0

package/dist/auth/core.d.ts

@@ -0,0 +1,66 @@
+import { getAuthMode } from "./mode.js";
+import { safeNext } from "./next-path.js";
+import { SIGN_IN_PROBLEMS } from "./problems.js";
+import { type MiiUser } from "./lookup.js";
+import { type MiiIdentity } from "./plaza.js";
+import { type UsersConfig } from "./users-config.js";
+export type { MiiUser } from "./lookup.js";
+export type { AuthMode } from "./mode.js";
+export type { MiiIdentity, SignInFailure, SignInResult } from "./plaza.js";
+export type { UsersConfig } from "./users-config.js";
+export { SIGN_IN_PROBLEMS } from "./problems.js";
+export { safeNext } from "./next-path.js";
+export { getAuthMode } from "./mode.js";
+export { SESSION_COOKIE, SESSION_TTL_MS } from "./lookup.js";
+export { miiAuthConfig, type MiiAuthConfig } from "./config.js";
+export { redeemWithPlaza, signInWithPlaza } from "./plaza.js";
+export type CreateMiiAuthCoreOptions = {
+    /** Which table holds this app's people, if not the default `mii_auth_users`. */
+    readonly users?: UsersConfig;
+    /** Where to report failures that are ours, not the person's. Defaults to console.error. */
+    readonly reportError?: (error: unknown, context: Record<string, string>) => void;
+};
+export type MiiAuthCore = {
+    /** The user behind a session token, or null. The app reads its own cookie. */
+    resolveSession(token: string): Promise<MiiUser | null>;
+    /** Start a session; the app sets the cookie itself (see cookie notes below). */
+    issueSession(userId: string): Promise<{
+        token: string;
+        expiresAt: Date;
+    }>;
+    /** End one session by its token. */
+    revokeSession(token: string): Promise<void>;
+    upsertMemberFromIdentity(identity: MiiIdentity): Promise<{
+        id: string;
+        status: string;
+    }>;
+    deactivateUser(userId: string): Promise<void>;
+    /**
+     * The pane's silent sign-in: spend a ?mii_code= for an identity, upsert the
+     * member, start a session. Null when the code is spent/stale or the member
+     * is inactive (send them to /login).
+     */
+    redeemPaneCode(code: string): Promise<{
+        token: string;
+        expiresAt: Date;
+    } | null>;
+    getAuthMode: typeof getAuthMode;
+    readonly SESSION_COOKIE: string;
+    readonly SIGN_IN_PROBLEMS: typeof SIGN_IN_PROBLEMS;
+    readonly safeNext: typeof safeNext;
+};
+/**
+ * Cookie attributes the app must use with issueSession's token, mirrored from
+ * the Next adapter: inside Plaza's App pane the app is a third party, so the
+ * cookie must be SameSite=None + Secure + partitioned or the pane signs in
+ * forever; opened directly it is an ordinary Lax cookie. Decide by the
+ * request's `Sec-Fetch-Dest: iframe` header.
+ */
+export declare function cookieAttributes(embedded: boolean): {
+    httpOnly: true;
+    path: "/";
+    sameSite: "none" | "lax";
+    secure: boolean;
+    partitioned: boolean;
+};
+export declare function createMiiAuthCore(options?: CreateMiiAuthCoreOptions): MiiAuthCore;

package/dist/auth/core.js

@@ -0,0 +1,62 @@
+import { makeAuthSql } from "./db.js";
+import { getAuthMode } from "./mode.js";
+import { safeNext } from "./next-path.js";
+import { SIGN_IN_PROBLEMS } from "./problems.js";
+import { issueSession, resolveSession, SESSION_COOKIE, SESSION_TTL_MS, hashToken } from "./lookup.js";
+import { redeemWithPlaza } from "./plaza.js";
+import { deactivateUser, upsertMemberFromIdentity } from "./users.js";
+import { resolveUsers } from "./users-config.js";
+export { SIGN_IN_PROBLEMS } from "./problems.js";
+export { safeNext } from "./next-path.js";
+export { getAuthMode } from "./mode.js";
+export { SESSION_COOKIE, SESSION_TTL_MS } from "./lookup.js";
+export { miiAuthConfig } from "./config.js";
+export { redeemWithPlaza, signInWithPlaza } from "./plaza.js";
+/**
+ * Cookie attributes the app must use with issueSession's token, mirrored from
+ * the Next adapter: inside Plaza's App pane the app is a third party, so the
+ * cookie must be SameSite=None + Secure + partitioned or the pane signs in
+ * forever; opened directly it is an ordinary Lax cookie. Decide by the
+ * request's `Sec-Fetch-Dest: iframe` header.
+ */
+export function cookieAttributes(embedded) {
+    return {
+        httpOnly: true,
+        path: "/",
+        sameSite: embedded ? "none" : "lax",
+        secure: embedded || process.env.NODE_ENV === "production",
+        partitioned: embedded
+    };
+}
+export function createMiiAuthCore(options = {}) {
+    const users = resolveUsers(options.users);
+    const ctx = {
+        getSql: makeAuthSql(users),
+        users,
+        reportError: options.reportError ??
+            ((error, context) => console.error("mii-auth error", context, error))
+    };
+    return {
+        resolveSession: (token) => resolveSession(ctx, token),
+        issueSession: (userId) => issueSession(ctx, userId),
+        revokeSession: async (token) => {
+            const sql = await ctx.getSql();
+            await sql `delete from mii_auth_sessions where token_hash = ${hashToken(token)}`;
+        },
+        upsertMemberFromIdentity: (identity) => upsertMemberFromIdentity(ctx, identity),
+        deactivateUser: (userId) => deactivateUser(ctx, userId),
+        redeemPaneCode: async (code) => {
+            const identity = await redeemWithPlaza(code);
+            if (identity === null)
+                return null;
+            const user = await upsertMemberFromIdentity(ctx, identity);
+            if (user.status !== "active")
+                return null;
+            return issueSession(ctx, user.id);
+        },
+        getAuthMode,
+        SESSION_COOKIE,
+        SIGN_IN_PROBLEMS,
+        safeNext
+    };
+}

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,79 @@
+/**
+ * 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;
+        readonly defaults: string;
+        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/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,19 @@
+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 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,43 @@
+// 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";
+/**
+ * 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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shubh90/app-runtime",
-  "version": "0.2.2",
-  "description": "The platform contract every mii org app depends on \u2014 sign-in, and the Next.js config an app must not diverge from. A versioned package, not files copied into each repo.",
+  "version": "0.4.0",
+  "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",
   "publishConfig": {
@@ -20,9 +20,25 @@
       "types": "./dist/auth/index.d.ts",
       "import": "./dist/auth/index.js"
     },
+    "./auth/core": {
+      "types": "./dist/auth/core.d.ts",
+      "import": "./dist/auth/core.js"
+    },
     "./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": {
@@ -33,12 +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"
   }