@altertable/data-app 0.59.1

package/docs/bootstrap.md

@@ -0,0 +1,76 @@
+# Standalone bootstrap
+
+`@altertable/data-app/bootstrap` resolves to a self-contained classic browser
+script. It has no imports, React dependencies, or app navigation behavior. The
+package builds it once; a backend can embed the published file without running a
+bundler.
+
+This entry is a script asset, not a module API. Resolve and read it on the server;
+do not import it for execution in Node.js or Bun. For a bootstrap you bundle
+yourself, use `startDataAppBootstrap` from [embedding](embed.md).
+
+## Generate the backend HTML
+
+Install an exact package version in the backend runtime's `package.json`, commit
+the lockfile, and run this generation step before building or deploying the worker:
+
+```js
+// scripts/build-runtime.mjs
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+
+const parentOrigin = 'https://app.altertable.ai';
+const path = import.meta.resolve('@altertable/data-app/bootstrap');
+const javascript = await readFile(new URL(path), 'utf8');
+const inline = javascript.replace(/<\/script/gi, '<\\/script');
+const originAttribute = parentOrigin
+  .replaceAll('&', '&amp;')
+  .replaceAll('"', '&quot;')
+  .replaceAll('<', '&lt;')
+  .replaceAll('>', '&gt;');
+
+const html = `<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+  </head>
+  <body>
+    <div id="root"></div>
+    <script data-parent-origin="${originAttribute}">${inline}</script>
+  </body>
+</html>`;
+
+await mkdir('generated', { recursive: true });
+await writeFile(
+  'generated/runtime-html.js',
+  `export const RUNTIME_HTML = ${JSON.stringify(html)};\n`
+);
+```
+
+```fish
+node scripts/build-runtime.mjs
+```
+
+The worker imports `RUNTIME_HTML` and serves it as `text/html; charset=utf-8`.
+The resulting HTML needs no package imports or network fetches at runtime.
+
+## Configuration and security
+
+Use a regular inline `<script>` with `data-parent-origin` on that same element,
+after the app's mount element. The script reads `document.currentScript` and
+starts immediately. Do not use `type="module"`.
+
+The hosting service must supply an exact trusted origin, such as
+`https://app.altertable.ai`, through deployment configuration. Missing or invalid
+origins fail before installing a transport. Do not derive this value from an
+unverified query parameter, referrer, or incoming message.
+
+Serve the HTML with the [bootstrap CSP](embed.md#trusted-bootstrap), including a
+`frame-ancestors` header restricted to the trusted host. The script installs the
+authenticated transport, retains opaque host state, evaluates the app bundle
+sent by the host, and reports readiness or failure. The app attaches its own
+navigation adapter. Backend authorization still applies to every data request.
+
+Upgrade the host package and bootstrap artifact together when changing the bridge
+protocol. See [client navigation](client.md#app-navigation) and
+[embedding](embed.md) for the communication boundaries.

package/docs/client.md

@@ -0,0 +1,127 @@
+# Client
+
+Import `createDataClient` and `DataAppError` from
+`@altertable/data-app/client`. The client uses Fetch APIs and has no React or
+server dependency.
+
+```ts
+import { createDataClient } from '@altertable/data-app/client';
+import type { operations } from './operations';
+
+const client = createDataClient<typeof operations>();
+const response = await client.query('activity', input, { signal });
+```
+
+The app defines `operations`, `input`, and an optional cancellation `signal`.
+Operation input and output types are inferred from the server registry. Keep the
+registry import type-only so its SQL and implementation stay on the server.
+
+The default endpoint is `/api/data`. Override it with
+`createDataClient({ endpoint, fetch })` to change the base URL or supply a Fetch
+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.
+`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).
+
+## 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.
+
+A URL-hosted app configures trust and installs the bridge before mounting:
+
+```ts
+import {
+  createIframeTransport,
+  installDataAppTransport,
+} from '@altertable/data-app/client';
+
+const bridge = createIframeTransport({
+  parentOrigin: 'https://host.example.com',
+});
+const uninstall = installDataAppTransport(bridge);
+```
+
+Use a configured trusted origin, not an unverified URL parameter. Installation makes data clients discover the connection. React mounting and
+URL controls attach the optional navigation adapter to that connection. Cleanup removes
+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:
+
+```ts
+import {
+  createMessageClient,
+  getDataAppTransport,
+} from '@altertable/data-app/client';
+
+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 });
+```
+
+The app supplies shared `routes` and optional `signal`. Both client and host
+validate messages. The bridge retains opaque host state through `snapshot()` and
+`subscribe(listener)`; only authenticated, current-session state reaches subscribers.
+It never changes browser history or interprets the host state.
+
+## App navigation
+
+Navigation is an optional app adapter, separate from bootstrap and data delivery:
+
+```ts
+import { createDataAppNavigation } from '@altertable/data-app/client';
+
+const navigation = createDataAppNavigation({ bridge });
+const currentLocation = navigation.snapshot();
+navigation.update({ search: '?period=last-7', hash: '#daily' }, 'push');
+// If app code changes its URL directly:
+navigation.publish('replace');
+// Before removing the app or its transport:
+navigation.dispose();
+```
+
+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.
+
+`getDataAppNavigation()` discovers an installed or verified local-preview bridge
+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
+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.
+
+A failed local-preview verification can be retried by the next explicit data
+request. Concurrent callers share the current verification attempt; aborting
+one caller does not cancel the others. Retrying does not automatically repeat
+a data operation or bypass the configured parent-origin check, and verification
+failure never falls back to untrusted iframe or HTTP delivery.

package/docs/config.md

@@ -0,0 +1,21 @@
+# App configuration
+
+Import `DataAppConfig` and `dataAppTitle` from `@altertable/data-app/config`.
+Configuration is shared by the app shell and browser mounting code.
+
+```ts
+import type { DataAppConfig } from '@altertable/data-app/config';
+
+export const config = {
+  title: 'Activity',
+  scope: { organization: 'example', environment: 'production' },
+  appearance: {},
+} satisfies DataAppConfig;
+```
+
+`title` names the exploration. `scope` identifies its organization and
+environment for display; it does not grant access to data.
+`appearance` is validated by the [appearance APIs](appearance.md).
+
+`dataAppTitle(config)` produces a document title containing the app title and
+scope. [React mounting](react.md) applies it automatically.

package/docs/contract.md

@@ -0,0 +1,95 @@
+# Contracts
+
+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
+should import their operation types using `import type`.
+
+## Execute named queries
+
+The app supplies `calendar`, `parseActivity`, `checkInput`, `buildActivitySql`,
+and `parseActivityRows` in this example.
+
+```ts
+import {
+  defineOperation,
+  defineQueryNames,
+} from '@altertable/data-app/contract';
+
+const queries = defineQueryNames({ activity: 'feature-activity' });
+const activity = defineOperation({
+  queryNames: queries,
+  input: calendar.parseRequest,
+  output: parseActivity,
+  checks: [checkInput],
+  policy: { maxQueryRows: 100, maxDurationMs: 15000, exposeSql: true },
+  async run({ query }, input) {
+    const result = await query(queries.activity, buildActivitySql(input));
+    return parseActivityRows(result);
+  },
+});
+```
+
+`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.
+
+## Shared date ranges
+
+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`.
+
+```ts
+import { defineDateRangeContract } from '@altertable/data-app/contract';
+
+export const calendar = defineDateRangeContract({
+  minDate: '2026-01-01',
+  maxRangeDays: 90,
+  timeZone: 'UTC',
+});
+```
+
+`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.
+
+See [server authorization](server.md) and [React views](react.md) for the two
+sides of an operation.
+
+## Message routes
+
+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.
+
+```ts
+import {
+  createMessageRouter,
+  defineMessageRoute,
+  navigationUpdateRoute,
+} from '@altertable/data-app/contract';
+import { createNavigationHandler } from '@altertable/data-app/embed';
+
+const routes = {
+  echo: defineMessageRoute({ input: parseString, output: parseString }),
+  'navigation.update': navigationUpdateRoute,
+};
+const router = createMessageRouter(routes, {
+  echo: value => value,
+  'navigation.update': createNavigationHandler(),
+});
+```
+
+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
+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
+server. Request handlers receive `{ signal }` for cancellation.

