@trylight/app 0.3.2 → 0.3.5

package/README.md

@@ -10,7 +10,7 @@ its tables and their typed client, its door, its contracts and its chat.
 | `@trylight/app/schema` | `entity(name, columns, access)`: a Drizzle table plus `id`, `created_at`, `updated_at`, `created_by`, `field_sources`; `lightChanges` (the audit table); `lightImages` (the app's copy of its logos and photos); `fieldSource` (the `{url, evidence}` schema) |
 | `@trylight/app` | `createApp<typeof contracts>()` → `app.table(entity)` (`list/get/create/update/delete`, `useList/useInfiniteList/useGet/useCreate/useUpdate/useDelete`, typed by the entity passed; `useList(...).rows` is never undefined), `app.contracts` (`useInvocation`), and `imageSrc(url)` (where a logo or photo loads from) |
 | `@trylight/app/server` | `createLightServer({ schema, contracts })` → `light.db` (Drizzle), `light.session(request)`, `light.signIn(email, password)`, and the route handlers `light.entities`, `light.image`, `light.invoke.handler`, `light.chat` |
-| `@trylight/app/platform` | the door for server functions, framing, analytics/error policies, the pane bridge |
+| `@trylight/app/platform` | the door for server functions, framing, analytics/error policies, the pane bridge, `fetchThroughRestart` (`createStart`'s `serverFns.fetch`) |
 | `@trylight/app/vite` | `lightDb()`: the dev server syncs `db/schema` into the database on every change |
 | `light-db` (bin) | `sync`, `migrate`, `check`: the app's `pnpm db:*` scripts |
 
@@ -41,6 +41,16 @@ text column, case-insensitively, on the server.
 
 Joins and aggregates stay typed server functions over `light.db`.
 
+### Through a dev server restart
+
+Table calls, contract calls and server functions (through
+`fetchThroughRestart`) wait while the gateway answers that the app is starting
+(503 + `x-mii-app-starting`, any method) or, for reads only, while the
+connection fails, for up to `RESTART_WAIT_MS`; then the last answer or error
+is the caller's. The pane hears each request that starts or stops waiting
+(`light:requests-held`: `held` still waiting, `started` for a new one) and swaps
+in a reloaded frame only once none is held.
+
 ### Live data
 
 An open page shows other people's and agents' changes without a refresh.

package/dist/auth/next-path.js

@@ -1,10 +1,16 @@
-// Only a path on this app is a valid place to land after signing in. Anything
-// absolute (or protocol-relative) would make the login flow an open redirect.
+import { SAME_ORIGIN_BASE } from "../platform/contract.js";
+// Only a path on this app is a valid place to land after signing in. Parsed,
+// not pattern-matched: browsers read `//host`, `/\host` and `/\t/host` as
+// another site. The candidate is returned as given, not normalised: its
+// pathname could read `//host`.
 export function safeNext(candidate) {
     if (candidate === null ||
         !candidate.startsWith("/") ||
-        candidate.startsWith("//")) {
+        // The parser drops tabs and line breaks; a Location header refuses them.
+        [...candidate].some((character) => character < " ")) {
         return "/";
     }
-    return candidate;
+    return new URL(candidate, SAME_ORIGIN_BASE).origin === SAME_ORIGIN_BASE
+        ? candidate
+        : "/";
 }

package/dist/client.js

@@ -12,6 +12,7 @@ import { getTableColumns, getTableName } from "drizzle-orm";
 import { z } from "zod/v4";
 import { ENTITIES_PATH } from "./platform/contract.js";
 import { EntityError, LIST_LIMIT, tableQueryKey } from "./entities.js";
+import { fetchThroughRestart } from "./platform/restart.js";
 export { EntityError, LIST_LIMIT } from "./entities.js";
 export { siteOf } from "./schema.js";
 export { imageSrc } from "./images.js";
@@ -354,7 +355,7 @@ function json(body) {
 }
 const refusal = z.object({ error: z.string(), code: z.string() });
 async function call(method, path, init = {}) {
-    const response = await fetch(path, { ...init, method, credentials: "same-origin" });
+    const response = await fetchThroughRestart(path, { ...init, method, credentials: "same-origin" });
     if (response.ok)
         return response.json();
     const read = refusal.safeParse(await response.json().catch(() => null));

package/dist/invoke/index.js

@@ -3,6 +3,7 @@
 // the hook reports how long it has been and the app decides what that means.
 import { useEffect, useMemo, useState } from "react";
 import { z } from "zod/v4";
+import { fetchThroughRestart, wait } from "../platform/restart.js";
 import { errorBody } from "../request-error.js";
 import { failedRun, InvocationError } from "./error.js";
 import { INVOKE_BASE_PATH, STORAGE_KEYS } from "../platform/contract.js";
@@ -65,7 +66,7 @@ async function awaitInvocation(started, signal = null, onPoll = unwatched) {
 async function call(method, path, body, signal) {
     let response;
     try {
-        response = await fetch(`${INVOKE_BASE_PATH}${path}`, {
+        response = await fetchThroughRestart(`${INVOKE_BASE_PATH}${path}`, {
             method,
             credentials: "same-origin",
             ...(body === null ? {} : { headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) }),
@@ -90,23 +91,6 @@ async function call(method, path, body, signal) {
         throw new InvocationError(response.status, "not_the_handler", "The app's invoke routes are not reachable.");
     }
 }
-function wait(ms, signal) {
-    return new Promise((resolve, reject) => {
-        if (signal === null) {
-            setTimeout(resolve, ms);
-            return;
-        }
-        const abort = () => {
-            clearTimeout(timer);
-            reject(signal.reason);
-        };
-        const timer = setTimeout(() => {
-            signal.removeEventListener("abort", abort);
-            resolve();
-        }, ms);
-        signal.addEventListener("abort", abort, { once: true });
-    });
-}
 // This browser's note of a remembered run. Storage can be blocked or full;
 // then the run is simply not picked up again. Whose run it is the platform decides:
 // another person's id reads as not found, and the note is let go of.

package/dist/platform/contract.d.ts

@@ -5,17 +5,23 @@ export declare const IMAGE_PATH = "/api/light/image";
 export declare const BUILD_PATH = "/api/light/build";
 export declare const INVOKE_BASE_PATH = "/api/mii/invoke";
 export declare const CHAT_BASE_PATH = "/api/mii/chat";
+/** A base to resolve an app-relative path against when checking it stays on the app; never contacted. */
+export declare const SAME_ORIGIN_BASE = "https://app.invalid";
 /** The platform's sign-in API, called with an app's own id. */
 export declare const PLATFORM_AUTH_PATHS: {
     signIn: string;
     requestPasswordReset: string;
     redeemPaneCode: string;
     config: string;
+    /** "Continue with Google / Microsoft": the platform signs the person in and returns with a one-time code. */
+    socialSignIn: string;
 };
 /** The platform's chat API: an app's chat route forwards any path beneath it, so a new widget route needs no SDK release. */
 export declare const PLATFORM_CHAT_PATH = "/api/app-chat/v1/chat";
 /** What this app's chat server forwards beyond the first contract: the widget, served to every app version, offers only these. */
 export declare const CHAT_FEATURES_HEADER = "X-Mii-Chat-Features";
+/** The gateway's mark on its 503 while the app's server is down: the request never reached the app. */
+export declare const STARTING_HEADER = "x-mii-app-starting";
 /** Every TanStack query the SDK owns sits under this key. */
 export declare const QUERY_ROOT = "light";
 export declare const SESSION_COOKIE = "mii_session";
@@ -39,4 +45,12 @@ export declare const PANE_MESSAGES: {
     error: "mii-preview:error";
     picked: "mii-preview:picked";
     located: "mii-preview:located";
+    /** From @trylight/vite-plugin's client: the page mounted, or is about to reload. */
+    mounted: "light:mounted";
+    willReload: "light:will-reload";
+    /** From the gateway's page for a sandbox still waking. */
+    starting: "light:starting";
+    appError: "app_error";
+    /** How many requests are waiting out a dev server restart; the pane swaps in a reload only at zero. */
+    requestsHeld: "light:requests-held";
 };

package/dist/platform/contract.js

@@ -11,17 +11,23 @@ export const IMAGE_PATH = `/api/${NAMESPACE}/image`;
 export const BUILD_PATH = `/api/${NAMESPACE}/build`;
 export const INVOKE_BASE_PATH = `/api/${LEGACY_NAMESPACE}/invoke`;
 export const CHAT_BASE_PATH = `/api/${LEGACY_NAMESPACE}/chat`;
+/** A base to resolve an app-relative path against when checking it stays on the app; never contacted. */
+export const SAME_ORIGIN_BASE = "https://app.invalid";
 /** The platform's sign-in API, called with an app's own id. */
 export const PLATFORM_AUTH_PATHS = {
     signIn: "/api/app-auth/sign-in",
     requestPasswordReset: "/api/app-auth/request-password-reset",
     redeemPaneCode: "/api/app-auth/redeem",
-    config: "/api/app-auth/config"
+    config: "/api/app-auth/config",
+    /** "Continue with Google / Microsoft": the platform signs the person in and returns with a one-time code. */
+    socialSignIn: "/api/app-auth/social"
 };
 /** The platform's chat API: an app's chat route forwards any path beneath it, so a new widget route needs no SDK release. */
 export const PLATFORM_CHAT_PATH = "/api/app-chat/v1/chat";
 /** What this app's chat server forwards beyond the first contract: the widget, served to every app version, offers only these. */
 export const CHAT_FEATURES_HEADER = "X-Mii-Chat-Features";
+/** The gateway's mark on its 503 while the app's server is down: the request never reached the app. */
+export const STARTING_HEADER = `x-${LEGACY_NAMESPACE}-app-starting`;
 /** Every TanStack query the SDK owns sits under this key. */
 export const QUERY_ROOT = NAMESPACE;
 export const SESSION_COOKIE = `${LEGACY_NAMESPACE}_session`;
@@ -39,6 +45,13 @@ const PANE_PREFIX = `${LEGACY_NAMESPACE}-preview:`;
 function paneMessage(name) {
     return `${PANE_PREFIX}${name}`;
 }
+function namespaced(name) {
+    return `${NAMESPACE}:${name}`;
+}
+/** Keeps a message type's literal type in the object below. */
+function exact(value) {
+    return value;
+}
 /** postMessage types between an app framed in the platform's App pane and the pane. */
 export const PANE_MESSAGES = {
     hello: paneMessage("hello"),
@@ -48,5 +61,13 @@ export const PANE_MESSAGES = {
     route: paneMessage("route"),
     error: paneMessage("error"),
     picked: paneMessage("picked"),
-    located: paneMessage("located")
+    located: paneMessage("located"),
+    /** From @trylight/vite-plugin's client: the page mounted, or is about to reload. */
+    mounted: namespaced("mounted"),
+    willReload: namespaced("will-reload"),
+    /** From the gateway's page for a sandbox still waking. */
+    starting: namespaced("starting"),
+    appError: exact("app_error"),
+    /** How many requests are waiting out a dev server restart; the pane swaps in a reload only at zero. */
+    requestsHeld: namespaced("requests-held")
 };

package/dist/platform/live-data.js

@@ -9,6 +9,7 @@ import { z } from "zod/v4";
 import { EntityError, tableQueryKey } from "../entities.js";
 import { CHANGES_PATH, QUERY_ROOT } from "./contract.js";
 import { POLL_MS } from "./timing.js";
+import { isStarting } from "./restart.js";
 const changes = z.object({ cursor: z.string(), changedTables: z.array(z.string()) });
 /**
  * Polls `_changes` as a TanStack query. One the server breaks on (or answers
@@ -63,6 +64,8 @@ export async function fetchChanges(since) {
         // fetch rejects only when no answer came back at all.
         return "unreachable";
     }
+    if (isStarting(response))
+        return "unreachable";
     if (response.status === 401)
         return "signed-out";
     if (!response.ok)

package/dist/platform/pane-bridge.js

@@ -20,6 +20,7 @@ import { z } from "zod/v4";
 import { PANE_MESSAGES } from "./contract.js";
 import { PLAZA_FRAME_ORIGINS } from "./index.js";
 import { LiveData } from "./live-data-mount.js";
+import { onHeldRequests } from "./restart.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", [
@@ -163,6 +164,8 @@ export function MiiPaneBridge() {
                 return;
             window.parent.postMessage({ type: PANE_MESSAGES.route, ...describe() }, plaza);
         });
+        // The pane swaps in a reload only once nothing here is held.
+        const stopHeld = onHeldRequests(({ held, started }) => send({ type: PANE_MESSAGES.requestsHeld, held, started }));
         document.body.appendChild(outline);
         window.addEventListener("error", onError);
         window.addEventListener("unhandledrejection", onRejection);
@@ -171,6 +174,7 @@ export function MiiPaneBridge() {
         document.addEventListener("click", onClick, true);
         return () => {
             stopRouteWatch();
+            stopHeld();
             window.removeEventListener("error", onError);
             window.removeEventListener("unhandledrejection", onRejection);
             window.removeEventListener("message", onMessage);

package/dist/platform/restart.d.ts

@@ -0,0 +1,18 @@
+export declare const isStarting: (response: Response) => boolean;
+/** How many requests are waiting out a restart, and whether this change is one starting to. */
+type HeldChange = {
+    readonly held: number;
+    readonly started: boolean;
+};
+/** Hears each request that starts or stops waiting out a restart. */
+export declare function onHeldRequests(listener: (change: HeldChange) => void): () => void;
+/**
+ * `fetch`, held through a restart: the gateway's starting answer is retried
+ * for any method, a failed connection only for a read (a write may have
+ * reached the app). Anything else, or the last try at RESTART_WAIT_MS, is
+ * the caller's as it came.
+ */
+export declare function fetchThroughRestart(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+/** Resolves after `ms`, or rejects with the signal's reason once it aborts. */
+export declare function wait(ms: number, signal: AbortSignal | null): Promise<void>;
+export {};

package/dist/platform/restart.js

@@ -0,0 +1,70 @@
+// A request that meets the app's dev server restarting waits for it to come back.
+import { STARTING_HEADER } from "./contract.js";
+import { RESTART_FIRST_RETRY_MS, RESTART_MAX_RETRY_MS, RESTART_WAIT_MS } from "./timing.js";
+export const isStarting = (response) => response.status === 503 && response.headers.has(STARTING_HEADER);
+// File-local: HTTP's safe methods, which only this retry decision needs; resending one cannot repeat a write.
+const SAFE_TO_RESEND = new Set(["GET", "HEAD", "OPTIONS"]);
+let held = 0;
+const listeners = new Set();
+/** Hears each request that starts or stops waiting out a restart. */
+export function onHeldRequests(listener) {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+}
+function hold(started) {
+    held += started ? 1 : -1;
+    for (const listener of listeners)
+        listener({ held, started });
+}
+/**
+ * `fetch`, held through a restart: the gateway's starting answer is retried
+ * for any method, a failed connection only for a read (a write may have
+ * reached the app). Anything else, or the last try at RESTART_WAIT_MS, is
+ * the caller's as it came.
+ */
+export async function fetchThroughRestart(input, init = {}) {
+    const { method = input instanceof Request ? input.method : "GET", signal = null } = init;
+    const giveUpAt = Date.now() + RESTART_WAIT_MS;
+    let waiting = false;
+    try {
+        for (let attempt = 0;; attempt += 1) {
+            try {
+                const response = await fetch(input instanceof Request ? input.clone() : input, init);
+                if (!isStarting(response) || Date.now() >= giveUpAt)
+                    return response;
+            }
+            catch (error) {
+                // fetch rejects with a TypeError only when no answer came back; an abort is the caller's.
+                if (!(error instanceof TypeError) || !SAFE_TO_RESEND.has(method.toUpperCase()) || Date.now() >= giveUpAt)
+                    throw error;
+            }
+            if (!waiting) {
+                waiting = true;
+                hold(true);
+            }
+            await wait(Math.min(RESTART_FIRST_RETRY_MS * 2 ** attempt, RESTART_MAX_RETRY_MS), signal);
+        }
+    }
+    finally {
+        if (waiting)
+            hold(false);
+    }
+}
+/** Resolves after `ms`, or rejects with the signal's reason once it aborts. */
+export function wait(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal === null) {
+            setTimeout(resolve, ms);
+            return;
+        }
+        const abort = () => {
+            clearTimeout(timer);
+            reject(signal.reason);
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", abort);
+            resolve();
+        }, ms);
+        signal.addEventListener("abort", abort, { once: true });
+    });
+}

package/dist/platform/timing.d.ts

@@ -6,6 +6,11 @@ export declare const CHECK_MS = 60000;
 export declare const IDLE_MS = 5000;
 /** After a reload: how long a list may take to be tall enough to scroll back; past it, it stays at the top. */
 export declare const SCROLL_RESTORE_MS = 5000;
+/** A request meeting a dev server restart waits this long for it at most, then fails with what it got. */
+export declare const RESTART_WAIT_MS = 30000;
+/** Backoff between a held request's tries: from the first, doubling up to the max. */
+export declare const RESTART_FIRST_RETRY_MS = 250;
+export declare const RESTART_MAX_RETRY_MS = 1000;
 /** A contract read that failed: how long before asking again. */
 export declare const INVOCATION_RETRY_MS = 1500;
 /** How long a page remembers a contract invocation it started, across reloads. */

package/dist/platform/timing.js

@@ -7,6 +7,11 @@ export const CHECK_MS = 60_000;
 export const IDLE_MS = 5_000;
 /** After a reload: how long a list may take to be tall enough to scroll back; past it, it stays at the top. */
 export const SCROLL_RESTORE_MS = 5_000;
+/** A request meeting a dev server restart waits this long for it at most, then fails with what it got. */
+export const RESTART_WAIT_MS = 30_000;
+/** Backoff between a held request's tries: from the first, doubling up to the max. */
+export const RESTART_FIRST_RETRY_MS = 250;
+export const RESTART_MAX_RETRY_MS = 1_000;
 /** A contract read that failed: how long before asking again. */
 export const INVOCATION_RETRY_MS = 1500;
 /** How long a page remembers a contract invocation it started, across reloads. */

package/dist/platform.d.ts

@@ -1,3 +1,4 @@
 export { FRAME_ANCESTORS, isAgentBrowser, mayCallServerFn, miiAnalyticsPolicy, miiErrorPolicy, PLAZA_FRAME_ORIGINS, type ServerFnName } from "./platform/index.js";
 export { MiiPaneBridge } from "./platform/pane-bridge.js";
 export { ReloadOnNewBuild } from "./platform/new-build-mount.js";
+export { fetchThroughRestart } from "./platform/restart.js";

package/dist/platform.js

@@ -1,6 +1,8 @@
 // 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,
-// the pane bridge, and moving an open page onto a new build.
+// the pane bridge, moving an open page onto a new build, and the fetch that
+// waits out a dev server restart.
 export { FRAME_ANCESTORS, isAgentBrowser, mayCallServerFn, miiAnalyticsPolicy, miiErrorPolicy, PLAZA_FRAME_ORIGINS } from "./platform/index.js";
 export { MiiPaneBridge } from "./platform/pane-bridge.js";
 export { ReloadOnNewBuild } from "./platform/new-build-mount.js";
+export { fetchThroughRestart } from "./platform/restart.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trylight/app",
-  "version": "0.3.2",
+  "version": "0.3.5",
   "description": "The Light SDK every v2 org app depends on: entities (Drizzle tables with a typed client), sign-in, contracts and in-app chat.",
   "license": "UNLICENSED",
   "type": "module",
@@ -12,7 +12,6 @@
     "url": "https://github.com/shubh9/mii.git",
     "directory": "packages/app-sdk"
   },
-  "packageManager": "pnpm@11.0.9",
   "files": [
     "dist",
     "bin"
@@ -42,15 +41,6 @@
       "default": "./dist/vite.js"
     }
   },
-  "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.build.json",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint src test --max-warnings 0",
-    "test": "node --test --import tsx \"test/**/*.test.ts\"",
-    "check": "tsx scripts/write-brand.ts --check && pnpm run typecheck && pnpm run lint && pnpm run test && pnpm run build",
-    "prepack": "pnpm run build",
-    "brand": "tsx scripts/write-brand.ts"
-  },
   "peerDependencies": {
     "@tanstack/react-query": ">=5.69",
     "@tanstack/react-router": ">=1.170",
@@ -84,5 +74,13 @@
     "typescript-eslint": "^8.70.1",
     "vite": "^8.2.0",
     "zod": "^4.6.5"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src test --max-warnings 0",
+    "test": "node --test --import tsx \"test/**/*.test.ts\"",
+    "check": "tsx scripts/write-brand.ts --check && pnpm run typecheck && pnpm run lint && pnpm run test && pnpm run build",
+    "brand": "tsx scripts/write-brand.ts"
   }
-}
+}