@trylight/app 0.2.0 → 0.3.0

package/README.md

@@ -41,6 +41,20 @@ text column, case-insensitively, on the server.
 
 Joins and aggregates stay typed server functions over `light.db`.
 
+### Live data
+
+An open page shows other people's and agents' changes without a refresh.
+`MiiPaneBridge` (every app renders it) runs a TanStack query over
+`/api/light/entities/_changes?since=<cursor>` (`src/platform/live-data.ts`):
+every `POLL_MS` while the tab is visible, at once on focus and reconnect. The
+route answers from `light_changes` with the tables changed since the cursor
+(looking `CHANGES_OVERLAP` behind it, for transactions that committed after
+the last poll read) and the next cursor; never rows. Each changed table's
+queries are invalidated by its key (except a table this tab is writing: the
+write's own refetch follows it), and the route loaders reloaded. `light_changes`' `created_at` index is made
+after every migrate (`src/db/audit.ts`). The poll is one `ChangeFeed`; a pushed
+transport can replace it.
+
 ## Images
 
 `/api/light/image?src=…` serves a logo or photo a row points at from the

package/dist/brand.generated.js

@@ -1,3 +1,3 @@
 // Generated from config/brand.json by scripts/write-brand.ts. Do not edit.
 /** The platform app's origins, current domain first. */
-export const APP_ORIGINS = ["https://plaza.miis.run"];
+export const APP_ORIGINS = ["https://trylight.ai", "https://plaza.miis.run"];

package/dist/client.js

@@ -10,7 +10,7 @@ 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 } from "./entities.js";
+import { ENTITIES_PATH, EntityError, LIST_LIMIT, tableQueryKey } from "./entities.js";
 export { EntityError, LIST_LIMIT } from "./entities.js";
 export { siteOf } from "./schema.js";
 export { imageSrc } from "./images.js";
