@altertable/data-app 0.61.0 → 0.63.0

package/docs/embed.md

@@ -6,13 +6,13 @@ app UI stylesheet.
 
 ## Sources
 
-`attachDataAppShell` owns iframe loading, sandbox policy, startup timeout, and
+`attachDataAppBridge()` in source mode 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';
+import { attachDataAppBridge } from '@altertable/data-app/embed';
 
-const dispose = attachDataAppShell({
+const host = attachDataAppBridge({
   iframe,
   source: { type: 'url', url: 'https://apps.example.com/report' },
   onMessage: router.dispatch,
@@ -20,8 +20,8 @@ const dispose = attachDataAppShell({
 ```
 
 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
+Call `host.dispose()` before replacing the source or retrying. A URL source requires HTTP(S)
+and a different origin from its host. The source bridge 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.
@@ -31,24 +31,25 @@ A bundle source has this shape:
 ```ts
 const source = {
   type: 'bundle' as const,
-  bootstrapUrl: 'https://preview.example.com/bootstrap',
+  bootstrapUrl: 'https://my-report-app-1.apps.example.net/',
   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.
+The host provides a self-contained JavaScript bundle. React bridges replace the
+iframe whenever its JavaScript content changes. 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).
+For Cloudflare hosting, upload the [Worker asset](worker.md). It includes the
+bootstrap HTML and security policy; deployments supply the runtime domain and
+trusted parent origins through bindings.
 
-Bundle this initializer into the trusted bootstrap document, before any app code:
+For other hosts that own their HTML and security policy, bundle this initializer
+into the bootstrap document before any app code:
 
 ```ts
 import { startDataAppBootstrap } from '@altertable/data-app/embed';
@@ -59,22 +60,21 @@ const dispose = startDataAppBootstrap({
 ```
 
 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
+session token. Its hosting service must enforce its CSP. The bridge 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`.
+app bundle; non-React apps use `createDataAppNavigation()` from `/client`.
 
 ## Delivery and navigation
 
-`attachDataAppBridge` is the lower-level API for a host-owned iframe. Supply
+`attachDataAppBridge()` also supports connection mode 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
+`onMessage` dispatcher. Both modes use the same transport. It returns `dispose()` and `setPresentation()` methods and owns source/origin checks, request
+correlation, cancellation, bounded pending requests, and reconnection. Use source mode 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.
 
@@ -91,16 +91,84 @@ opaque apps keep that state in memory rather than modifying their document URL.
 `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.
+The source bridge'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.
 
-Message types follow `{scope}:{action}`: `bridge:connect`, `bridge:ready`,
-`bridge:initialize`, `bridge:request`, `bridge:result`, `bridge:error`,
-`bridge:cancel`, `bridge:disconnect`, `runtime:ready`, `runtime:error`,
-`script:load`, and `state:update`. Routed requests use the same convention,
-including `data:query` and `navigation:update`. Hosts, apps, and bootstrap scripts
-must use matching names; the former unscoped and dot-separated names are no
-longer supported.
+## SQL query route
+
+Hosts serving browser-owned operations register `sqlQueryRoute` explicitly:
+
+```ts
+import {
+  createMessageRouter,
+  sqlQueryRoute,
+} from '@altertable/data-app/contract';
+import { createSqlQueryHandler } from '@altertable/data-app/embed';
+
+const router = createMessageRouter(
+  { 'data:sql': sqlQueryRoute },
+  {
+    'data:sql': createSqlQueryHandler(async (query, { signal }) => {
+      return authorizedLakehouseForCurrentViewer(query, signal);
+    }),
+  }
+);
+// Supply router.dispatch as the shell's onMessage handler.
+```
+
+The host supplies `authorizedLakehouseForCurrentViewer()`. Its backend must enforce
+viewer/dataset permissions, permitted query behavior, maximum rows, execution
+time, concurrency, and response size independently of browser policy. Route
+validation is not SQL authorization. `createSqlQueryHandler()` calls authorization
+for each query, forwards cancellation, and preserves `DataSourceError` reasons
+as public `source_*` errors with request IDs. Authorization failures return
+`forbidden`; unknown query errors are hidden. Custom handlers can return deliberate
+public failures with `MessageRoutingError`.
+
+`SqlQueryInput` (exported from `/contract`) carries
+`{ statement: string, limit: number }`; responses are
+`{ columns: { name: string, type?: string }[], rows: unknown[][], queryId?: string }`.
+The route rejects empty statements, unsafe or nonpositive limits, malformed
+results, and results exceeding the requested limit. The bridge's existing payload
+and pending-call limits apply, and cancellation reaches the handler's signal.
+Operation names and inputs stay in the app; query evidence is assembled there.
+
+`dataAppRoutes` retains named `data:query` and navigation routes for existing
+server-backed hosts. SQL hosts opt into `data:sql`; they need no named-operation
+handler unless they also serve HTTP-style apps. Update the host before switching
+an app to browser-owned operations. Older hosts reject `data:sql` as unknown.
+
+## Parent presentation
+
+The parent declares where the iframe is mounted and owns its resolved theme:
+
+```ts
+const host = attachDataAppBridge({
+  iframe,
+  source: { type: 'url', url: 'https://apps.example.com/report' },
+  presentation: { surface: 'embedded', theme: 'dark' },
+  onMessage: router.dispatch,
+});
+
+// Update presentation without replacing the iframe or its bridge session.
+host.setPresentation({ surface: 'embedded', theme: 'light' });
+```
+
+Both source and connection modes support the `presentation` option and
+`host.setPresentation(presentation)` method. `DataAppPresentation` is exported from
+`/embed`. Use `surface: 'embedded'` when the parent provides page chrome, as in the
+Altertable frontend, and `'standalone'` when the app provides its own header and
+footer. `theme` must be resolved to `'light'` or
+`'dark'`; the parent decides how its system preference is resolved.
+
+Presentation travels over `postMessage()` in the authenticated `bridge:initialize` and
+`state:update` messages, alongside `search` and `hash`. Framework-neutral apps
+can narrow the unknown state returned by `bridge.snapshot()` to read its
+`presentation` field, and subscribe through `bridge.subscribe()`. React `<DataApp>` consumes it automatically.
+An embedded surface renders toolbar actions without the page header or footer.
+Both surfaces follow the parent's theme, including presentation mode, without
+changing saved viewer preferences. Omitting presentation preserves standalone behavior;
+`host.setPresentation(undefined)` restores it.

package/docs/hosted-apps.md

@@ -0,0 +1,39 @@
+# Author a data app
+
+Follow the [shared authoring flow](app-authoring.md) using [index.tsx](../examples/starter-data-app/index.tsx) for a hosted / remote / cloud data app. Keep the app in
+one file with public package imports; omit server files, HTML, credentials, and
+relative or app-alias imports.
+
+Replace the sample SQL, parsers, filters, data context, story, and configuration with
+an exploration of the source data you inspected. The starter uses two SQL
+`VALUES` rows, so it needs no production table.
+
+For execution details, see [browser-owned operations](client.md#browser-owned-operations-for-bundle-apps).
+
+## Convert a local data app
+
+1. Combine the app's operations and parsers, data context, views, story,
+   configuration, and browser entry into one `index.tsx`, following the
+   [single-file starter](../examples/starter-data-app/index.tsx).
+2. Replace the HTTP client with `createDataClient({ operations })`, using the
+   operation registry as a value. See [browser-owned operations](client.md#browser-owned-operations-for-bundle-apps)
+   for execution through the host.
+3. Remove the Bun server, HTML, server adapters, credentials, and relative or
+   app-alias imports. Rewrite any operation that depends on server-only code
+   to use the operation's `query()` helper.
+4. Confirm the host can query the same catalogs, tables, and fields.
+   [Verify the app](app-authoring.md#verify-the-app) in the hosted runtime against
+   the local version's filters and findings.
+
+## Preview in this repository
+
+```fish
+bun install --frozen-lockfile
+bun run build
+bun browser-tests/server.ts
+```
+
+Open [the starter preview](http://127.0.0.1:27418/starter-data-app).
+Its test host executes the sample SQL through the iframe bridge using SQLite.
+
+For checks, see [Contributing](../CONTRIBUTING.md).

package/docs/local-data-apps.md

@@ -0,0 +1,14 @@
+# Author a local data app
+
+Start from the CLI scaffold or the [local starter](https://github.com/altertable-ai/data-app/tree/main/examples/starter-local-data-app).
+Use the starter's README for setup and its AGENTS.md to find app-owned files.
+Replace the connectivity screen with the exploration and story from the
+[shared authoring flow](app-authoring.md).
+
+| Task                                    | Documentation                            |
+| --------------------------------------- | ---------------------------------------- |
+| Serve locally with Bun                  | [Bun server](server-bun.md)              |
+| Execute and authorize server operations | [Server](server.md)                      |
+| Call operations from the browser        | [HTTP client](client.md#http-operations) |
+
+You can also [convert the local app to a hosted data app](hosted-apps.md#convert-a-local-data-app).

package/docs/react-embed.md

@@ -1,36 +1,70 @@
 # 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.
+Import `<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
+The bridge owns iframe setup and `postMessage()` communication. The consuming
+frontend or CLI owns its shell: fetching a bundle, subscriptions, layout, loading
+and error UI, and retry controls. Both hosts use the same bridge and transport.
+
+## Source-managed iframe
+
+Use `source` for local URL apps or hosted bundles. The bridge creates the iframe,
+configures its sandbox, loads its source, and reports connection status. It renders
+only the iframe; it adds no loading, error, or retry UI and does not hide the frame.
 
 ```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>}
-/>;
+import { useReducer, useState } from 'react';
+import { DataAppBridge } from '@altertable/data-app/react/embed';
+import type { DataAppStatus } from '@altertable/data-app/embed';
+
+function Shell() {
+  const [status, setStatus] = useState<DataAppStatus>('connecting');
+  const [attempt, retry] = useReducer(value => value + 1, 0);
+
+  return (
+    <div className="app-shell">
+      {status !== 'ready' && status !== 'failed' && <p>Loading report…</p>}
+      {status === 'failed' && <button onClick={retry}>Retry report</button>}
+      <DataAppBridge
+        key={attempt}
+        title="Activity report"
+        source={{ type: 'url', url: 'http://127.0.0.1:25837/' }}
+        onMessage={router.dispatch}
+        onStatusChange={setStatus}
+        iframeProps={{ className: 'app-frame', hidden: status !== 'ready' }}
+      />
+    </div>
+  );
+}
 ```
 
 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 local URL must have a different origin from its shell. For hosted bundles,
+replace `source` with:
+
+```tsx
+source={{ type: 'bundle', bootstrapUrl, javascript }}
+```
+
+The host supplies those bundle values. 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.
+Source URL or JavaScript content changes replace the entire iframe. Change the
+bridge's React `key` to retry with a fresh 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.
+
+`iframeProps` forwards presentation and accessibility attributes to the iframe,
+including `className`, `style`, and `hidden`. The bridge controls `src`, `srcDoc`,
+`sandbox`, `referrerPolicy`, `loading`, and the callback ref. Loading is always
+`eager` so an iframe hidden until ready can start. Supply `title` directly.
 
 ## Host-owned iframe
 
-Use `DataAppBridge` when the host owns iframe rendering:
+Use the same `<DataAppBridge>` with `iframe` and `connection` when the host already
+owns a loaded iframe and its security policy:
 
 ```tsx
 import { useState, type ComponentRef } from 'react';
@@ -52,6 +86,23 @@ function Host() {
 ```
 
 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.
+mounting and replacement; listeners attach to the iframe's owner document. This
+mode renders nothing and handles delivery only. Use source mode for bundle
+loading, sandbox policy, token rotation, and startup timeout. The two prop modes
+are mutually exclusive.
+
+## Loading an embedded app
+
+Use `<DataAppSkeleton>` from `/react` while the host builds or starts an app.
+Call `injectDataAppShellStyles()` from `/react` before rendering the placeholder.
+The host owns when to show it and supplies any surrounding header or footer.
+`/react/embed` itself remains independent of UI components and styles.
+
+## Parent-owned presentation
+
+Pass `presentation={{ surface: 'embedded', theme: resolvedTheme }}`
+to `<DataAppBridge>` in either source or connection mode. Use `'standalone'` when the app should render its own page chrome.
+Prop updates publish trusted state without reloading the iframe or reconnecting
+the session. Resolve system preference in the parent to `'light'` or `'dark'`.
+Inside an embedded surface, `<DataApp>` retains toolbar actions and hides its header
+and footer. See [parent presentation](embed.md#parent-presentation).