@altertable/data-app 0.59.1 → 0.62.0

package/dist/{bootstrap.js → worker.js}

@@ -1,4 +1,53 @@
-(() => {
+// src/worker/trusted-parent.ts
+function exactOrigin(value) {
+  const url = new URL(value);
+  if (!/^https?:$/.test(url.protocol) || url.origin !== value) {
+    throw new Error("Expected an exact HTTP(S) parent origin.");
+  }
+  return url;
+}
+function trustedParent(config, searchParams) {
+  if (typeof config !== "string" || !config.trim()) {
+    throw new Error("Missing trusted parent origins.");
+  }
+  const allowed = config.trim().split(/\s+/).map((value) => {
+    const wildcard = value.startsWith("https://*.");
+    const url = exactOrigin(wildcard ? value.replace("*.", "") : value);
+    if (url.hostname.includes("*") || wildcard && url.port) {
+      throw new Error("Invalid parent origin pattern.");
+    }
+    return { value, url, wildcard };
+  });
+  const requested = searchParams.getAll("__altertable_parent");
+  if (!requested.length) {
+    const fallback = allowed.find((origin) => !origin.wildcard);
+    if (!fallback)
+      throw new Error("An exact default parent origin is required.");
+    return fallback.value;
+  }
+  if (requested.length !== 1)
+    return null;
+  let url;
+  try {
+    url = exactOrigin(requested[0]);
+  } catch {
+    return null;
+  }
+  const permitted = allowed.some((origin) => {
+    if (!origin.wildcard)
+      return origin.value === requested[0];
+    if (url.protocol !== "https:" || url.port)
+      return false;
+    const suffix = `.${origin.url.hostname}`;
+    return url.hostname.endsWith(suffix) && /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(url.hostname.slice(0, -suffix.length));
+  });
+  return permitted ? requested[0] : null;
+}
+
+// src/worker/index.ts
+var TOKEN_RE = /^(?=.{1,63}$)[a-z0-9]+(?:-[a-z0-9]+)+-app-[1-9][0-9]*$/;
+var PAGE_CSP = "default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src data: blob:; connect-src 'none'; form-action 'none'; base-uri 'none'";
+var inlineBootstrap = `(() => {
   // src/core/bridge.ts
   var BRIDGE = "altertable:data-app";
   var MAX_PENDING = 128;
@@ -30,6 +79,9 @@
       this.name = "MessageRoutingError";
     }
   }
+  function defineMessageRoute(route) {
+    return route;
+  }
   function defineDataQueryRoute(operations) {
     return {
       operations,
@@ -51,7 +103,7 @@
         if (!value || typeof value !== "object")
           throw new Error("Invalid data response.");
         const response = value;
-        if (!Number.isInteger(response.status) || response.status < 100 || response.status > 599 || !response.body || typeof response.body !== "object")
+        if (!Number.isInteger(response.status) || response.status < 100 || response.status > 599 || !response.body || typeof response.body !== "object" || Array.isArray(response.body))
           throw new Error("Invalid data response.");
         const body = response.body;
         if (response.status < 200 || response.status >= 300) {
@@ -73,6 +125,28 @@
       }
     };
   }
+  var sqlQueryRoute = defineMessageRoute({
+    input(value) {
+      if (!value || typeof value !== "object")
+        throw new Error("Invalid SQL query.");
+      const query = value;
+      if (typeof query.statement !== "string" || !query.statement.trim() || typeof query.limit !== "number" || !Number.isSafeInteger(query.limit) || query.limit < 1)
+        throw new Error("Invalid SQL query.");
+      return { statement: query.statement, limit: query.limit };
+    },
+    output(value, input) {
+      if (!value || typeof value !== "object")
+        throw new Error("Invalid query result.");
+      const result = value;
+      if (!Array.isArray(result.columns) || !result.columns.every((column) => column && typeof column.name === "string" && (column.type === undefined || typeof column.type === "string")) || !Array.isArray(result.rows) || result.rows.length > input.limit || !result.rows.every((row) => Array.isArray(row) && row.length === result.columns.length) || result.queryId !== undefined && typeof result.queryId !== "string")
+        throw new Error("Invalid query result.");
+      return {
+        columns: result.columns,
+        rows: result.rows,
+        ...result.queryId === undefined ? {} : { queryId: result.queryId }
+      };
+    }
+  });
 
   // src/client/messages.ts
   function createMessageClient(routes, transport) {
@@ -120,6 +194,11 @@
   }
 
   // src/client/iframe.ts
+  function rethrowDataMessageError(error) {
+    if (error instanceof MessageRoutingError)
+      throw new DataAppError(error.message, error.code, error.requestId);
+    throw error;
+  }
   function createIframeTransport({
     parentOrigin,
     window: frame = window,
@@ -148,20 +227,20 @@
       if (event.origin !== parentOrigin || event.source !== frame.parent || !isBridgeMessage(event.data))
         return;
       const message = event.data;
-      if (message.type === "connect") {
+      if (message.type === "bridge:connect") {
         if (mode === "bundle") {
           if (!validId(message.token))
             return;
           token = message.token;
         }
-        send({ type: "ready" });
+        send({ type: "bridge:ready" });
         return;
       }
       if (mode === "bundle" && (!token || message.token !== token))
         return;
       if (message.documentId !== documentId)
         return;
-      if (message.type === "initialize" && validId(message.sessionId)) {
+      if (message.type === "bridge:initialize" && validId(message.sessionId)) {
         if (sessionId && sessionId !== message.sessionId) {
           for (const entry of pending.values())
             entry.reject(new DataAppError("The preview reconnected. Retry the request.", "bridge_reset"));
@@ -173,16 +252,16 @@
             entry.start();
         receiveState(message.state);
         if (mode === "url")
-          send({ type: "runtime.ready" });
+          send({ type: "runtime:ready" });
         return;
       }
       if (!sessionId || message.sessionId !== sessionId)
         return;
-      if (message.type === "state") {
+      if (message.type === "state:update") {
         receiveState(message.state);
         return;
       }
-      if (message.type === "script.load" && mode === "bundle" && typeof message.javascript === "string") {
+      if (message.type === "script:load" && mode === "bundle" && typeof message.javascript === "string") {
         loadScript?.(message.javascript);
         return;
       }
@@ -191,9 +270,9 @@
       const entry = pending.get(message.id);
       if (!entry)
         return;
-      if (message.type === "result" && "response" in message) {
+      if (message.type === "bridge:result" && "response" in message) {
         entry.resolve(message.response);
-      } else if (message.type === "error" && typeof message.code === "string" && typeof message.message === "string") {
+      } else if (message.type === "bridge:error" && typeof message.code === "string" && typeof message.message === "string") {
         entry.reject(new MessageRoutingError(message.code, message.message, typeof message.requestId === "string" ? message.requestId : undefined));
       }
     }
@@ -215,13 +294,13 @@
         }
         function abort() {
           if (sent)
-            send({ type: "cancel", id });
+            send({ type: "bridge:cancel", id });
           cleanup();
           reject(signal?.reason);
         }
         const timer = setTimeout(() => {
           if (sent)
-            send({ type: "cancel", id });
+            send({ type: "bridge:cancel", id });
           cleanup();
           reject(new DataAppError(sessionId ? "The data request timed out." : "The preview shell is unavailable. Reload the preview.", sessionId ? "timeout" : "bridge_unavailable"));
         }, timeoutMs);
@@ -231,7 +310,7 @@
               return;
             try {
               send({
-                type: "request",
+                type: "bridge:request",
                 id,
                 route: message.route,
                 payload: message.payload
@@ -256,28 +335,22 @@
         if (sessionId)
           entry.start();
         else
-          send({ type: "ready" });
+          send({ type: "bridge:ready" });
       });
     }
-    const messages = createMessageClient({ "data.query": defineDataQueryRoute() }, requestMessage);
-    async function queryData(operation, input, signal) {
-      try {
-        return await messages.request("data.query", { operation, input }, { signal });
-      } catch (error) {
-        if (error instanceof MessageRoutingError)
-          throw new DataAppError(error.message, error.code, error.requestId);
-        throw error;
-      }
+    const messages = createMessageClient({ "data:query": defineDataQueryRoute(), "data:sql": sqlQueryRoute }, requestMessage);
+    function queryOperation(operation, input, signal) {
+      return messages.request("data:query", { operation, input }, { signal }).catch(rethrowDataMessageError);
     }
     function disconnect() {
-      send({ type: "disconnect" });
+      send({ type: "bridge:disconnect" });
       sessionId = undefined;
       for (const entry of pending.values())
         entry.reject(new DataAppError("The preview has closed.", "bridge_closed"));
     }
     function resume(event) {
       if (event.persisted)
-        send({ type: "ready" });
+        send({ type: "bridge:ready" });
     }
     function dispose() {
       if (disposed)
@@ -292,10 +365,15 @@
     frame.addEventListener("pagehide", disconnect);
     frame.addEventListener("pageshow", resume);
     if (mode === "url")
-      send({ type: "ready" });
+      send({ type: "bridge:ready" });
     return {
       request: requestMessage,
-      transport: queryData,
+      transport: queryOperation,
+      lakehouse: {
+        queryAll(statement, { limit, signal }) {
+          return messages.request("data:sql", { statement, limit }, { signal }).catch(rethrowDataMessageError);
+        }
+      },
       dispose,
       mode,
       snapshot() {
@@ -308,10 +386,10 @@
         };
       },
       ready() {
-        send({ type: "runtime.ready" });
+        send({ type: "runtime:ready" });
       },
       fail() {
-        send({ type: "runtime.error" });
+        send({ type: "runtime:error" });
       }
     };
   }
@@ -386,3 +464,57 @@
     throw new Error("Missing trusted parent origin.");
   startDataAppBootstrap({ parentOrigin });
 })();
+`.replace(/<\/script/gi, (match) => `<\\${match.slice(1)}`);
+function runtimeHtml(parentOrigin) {
+  const attribute = parentOrigin.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("'", "&#39;");
+  return `<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+    <meta http-equiv="Content-Security-Policy" content="${PAGE_CSP}">
+  </head>
+  <body>
+    <div id="root"></div>
+    <script data-parent-origin="${attribute}">${inlineBootstrap}</script>
+  </body>
+</html>
+`;
+}
+function isPreviewHost(hostname, domainName) {
+  const suffix = `.${domainName}`;
+  return hostname.endsWith(suffix) && TOKEN_RE.test(hostname.slice(0, -suffix.length));
+}
+var worker_default = {
+  fetch(request, env) {
+    const url = new URL(request.url);
+    if (!isPreviewHost(url.hostname, env.DOMAIN_NAME) || url.pathname !== "/") {
+      return new Response(null, { status: 404 });
+    }
+    if (request.method !== "GET" && request.method !== "HEAD") {
+      return new Response(null, {
+        status: 405,
+        headers: { Allow: "GET, HEAD" }
+      });
+    }
+    let parent;
+    try {
+      parent = trustedParent(env.PARENT_ORIGINS, url.searchParams);
+    } catch {
+      return new Response(null, { status: 503 });
+    }
+    if (!parent)
+      return new Response(null, { status: 403 });
+    return new Response(request.method === "HEAD" ? null : runtimeHtml(parent), {
+      headers: {
+        "Content-Type": "text/html; charset=utf-8",
+        "Content-Security-Policy": `${PAGE_CSP}; frame-ancestors ${env.PARENT_ORIGINS.trim().split(/\s+/).join(" ")}`,
+        "X-Content-Type-Options": "nosniff",
+        "Referrer-Policy": "no-referrer"
+      }
+    });
+  }
+};
+export {
+  worker_default as default
+};

package/docs/app-authoring.md

@@ -7,12 +7,12 @@ calls, and reusable React UI.
 1. Inspect the source data, time coverage, and existing definitions before choosing
    the exploration. Build findings from observed results and distinguish
    association from cause.
-2. Define named, bounded [operations](contract.md) on the server. Put shared input
+2. Define named, bounded [operations](contract.md) in the execution runtime. Put shared input
    contracts in a browser-safe module and validate outputs before returning them.
-3. Use a [server handler](server.md) that authorizes each request, or the
+3. For HTTP apps, use a [server handler](server.md) that authorizes each request, or the
    [Bun adapter](server-bun.md) for local development.
 4. Create a typed [client](client.md) and compose [React views](react.md). Import
-   the operation registry with `import type` in browser code.
+   the operation registry with `import type` for HTTP apps, or as a value for bundle apps.
 5. Define glossary and query evidence, handle empty results, and preserve the
    displayed input while a request refreshes or fails. A measured zero and an
    unavailable value must remain distinct.
@@ -21,6 +21,26 @@ calls, and reusable React UI.
 
 Import through `@altertable/data-app/<entry>`. Installed package files are
 dependencies; customize the app's own source rather than editing `node_modules`.
-SQL, credentials, and viewer authorization belong on the server.
+For HTTP apps, SQL, credentials, and viewer authorization belong on the server.
+For bundle apps, define operations in the browser and pass them to
+`createDataClient({ operations })`; SQL travels through the authorized
+[SQL bridge](embed.md#sql-query-route). Credentials, viewer authorization, and
+enforced query limits remain backend-owned.
+
+## Execution ownership
+
+The client selects one of two paths when it is created:
+
+| App model  | Operation execution                                                                                      | Query delivery                                                                                        |
+| ---------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| HTTP app   | The browser sends a name and input; the server authorizes the request and runs its registered operation. | A server-owned lakehouse adapter executes SQL.                                                        |
+| Bundle app | The browser directly runs the registry passed to `createDataClient({ operations })`.                     | `bridge.lakehouse` sends SQL to the host, which authorizes each query and supplies a backend adapter. |
+
+Both paths use the same internal operation executor for input/output validation,
+query names, row bounds, deadlines, evidence, and response serialization limits.
+The executor accepts a `Lakehouse` and never chooses a transport or authorizes a
+viewer. Each adapter owns its boundary: HTTP owns request parsing and responses;
+the bridge owns message delivery; the SQL host owns authorization and public query
+errors. Backend permissions and resource limits apply independently of app policy.
 
 For agent-assisted authoring, see the [starter AGENTS.md template](starter-agent-instructions.md).

package/docs/appearance.md

@@ -1,30 +1,43 @@
 # Appearance
 
 Import `parseAppearance`, `applyAppearance`, and `createThemeController` from
-`@altertable/data-app/appearance`. Parsing is safe on the server; applying tokens
-and controlling theme require a browser document.
+`@altertable/data-app/appearance`. Parsing is safe on the server. Applying tokens requires a browser document;
+viewer preferences use browser storage.
 
 ```ts
 import { parseAppearance } from '@altertable/data-app/appearance';
 
 const appearance = parseAppearance({
-  mode: 'system',
+  theme: 'system',
   accentColor: '#405d47',
   density: 'comfortable',
 });
 ```
 
 `parseAppearance` fills omitted settings with defaults and rejects unknown keys
-or invalid values. Settings include light/dark/system mode, neutral/slate/warm
+or invalid values. Settings include light/dark/system theme, neutral/slate/warm
 base colors, accent colors, a chart palette, density, corner radius, elevation,
 and body/heading typography. Colors are six-digit hexadecimal values.
 
 `applyAppearance(appearance)` installs semantic CSS tokens on the document root
 and returns a cleanup function for system-theme listening.
-`createThemeController(appearance)` applies the initial theme and provides
-`getMode`, `setMode`, and `subscribe`. Viewer mode persists in local storage
-independently of app-authored brand settings. Storage failures do not prevent
-the selection from applying to the current page.
+`createThemeController(initialTheme)` manages the viewer's preference through
+`getTheme`, `setTheme`, and `subscribe`. It reads and persists local storage
+when available. Apply the preference with `applyAppearance` in the UI owner;
+the controller itself does not modify the document.
 
 The React `DataApp` shell manages appearance for normal app usage. See
 [configuration](config.md), [React](react.md), and [styles](react-styles.md).
+
+`Theme` is the resolved `'light' | 'dark'` theme. `ThemePreference` additionally
+allows `'system'` for standalone viewers. A trusted host supplies a `theme: Theme`
+through [parent presentation](embed.md#parent-presentation). React applies that
+theme directly with app-owned brand tokens; standalone viewers use the preference
+controller. Appearance effect cleanup releases the system preference listener.
+
+When migrating theme controls, replace `getMode`/`setMode` with
+`getTheme`/`setTheme`, and initialize the controller with a `ThemePreference`
+rather than appearance settings. Subscribe to the controller and compose its
+preference with `applyAppearance` to update document tokens.
+
+Appearance configuration uses `theme` (formerly `mode`).

package/docs/client.md

@@ -22,14 +22,51 @@ implementation. Calls POST JSON to `/api/data/:operation`; the client sends
 operation inputs rather than SQL or credentials.
 
 `DataResponse` contains `data`, the exact request `input`, `requestId`,
-`queriedAt`, and `queryIds`. `queries` is present only when the server permits
-SQL disclosure. Use the returned input when labeling stale data during a refresh.
+`queriedAt`, and `queryIds`. `queries` is present when the operation exposes SQL
+and the execution runtime permits disclosure. Use the returned input when labeling stale data during a refresh.
+HTTP and iframe delivery validate the same success envelope: data, request ID,
+query timestamp, query IDs, and optional query evidence. Malformed responses
+reject with `invalid_response`.
+
 `DataAppError` exposes a `code` and optional `requestId`; cancellation follows
 the supplied abort signal.
 
 See [contracts](contract.md), [server handlers](server.md), and
 [React bindings](react.md).
 
+## Browser-owned operations for bundle apps
+
+Bundle apps pass their operation registry as a value:
+
+```ts
+import { connectionCheck } from '@altertable/data-app/contract';
+import { createDataClient } from '@altertable/data-app/client';
+
+const client = createDataClient({
+  operations: { connection: connectionCheck() },
+});
+const response = await client.query('connection', {});
+```
+
+The client runs input parsing, operation logic, and output parsing in the browser.
+It uses the same executor as the server handler for query names, row and duration
+bounds, response size, and query evidence. Each query sends `{ statement, limit }`
+to the installed iframe bridge's `data:sql` route; the host needs no operation
+registry. SQL is visible in the browser, even when `exposeSql` is false; that flag
+only controls evidence in the returned response. Credentials remain backend-owned.
+
+The trusted bootstrap installs the bridge for bundle apps. A custom runtime must
+install it before querying. An explicit `lakehouse` can supply another authorized
+adapter, including `bridge.lakehouse` or a local server adapter. `operations` cannot
+be combined with `transport`, `endpoint`, or `fetch`; a `lakehouse` requires
+`operations`. The exported `DataClientOptions` union rejects mixed configurations
+at compile time. Omitting `operations` preserves named HTTP/iframe operation delivery.
+
+The host must implement and authorize the [SQL route](embed.md#sql-query-route).
+Browser policies improve app behavior; backend access and resource limits must be
+enforced independently because a frame can forge requests. Cancellation reaches
+the host through the existing bridge cancellation protocol.
+
 ## Iframe transport
 
 `createDataClient({ transport })` accepts a `DataTransport`. Without an explicit
@@ -68,7 +105,7 @@ import {
 const bridge = getDataAppTransport();
 if (!bridge) throw new Error('An iframe transport must be installed first.');
 const messages = createMessageClient(routes, bridge.request);
-const result = await messages.request('echo', 'hello', { signal });
+const result = await messages.request('demo:echo', 'hello', { signal });
 ```
 
 The app supplies shared `routes` and optional `signal`. Both client and host

package/docs/contract.md

@@ -2,7 +2,7 @@
 
 Import operation definitions, parsers, and shared types from
 `@altertable/data-app/contract`. This entry is safe to import in browser and server
-modules. Keep SQL and operation implementations on the server; browser modules
+modules. For HTTP apps, keep SQL and operation implementations on the server; browser modules
 should import their operation types using `import type`.
 
 ## Execute named queries
@@ -30,7 +30,7 @@ const activity = defineOperation({
 });
 ```
 
-`query` inherits the operation's limit and cancellation signal; `{ limit }` can lower a particular query's bound. Names are checked by TypeScript and at runtime. The server records the SQL and query ID when execution occurs, so evidence does not need a separate result field. Browser modules import operation types with `import type`; they never import server implementations.
+`query` inherits the operation's limit and cancellation signal; `{ limit }` can lower a particular query's bound. Names are checked by TypeScript and at runtime. The executor records the SQL and query ID when execution occurs, so evidence does not need a separate result field. HTTP browser modules import operation types with `import type`. Bundle apps import their browser-owned operation registry as a value and use [browser execution](client.md#browser-owned-operations-for-bundle-apps). Never bundle credentials or server adapters.
 
 ## Shared date ranges
 
@@ -63,6 +63,8 @@ Message contracts describe the payloads allowed between an embedded app and its
 host. Share these contracts with the app; keep handlers and authorization in the
 host/server.
 
+Name routes `{scope}:{action}`, for example `data:query` or `navigation:update`.
+
 ```ts
 import {
   createMessageRouter,
@@ -72,12 +74,12 @@ import {
 import { createNavigationHandler } from '@altertable/data-app/embed';
 
 const routes = {
-  echo: defineMessageRoute({ input: parseString, output: parseString }),
-  'navigation.update': navigationUpdateRoute,
+  'demo:echo': defineMessageRoute({ input: parseString, output: parseString }),
+  'navigation:update': navigationUpdateRoute,
 };
 const router = createMessageRouter(routes, {
-  echo: value => value,
-  'navigation.update': createNavigationHandler(),
+  'demo:echo': value => value,
+  'navigation:update': createNavigationHandler(),
 });
 ```
 
@@ -90,6 +92,6 @@ errors are replaced with a generic failure.
 input and output and preserves its response evidence. It infers the result type
 from the selected operation when used with `createMessageClient`. Share input and
 output parsers, not operation implementations containing SQL or credentials.
-`dataAppRoutes` supplies generic `data.query` and `navigation.update` contracts;
+`dataAppRoutes` supplies generic `data:query` and `navigation:update` contracts;
 generic hosts must delegate operation validation and authorization to their
 server. Request handlers receive `{ signal }` for cancellation.