@@ -123,12 +123,13 @@ function putBack(client, id, before) {
 /** One entity table's rows: plain calls, and TanStack Query hooks over them. */
 function tableClient(entity) {
     const base = `${ENTITIES_PATH}/${getTableName(entity)}`;
+    const all = tableQueryKey(getTableName(entity));
     const keys = {
-        all: ["light", base],
-        list: (options) => ["light", base, "list", options],
-        pages: (options) => ["light", base, "pages", options],
-        get: (id) => ["light", base, "get", id],
-        write: ["light", base, "write"]
+        all,
+        list: (options) => [...all, "list", options],
+        pages: (options) => [...all, "pages", options],
+        get: (id) => [...all, "get", id],
+        write: [...all, "write"]
     };
     const list = (options = {}) => call("GET", `${base}?q=${encodeURIComponent(JSON.stringify(options))}`);
     const get = (id) => call("GET", `${base}/${id}`);

package/dist/db/audit.d.ts

@@ -10,7 +10,7 @@ export declare function entityTables(schema: Record<string, unknown>): string[];
 /**
  * Puts the change trigger on each of `tables` the database has (one a
  * migration hasn't made yet is tracked on the migrate that makes it), and
- * makes light_changes append-only. Runs after migrating.
+ * makes light_changes append-only and indexed by time. Runs after migrating.
  */
 export declare function trackTables(sql: postgres.Sql, tables: string[]): Promise<void>;
 /** A table, or a column of one, that a migration destroys: what it archives first. */

package/dist/db/audit.js

@@ -106,10 +106,16 @@ begin
     archived, case when col is null then 'rows' else 'values' end, concat_ws('.', tbl, col), tag);
 end $$;
 `;
-/** light_changes is a drizzle table (db/schema exports it), so it exists only once migrated. */
-const CHANGES_APPEND_ONLY = `
+/**
+ * light_changes is a drizzle table (db/schema exports it), so it exists only
+ * once migrated. Its created_at index (open pages' poll reads the last
+ * few seconds) is made here, not in the schema, so every app gets it on its
+ * next migrate without a migration of its own.
+ */
+const CHANGES_SETUP = `
 create or replace trigger light_append_only before update or delete or truncate on light_changes
   for each statement execute function light_append_only();
+create index if not exists light_changes_created_idx on light_changes (created_at);
 `;
 /** Makes light_archive and the functions migrations and triggers call. Runs before migrating. */
 export async function prepareAudit(sql) {
@@ -130,11 +136,11 @@ export function entityTables(schema) {
 /**
  * Puts the change trigger on each of `tables` the database has (one a
  * migration hasn't made yet is tracked on the migrate that makes it), and
- * makes light_changes append-only. Runs after migrating.
+ * makes light_changes append-only and indexed by time. Runs after migrating.
  */
 export async function trackTables(sql, tables) {
     await sql `select light_track(name) from unnest(${sql.array(tables)}::text[]) as name where to_regclass(quote_ident(name)) is not null`;
-    await sql.unsafe(CHANGES_APPEND_ONLY);
+    await sql.unsafe(CHANGES_SETUP);
 }
 const snapshotTable = z.looseObject({
     name: z.string(),

package/dist/db/cli.js

@@ -21,7 +21,7 @@ const PLATFORM_MIGRATE = "/run/mii/migrate.sock";
 /** Postgres advisory locks: one migrate, and one sync, of a database at a time. */
 const MIGRATE_LOCK_KEY = 4_815_162_342;
 const SYNC_LOCK_KEY = 4_815_162_343;
-/** Exit code of a migrate whose migrations committed but whose change triggers didn't go on. */
+/** Exit code of a migrate whose migrations committed but whose change tracking (triggers, index) didn't go on. */
 const APPLIED_UNTRACKED = 2;
 // pg_advisory_lock waits for the one before it; a process that dies releases it.
 // Only on a direct connection: behind a transaction pooler the lock stays on a
@@ -101,7 +101,7 @@ async function applyMigrations() {
         console.log("Database is up to date with db/migrations.");
         // The migrations are committed: a failure here must not take their files back.
         return await trackTables(client, tables).then(() => 0, (error) => {
-            console.error(`The change triggers didn't go on (${error instanceof Error ? error.message : String(error)}); the next migrate tries again.`);
+            console.error(`Change tracking didn't go on (${error instanceof Error ? error.message : String(error)}); the next migrate tries again.`);
             return APPLIED_UNTRACKED;
         });
     }

package/dist/entities.d.ts

@@ -1,5 +1,9 @@
 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. */
+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;
 /** A value as JSON carries it: a Date column arrives as its ISO string. */

package/dist/entities.js

@@ -1,4 +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}`];
 /** 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/platform/live-data-mount.d.ts

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

package/dist/platform/live-data-mount.js

@@ -0,0 +1,18 @@
+"use client";
+// Mounted by MiiPaneBridge, so every app has it: the page's query client and router, given to live-data.ts.
+import { useQueryClient } from "@tanstack/react-query";
+import { useRouter } from "@tanstack/react-router";
+import { useEffect } from "react";
+import { fetchChanges, pollChanges, refreshTables } from "./live-data.js";
+export function LiveData() {
+    const queries = useQueryClient();
+    const router = useRouter();
+    useEffect(() => {
+        const feed = pollChanges(queries, fetchChanges);
+        return feed((tables) => {
+            refreshTables(queries, tables);
+            void router.invalidate();
+        });
+    }, [queries, router]);
+    return null;
+}

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

@@ -0,0 +1,30 @@
+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>;
+}, z.core.$strip>;
+/**
+ * A poll's answer; "unreachable" (offline, the server restarting: asked again
+ * next interval); or "signed-out" (the login page itself; the page's own
+ * reads send a person to sign in, never the poll).
+ */
+type Poll = z.infer<typeof changes> | "unreachable" | "signed-out";
+/** Calls `onChanged` with the tables that changed, as it hears; the returned function stops it. */
+export type ChangeFeed = (onChanged: (tables: string[]) => void) => () => void;
+/**
+ * Polls `_changes` as a TanStack query. One the server breaks on (or answers
+ * in a shape it shouldn't) is the query's error, asked again next interval
+ * and reported once (reportError: the pane and Sentry hear it) until a poll works again.
+ */
+export declare function pollChanges(queries: QueryClient, fetchChanges: (since: string | null) => Promise<Poll>): ChangeFeed;
+export declare function fetchChanges(since: string | null): Promise<Poll>;
+/**
+ * Each changed table's on-screen queries refetch, and the route loaders. A
+ * table this tab is writing is left to its write, whose own refetch follows
+ * it (client.ts's settle) and brings these changes too.
+ */
+export declare function refreshTables(queries: QueryClient, tables: string[]): void;
+export {};

package/dist/platform/live-data.js

@@ -0,0 +1,83 @@
+// Open pages show other people's and agents' changes: what changed is told,
+// not pushed — a changed table's on-screen queries and the page's route
+// loaders refetch, through TanStack Query's own invalidation. How a page hears
+// of a change is a ChangeFeed; today a poll of `_changes` that TanStack Query
+// itself runs (refetchInterval while the tab is visible, at once on focus and
+// 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;
+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
+ * in a shape it shouldn't) is the query's error, asked again next interval
+ * and reported once (reportError: the pane and Sentry hear it) until a poll works again.
+ */
+export function pollChanges(queries, fetchChanges) {
+    return (onChanged) => {
+        let cursor = null;
+        let reported = false;
+        const observer = new QueryObserver(queries, {
+            queryKey: ["light", 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),
+            // "always", not true: an app's own default staleTime must not hold back a returning tab.
+            refetchOnWindowFocus: "always",
+            refetchOnReconnect: "always",
+            retry: false,
+            // Each answer once: not again as the next poll starts.
+            notifyOnChangeProps: ["data", "error"]
+        });
+        const stop = observer.subscribe((result) => {
+            if (result.status === "error") {
+                if (!reported)
+                    reportError(result.error);
+                reported = true;
+                return;
+            }
+            if (result.status !== "success" || result.data === "unreachable")
+                return;
+            reported = false;
+            if (result.data === "signed-out")
+                return;
+            cursor = result.data.cursor;
+            if (result.data.changedTables.length > 0)
+                onChanged(result.data.changedTables);
+        });
+        return () => {
+            stop();
+            queries.removeQueries({ queryKey: ["light", CHANGES_PATH], exact: true });
+        };
+    };
+}
+export async function fetchChanges(since) {
+    const path = since === null ? CHANGES_PATH : `${CHANGES_PATH}?since=${encodeURIComponent(since)}`;
+    let response;
+    try {
+        response = await fetch(path, { credentials: "same-origin" });
+    }
+    catch {
+        // fetch rejects only when no answer came back at all.
+        return "unreachable";
+    }
+    if (response.status === 401)
+        return "signed-out";
+    if (!response.ok)
+        throw new EntityError(`GET ${CHANGES_PATH} failed (${response.status}).`, response.status);
+    return changes.parse(await response.json());
+}
+/**
+ * Each changed table's on-screen queries refetch, and the route loaders. A
+ * table this tab is writing is left to its write, whose own refetch follows
+ * it (client.ts's settle) and brings these changes too.
+ */
+export function refreshTables(queries, tables) {
+    for (const table of tables) {
+        const key = tableQueryKey(table);
+        if (queries.isMutating({ mutationKey: [...key, "write"] }) === 0)
+            void queries.invalidateQueries({ queryKey: key });
+    }
+}

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

@@ -1 +1 @@
-export declare function MiiPaneBridge(): null;
+export declare function MiiPaneBridge(): import("react").JSX.Element;

package/dist/platform/pane-bridge.js

@@ -1,4 +1,5 @@
 "use client";
+import { jsx as _jsx } from "react/jsx-runtime";
 // 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,
@@ -17,6 +18,7 @@
 import { useEffect, useRef } from "react";
 import { z } from "zod/v4";
 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", [
@@ -177,7 +179,8 @@ export function MiiPaneBridge() {
             outline.remove();
         };
     }, []);
-    return null;
+    // The one platform component every app renders, so every app's pages stay fresh.
+    return _jsx(LiveData, {});
 }
 function rectOf(element) {
     const rect = element.getBoundingClientRect();

package/dist/schema.js

@@ -84,7 +84,9 @@ export const lightChanges = pgTable("light_changes", {
     created_at: timestamp({ withTimezone: true, mode: "string" })
         .notNull()
         .defaultNow()
-}, (t) => [index("light_changes_row_idx").on(t.table_name, t.row_id)]);
+}, 
+// Its created_at index is made by src/db/audit.ts on every migrate; declared here, its migration would fail on every app.
+(t) => [index("light_changes_row_idx").on(t.table_name, t.row_id)]);
 const bytea = customType({ dataType: () => "bytea" });
 /**
  * The app's own copy of each photo or logo its rows point at, kept on the

package/dist/server/entities.js

@@ -1,14 +1,15 @@
 // The one route behind `app.table(...)`: list, get, create, update and delete
 // on any entity table, each request checked against the table's own Zod
 // schema and the app's door. Each write names its person for the table's
-// trigger, which records the change in light_changes (src/db/audit.ts).
-import { and, asc, desc, eq, getTableColumns, getTableName, ilike, inArray, isNull, or, sql } from "drizzle-orm";
+// trigger, which records the change in light_changes (src/db/audit.ts), which
+// `_changes` reads to tell open pages what to refetch (src/platform/live-data.ts).
+import { and, asc, desc, eq, getTableColumns, getTableName, gt, ilike, inArray, isNull, or, sql } from "drizzle-orm";
 import { isDeepStrictEqual } from "node:util";
 import { createSchemaFactory } from "drizzle-zod";
 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";
+import { CHANGES_PATH, ENTITIES_PATH, LIST_LIMIT } from "../entities.js";
+import { PLATFORM_COLUMNS, fieldSource, isEntity, lightChanges } from "../schema.js";
 import { env } from "./env.js";
 /** Drizzle's text column types: what a search reads. */
 const SEARCHED_TYPES = new Set(["PgText", "PgVarchar", "PgChar"]);
@@ -35,6 +36,16 @@ const target = z.union([
     z.tuple([z.string(), z.uuid()]).transform(([table, id]) => ({ table, id }))
 ]);
 const postgresError = z.object({ cause: z.object({ code: z.string(), message: z.string() }) });
+/**
+ * How far behind its cursor a poll looks. A change's created_at is its
+ * transaction's start, so one that commits after a poll read can sit before
+ * that poll's cursor; the next poll still sees it if the transaction took
+ * less than this. The cost: a change is reported by the poll that sees it
+ * and by the next one, so the page refetches twice.
+ */
+const CHANGES_OVERLAP = "5 seconds";
+/** A cursor: the ISO time the server gave with the last answer. */
+const cursor = z.iso.datetime({ offset: true });
 export function createEntitiesHandler(options) {
     const tables = new Map(Object.values(options.schema)
         .filter(isEntity)
@@ -51,6 +62,13 @@ export function createEntitiesHandler(options) {
         if (!configured && !local) {
             return refuse(503, "auth_not_configured", "Sign-in isn't configured for this app.");
         }
+        if (url.pathname === CHANGES_PATH) {
+            if (request.method !== "GET")
+                return refuse(405, "method", `${request.method} isn't something ${url.pathname} does.`);
+            if (!mayRead(await options.session(request)))
+                return refuse(401, "not_signed_in", "Sign in to use this app.");
+            return changes(options.db(), url);
+        }
         const path = target.safeParse(url.pathname.slice(ENTITIES_PATH.length + 1).split("/"));
         const table = path.success ? tables.get(path.data.table) : undefined;
         if (!path.success || table === undefined) {
@@ -61,10 +79,8 @@ export function createEntitiesHandler(options) {
         const id = path.data.id;
         const method = request.method;
         if (method === "GET") {
-            // Members-only: someone signed in; anyone with the link (and a local dev server): anyone.
-            if (session.user === null && session.mode === "members") {
+            if (!mayRead(session))
                 return refuse(401, "not_signed_in", "Sign in to use this app.");
-            }
             return id === null ? list(db, table, url) : answer(() => get(db, table, id));
         }
         if (table.entity.$access.write === "agents") {
@@ -165,6 +181,25 @@ async function list(db, table, url) {
         .offset(offset);
     return Response.json(rows);
 }
+/** Members-only: someone signed in; anyone with the link (and a local dev server): anyone. */
+function mayRead(session) {
+    return session.user !== null || session.mode !== "members";
+}
+/** The tables changed since `since` (none without one: a tab's first poll only takes a cursor), and the cursor for the next poll. */
+async function changes(db, url) {
+    const since = url.searchParams.get("since");
+    const read = since === null ? null : cursor.safeParse(since);
+    if (read !== null && !read.success)
+        return refuse(400, "invalid", "since must be the cursor of the last answer.");
+    const rows = await db
+        .select({
+        cursor: sql `to_json(clock_timestamp())#>>'{}'`,
+        changedTables: sql `coalesce(array_agg(distinct ${lightChanges.table_name}), '{}')`
+    })
+        .from(lightChanges)
+        .where(read === null ? sql `false` : gt(lightChanges.created_at, sql `${read.data}::timestamptz - ${CHANGES_OVERLAP}::interval`));
+    return Response.json(exactlyOne(rows));
+}
 async function get(db, table, id) {
     return atMostOne(await db.select().from(table.entity).where(eq(table.id, id)));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trylight/app",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "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",
@@ -53,6 +53,7 @@
   },
   "peerDependencies": {
     "@tanstack/react-query": ">=5.69",
+    "@tanstack/react-router": ">=1.170",
     "drizzle-orm": ">=0.45",
     "postgres": ">=3",
     "react": ">=19",
@@ -70,6 +71,7 @@
   "devDependencies": {
     "@eslint-community/eslint-plugin-eslint-comments": "^4.8.1",
     "@tanstack/react-query": "^5.104.0",
+    "@tanstack/react-router": "^1.170.41",
     "@types/node": "^22.20.4",
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",