@altertable/data-app 0.61.0 → 0.62.0

package/dist/types/client/index.d.ts

@@ -1,13 +1,5 @@
-/**
- * Typed clients for HTTP and iframe delivery; safe to import in the browser.
- * @module @altertable/data-app/client
- * @see https://github.com/altertable-ai/data-app/blob/main/docs/client.md
- */
-import { type DataTransport } from './transport.js';
-export { createHttpTransport, DataAppError, type DataTransport, } from './transport.js';
-export { createIframeTransport, installDataAppTransport, getDataAppTransport, type IframeTransport, } from './iframe.js';
-export { createMessageClient } from './messages.js';
-import type { DataOperations, DisclosedQuery } from '../core/contract.js';
+import type { DataOperations, DisclosedQuery, Lakehouse } from '../core/contract.js';
+import type { DataTransport } from './transport.js';
 export type InputOf<T> = T extends {
     input: (value: unknown) => infer Input;
 } ? Input : never;
@@ -32,11 +24,25 @@ export type DataClient<Operations extends DataOperations> = {
         signal?: AbortSignal;
     }): Promise<DataResponse<OutputOf<Operations[Name]>, InputOf<Operations[Name]>>>;
 };
-/** Browser client for named operations; it sends inputs, never SQL or lakehouse credentials. */
-export declare function createDataClient<Operations extends DataOperations>(options?: {
+/** Browser operations and named-operation delivery are mutually exclusive configurations. */
+export type DataClientOptions<Operations extends DataOperations> = {
+    operations: Operations;
+    lakehouse?: Lakehouse;
+    transport?: never;
+    endpoint?: never;
+    fetch?: never;
+} | {
+    operations?: never;
+    lakehouse?: never;
     transport?: DataTransport;
     endpoint?: string;
     fetch?: typeof fetch;
-}): DataClient<Operations>;
+};
+/** Named HTTP operations, or browser-owned operations executed through an authorized SQL bridge. */
+export declare function createDataClient<Operations extends DataOperations>(options?: DataClientOptions<Operations>): DataClient<Operations>;
 export type { DataAppLocation, AppLocation } from './location.js';
 export { createDataAppNavigation, getDataAppNavigation, type DataAppNavigation, } from './navigation.js';
+export { createHttpTransport, DataAppError, type DataTransport, } from './transport.js';
+export { createIframeTransport, installDataAppTransport, getDataAppTransport, type IframeTransport, } from './iframe.js';
+export { createMessageClient } from './messages.js';
+export type { DataAppPresentation } from '../core/presentation.js';

package/dist/types/core/appearance.d.ts

@@ -1,5 +1,7 @@
+export type Theme = 'light' | 'dark';
+export type ThemePreference = Theme | 'system';
 export type AppearanceSettings = {
-    mode: 'light' | 'dark' | 'system';
+    theme: ThemePreference;
     baseColor: 'neutral' | 'slate' | 'warm';
     accentColor: string;
     darkAccentColor?: string;
@@ -12,10 +14,9 @@ export type AppearanceSettings = {
         heading: string;
     };
 };
-export type ThemeMode = AppearanceSettings['mode'];
 export type ThemeController = {
-    getMode: () => ThemeMode;
-    setMode: (mode: ThemeMode) => void;
+    getTheme: () => ThemePreference;
+    setTheme: (theme: ThemePreference) => void;
     subscribe: (listener: () => void) => () => void;
 };
 export declare function parseAppearance(value: unknown): AppearanceSettings;
@@ -24,5 +25,5 @@ export declare function parseAppearance(value: unknown): AppearanceSettings;
  * system-theme listening.
  */
 export declare function applyAppearance(value: unknown): () => void;
-/** Viewer color mode persists independently of app-authored brand tokens. */
-export declare function createThemeController(value: unknown): ThemeController;
+/** Persist a viewer theme preference. Applying appearance belongs to the UI owner. */
+export declare function createThemeController(initialTheme?: ThemePreference): ThemeController;

package/dist/types/core/contract.d.ts

@@ -80,7 +80,7 @@ export declare class DataSourceError extends Error {
     queryName?: string;
     constructor(reason: 'unauthorized' | 'forbidden' | 'rate_limited' | 'query_rejected' | 'unavailable', status?: number | undefined);
 }
