@trylight/app 0.1.9 → 0.2.0

package/dist/platform/index.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Platform 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. The app's origins come from config/brand.json; the
+ * Vercel alias and localhost are here because the platform is developed
+ * locally against real deployed org apps.
+ */
+export declare const PLAZA_FRAME_ORIGINS: readonly string[];
+export declare const FRAME_ANCESTORS: string;
+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({ vercelEnv, orgId, dsn, force }: 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 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({ vercelEnv, ingestHost, force }: 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;
+export { mayCallServerFn, type ServerFnName } from "./server-fn-door.js";

package/dist/platform/index.js

@@ -0,0 +1,80 @@
+// The platform policies every 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 the platform (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.
+import { APP_ORIGINS } from "../brand.generated.js";
+/**
+ * Platform 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. The app's origins come from config/brand.json; the
+ * Vercel alias and localhost are here because the platform is developed
+ * locally against real deployed org apps.
+ */
+export const PLAZA_FRAME_ORIGINS = [
+    ...APP_ORIGINS,
+    "https://miiplaza.vercel.app",
+    "http://localhost:3000",
+    "http://localhost:3111"
+];
+export const FRAME_ANCESTORS = `frame-ancestors 'self' ${PLAZA_FRAME_ORIGINS.join(" ")}`;
+const isDeployed = (vercelEnv) => vercelEnv === "production" || 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({ vercelEnv = "development", orgId, dsn, force = false }) {
+    return {
+        enabled: Boolean(dsn) && Boolean(orgId) && (isDeployed(vercelEnv) || force),
+        environment: vercelEnv,
+        tracesSampleRate: 0,
+        sendDefaultPii: false,
+        initialScope: { tags: { org_id: orgId } }
+    };
+}
+/**
+ * Analytics is in-house: posthog-js is purely the capture SDK, events go to
+ * the 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({ vercelEnv = "development", ingestHost, force = false }) {
+    return {
+        enabled: isDeployed(vercelEnv) || force,
+        options: {
+            api_host: 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;
+    }
+}
+export { mayCallServerFn } from "./server-fn-door.js";

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

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

package/dist/platform/pane-bridge.js

@@ -0,0 +1,216 @@
+"use client";
+// How an org app talks to the platform when the platform is showing it in a pane.
+//
+// The platform embeds the deployment in an iframe. That iframe is a different origin,
+// so the browser will not let the platform 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 the platform can ask.
+//
+// The platform 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 { z } from "zod/v4";
+import { PLAZA_FRAME_ORIGINS } from "./index.js";
+const PLAZA_ORIGINS = PLAZA_FRAME_ORIGINS;
+/** The platform → app. Anything else the platform posts is not for this bridge. */
+const inbound = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("mii-preview:hello") }),
+    z.object({ type: z.literal("mii-preview:select"), on: z.boolean() }),
+    z.object({ type: z.literal("mii-preview:locate"), id: z.string(), selector: z.string() })
+]);
+/**
+ * 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) => {
+            const { target } = event;
+            if (!selecting || !(target instanceof Element))
+                return;
+            const rect = 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) => {
+            const { target } = event;
+            if (!selecting || !(target instanceof Element))
+                return;
+            event.preventDefault();
+            event.stopPropagation();
+            // `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.
+            const label = target.getAttribute("data-el");
+            send({
+                type: "mii-preview:picked",
+                label: label === null ? target.textContent.trim().slice(0, 80) : label,
+                selector: selectorFor(target),
+                tag: target.tagName.toLowerCase(),
+                ...describe()
+            });
+        };
+        const onMessage = (event) => {
+            if (!PLAZA_ORIGINS.includes(event.origin))
+                return;
+            plazaRef.current = event.origin;
+            const read = inbound.safeParse(event.data);
+            if (!read.success)
+                return;
+            const message = read.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;
+            }
+            // Where is this element, right now, in this window? The platform 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 = [];
+    for (let node = element; node !== null; node = node.parentElement) {
+        if (node.isSameNode(document.body))
+            break;
+        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 current = node;
+        const tag = current.tagName.toLowerCase();
+        const parent = current.parentElement;
+        if (parent === null) {
+            parts.unshift(tag);
+            break;
+        }
+        const twins = [...parent.children].filter((child) => child.tagName === current.tagName);
+        parts.unshift(twins.length === 1 ? tag : `${tag}:nth-of-type(${twins.indexOf(current) + 1})`);
+    }
+    return parts.join(" > ");
+}

package/dist/platform/server-fn-door.d.ts

@@ -0,0 +1,27 @@
+/**
+ * A server function by where it is declared, as TanStack Start's compiler
+ * names it for middleware (`serverFnMeta`): `<file>#<variable>`, e.g.
+ * `src/routes/index.tsx#submitWaitlist`.
+ */
+export type ServerFnName = `${string}#${string}`;
+export type ServerFnCall = {
+    readonly fn: {
+        readonly filename: string;
+        readonly name: string;
+    };
+    readonly method: string;
+    /** The app's own list of functions anyone may call (a public waitlist form). */
+    readonly publicServerFns: readonly ServerFnName[];
+    /** Only asked when the function is not open to everyone. */
+    readonly session: () => Promise<{
+        readonly user: unknown;
+        readonly mode: "public" | "members";
+    }>;
+};
+/**
+ * Whether this call may run. Anyone may call the sign-in functions and the
+ * app's public list. Otherwise a members-only app needs a signed-in member for
+ * everything, and a public app lets anyone read (GET) but only a signed-in
+ * person write.
+ */
+export declare function mayCallServerFn(call: ServerFnCall): Promise<boolean>;