package/docs/embed.md

@@ -0,0 +1,98 @@
+# Embed a data app
+
+Import framework-neutral host APIs from `@altertable/data-app/embed`. For React
+hosts, see [React embedding](react-embed.md). Neither embedding entry requires the
+app UI stylesheet.
+
+## Sources
+
+`attachDataAppShell` owns iframe loading, sandbox policy, startup timeout, and
+message delivery. The host supplies an iframe and a validated message dispatcher:
+
+```ts
+import { attachDataAppShell } from '@altertable/data-app/embed';
+
+const dispose = attachDataAppShell({
+  iframe,
+  source: { type: 'url', url: 'https://apps.example.com/report' },
+  onMessage: router.dispatch,
+});
+```
+
+The host defines `iframe` and `router`; see [message contracts](contract.md#message-routes).
+Dispose before replacing the source or retrying. A URL source requires HTTP(S)
+and a different origin from its host. The shell adds `__altertable_parent` to the
+app URL. A hosted app must explicitly install a transport to its configured,
+trusted parent origin using the [client API](client.md#iframe-transport).
+The query parameter alone does not establish trust.
+
+A bundle source has this shape:
+
+```ts
+const source = {
+  type: 'bundle' as const,
+  bootstrapUrl: 'https://preview.example.com/bootstrap',
+  javascript: bundle.javascript,
+  revision: bundle.revision,
+};
+```
+
+The host provides a self-contained JavaScript bundle and a revision identifying
+that bundle. Serve the bootstrap page with a CSP compatible with the bundle.
+Bundle mode uses `sandbox="allow-scripts"` and an opaque origin; it cannot read
+the host document or use same-origin privileges. Both modes use
+`referrerPolicy="no-referrer"`.
+
+## Trusted bootstrap
+
+For backend HTML that embeds a ready-made script without bundling, use the
+[standalone bootstrap asset](bootstrap.md).
+
+Bundle this initializer into the trusted bootstrap document, before any app code:
+
+```ts
+import { startDataAppBootstrap } from '@altertable/data-app/embed';
+
+const dispose = startDataAppBootstrap({
+  parentOrigin: 'https://host.example.com',
+});
+```
+
+The bootstrap URL is trusted executable code: it receives the app script and
+session token. Its hosting service must enforce its CSP. The shell cannot impose
+CSP on a remote response. A starting policy for self-contained scripts and styles
+is `default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline';
+img-src data: blob:; connect-src 'none'; base-uri 'none'; form-action 'none'`.
+The initializer installs a shared transport before evaluating the app script;
+data clients discover it even when independently bundled. The bootstrap contains
+no app navigation adapter. React mounting or URL controls attach navigation in the
+app bundle; non-React apps use `createDataAppNavigation` from `/client`.
+
+## Delivery and navigation
+
+`attachDataAppBridge` is the lower-level API for a host-owned iframe. Supply
+`connection: { type: 'origin', origin }` or `{ type: 'opaque', token }`, and an
+`onMessage` dispatcher. It returns cleanup and owns source/origin checks, request
+correlation, cancellation, bounded pending requests, and reconnection. Use the
+shell for bundle loading and token rotation. The opaque destination requires
+wildcard delivery, but incoming messages still require the exact iframe window,
+null origin, token, document, and session to match.
+
+`createNavigationHandler({ window, reservedSearchParams })` handles the shared
+`navigation.update` route using browser history. Reserved host query parameters
+survive app changes. Supply your own handler when integrating a framework router.
+Host Back/Forward events publish opaque host state through the bridge. The app's
+optional navigation adapter interprets search/hash and synchronizes controls;
+opaque apps keep that state in memory rather than modifying their document URL.
+
+## Status and diagnostics
+
+`onStatusChange` receives `connecting`, `connected`, `ready`, `failed`, or
+`disconnected`. `connected` means transport initialization; `ready` means a URL
+client acknowledged initialization or a bundle script finished evaluation. It
+does not mean asynchronous data queries finished. Script errors report `failed`.
+The shell's `startupTimeoutMs` defaults to 30 seconds.
+
+`onDiagnostic` receives only message `direction` and `type`, never tokens or
+payloads. Routed handlers must authorize every data request. Message validation
+and iframe isolation do not grant access to data or execute SQL.

package/docs/format.md

@@ -0,0 +1,29 @@
+# Formatting
+
+Import number and date helpers from `@altertable/data-app/format`. They use
+JavaScript `Intl` APIs and can run in the browser or on the server.
+
+```ts
+import {
+  formatCount,
+  formatDateRange,
+  formatNumber,
+  formatPercent,
+} from '@altertable/data-app/format';
+
+formatCount(1200); // "1,200"
+formatPercent(0.116); // "11.6%"
+formatNumber(null); // "—"
+formatDateRange({ start: '2026-01-01', end: '2026-01-03' });
+```
+
+Percent values are ratios: `0.116` means 11.6%. Counts must be non-negative
+integers. Missing or non-finite numbers render as `—`, customizable with
+`missing`. Number formatting defaults to `en-US`; pass `locale` to override it.
+
+`formatMetric` accepts a `MetricFormat` with `kind: 'count'`, `'ratio'`, or
+`'currency'`; currency formats also require a currency code. `formatDateRange`
+formats ISO calendar dates in UTC and retains the year in its labels.
+`pluralize(count, singular, plural?)` selects a label for the count.
+
+See [React metric definitions](react.md#bound-views-and-widgets).

package/docs/react-embed.md

@@ -0,0 +1,57 @@
+# React embedding
+
+Import `DataAppShell` and `DataAppBridge` from
+`@altertable/data-app/react/embed`. This entry depends on React and the embedding
+engine, and does not load the app's widgets, React Query, or CSS.
+
+## Shell
+
+```tsx
+import { DataAppShell } from '@altertable/data-app/react/embed';
+
+<DataAppShell
+  title="Activity report"
+  source={{ type: 'url', url: 'https://apps.example.com/activity' }}
+  onMessage={router.dispatch}
+  loading={<p>Loading report…</p>}
+  renderError={retry => <button onClick={retry}>Retry report</button>}
+/>;
+```
+
+The host supplies `router` using [message contracts](contract.md#message-routes).
+For bundles, use `{ type: 'bundle', bootstrapUrl, javascript, revision }` as
+`source`. See [embedding](embed.md) for trust, sandbox, CSP, and bootstrap setup.
+
+The shell creates and owns the iframe. Source changes, bundle revision changes,
+and retries replace the entire frame. Handler changes use the latest callbacks
+without resetting the session. `startupTimeoutMs`, `onStatusChange`, and
+`onDiagnostic` have the same meaning as in the framework-neutral API. The iframe
+remains hidden until ready; loading and error UI have sensible defaults.
+
+## Host-owned iframe
+
+Use `DataAppBridge` when the host owns iframe rendering:
+
+```tsx
+import { useState, type ComponentRef } from 'react';
+import { DataAppBridge } from '@altertable/data-app/react/embed';
+
+function Host() {
+  const [iframe, setIframe] = useState<ComponentRef<'iframe'> | null>(null);
+  return (
+    <>
+      <iframe ref={setIframe} title="Report" src={appUrl} />
+      <DataAppBridge
+        iframe={iframe}
+        connection={{ type: 'origin', origin: new URL(appUrl).origin }}
+        onMessage={router.dispatch}
+      />
+    </>
+  );
+}
+```
+
+The app supplies `appUrl` and `router`. A callback ref lets the bridge observe late
+mounting and replacement; listeners attach to the iframe's owner document. The
+bridge handles delivery only. Use `DataAppShell` to manage source loading,
+sandbox policy, bundle tokens, and startup errors.

package/docs/react-styles.md

@@ -0,0 +1,17 @@
+# React styles
+
+Import the stylesheet once from the browser entry:
+
+```ts
+import '@altertable/data-app/react/styles.css';
+```
+
+This entry is a CSS asset, with a declaration for TypeScript side-effect imports.
+The app's bundler must process CSS imports. The React JavaScript entry does not
+load it automatically, so server rendering can import components without
+importing CSS into Node.
+
+Stylesheets live beside their components in `src/react/ui` and are combined into
+the published stylesheet during the build. Brand settings install semantic CSS
+variables through [appearance](appearance.md); the [React app shell](react.md)
+manages these for normal app usage.