-/** Server-only query interface supplied by a local or hosted adapter. */
+/** Query interface supplied by a server adapter or an authorized iframe bridge. */
 export type Lakehouse = {
     queryAll(statement: string, options: {
         limit: number;
@@ -93,8 +93,8 @@ export type OperationContext = {
     signal: AbortSignal;
 };
 /**
- * Both parsers run on the server before results cross the JSON boundary. Schema libraries can be
- * used inside either parser.
+ * Parsers run in the operation executor's runtime: server for HTTP apps, browser for bundle apps.
+ * Browser validation does not replace backend authorization or query limits.
  */
 export type DataOperation<Input, Output> = {
     input: (value: unknown) => Input;

package/dist/types/core/messages.d.ts

@@ -1,5 +1,5 @@
 import type { TransportResponse } from './bridge.js';
-import type { DisclosedQuery } from './contract.js';
+import type { DisclosedQuery, QueryResult } from './contract.js';
 export type MessageContext = {
     signal: AbortSignal;
 };
@@ -70,6 +70,12 @@ export type NavigationUpdate = {
     title?: string;
 };
 export declare const navigationUpdateRoute: MessageRoute<NavigationUpdate, null>;
+export type SqlQueryInput = {
+    statement: string;
+    limit: number;
+};
+/** SQL delivery for browser-owned operations. Hosts must enforce backend access and resource limits. */
+export declare const sqlQueryRoute: MessageRoute<SqlQueryInput, QueryResult>;
 export declare const dataAppRoutes: {
     'data:query': DataQueryRoute<OperationContracts>;
     'navigation:update': MessageRoute<NavigationUpdate, null>;

package/dist/types/core/operation.d.ts

@@ -0,0 +1,27 @@
+import { type DataOperations, type DisclosedQuery, type Lakehouse } from './contract.js';
+type Operation = DataOperations[string];
+type OperationExecutionOptions = {
+    operationName: string;
+    lakehouse: Lakehouse;
+    signal: AbortSignal;
+    /** Include query evidence in the response; this does not keep browser-owned SQL private. */
+    includeSql: boolean;
+    requestId: string;
+};
+/** Shared operation execution. Adapters own authorization, delivery, and public errors. */
+export declare function executeDataOperation(operation: Operation, value: unknown, { operationName, lakehouse, signal: requestSignal, includeSql, requestId, }: OperationExecutionOptions): Promise<{
+    body: {
+        data: unknown;
+        requestId: string;
+        queriedAt: string;
+        queryIds: string[];
+        queries?: DisclosedQuery[] | undefined;
+    };
+    serializedBody: string;
+}>;
+export declare function toDataOperationFailure(error: unknown, aborted?: boolean): {
+    status: number;
+    code: string;
+    message: string;
+};
+export {};

package/dist/types/core/presentation.d.ts

@@ -0,0 +1,7 @@
+import type { Theme } from './appearance.js';
+/** Presentation owned by the parent shell, delivered only over a trusted bridge. */
+export type DataAppPresentation = {
+    surface: 'embedded' | 'standalone';
+    theme: Theme;
+};
+export declare function isDataAppPresentation(value: unknown): value is DataAppPresentation;

package/dist/types/embed/bridge.d.ts

@@ -0,0 +1,12 @@
+import { type DataAppConnectionOptions } from './host.js';
+import { type DataAppSourceOptions } from './source.js';
+export type DataAppBridgeOptions = (DataAppSourceOptions & {
+    connection?: never;
+    window?: never;
+    javascript?: never;
+}) | (DataAppConnectionOptions & {
+    source?: never;
+    startupTimeoutMs?: never;
+});
+/** Source mode configures and loads the iframe; connection mode attaches to a host-owned document. */
+export declare function attachDataAppBridge(options: DataAppBridgeOptions): import("./host.js").DataAppHost;

package/dist/types/embed/host.d.ts

@@ -1,3 +1,4 @@
+import type { DataAppPresentation } from '../core/presentation.js';
 import { type MessageDispatcher } from '../core/messages.js';
 export type DataAppConnection = {
     type: 'origin';
@@ -11,13 +12,19 @@ export type DataAppDiagnostic = {
     direction: 'send' | 'receive';
     type: string;
 };
-/** The bridge owns delivery and cancellation; the routed handler owns validation, authorization and execution. */
-export declare function attachDataAppBridge({ iframe, connection, javascript, onStatusChange, onDiagnostic, onMessage, window: host, }: {
+export type DataAppHost = {
+    dispose: () => void;
+    setPresentation: (presentation?: DataAppPresentation) => void;
+};
+export type DataAppConnectionOptions = {
     iframe: HTMLIFrameElement;
     connection: DataAppConnection;
     javascript?: string;
+    presentation?: DataAppPresentation;
     onStatusChange?: (status: DataAppStatus) => void;
     onDiagnostic?: (event: DataAppDiagnostic) => void;
     onMessage: MessageDispatcher;
     window?: Window;
-}): () => void;
+};
+/** The bridge owns delivery and cancellation; the routed handler owns validation, authorization and execution. */
+export declare function attachDataAppConnection({ iframe, connection, javascript, presentation, onStatusChange, onDiagnostic, onMessage, window: host, }: DataAppConnectionOptions): DataAppHost;

package/dist/types/embed/index.d.ts

@@ -3,9 +3,12 @@
  * @module @altertable/data-app/embed
  * @see https://github.com/altertable-ai/data-app/blob/main/docs/embed.md
  */
-export { attachDataAppBridge } from './host.js';
-export type { DataAppConnection, DataAppStatus, DataAppDiagnostic, } from './host.js';
-export { attachDataAppShell } from './shell.js';
-export type { DataAppSource, DataAppShellOptions } from './shell.js';
+export { attachDataAppBridge } from './bridge.js';
+export type { DataAppBridgeOptions } from './bridge.js';
+export type { DataAppHost, DataAppConnection, DataAppStatus, DataAppDiagnostic, } from './host.js';
+export type { DataAppSource } from './source.js';
 export { startDataAppBootstrap } from './bootstrap.js';
 export { createNavigationHandler } from './navigation.js';
+export { sqlQueryRoute, type SqlQueryInput } from '../core/messages.js';
+export { createSqlQueryHandler } from './sql.js';
+export type { DataAppPresentation } from '../core/presentation.js';

package/dist/types/embed/{shell.d.ts → source.d.ts}

@@ -1,5 +1,6 @@
+import type { DataAppPresentation } from '../core/presentation.js';
 import type { MessageDispatcher } from '../core/messages.js';
-import { type DataAppStatus, type DataAppDiagnostic } from './host.js';
+import { type DataAppStatus, type DataAppHost, type DataAppDiagnostic } from './host.js';
 export type DataAppSource = {
     type: 'url';
     url: string;
@@ -7,15 +8,15 @@ export type DataAppSource = {
     type: 'bundle';
     bootstrapUrl: string;
     javascript: string;
-    revision: string;
 };
-export type DataAppShellOptions = {
+export type DataAppSourceOptions = {
     iframe: HTMLIFrameElement;
     source: DataAppSource;
+    presentation?: DataAppPresentation;
     onMessage: MessageDispatcher;
     onStatusChange?: (status: DataAppStatus) => void;
     onDiagnostic?: (event: DataAppDiagnostic) => void;
     startupTimeoutMs?: number;
 };
 /** Owns loading and sandbox policy. Dispose before replacing the source or retrying. */
-export declare function attachDataAppShell({ iframe, source, onMessage, onStatusChange, onDiagnostic, startupTimeoutMs, }: DataAppShellOptions): () => void;
+export declare function attachDataAppSource({ iframe, source, presentation, onMessage, onStatusChange, onDiagnostic, startupTimeoutMs, }: DataAppSourceOptions): DataAppHost;

package/dist/types/embed/sql.d.ts

@@ -0,0 +1,4 @@
+import type { Lakehouse } from '../core/contract.js';
+import { type MessageContext, type SqlQueryInput } from '../core/messages.js';
+/** Authorize every SQL request and supply a backend that independently enforces access and query limits. */
+export declare function createSqlQueryHandler(authorize: (query: SqlQueryInput, context: MessageContext) => Promise<Lakehouse>): (input: SqlQueryInput, context: MessageContext) => Promise<import("../core/contract.js").QueryResult>;

package/dist/types/react/embed/bridge.d.ts

@@ -1,12 +1,21 @@
-import { type ComponentRef } from 'react';
-import { type DataAppConnection, type DataAppStatus, type DataAppDiagnostic } from '../../embed/host.js';
-import type { MessageDispatcher } from '../../core/messages.js';
-export type DataAppBridgeProps = {
+import { type ComponentRef, type ComponentPropsWithoutRef } from 'react';
+import { type DataAppBridgeOptions } from '../../embed/bridge.js';
+import type { DataAppConnection } from '../../embed/host.js';
+import type { DataAppSource } from '../../embed/source.js';
+export type DataAppBridgeProps = Pick<DataAppBridgeOptions, 'onMessage' | 'onStatusChange' | 'onDiagnostic' | 'presentation'> & ({
+    source: DataAppSource;
+    title: string;
+    startupTimeoutMs?: number;
+    iframeProps?: Omit<ComponentPropsWithoutRef<'iframe'>, 'src' | 'srcDoc' | 'sandbox' | 'referrerPolicy' | 'loading' | 'children' | 'title'>;
+    iframe?: never;
+    connection?: never;
+} | {
     iframe: ComponentRef<'iframe'> | null;
     connection: DataAppConnection;
-    onMessage: MessageDispatcher;
-    onStatusChange?: (status: DataAppStatus) => void;
-    onDiagnostic?: (event: DataAppDiagnostic) => void;
-};
-/** Delivery only; the host owns the iframe and route handlers, including navigation. */
-export declare function DataAppBridge({ iframe, connection, onMessage, onStatusChange, onDiagnostic, }: DataAppBridgeProps): null;
+    source?: never;
+    title?: never;
+    startupTimeoutMs?: never;
+    iframeProps?: never;
+});
+/** Owns iframe setup and delivery. The consuming shell owns loading, error UI, and retries. */
+export declare function DataAppBridge(props: DataAppBridgeProps): import("react").JSX.Element;

package/dist/types/react/embed/index.d.ts

@@ -5,5 +5,3 @@
  */
 export { DataAppBridge } from './bridge.js';
 export type { DataAppBridgeProps } from './bridge.js';
-export { DataAppShell } from './shell.js';
-export type { DataAppShellProps } from './shell.js';

package/dist/types/react/ui/DataAppSkeleton.d.ts

@@ -0,0 +1,8 @@
+import type { ComponentPropsWithRef, ReactNode } from 'react';
+
+export type DataAppSkeletonProps = Omit<ComponentPropsWithRef<'output'>, 'children' | 'role' | 'aria-busy'> & {
+    header?: ReactNode;
+    footer?: ReactNode;
+};
+/** Host-side placeholder while a data app starts. Header and footer slots remain host-owned; widget placeholders are decorative. */
+export declare function DataAppSkeleton({ header, footer, className, ...props }: DataAppSkeletonProps): import("react").JSX.Element;

package/dist/types/react/ui/SearchInput.d.ts

@@ -1,7 +1,7 @@
 import type { ComponentPropsWithRef, ReactNode } from 'react';
 
 /** One search control surface for picker search and table/page search. */
-export declare function SearchInput({ size, endAction, loading, className, ...props }: Omit<ComponentPropsWithRef<'input'>, 'size' | 'children'> & {
+export declare function SearchInput({ size, endAction, loading, className, onKeyDown, ...props }: Omit<ComponentPropsWithRef<'input'>, 'size' | 'children'> & {
     size?: 'default' | 'compact';
     endAction?: ReactNode;
     /** Replaces the search glyph in its existing space; input and results remain usable. */

package/dist/types/react/ui/index.d.ts

@@ -56,6 +56,8 @@ export { EmptyState } from './EmptyState.js';
 export type { EmptyStateProps } from './EmptyState.js';
 export { Skeleton } from './Skeleton.js';
 export type { SkeletonProps } from './Skeleton.js';
+export { DataAppSkeleton } from './DataAppSkeleton.js';
+export type { DataAppSkeletonProps } from './DataAppSkeleton.js';
 export { DataBoundary } from './DataBoundary.js';
 export { resolveDataView } from '../../core/data-view.js';
 export { displayedSnapshot } from '../../core/data-view.js';

package/dist/types/react/ui/useAppAppearance.d.ts

@@ -0,0 +1,3 @@
+import { type Theme } from '../../core/appearance.js';
+/** The parent theme takes precedence; only standalone viewers receive controls. */
+export declare function useAppAppearance(appearance: unknown, hostTheme?: Theme): import("../../core/appearance.js").ThemeController | undefined;

package/dist/types/react/ui/useDataAppPresentation.d.ts

@@ -0,0 +1,3 @@
+import { type DataAppPresentation } from '../../core/presentation.js';
+/** Local preview verifies its parent before accepting presentation context. */
+export declare function useDataAppPresentation(): DataAppPresentation | undefined;

package/dist/types/react/view-controls.d.ts

@@ -2,7 +2,7 @@ import type { ReactNode } from 'react';
 import { type AppVariableValues, type VariableCollection } from './ui/variables.js';
 import type { ResolvedVariables } from './view.js';
 /** URL values resolve before facets; facet keys include their dependent inputs for cached, bounded loading. */
-export declare function useViewVariables<Variables extends VariableCollection>(definitions: Variables, loadFacet: (operation: string, input: unknown, signal: AbortSignal) => Promise<unknown>): {
+export declare function useViewVariables<Variables extends VariableCollection>(definitions: Variables, clientScope: string, loadFacet: (operation: string, input: unknown, signal: AbortSignal) => Promise<unknown>): {
     values: AppVariableValues<Variables>;
     set: <Key extends keyof Variables & string>(name: Key, value: AppVariableValues<Variables>[Key]) => void;
     reset: <Key extends keyof Variables & string>(name: Key) => void;

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,
@@ -259,15 +338,9 @@
           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: "bridge:disconnect" });
@@ -295,7 +368,12 @@
       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() {
@@ -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`).