@trylight/app 0.3.1 → 0.3.2

package/dist/auth/lookup.d.ts

@@ -1,7 +1,7 @@
 import type { AuthContext } from "./context.js";
 import { type PlazaSession } from "./plaza.js";
 /** The cookie holding this app's own session. Nothing of the platform's is read here. */
-export declare const SESSION_COOKIE = "mii_session";
+export { SESSION_COOKIE } from "../platform/contract.js";
 /**
  * How often a session asks the platform whether it still stands. Someone removed from
  * the org is signed out of the app within this long; their chat stops at once,

package/dist/auth/lookup.js

@@ -1,7 +1,7 @@
 import { createHash, randomBytes } from "node:crypto";
 import { checkPlazaSession, revokePlazaSession } from "./plaza.js";
 /** The cookie holding this app's own session. Nothing of the platform's is read here. */
-export const SESSION_COOKIE = "mii_session";
+export { SESSION_COOKIE } from "../platform/contract.js";
 /**
  * How often a session asks the platform whether it still stands. Someone removed from
  * the org is signed out of the app within this long; their chat stops at once,

package/dist/auth/mode.js

@@ -1,5 +1,6 @@
 import { z } from "zod/v4";
 import { miiAuthConfig } from "./config.js";
+import { PLATFORM_AUTH_PATHS } from "../platform/contract.js";
 // Who may open this app, as set in the platform (Settings → Workspaces → "Who can open
 // it"). Read from the platform rather than baked into the build so the switch takes
 // effect on the next request, not the next deploy.
@@ -40,7 +41,7 @@ export async function getAuthMode() {
 }
 async function fetchMode() {
     const { plazaUrl, appId } = miiAuthConfig();
-    const response = await fetch(`${plazaUrl}/api/app-auth/config?app_id=${encodeURIComponent(appId)}`, { cache: "no-store" });
+    const response = await fetch(`${plazaUrl}${PLATFORM_AUTH_PATHS.config}?app_id=${encodeURIComponent(appId)}`, { cache: "no-store" });
     if (!response.ok) {
         throw new Error(`The platform's app-auth config answered ${response.status}.`);
     }

package/dist/auth/plaza.js

@@ -1,5 +1,6 @@
 import { z } from "zod/v4";
 import { miiAuthConfig } from "./config.js";
+import { PLATFORM_AUTH_PATHS } from "../platform/contract.js";
 /**
  * Check an email and password with the platform, and get back who the person is and
  * the session the platform signed for them.
@@ -8,7 +9,7 @@ export async function signInWithPlaza(email, password) {
     const { plazaUrl, appId } = miiAuthConfig();
     let response;
     try {
-        response = await fetch(`${plazaUrl}/api/app-auth/sign-in`, {
+        response = await fetch(`${plazaUrl}${PLATFORM_AUTH_PATHS.signIn}`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({ appId, email, password }),
@@ -50,7 +51,7 @@ export async function requestPasswordResetWithPlaza(email, returnTo) {
     const { plazaUrl, appId } = miiAuthConfig();
     let response;
     try {
-        response = await fetch(`${plazaUrl}/api/app-auth/request-password-reset`, {
+        response = await fetch(`${plazaUrl}${PLATFORM_AUTH_PATHS.requestPasswordReset}`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({ appId, email, returnTo }),
@@ -80,7 +81,7 @@ export async function requestPasswordResetWithPlaza(email, returnTo) {
  */
 export async function redeemWithPlaza(code) {
     const { plazaUrl, appId } = miiAuthConfig();
-    const response = await fetch(`${plazaUrl}/api/app-auth/redeem`, {
+    const response = await fetch(`${plazaUrl}${PLATFORM_AUTH_PATHS.redeemPaneCode}`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({ appId, code }),

package/dist/chat/paths.d.ts

@@ -1,10 +1,3 @@
-/** Where an app mounts its chat routes, and where the widget calls them. */
-export declare const CHAT_BASE_PATH = "/api/mii/chat";
-/**
- * What the app's chat server can do beyond the first contract, listed on its
- * answers. The platform serves the widget to apps on every runtime version, so the
- * widget offers only what this app's server says it forwards.
- */
-export declare const CHAT_FEATURES_HEADER = "X-Mii-Chat-Features";
+/** Features listed in CHAT_FEATURES_HEADER. */
 export declare const REACTIONS_FEATURE = "reactions";
 export declare const CREDITS_FEATURE = "credits";

package/dist/chat/paths.js

@@ -1,10 +1,3 @@
-/** Where an app mounts its chat routes, and where the widget calls them. */
-export const CHAT_BASE_PATH = "/api/mii/chat";
-/**
- * What the app's chat server can do beyond the first contract, listed on its
- * answers. The platform serves the widget to apps on every runtime version, so the
- * widget offers only what this app's server says it forwards.
- */
-export const CHAT_FEATURES_HEADER = "X-Mii-Chat-Features";
+/** Features listed in CHAT_FEATURES_HEADER. */
 export const REACTIONS_FEATURE = "reactions";
 export const CREDITS_FEATURE = "credits";

package/dist/chat/server.js

@@ -15,12 +15,8 @@
 // the platform signed when the person signed in. The platform checks that token and the
 // person's membership on every request.
 import { miiAuthConfig } from "../auth/config.js";
-import { CHAT_BASE_PATH, CHAT_FEATURES_HEADER, CREDITS_FEATURE, REACTIONS_FEATURE } from "./paths.js";
-// The platform's browser-facing chat routes all sit under this one prefix, and this
-// server forwards any path beneath it: a widget route the platform adds needs no
-// release of this package. The platform's server-only routes (session) are outside it,
-// and each route under it validates its own ids.
-const PLAZA_CHAT_PATH = "/api/app-chat/v1/chat";
+import { CHAT_BASE_PATH, CHAT_FEATURES_HEADER, PLATFORM_CHAT_PATH } from "../platform/contract.js";
+import { CREDITS_FEATURE, REACTIONS_FEATURE } from "./paths.js";
 // Plain segments only: no dots, no percent-encoding, no empty segment. A path
 // that could climb out of the platform's prefix (`..`, `%2e%2e`, `%2f`, `//`) never
 // leaves this server.
@@ -28,7 +24,7 @@ const FORWARDABLE_PATH = /^(\/[A-Za-z0-9_-]+)+$/;
 // What the thread's poll and its pages may carry through. Everything else in
 // the query string is dropped rather than forwarded.
 const FORWARDED_QUERY = ["after", "afterId", "limit", "before", "beforeId"];
-export function createMiiChatHandler(auth, { reportError = (error, context) => console.error("mii-chat error", context, error) } = {}) {
+export function createMiiChatHandler(auth, { reportError = (error, context) => console.error("chat route error", context, error) } = {}) {
     return async (request) => {
         const url = new URL(request.url);
         if (!url.pathname.startsWith(`${CHAT_BASE_PATH}/`)) {
@@ -56,7 +52,7 @@ export function createMiiChatHandler(auth, { reportError = (error, context) => c
             return refuse(401, "sign_in_again", "Sign out and back in to use it here.");
         }
         const { plazaUrl } = miiAuthConfig();
-        const target = new URL(`${plazaUrl}${PLAZA_CHAT_PATH}${path}`);
+        const target = new URL(`${plazaUrl}${PLATFORM_CHAT_PATH}${path}`);
         for (const key of FORWARDED_QUERY) {
             const value = url.searchParams.get(key);
             if (value !== null)
@@ -83,7 +79,7 @@ export function createMiiChatHandler(auth, { reportError = (error, context) => c
             answer = await fetch(target, init);
         }
         catch (error) {
-            reportError(error, { where: "mii-chat", step: "forward" });
+            reportError(error, { where: "chat-route", step: "forward" });
             return refuse(502, "unavailable", "Couldn't reach the chat. Try again in a moment.");
         }
         // The platform no longer stands behind this session: the token is no good, or the
@@ -93,7 +89,7 @@ export function createMiiChatHandler(auth, { reportError = (error, context) => c
             await auth.revokeSession(token, answer.status === 403 ? "not_a_member" : "token_rejected");
         }
         if (answer.status >= 500) {
-            reportError(new Error(`Platform chat answered ${answer.status}: ${(await answer.clone().text()).slice(0, 300)}`), { where: "mii-chat", step: "plaza" });
+            reportError(new Error(`Platform chat answered ${answer.status}: ${(await answer.clone().text()).slice(0, 300)}`), { where: "chat-route", step: "plaza" });
         }
         // An avatar may be cached for the person; chat data never is.
         const cacheControl = answer.headers.get("cache-control");

package/dist/client.js

@@ -10,7 +10,8 @@ import { useEffect, useMemo, useState } from "react";
 import { createInvoker } from "./invoke/index.js";
 import { getTableColumns, getTableName } from "drizzle-orm";
 import { z } from "zod/v4";
-import { ENTITIES_PATH, EntityError, LIST_LIMIT, tableQueryKey } from "./entities.js";
+import { ENTITIES_PATH } from "./platform/contract.js";
+import { EntityError, LIST_LIMIT, tableQueryKey } from "./entities.js";
 export { EntityError, LIST_LIMIT } from "./entities.js";
 export { siteOf } from "./schema.js";
 export { imageSrc } from "./images.js";

package/dist/entities.d.ts

@@ -1,8 +1,5 @@
 import type { Entity, PlatformColumn } from "./schema.js";
-export declare const ENTITIES_PATH = "/api/light/entities";
-/** Which tables changed since a cursor (open pages' poll): `?since=<cursor>` → {cursor, changedTables}. */
-export declare const CHANGES_PATH = "/api/light/entities/_changes";
-/** The TanStack Query key everything cached from one table sits under; a change to the table invalidates it. */
+/** Everything cached from one table sits under this key; a change to the table invalidates it. */
 export declare const tableQueryKey: (table: string) => string[];
 /** The most rows one list returns; page past it with `offset` (useInfiniteList does). */
 export declare const LIST_LIMIT = 1000;

package/dist/entities.js

@@ -1,8 +1,8 @@
-export const ENTITIES_PATH = "/api/light/entities";
-/** Which tables changed since a cursor (open pages' poll): `?since=<cursor>` → {cursor, changedTables}. */
-export const CHANGES_PATH = `${ENTITIES_PATH}/_changes`;
-/** The TanStack Query key everything cached from one table sits under; a change to the table invalidates it. */
-export const tableQueryKey = (table) => ["light", `${ENTITIES_PATH}/${table}`];
+// What the browser client and the entities route agree on: the path, the
+// shapes of a request, and the row types a schema gives them.
+import { ENTITIES_PATH, QUERY_ROOT } from "./platform/contract.js";
+/** Everything cached from one table sits under this key; a change to the table invalidates it. */
+export const tableQueryKey = (table) => [QUERY_ROOT, `${ENTITIES_PATH}/${table}`];
 /** The most rows one list returns; page past it with `offset` (useInfiniteList does). */
 export const LIST_LIMIT = 1000;
 /** A refused or failed entities call, with the route's own reason. */

package/dist/images.d.ts

@@ -1,4 +1,3 @@
-export declare const IMAGE_PATH = "/api/light/image";
 /**
  * Where a row's photo or logo loads from: the app's own copy (kept from the
  * first view on) for an address on the web, the value itself for one of the

package/dist/images.js

@@ -1,7 +1,7 @@
 // What the browser and the image route agree on: where a row's photo or logo
 // loads from. Nothing here may touch a database or the DOM.
+import { IMAGE_PATH } from "./platform/contract.js";
 import { webUrl } from "./schema.js";
-export const IMAGE_PATH = "/api/light/image";
 /**
  * Where a row's photo or logo loads from: the app's own copy (kept from the
  * first view on) for an address on the web, the value itself for one of the

package/dist/invoke/index.d.ts

@@ -4,10 +4,6 @@ export { InvocationError };
 export type { Invocation, InvocationState } from "./contracts.js";
 /** How long one read asks the platform to hold a pending invocation; the platform clamps it to its own limit. */
 export declare const INVOCATION_WAIT_SECONDS = 60;
-/** The pause after a read that failed before asking again. */
-export declare const INVOCATION_RETRY_MS = 1500;
-/** How long a run started with `remember` is picked up again in this browser. */
-export declare const INVOCATION_REMEMBER_MS: number;
 type Result = Record<string, unknown>;
 /**
  * `id` and `input` are null until the platform has the invocation. `input` is the

package/dist/invoke/index.js

@@ -5,16 +5,12 @@ import { useEffect, useMemo, useState } from "react";
 import { z } from "zod/v4";
 import { errorBody } from "../request-error.js";
 import { failedRun, InvocationError } from "./error.js";
-import { INVOKE_BASE_PATH } from "./paths.js";
+import { INVOKE_BASE_PATH, STORAGE_KEYS } from "../platform/contract.js";
+import { INVOCATION_REMEMBER_MS, INVOCATION_RETRY_MS } from "../platform/timing.js";
 export { InvocationError };
 /** How long one read asks the platform to hold a pending invocation; the platform clamps it to its own limit. */
 export const INVOCATION_WAIT_SECONDS = 60;
-/** The pause after a read that failed before asking again. */
-export const INVOCATION_RETRY_MS = 1500;
-/** How long a run started with `remember` is picked up again in this browser. */
-export const INVOCATION_REMEMBER_MS = 24 * 60 * 60 * 1000;
 const ELAPSED_TICK_MS = 1000;
-const REMEMBERED_PREFIX = "mii-invocation:";
 export function createInvoker() {
     return {
         async invoke(key, input, signal = null) {
@@ -49,7 +45,7 @@ async function readAnswered(id, holdSeconds, signal = null, onPoll = unwatched)
             // invocation, which carries on either way.
             if (!(error instanceof InvocationError) || (error.status !== 0 && error.status < 500))
                 throw error;
-            console.error("mii-invoke: a read failed; trying again", error);
+            console.error("invoke: a read failed; trying again", error);
             onPoll(null, error);
             await wait(INVOCATION_RETRY_MS, signal);
         }
@@ -162,7 +158,7 @@ const IDLE = { state: "idle" };
  * With `remember`, `restore()` picks up the run this browser last started with it.
  */
 export function createInvocationController(key, onStatus, { remember = null } = {}) {
-    const name = remember === null ? null : `${REMEMBERED_PREFIX}${key}:${remember}`;
+    const name = remember === null ? null : `${STORAGE_KEYS.invocationPrefix}${key}:${remember}`;
     // The run this button follows. `note` goes false once it is replaced or
     // reset, so a start still in flight is never noted; an unmount leaves it.
     let current = null;

package/dist/invoke/server.js

@@ -6,7 +6,7 @@ import { isSameOrigin, readCookie } from "../chat/server.js";
 import { errorBody } from "../request-error.js";
 import { isUuid } from "../uuid.js";
 import { failedRun, InvocationError } from "./error.js";
-import { INVOKE_BASE_PATH } from "./paths.js";
+import { INVOKE_BASE_PATH } from "../platform/contract.js";
 export { InvocationError };
 function routeOf(request) {
     const { pathname } = new URL(request.url);
@@ -125,7 +125,7 @@ async function askPlaza(auth, person, call) {
 // refinement or a transform. The app's own Zod has the last word.
 function resultMismatch(id, error, reportError) {
     const problem = `The result of invocation ${id} does not match this app's output schema:\n${z.prettifyError(error)}`;
-    reportError(new Error(problem), { where: "mii-invoke", step: "result" });
+    reportError(new Error(problem), { where: "invoke-route", step: "result" });
     return new InvocationError(422, "result_mismatch", problem);
 }
 /**
@@ -133,7 +133,7 @@ function resultMismatch(id, error, reportError) {
  * Every output is converted to JSON Schema here, once, so one with no JSON
  * Schema form stops the server starting, not someone's press of the button.
  */
-export function createMiiInvoke(auth, contracts, { reportError = (error, context) => console.error("mii-invoke error", context, error) } = {}) {
+export function createMiiInvoke(auth, contracts, { reportError = (error, context) => console.error("invoke route error", context, error) } = {}) {
     const declared = new Map(Object.entries(contracts).map(([key, contract]) => [key, declare(key, contract)]));
     const handler = async (request) => {
         const route = routeOf(request);
@@ -168,13 +168,13 @@ export function createMiiInvoke(auth, contracts, { reportError = (error, context
         }
         catch (error) {
             if (!request.signal.aborted)
-                reportError(error, { where: "mii-invoke", step: "forward" });
+                reportError(error, { where: "invoke-route", step: "forward" });
             return refuse(502, "unavailable", "Couldn't reach the platform. Try again in a moment.");
         }
         if (!answer.ok) {
             if (answer.status >= 500) {
                 reportError(new Error(`Platform answered ${answer.status}: ${(await answer.clone().text()).slice(0, 300)}`), {
-                    where: "mii-invoke",
+                    where: "invoke-route",
                     step: "plaza"
                 });
             }

package/dist/platform/contract.d.ts

@@ -0,0 +1,42 @@
+export declare const ENTITIES_PATH = "/api/light/entities";
+export declare const CHANGES_PATH = "/api/light/entities/_changes";
+export declare const IMAGE_PATH = "/api/light/image";
+/** The template's src/routes/api/light/build.ts. */
+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";
+/** 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;
+};
+/** 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";
+/** Every TanStack query the SDK owns sits under this key. */
+export declare const QUERY_ROOT = "light";
+export declare const SESSION_COOKIE = "mii_session";
+export declare const STORAGE_KEYS: {
+    /** sessionStorage: the build this tab already reloaded for after a missing chunk, so a second miss on it can't loop. */
+    chunkRetryBuildId: string;
+    /** sessionStorage: scroll positions saved just before a reload onto a new build. */
+    scrollBeforeReload: string;
+    /** localStorage prefix: a contract invocation remembered across reloads. */
+    invocationPrefix: string;
+    /** localStorage, and the URL parameter that sets it: this browser is the org's own automation. */
+    agentBrowser: string;
+};
+/** postMessage types between an app framed in the platform's App pane and the pane. */
+export declare const PANE_MESSAGES: {
+    hello: "mii-preview:hello";
+    select: "mii-preview:select";
+    locate: "mii-preview:locate";
+    ready: "mii-preview:ready";
+    route: "mii-preview:route";
+    error: "mii-preview:error";
+    picked: "mii-preview:picked";
+    located: "mii-preview:located";
+};

package/dist/platform/contract.js

@@ -0,0 +1,52 @@
+// The names an app's pages, its server and the platform agree on. Deployed
+// apps and the platform's pane depend on every value here: rename freely, never
+// change a value without both sides moving.
+const NAMESPACE = "light";
+/** The platform's former name: the pane protocol, the session cookie and two routes still carry it. */
+const LEGACY_NAMESPACE = "mii";
+export const ENTITIES_PATH = `/api/${NAMESPACE}/entities`;
+export const CHANGES_PATH = `${ENTITIES_PATH}/_changes`;
+export const IMAGE_PATH = `/api/${NAMESPACE}/image`;
+/** The template's src/routes/api/light/build.ts. */
+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`;
+/** 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"
+};
+/** 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";
+/** Every TanStack query the SDK owns sits under this key. */
+export const QUERY_ROOT = NAMESPACE;
+export const SESSION_COOKIE = `${LEGACY_NAMESPACE}_session`;
+export const STORAGE_KEYS = {
+    /** sessionStorage: the build this tab already reloaded for after a missing chunk, so a second miss on it can't loop. */
+    chunkRetryBuildId: `${NAMESPACE}:chunk-retry-build-id`,
+    /** sessionStorage: scroll positions saved just before a reload onto a new build. */
+    scrollBeforeReload: `${NAMESPACE}:scroll-before-reload`,
+    /** localStorage prefix: a contract invocation remembered across reloads. */
+    invocationPrefix: `${LEGACY_NAMESPACE}-invocation:`,
+    /** localStorage, and the URL parameter that sets it: this browser is the org's own automation. */
+    agentBrowser: `${LEGACY_NAMESPACE}_agent`
+};
+const PANE_PREFIX = `${LEGACY_NAMESPACE}-preview:`;
+function paneMessage(name) {
+    return `${PANE_PREFIX}${name}`;
+}
+/** postMessage types between an app framed in the platform's App pane and the pane. */
+export const PANE_MESSAGES = {
+    hello: paneMessage("hello"),
+    select: paneMessage("select"),
+    locate: paneMessage("locate"),
+    ready: paneMessage("ready"),
+    route: paneMessage("route"),
+    error: paneMessage("error"),
+    picked: paneMessage("picked"),
+    located: paneMessage("located")
+};

package/dist/platform/index.js

@@ -5,6 +5,7 @@
 // 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";
+import { STORAGE_KEYS } from "./contract.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
@@ -66,11 +67,11 @@ export function miiAnalyticsPolicy({ vercelEnv = "development", ingestHost, forc
  */
 export function isAgentBrowser(win) {
     try {
-        if (new URLSearchParams(win.location.search).has("mii_agent")) {
-            win.localStorage.setItem("mii_agent", "1");
+        if (new URLSearchParams(win.location.search).has(STORAGE_KEYS.agentBrowser)) {
+            win.localStorage.setItem(STORAGE_KEYS.agentBrowser, "1");
         }
         return (win.navigator.webdriver === true ||
-            win.localStorage.getItem("mii_agent") === "1");
+            win.localStorage.getItem(STORAGE_KEYS.agentBrowser) === "1");
     }
     catch {
         // localStorage can be unavailable (privacy modes); never break the app.

package/dist/platform/keep-scroll.d.ts

@@ -0,0 +1,5 @@
+export declare function keepScroll(): void;
+export declare function restoreScroll(): void;
+export declare function takeSession(key: string): string | null;
+export declare function readSession(key: string): string | null;
+export declare function writeSession(key: string, value: string): void;

package/dist/platform/keep-scroll.js

@@ -0,0 +1,75 @@
+// The router restores the window's scroll before a list inside the page has its rows; these wait until each is tall enough.
+import { z } from "zod/v4";
+import { STORAGE_KEYS } from "./contract.js";
+import { SCROLL_RESTORE_MS } from "./timing.js";
+const scrollPositions = z.array(z.object({ selector: z.string(), top: z.number() }));
+function pathTo(element) {
+    const parts = [];
+    for (let node = element; node !== null; node = node.parentElement) {
+        const at = node.parentElement === null ? 1 : [...node.parentElement.children].indexOf(node) + 1;
+        parts.unshift(`${node.tagName.toLowerCase()}:nth-child(${at})`);
+    }
+    return `:root > ${parts.slice(1).join(" > ")}`;
+}
+export function keepScroll() {
+    const scrolled = [...document.body.querySelectorAll("*")].filter((element) => element.scrollTop > 0);
+    writeSession(STORAGE_KEYS.scrollBeforeReload, JSON.stringify(scrolled.map((element) => ({ selector: pathTo(element), top: element.scrollTop }))));
+}
+export function restoreScroll() {
+    const saved = takeSession(STORAGE_KEYS.scrollBeforeReload);
+    if (saved === null)
+        return;
+    // Another build's shape: start at the top.
+    const read = scrollPositions.safeParse(parseJson(saved));
+    if (!read.success)
+        return;
+    let pending = read.data;
+    const until = performance.now() + SCROLL_RESTORE_MS;
+    const step = () => {
+        pending = pending.filter(({ selector, top }) => {
+            const element = document.querySelector(selector);
+            if (element === null || element.scrollHeight - element.clientHeight < top)
+                return true;
+            element.scrollTop = top;
+            return false;
+        });
+        if (pending.length > 0 && performance.now() < until)
+            requestAnimationFrame(step);
+    };
+    requestAnimationFrame(step);
+}
+// Storage can be blocked (privacy settings); never worth breaking the page for.
+export function takeSession(key) {
+    try {
+        const value = sessionStorage.getItem(key);
+        sessionStorage.removeItem(key);
+        return value;
+    }
+    catch {
+        return null;
+    }
+}
+export function readSession(key) {
+    try {
+        return sessionStorage.getItem(key);
+    }
+    catch {
+        return null;
+    }
+}
+export function writeSession(key, value) {
+    try {
+        sessionStorage.setItem(key, value);
+    }
+    catch {
+        return;
+    }
+}
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/platform/live-data.d.ts

@@ -1,7 +1,5 @@
 import { type QueryClient } from "@tanstack/react-query";
 import { z } from "zod/v4";
-/** How often a visible tab asks what changed: an agent's write shows within about this long. */
-export declare const POLL_MS = 3000;
 declare const changes: z.ZodObject<{
     cursor: z.ZodString;
     changedTables: z.ZodArray<z.ZodString>;

package/dist/platform/live-data.js

@@ -6,9 +6,9 @@
 // reconnect), later a pushed one (SSE) behind the same type.
 import { QueryObserver } from "@tanstack/react-query";
 import { z } from "zod/v4";
-import { CHANGES_PATH, EntityError, tableQueryKey } from "../entities.js";
-/** How often a visible tab asks what changed: an agent's write shows within about this long. */
-export const POLL_MS = 3_000;
+import { EntityError, tableQueryKey } from "../entities.js";
+import { CHANGES_PATH, QUERY_ROOT } from "./contract.js";
+import { POLL_MS } from "./timing.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
@@ -20,7 +20,7 @@ export function pollChanges(queries, fetchChanges) {
         let cursor = null;
         let reported = false;
         const observer = new QueryObserver(queries, {
-            queryKey: ["light", CHANGES_PATH],
+            queryKey: [QUERY_ROOT, CHANGES_PATH],
             queryFn: () => fetchChanges(cursor),
             // Signed out: nothing to watch until the tab is shown again.
             refetchInterval: (query) => (query.state.data === "signed-out" ? false : POLL_MS),
@@ -49,7 +49,7 @@ export function pollChanges(queries, fetchChanges) {
         });
         return () => {
             stop();
-            queries.removeQueries({ queryKey: ["light", CHANGES_PATH], exact: true });
+            queries.removeQueries({ queryKey: [QUERY_ROOT, CHANGES_PATH], exact: true });
         };
     };
 }

package/dist/platform/new-build-mount.d.ts

@@ -0,0 +1,4 @@
+/** `buildId` null off Vercel: a dev server has HMR, nothing is watched. */
+export declare function ReloadOnNewBuild({ buildId }: {
+    buildId: string | null;
+}): null;

package/dist/platform/new-build-mount.js

@@ -0,0 +1,65 @@
+"use client";
+// The browser half of new-build.ts, mounted by the template's MiiPlatform.
+import { useQueryClient } from "@tanstack/react-query";
+import { useRouter } from "@tanstack/react-router";
+import { useEffect, useState } from "react";
+import { STORAGE_KEYS } from "./contract.js";
+import { keepScroll, readSession, restoreScroll, writeSession } from "./keep-scroll.js";
+import { fetchLive, watchBuild } from "./new-build.js";
+const TYPING_IN = new Set(["INPUT", "TEXTAREA", "SELECT"]);
+/** Through shadow roots: the platform's chat bubble is one. */
+function focusedElement() {
+    let focused = document.activeElement;
+    while (focused !== null && focused.shadowRoot !== null && focused.shadowRoot.activeElement !== null)
+        focused = focused.shadowRoot.activeElement;
+    return focused;
+}
+function busy() {
+    const focused = focusedElement();
+    if (focused instanceof HTMLElement && (TYPING_IN.has(focused.tagName) || focused.isContentEditable))
+        return true;
+    return document.querySelector('[role="dialog"], dialog[open]') !== null;
+}
+/** `buildId` null off Vercel: a dev server has HMR, nothing is watched. */
+export function ReloadOnNewBuild({ buildId }) {
+    // router.invalidate() re-runs the root loader, which would answer with the live build.
+    const [servedBy] = useState(buildId);
+    const queries = useQueryClient();
+    const router = useRouter();
+    useEffect(() => {
+        if (servedBy === null)
+            return;
+        restoreScroll();
+        return watchBuild({
+            buildId: servedBy,
+            queries,
+            fetchLive,
+            visible: () => document.visibilityState === "visible",
+            busy,
+            // The router also announces its own reloads and search-param changes.
+            onNavigate: (callback) => router.subscribe("onBeforeNavigate", ({ toLocation, pathChanged }) => {
+                if (pathChanged)
+                    callback(toLocation.publicHref);
+            }),
+            onChunkMissing: (callback) => {
+                // Not prevented, Vite throws the error on to the page.
+                const onError = (event) => {
+                    if (callback())
+                        event.preventDefault();
+                };
+                window.addEventListener("vite:preloadError", onError);
+                return () => window.removeEventListener("vite:preloadError", onError);
+            },
+            reload: () => {
+                keepScroll();
+                window.location.reload();
+            },
+            go: (href) => window.location.assign(href),
+            chunkRetryBuildId: {
+                get: () => readSession(STORAGE_KEYS.chunkRetryBuildId),
+                set: (build) => writeSession(STORAGE_KEYS.chunkRetryBuildId, build)
+            }
+        });
+    }, [servedBy, queries, router]);
+    return null;
+}

package/dist/platform/new-build.d.ts

@@ -0,0 +1,21 @@
+import { type QueryClient } from "@tanstack/react-query";
+export type BuildEnv = {
+    buildId: string;
+    queries: QueryClient;
+    fetchLive(): Promise<string | null>;
+    visible(): boolean;
+    /** An input has focus, or a dialog is open. */
+    busy(): boolean;
+    /** Before a navigation to another page. */
+    onNavigate(callback: (href: string) => void): () => void;
+    /** vite:preloadError; the callback says whether it reloaded. */
+    onChunkMissing(callback: () => boolean): () => void;
+    reload(): void;
+    go(href: string): void;
+    chunkRetryBuildId: {
+        get(): string | null;
+        set(build: string): void;
+    };
+};
+export declare function watchBuild(env: BuildEnv): () => void;
+export declare function fetchLive(): Promise<string | null>;

package/dist/platform/new-build.js

@@ -0,0 +1,63 @@
+// An open page moves onto a newly published build at a moment nobody is mid-task.
+import { QueryObserver } from "@tanstack/react-query";
+import { z } from "zod/v4";
+import { BUILD_PATH, QUERY_ROOT } from "./contract.js";
+import { CHECK_MS, IDLE_MS } from "./timing.js";
+const live = z.object({ buildId: z.string().nullable() });
+export function watchBuild(env) {
+    let stale = false;
+    let quietCheck = null;
+    const stopQuietCheck = () => {
+        if (quietCheck !== null)
+            clearTimeout(quietCheck);
+    };
+    const reloadWhenQuiet = () => {
+        if (!env.visible())
+            return env.reload();
+        quietCheck = setTimeout(() => (!env.visible() || !env.busy() ? env.reload() : reloadWhenQuiet()), IDLE_MS);
+    };
+    const check = new QueryObserver(env.queries, {
+        queryKey: [QUERY_ROOT, BUILD_PATH],
+        queryFn: () => env.fetchLive(),
+        refetchInterval: CHECK_MS,
+        // A hidden tab is the best one to reload.
+        refetchIntervalInBackground: true,
+        refetchOnWindowFocus: "always",
+        refetchOnReconnect: "always",
+        retry: false,
+        notifyOnChangeProps: ["data"]
+    });
+    const stopCheck = check.subscribe((result) => {
+        if (stale || result.status !== "success" || result.data === env.buildId)
+            return;
+        stale = true;
+        stopCheck();
+        reloadWhenQuiet();
+    });
+    const stopNavigate = env.onNavigate((href) => {
+        if (!stale)
+            return void check.refetch();
+        stopQuietCheck();
+        env.go(href);
+    });
+    const stopChunks = env.onChunkMissing(() => {
+        if (env.chunkRetryBuildId.get() === env.buildId)
+            return false;
+        env.chunkRetryBuildId.set(env.buildId);
+        env.reload();
+        return true;
+    });
+    return () => {
+        stopQuietCheck();
+        stopCheck();
+        stopNavigate();
+        stopChunks();
+        env.queries.removeQueries({ queryKey: [QUERY_ROOT, BUILD_PATH], exact: true });
+    };
+}
+export async function fetchLive() {
+    const response = await fetch(BUILD_PATH, { cache: "no-store" });
+    if (!response.ok)
+        throw new Error(`GET ${BUILD_PATH} failed (${response.status}).`);
+    return live.parse(await response.json()).buildId;
+}

package/dist/platform/pane-bridge.js

@@ -17,14 +17,15 @@ import { jsx as _jsx } from "react/jsx-runtime";
 // 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 { PANE_MESSAGES } from "./contract.js";
 import { PLAZA_FRAME_ORIGINS } from "./index.js";
 import { LiveData } from "./live-data-mount.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() })
+    z.object({ type: z.literal(PANE_MESSAGES.hello) }),
+    z.object({ type: z.literal(PANE_MESSAGES.select), on: z.boolean() }),
+    z.object({ type: z.literal(PANE_MESSAGES.locate), id: z.string(), selector: z.string() })
 ]);
 /**
  * Route changes without a router dependency: popstate covers back/forward,
@@ -76,12 +77,12 @@ export function MiiPaneBridge() {
         // 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",
+            type: PANE_MESSAGES.error,
             message: event.message,
             source: `${event.filename}:${event.lineno}`
         });
         const onRejection = (event) => send({
-            type: "mii-preview:error",
+            type: PANE_MESSAGES.error,
             message: String(event.reason),
             source: "unhandled rejection"
         });
@@ -118,7 +119,7 @@ export function MiiPaneBridge() {
             // arrives here under the name it already has.
             const label = target.getAttribute("data-el");
             send({
-                type: "mii-preview:picked",
+                type: PANE_MESSAGES.picked,
                 label: label === null ? target.textContent.trim().slice(0, 80) : label,
                 selector: selectorFor(target),
                 tag: target.tagName.toLowerCase(),
@@ -133,11 +134,11 @@ export function MiiPaneBridge() {
             if (!read.success)
                 return;
             const message = read.data;
-            if (message.type === "mii-preview:hello") {
-                send({ type: "mii-preview:ready", ...describe() });
+            if (message.type === PANE_MESSAGES.hello) {
+                send({ type: PANE_MESSAGES.ready, ...describe() });
                 return;
             }
-            if (message.type === "mii-preview:select") {
+            if (message.type === PANE_MESSAGES.select) {
                 selecting = message.on;
                 document.body.style.cursor = selecting ? "crosshair" : "";
                 if (!selecting)
@@ -150,7 +151,7 @@ export function MiiPaneBridge() {
             // different size than the one being replayed.
             const found = document.querySelector(message.selector);
             send({
-                type: "mii-preview:located",
+                type: PANE_MESSAGES.located,
                 id: message.id,
                 rect: found === null ? null : rectOf(found)
             });
@@ -160,7 +161,7 @@ export function MiiPaneBridge() {
             const plaza = plazaRef.current;
             if (plaza === null)
                 return;
-            window.parent.postMessage({ type: "mii-preview:route", ...describe() }, plaza);
+            window.parent.postMessage({ type: PANE_MESSAGES.route, ...describe() }, plaza);
         });
         document.body.appendChild(outline);
         window.addEventListener("error", onError);

package/dist/platform/timing.d.ts

@@ -0,0 +1,12 @@
+/** Live data: an agent's change shows on an open page within about this long. */
+export declare const POLL_MS = 3000;
+/** New build: how often a tab asks which build is live; browsers throttle hidden tabs' timers to about this anyway. */
+export declare const CHECK_MS = 60000;
+/** New build: how long nobody may be typing or have a dialog open before a visible tab reloads. */
+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 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. */
+export declare const INVOCATION_REMEMBER_MS: number;

package/dist/platform/timing.js

@@ -0,0 +1,13 @@
+// How often and how long the SDK waits in the browser: the knobs, in one place.
+/** Live data: an agent's change shows on an open page within about this long. */
+export const POLL_MS = 3_000;
+/** New build: how often a tab asks which build is live; browsers throttle hidden tabs' timers to about this anyway. */
+export const CHECK_MS = 60_000;
+/** New build: how long nobody may be typing or have a dialog open before a visible tab reloads. */
+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 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. */
+export const INVOCATION_REMEMBER_MS = 24 * 60 * 60 * 1000;

package/dist/platform.d.ts

@@ -1,2 +1,3 @@
 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";

package/dist/platform.js

@@ -1,5 +1,6 @@
 // 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.
+// the pane bridge, and moving an open page onto a new build.
 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";

package/dist/server/entities.js

@@ -8,7 +8,8 @@ import { isDeepStrictEqual } from "node:util";
 import { createSchemaFactory } from "drizzle-zod";
 import { isSameOrigin } from "../chat/server.js";
 import { z } from "zod/v4";
-import { CHANGES_PATH, ENTITIES_PATH, LIST_LIMIT } from "../entities.js";
+import { LIST_LIMIT } from "../entities.js";
+import { CHANGES_PATH, ENTITIES_PATH } from "../platform/contract.js";
 import { PLATFORM_COLUMNS, fieldSource, isEntity, lightChanges } from "../schema.js";
 import { env } from "./env.js";
 /** Drizzle's text column types: what a search reads. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trylight/app",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "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,6 +12,7 @@
     "url": "https://github.com/shubh9/mii.git",
     "directory": "packages/app-sdk"
   },
+  "packageManager": "pnpm@11.0.9",
   "files": [
     "dist",
     "bin"
@@ -41,6 +42,15 @@
       "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",
@@ -74,13 +84,5 @@
     "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"
   }
-}
+}

package/dist/invoke/paths.d.ts

@@ -1,2 +0,0 @@
-/** Where an app mounts its invoke routes, and where `invoke()` calls them. */
-export declare const INVOKE_BASE_PATH = "/api/mii/invoke";

package/dist/invoke/paths.js

@@ -1,2 +0,0 @@
-/** Where an app mounts its invoke routes, and where `invoke()` calls them. */
-export const INVOKE_BASE_PATH = "/api/mii/invoke";