package/dist/platform/server-fn-door.js

@@ -0,0 +1,32 @@
+// The door on an org app's server functions. A page's door (its route guard)
+// never sees a server function called directly by URL, so without this an app
+// whose functions forget their own guard serves the org's data to anyone.
+/**
+ * The template's server functions a signed-out visitor needs to become signed
+ * in: who am I, the two ways to sign in, signing out, and the config the login
+ * page renders with.
+ */
+const SIGN_IN_SERVER_FNS = [
+    "src/lib/auth.ts#getSessionUser",
+    "src/lib/auth.ts#redeemPaneCode",
+    "src/lib/auth.ts#loginWithPassword",
+    "src/lib/auth.ts#logout",
+    "src/routes/__root.tsx#getPlatformConfig"
+];
+/**
+ * Whether this call may run. Anyone may call the sign-in functions and the
+ * app's public list. Otherwise a members-only app needs a signed-in member for
+ * everything, and a public app lets anyone read (GET) but only a signed-in
+ * person write.
+ */
+export async function mayCallServerFn(call) {
+    const name = `${call.fn.filename}#${call.fn.name}`;
+    if (SIGN_IN_SERVER_FNS.includes(name) ||
+        call.publicServerFns.includes(name)) {
+        return true;
+    }
+    const { user, mode } = await call.session();
+    if (user !== null)
+        return true;
+    return mode === "public" && call.method === "GET";
+}

package/dist/platform.d.ts

@@ -1,2 +1,2 @@
-export { FRAME_ANCESTORS, isAgentBrowser, mayCallServerFn, miiAnalyticsPolicy, miiErrorPolicy, PLAZA_FRAME_ORIGINS, type ServerFnName } from "@shubh90/app-runtime/platform";
-export { MiiPaneBridge } from "@shubh90/app-runtime/react";
+export { FRAME_ANCESTORS, isAgentBrowser, mayCallServerFn, miiAnalyticsPolicy, miiErrorPolicy, PLAZA_FRAME_ORIGINS, type ServerFnName } from "./platform/index.js";
+export { MiiPaneBridge } from "./platform/pane-bridge.js";

package/dist/platform.js

@@ -1,5 +1,5 @@
 // The platform contract a page and the global middleware need: framing by
 // the platform's App pane, the server-function door, analytics and error policies,
-// and the pane bridge. Behaviour lives in @shubh90/app-runtime.
-export { FRAME_ANCESTORS, isAgentBrowser, mayCallServerFn, miiAnalyticsPolicy, miiErrorPolicy, PLAZA_FRAME_ORIGINS } from "@shubh90/app-runtime/platform";
-export { MiiPaneBridge } from "@shubh90/app-runtime/react";
+// and the pane bridge.
+export { FRAME_ANCESTORS, isAgentBrowser, mayCallServerFn, miiAnalyticsPolicy, miiErrorPolicy, PLAZA_FRAME_ORIGINS } from "./platform/index.js";
+export { MiiPaneBridge } from "./platform/pane-bridge.js";

package/dist/request-error.d.ts

@@ -0,0 +1,10 @@
+/** A refusal from one of this app's own platform routes. */
+export declare class RequestError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+export declare function errorBody(text: string, fallback: string): {
+    code: string;
+    detail: string;
+};

package/dist/request-error.js

@@ -0,0 +1,29 @@
+/** A refusal from one of this app's own platform routes. */
+export class RequestError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+    }
+}
+// The platform answers { error: <sentence>, code? }. Whatever sits in front of the app
+// (a CDN, a dev server) may answer with a page of HTML instead: `fallback` is
+// the sentence for an answer that carries none.
+export function errorBody(text, fallback) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return { code: "error", detail: fallback };
+    }
+    const body = Object(parsed);
+    return { code: asText(body.code, "error"), detail: asText(body.error, fallback) };
+}
+/** `value` when it is text, else `fallback`. */
+function asText(value, fallback) {
+    // eslint-disable-next-line no-restricted-syntax -- the chat widget's eager bundle rides on every org-app page; a schema library here would too
+    return typeof value === "string" ? value : fallback;
+}

