@altertable/data-app 0.61.0 → 0.63.0

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

@@ -1,4 +1,4 @@
-import type { EmptyStateProps } from './ui/EmptyState.js';
+import type { EmptyContent } from './ui/presentation.js';
 import type { AppVariableValues, DateRangeVariable, VariableCollection } from '../core/variables.js';
 import type { DateRangeRequest } from '../core/contract.js';
 export type ResolvedVariables<Variables extends VariableCollection> = {
@@ -23,7 +23,7 @@ export type DataViewDefinition<Name extends string, Variables extends VariableCo
     bindings?: ViewBindings<Variables, Input>;
     /** App-owned semantics: measured zero need not mean an empty result. */
     isEmpty: (data: Data) => boolean;
-    empty: Pick<EmptyStateProps, 'title' | 'description'>;
+    empty: EmptyContent;
 } & ({
     date: ViewDate<Variables, Input>;
     describeInput?: (input: Input) => string;

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

@@ -1,26 +1,62 @@
 # Author a data app
 
-An app owns its question, SQL, result parsing, business definitions, configuration,
-and presentation. The package supplies contracts, request handling, typed client
-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
-   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
-   [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.
-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.
-6. Verify the app's findings and interactions against the original question.
-   Inspect loading, error, stale, and empty states at desktop and phone widths.
-
-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 agent-assisted authoring, see the [starter AGENTS.md template](starter-agent-instructions.md).
+Build an exploration that answers the user's question and a story that presents
+its strongest findings. Both use the same queries, definitions, and evidence.
+
+## Inspect the data
+
+Inspect the relevant catalogs, tables, and fields, their time coverage, and
+existing definitions. Choose a question the available data can answer.
+
+## Build the exploration
+
+Choose the execution path:
+
+| App                                | Guide                                   |
+| ---------------------------------- | --------------------------------------- |
+| Data app (hosted / remote / cloud) | [Single-file authoring](hosted-apps.md) |
+| Local data app                     | [Local authoring](local-data-apps.md)   |
+
+Lead with a supported finding and expose the relevant fields as filter variables. Use a date filter for questions worth exploring over time,
+or a fixed period snapshot for a deliberate historical analysis.
+Register inspected tables and fields with `defineDataIdentifiers()` and use
+`<DataIdentifier>` when naming sources. Register terms and query evidence so
+readers can inspect the source of each claim.
+
+Connect visualizations with introductions and explanations. Use `<TextWidget>`
+for a narrative panel with the standard widget frame, or `<TextContent>` for
+borderless prose. Bind claims to `result.select((data, input) => ...)` so their
+values and scope follow the displayed results through filter changes, refresh,
+and failure.
+
+| Task                                       | Documentation                                              |
+| ------------------------------------------ | ---------------------------------------------------------- |
+| Define queries, inputs, and result parsing | [Operations](contract.md)                                  |
+| Build views, filters, and request states   | [React](react.md)                                          |
+| Introduce and explain visualizations       | [Narrative text](react.md#narrative-text)                  |
+| Find formatters and presentation helpers   | [App helpers](react.md#reuse-app-helpers)                  |
+| Register source names                      | [Source identifiers](react.md#register-source-identifiers) |
+| Choose date and field filters              | [Filter variables](react.md#time-views-and-field-filters)  |
+| Handle refresh and stale results           | [Displayed results](react.md#preserve-displayed-results)   |
+| Bind definitions and source evidence       | [Data context](react.md#bind-evidence)                     |
+
+Use the exported types for configuration, appearance, formatting, and component
+options.
+
+## Present the findings
+
+Compose a [story](react.md#present-data-with-stories) from the exploration's
+findings. Lead with the answer, then show the evidence and comparisons that
+explain it. Select the findings that matter to the audience; do not turn every
+row or chart into a step.
+
+## Verify the app
+
+Verify findings against the source and the user's question. Distinguish measured
+zero, unavailable values, and empty results. Check filters, refresh, loading,
+empty, error, and stale states, then present the story. Inspect both experiences
+at phone and desktop widths in light and dark themes.
+
+The app owns its queries, result parsing, business definitions, configuration,
+and presentation. Credentials, authorization, and enforced access/query limits
+stay backend-owned. Edit app-owned files; installed package files are dependencies.

package/docs/client.md

@@ -1,9 +1,11 @@
 # Client
 
-Import `createDataClient` and `DataAppError` from
+Import `createDataClient()` and `DataAppError` from
 `@altertable/data-app/client`. The client uses Fetch APIs and has no React or
 server dependency.
 
+## HTTP operations
+
 ```ts
 import { createDataClient } from '@altertable/data-app/client';
 import type { operations } from './operations';
@@ -22,20 +24,58 @@ 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
+
+Start with the complete [single-file example](../examples/starter-data-app/index.tsx)
+and [data app authoring guide](hosted-apps.md).
+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.
+Operation policy bounds rows, duration, and response size and records 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
 transport, endpoint, or Fetch implementation, it discovers an installed iframe
 transport before falling back to HTTP. Explicit endpoint/Fetch options select
-HTTP. `createHttpTransport` provides the underlying operation delivery adapter.
+HTTP. `createHttpTransport()` provides the underlying operation delivery adapter.
 
 A URL-hosted app configures trust and installs the bridge before mounting:
 
@@ -56,8 +96,8 @@ URL controls attach the optional navigation adapter to that connection. Cleanup
 the installation and disposes pending work. Bundle apps receive this installation
 from the [trusted bootstrap](embed.md#trusted-bootstrap).
 
-`getDataAppTransport()` returns the explicitly installed bridge. Its `request`
-transport supports custom typed routes:
+`getDataAppTransport()` returns the explicitly installed bridge. Its `request()`
+method supports custom typed routes:
 
 ```ts
 import {
@@ -92,7 +132,7 @@ navigation.publish('replace');
 navigation.dispose();
 ```
 
-The adapter provides `snapshot`, `subscribe`, and `update`. Opaque sandboxes keep
+The adapter provides `snapshot()`, `subscribe()`, and `update()`. Opaque sandboxes keep
 search/hash in memory; URL frames preserve their URL and local-preview parent
 marker. Host Back/Forward state is applied without publishing it back.
 
@@ -100,14 +140,6 @@ marker. Host Back/Forward state is applied without publishing it back.
 and shares one adapter per document. React mounting and URL-backed controls call
 it automatically. Apps that only use data delivery do not attach navigation.
 
-Migration: replace `bridge.appLocation` with the navigation adapter and
-`bridge.location(mode)` with `navigation.publish(mode)`. The version-1 wire envelope
-now carries host context in `initialize.state` and subsequent `state` messages;
-upgrade independently deployed hosts and runtimes together.
-Transport state is shared per window across separately bundled entry points;
-install only one transport per document. Public error classes retain `instanceof`
-recognition across independent bootstrap and app bundles in that window.
-
 ## Pending request limits
 
 Each iframe bridge accepts at most 128 unresolved requests, including requests
@@ -115,10 +147,7 @@ waiting for the connection handshake. Further calls reject with `bridge_busy`
 until a pending call completes, is cancelled, or times out. This bounds the
 client's promises, timers, and queued messages.
 
-The host independently limits pending requests to 128: an iframe can send
-messages directly without using the client helper. The shared cap is a resource
-policy, not a requirement of the message protocol. It rejects excess requests;
-it does not queue them or limit the total number of calls over a session.
+Hosts enforce their own request limits independently of the client.
 
 A failed local-preview verification can be retried by the next explicit data
 request. Concurrent callers share the current verification attempt; aborting

package/docs/contract.md

@@ -2,13 +2,13 @@
 
 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
 
-The app supplies `calendar`, `parseActivity`, `checkInput`, `buildActivitySql`,
-and `parseActivityRows` in this example.
+The app supplies `calendar`, `parseActivity()`, `checkInput`, `buildActivitySql()`,
+and `parseActivityRows()` in this example.
 
 ```ts
 import {
@@ -30,14 +30,14 @@ 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. Responses include executed SQL and query IDs when disclosure is allowed. 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
 
-Use `defineDateRangeContract` in a browser-safe module to share source coverage,
+Use `defineDateRangeContract()` in a browser-safe module to share source coverage,
 time zone, maximum range, and comparison rules between the server parser and
-React variables. The server uses `calendar.parseRequest`; React uses the same
-contract with `dateRangeVariable`.
+React variables. The server uses `calendar.parseRequest()`; React uses the same
+contract with `dateRangeVariable()`.
 
 ```ts
 import { defineDateRangeContract } from '@altertable/data-app/contract';
@@ -49,7 +49,7 @@ export const calendar = defineDateRangeContract({
 });
 ```
 
-`parseEmptyInput`, `parseTrue`, `parseCount`, and `parseDateRangeInput` validate
+`parseEmptyInput()`, `parseTrue()`, `parseCount()`, and `parseDateRangeInput()` validate
 common inputs and results. `connectionCheck()` defines a bounded connectivity
 operation. A successful connectivity check confirms access; it is not an
 analysis result.
@@ -83,14 +83,14 @@ const router = createMessageRouter(routes, {
 });
 ```
 
-The app defines `parseString` to validate unknown values. `router.dispatch` checks
+The app defines `parseString()` to validate unknown values. `router.dispatch()` checks
 registered routes, input, output, and cancellation. `MessageRoutingError` exposes
 an intentional public code, message, and optional request ID; other handler
 errors are replaced with a generic failure.
 
 `defineDataQueryRoute(operationContracts)` validates the selected operation's
 input and output and preserves its response evidence. It infers the result type
-from the selected operation when used with `createMessageClient`. Share input and
+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;
 generic hosts must delegate operation validation and authorization to their