package/dist/schema.d.ts

@@ -179,7 +179,7 @@ export declare const lightChanges: PgTableWithColumns<{
             tableName: "light_changes";
             dataType: "string";
             columnType: "PgText";
-            data: "person" | "agent" | "database";
+            data: "database" | "agent" | "person";
             driverParam: string;
             notNull: true;
             hasDefault: false;

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

@@ -0,0 +1,7 @@
+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>, { attempts, baseDelayMs, sleep }?: DbRetryOptions): Promise<T>;

package/dist/server/db-retry.js

@@ -0,0 +1,58 @@
+// 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.
+import { z } from "zod/v4";
+const TRANSIENT_CODES = new Set([
+    "EAI_AGAIN",
+    "ENOTFOUND",
+    "ETIMEDOUT",
+    "ECONNRESET",
+    "ECONNREFUSED",
+    "ENETUNREACH",
+    "EHOSTUNREACH",
+    "CONNECT_TIMEOUT"
+]);
+const DB_RETRY_ATTEMPTS = 4;
+const BASE_DELAY_MS = 250;
+/** A Node system error names its code; anything wrapping one names it as its cause. */
+const coded = z.object({ code: z.string() });
+const caused = z.object({ cause: z.unknown() });
+/** The error's code, or the wrapped one's; "unknown" for an error that names none. */
+function errorCode(error) {
+    let current = error;
+    for (let depth = 0; depth < 5; depth += 1) {
+        const named = coded.safeParse(current);
+        if (named.success)
+            return named.data.code;
+        const wrapped = caused.safeParse(current);
+        if (!wrapped.success)
+            return "unknown";
+        current = wrapped.data.cause;
+    }
+    return "unknown";
+}
+function isTransientConnectionError(error) {
+    return TRANSIENT_CODES.has(errorCode(error));
+}
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export async function withDbRetry(operation, { attempts = DB_RETRY_ATTEMPTS, baseDelayMs = BASE_DELAY_MS, 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)}). 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/entities.js

@@ -5,7 +5,7 @@
 import { and, asc, desc, eq, getTableColumns, getTableName, ilike, inArray, isNull, or, sql } from "drizzle-orm";
 import { isDeepStrictEqual } from "node:util";
 import { createSchemaFactory } from "drizzle-zod";
-import { isSameOrigin } from "@shubh90/app-runtime/chat/server";
+import { isSameOrigin } from "../chat/server.js";
 import { z } from "zod/v4";
 import { ENTITIES_PATH, LIST_LIMIT } from "../entities.js";
 import { PLATFORM_COLUMNS, fieldSource, isEntity } from "../schema.js";

package/dist/server/health.d.ts

@@ -0,0 +1,17 @@
+import { type DbRetryOptions } from "./db-retry.js";
+export type HealthHandlerOptions = {
+    /** Defaults to process.env.DATABASE_URL, read per request; null when unset. */
+    readonly databaseUrl?: () => string | null;
+    /** Defaults to process.env.MII_ORG_ID. */
+    readonly orgId?: () => string | null;
+    /** 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 the platform 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({ databaseUrl, orgId, retry }?: HealthHandlerOptions): () => Promise<Response>;

package/dist/server/health.js

@@ -0,0 +1,42 @@
+// The readiness route the platform calls on every org app, as a web-standard
+// handler (Request → Response).
+import postgres from "postgres";
+import { withDbRetry } from "./db-retry.js";
+/** An env var as it is now: its text, or null when unset. */
+function envVar(name) {
+    const { [name]: value = null } = process.env;
+    return value;
+}
+/**
+ * GET /api/health — the readiness gate. The sandbox refuses to report an
+ * instance as up, and the platform 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({ databaseUrl = () => envVar("DATABASE_URL"), orgId = () => envVar("MII_ORG_ID"), retry } = {}) {
+    return async function health() {
+        const url = databaseUrl();
+        if (url === null || 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 = { database: null, now: null }] = await withDbRetry(() => sql `
+          select current_database() as database, now()::text as now
+        `, retry);
+            return Response.json({
+                ok: true,
+                orgId: orgId(),
+                database: result.database,
+                databaseTime: result.now
+            });
+        }
+        catch (err) {
+            return Response.json({ ok: false, error: err instanceof Error ? err.message : "Unknown error" }, { status: 503 });
+        }
+        finally {
+            await sql.end();
+        }
+    };
+}