@altertable/data-app 0.59.1 → 0.62.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,7 +60,7 @@ 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'`.
@@ -70,16 +71,15 @@ 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, setPresentation }` 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.
 
 `createNavigationHandler({ window, reservedSearchParams })` handles the shared
-`navigation.update` route using browser history. Reserved host query parameters
+`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;
@@ -91,8 +91,103 @@ 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` and `/embed`) 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` and `/client`. 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.
+
+The host attachment is an explicit `{ dispose, setPresentation }` object. Replace
+former cleanup calls (`dispose()`) with `host.dispose()`. React hosts manage this
+lifecycle automatically.
+
+## Migration
+
+`attachDataAppShell` and `DataAppShellOptions` have been removed. Use
+`attachDataAppBridge` with the same source options and `DataAppBridgeOptions`.
+Source and connection options are mutually exclusive. The frontend and CLI own
+their shell UI; this package provides iframe bridges only.

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:
 
-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.
+```tsx
+source={{ type: 'bundle', bootstrapUrl, javascript }}
+```
+
+The host supplies those bundle values. See [embedding](embed.md) for trust,
+sandbox, CSP, and bootstrap setup.
+
+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,32 @@ 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.
+
+## Migration from the package shell
+
+`DataAppShell` and `DataAppShellProps` have been removed. Replace the import with
+`DataAppBridge` and keep `source`, `title`, and message/status callbacks. Move
+`loading` and `renderError` into the consuming shell, use `iframeProps.hidden` to
+control visibility, and change the bridge's key for retries. Frontend bundle
+fetching and subscriptions and CLI local-server forwarding remain host concerns.
+
+## Loading placeholder
+
+For a shared placeholder while building or connecting, render `DataAppSkeleton`
+from `@altertable/data-app/react` in the consuming shell. Import
+`@altertable/data-app/react/styles.css` once in that host's browser entry. See
+[React](react.md#loading-an-embedded-app) for usage. The bridge does not render
+loading UI itself.
+
+## 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).

package/docs/react.md

@@ -28,6 +28,34 @@ All of these APIs are exported from `/react`. Each component's stylesheet lives
 | Present loaded findings                           | [PresentStory](https://github.com/altertable-ai/data-app/blob/main/src/react/ui/PresentStory.tsx)                                                                                                                | StoryFinding                                                                                                                                                                                                                                       |
 | Build custom controls and overlays                | [Button](https://github.com/altertable-ai/data-app/blob/main/src/react/ui/Button.tsx), [Sheet](https://github.com/altertable-ai/data-app/blob/main/src/react/ui/Sheet.tsx)                                       | IconButton, Tooltip, HelpPopover, Kbd                                                                                                                                                                                                              |
 
+## Loading an embedded app
+
+`DataAppSkeleton` is a host-side placeholder while an embedded app is building or
+starting. It composes the shared metric, visualization, and data widgets with
+skeleton content: three metric cards, a chart, and table rows. Optional `header`
+and `footer` React nodes let the host supply its own layout; neither renders by
+default.
+It adapts to container width and inherits the package's appearance variables and
+reduced-motion skeleton animation.
+
+```tsx
+import { DataAppSkeleton } from '@altertable/data-app/react';
+import '@altertable/data-app/react/styles.css';
+
+<DataAppSkeleton
+  aria-label="Loading activity report"
+  className="app-loading"
+  header={<ReportHeaderSkeleton />}
+  footer={<ReportFooterSkeleton />}
+/>;
+```
+
+The container announces a loading status; its widget placeholders are hidden from
+assistive technology. Supplied header and footer nodes remain accessible and can
+use the exported `Skeleton` component for their own placeholders. Standard output props, including `style` and `ref`, can be used
+for layout. The consuming shell controls when to display it. The `/react/embed`
+entry remains independent of UI components and the stylesheet.
+
 ## Bound views and widgets
 
 | Definition        | Runtime owns                                                                                                                                     |
@@ -224,6 +252,18 @@ zero counts. `SelectableBarChart` can share controlled selection with the picker
 inspection sheets render the same visual and controls. Keep interactive state
 above both mounts when authoring custom children.
 
+Widget headings open inspection when evidence is available; a disclosure arrow
+appears beside the heading on hover or keyboard focus. The top-end toolbar is
+reserved for actions and request status. Empty widgets omit their footer, charts
+omit interaction instructions without data, and table pagination appears only
+when there is more than one page. Local `DataBoundary` and `DataSection` inline
+notices sit above retained section content; use widget status for widget feedback
+and page controls or notices for page feedback.
+
+Combobox search text aligns with option labels. Empty search inputs blur on
+Escape; a second Escape dismisses an open picker. Picker failures show a centered
+message with the retry action below it.
+
 `DataApp.story` receives the displayed snapshot, including its original input
 during refresh or failure. Return one to four `StoryFinding` values with unique
 IDs and registered evidence. `PresentStory` presents those findings directly;
@@ -246,3 +286,14 @@ and phone interactions. Fixtures are excluded from the published package.
 Previous data and evidence are retained only when the input changes within the
 same operation. Switching to another operation shows its own cached response or
 an initial loading/error state; it never inherits another operation's result.
+
+Operation and facet caches are scoped to the `DataClient` instance. Hooks created
+from the same client share queries; separate clients do not share results, stale
+data, or cancellation even under one provider. Keep client instances stable
+across renders to preserve their cache.
+
+When a trusted parent supplies [parent presentation](embed.md#parent-presentation),
+`DataApp` follows its resolved theme and suppresses local theme controls,
+including in presentations. On an embedded surface (`surface: 'embedded'`),
+only toolbar actions remain above the app body; the title, scope, description, and
+footer are omitted. Variables and request states remain available.

package/docs/releasing.md

@@ -37,6 +37,11 @@ The manifest starts at the imported runtime version `0.59.1`. This records the
 version baseline, not a claim that it is published. Release Please computes the
 next version from release-relevant commits on `main`.
 
+While the package is below `1.0.0`, breaking changes bump the minor version via
+`bump-minor-pre-major`. Features also bump the minor version, and fixes bump the
+patch version. Breaking changes remain documented in release notes. Remove this
+option when preparing the first stable `1.0.0` release.
+
 ## Release flow
 
 1. Merge Conventional Commits into `main`.

package/docs/server-bun.md

@@ -24,3 +24,8 @@ Missing credentials fail the query. Keep these variables out of browser code.
 Local serving permits SQL disclosure and does not authenticate hosted viewers.
 Use [the portable server handler](server.md) with per-request authorization when
 hosting an app for other people.
+
+The local adapter validates NDJSON metadata, optional string or typed column
+headers, and array rows before returning a result. Query IDs must be strings.
+Rows must match the column count when a header is present; headerless array rows
+remain supported with empty column metadata. Empty results remain valid.

package/docs/starter-agent-instructions.md

@@ -47,5 +47,7 @@ interactions at phone and desktop widths, including loading, empty, error, and
 stale states. Verify that the exploration answers the user's question.
 ```
 
-The CLI's existing starter remains owned by its repository. Updating its template
-and checks to consume the published package is a separate migration.
+A runnable port of the CLI starter lives in
+[`examples/starter`](https://github.com/altertable-ai/data-app/tree/main/examples/starter). It consumes the built public
+package and keeps its own app instructions. Updating CLI scaffolding to consume
+the published package remains a separate migration.

package/docs/worker.md

@@ -0,0 +1,57 @@
+# Cloudflare Worker asset
+
+`@altertable/data-app/worker` resolves to a precompiled, self-contained ESM Worker
+script. Upload this one file as the deployment's main module. It includes the
+bootstrap and HTML; no bundling, HTML generation,
+runtime imports, or asset fetches are needed in the hosting backend.
+
+This export is a script asset, not a Node.js or Bun API. Pin an exact package
+version and commit the lockfile. Resolve and read the installed asset, then pass
+its contents to your deployment tooling:
+
+```js
+import { readFile } from 'node:fs/promises';
+
+const workerScript = await readFile(
+  new URL(import.meta.resolve('@altertable/data-app/worker')),
+  'utf8'
+);
+// Upload workerScript as worker.js, with main_module = "worker.js".
+```
+
+The hosting backend retains ownership of domains, routes, deployment settings,
+and these string bindings:
+
+| Binding          | Meaning                                                                    | Example                                                 |
+| ---------------- | -------------------------------------------------------------------------- | ------------------------------------------------------- |
+| `DOMAIN_NAME`    | Runtime domain without scheme, port, or trailing dot                       | `apps.example.net`                                      |
+| `PARENT_ORIGINS` | Space-separated trusted HTTP(S) origins; first exact origin is the default | `https://app.example.com https://*.preview.example.com` |
+
+The Worker serves only `/` on a single preview label under `DOMAIN_NAME` matching
+`/^(?=.{1,63}$)[a-z0-9]+(?:-[a-z0-9]+)+-app-[1-9][0-9]*$/`. Other hosts and paths
+return 404. GET returns HTML; HEAD returns the same headers with no body. Other
+methods return 405 with `Allow: GET, HEAD`.
+
+`__altertable_parent` selects an **exact** parent origin only after validation
+against `PARENT_ORIGINS`. It cannot add trust. HTTPS wildcard entries allow one
+subdomain label, without a port, for staging previews. Their apex and deeper
+subdomains are rejected. Exact origins cannot contain paths, trailing slashes,
+credentials, queries, or fragments. Invalid, duplicate, or unapproved selections
+return 403. Missing or invalid origin configuration returns 503; an absent
+selection requires an exact default origin. Referrers and messages never supply
+trust.
+
+The package owns the unstyled HTML (`#root` followed by an inline classic script),
+attribute and script escaping, restrictive CSP with configured `frame-ancestors`,
+`no-referrer`, and `nosniff`. App scripts load through the authenticated
+`altertable:data-app` bridge and retain opaque host state. Apps own styling and
+navigation. Bundle apps execute their operation registry in the browser and send
+SQL through the [host query route](embed.md#sql-query-route); the Worker does not
+resolve operation names or execute queries. Data requests require backend authorization.
+
+If Terraform reads a file, copy the resolved `/worker` asset unchanged to that
+file during deployment preparation. Configure `DOMAIN_NAME`, `PARENT_ORIGINS`,
+domains, routes, and deployment settings in Terraform. Upgrade the host package
+and Worker together for protocol changes.
+Custom hosts that bundle their own bootstrap can use `startDataAppBootstrap` from
+[/embed](embed.md#trusted-bootstrap).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@altertable/data-app",
-  "version": "0.59.1",
+  "version": "0.62.0",
   "description": "Contracts, transport, and React UI for Altertable data apps",
   "keywords": [
     "altertable",
@@ -22,6 +22,9 @@
     "type": "git",
     "url": "git+https://github.com/altertable-ai/data-app.git"
   },
+  "workspaces": [
+    "examples/starter"
+  ],
   "files": [
     "dist",
     "docs",
@@ -71,8 +74,8 @@
       "types": "./dist/types/embed/index.d.ts",
       "import": "./dist/embed/index.js"
     },
-    "./bootstrap": {
-      "default": "./dist/bootstrap.js"
+    "./worker": {
+      "default": "./dist/worker.js"
     },
     "./react/embed": {
       "types": "./dist/types/react/embed/index.d.ts",
@@ -90,11 +93,12 @@
     "format": "oxfmt .",
     "format:check": "oxfmt --check .",
     "test": "bun test ./tests",
-    "check": "bun run typecheck && bun run lint && bun run format:check && bun run test && bun run build && bun run test:package",
+    "check": "bun run build && bun run typecheck && bun run lint && bun run format:check && bun run test && bun run test:package && bun run test:starter",
     "test:package": "bun run scripts/check-package.ts",
     "check:workflows": "bash scripts/check-workflows.sh",
     "test:browser": "playwright test --config browser-tests/playwright.config.ts",
-    "lint:fix": "oxlint --type-aware --fix src tests scripts browser-tests"
+    "lint:fix": "oxlint --type-aware --fix src tests scripts browser-tests",
+    "test:starter": "bun run scripts/check-starter.ts"
   },
   "dependencies": {
     "@floating-ui/react": "0.27.20",

package/dist/chunks/contract-14vxdcrs.js.map

@@ -1,10 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../src/core/appearance.ts"],
-  "sourcesContent": [
-    "/**\n * Brand settings; parsing is portable, while theme application requires the browser.\n * @module @altertable/data-app/appearance\n * @see https://github.com/altertable-ai/data-app/blob/main/docs/appearance.md\n */\nimport { invariant } from '@/src/core/invariant';\n\nexport type AppearanceSettings = {\n  mode: 'light' | 'dark' | 'system';\n  baseColor: 'neutral' | 'slate' | 'warm';\n  accentColor: string;\n  darkAccentColor?: string;\n  chartColors: string[];\n  density: 'compact' | 'comfortable' | 'spacious';\n  cornerRadius: 'none' | 'small' | 'medium' | 'large';\n  elevation: 'flat' | 'subtle' | 'raised';\n  typography: { body: string; heading: string };\n};\n\nexport type ThemeMode = AppearanceSettings['mode'];\n\nexport type ThemeController = {\n  getMode: () => ThemeMode;\n  setMode: (mode: ThemeMode) => void;\n  subscribe: (listener: () => void) => () => void;\n};\n\nconst defaults: AppearanceSettings = {\n  mode: 'light',\n  baseColor: 'neutral',\n  accentColor: '#405d47',\n  darkAccentColor: '#a6c4ad',\n  chartColors: [\n    '#285fc0',\n    '#a95319',\n    '#147862',\n    '#7243aa',\n    '#aa3958',\n    '#475569',\n  ],\n  density: 'comfortable',\n  cornerRadius: 'medium',\n  elevation: 'subtle',\n  typography: { body: 'system', heading: 'system' },\n};\n\nfunction record(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\nfunction oneOf<T extends string>(\n  value: unknown,\n  options: readonly T[]\n): value is T {\n  return typeof value === 'string' && options.includes(value as T);\n}\n\nfunction color(value: unknown): value is string {\n  return typeof value === 'string' && /^#[0-9a-fA-F]{6}$/.test(value);\n}\n\nfunction font(value: unknown): value is string {\n  return (\n    typeof value === 'string' &&\n    value.length > 0 &&\n    value.length <= 120 &&\n    !/[;{}()]/.test(value)\n  );\n}\n\nexport function parseAppearance(value: unknown): AppearanceSettings {\n  if (value === undefined)\n    return {\n      ...defaults,\n      chartColors: [...defaults.chartColors],\n      typography: { ...defaults.typography },\n    };\n  invariant(\n    record(value) &&\n      Object.keys(value).every(key =>\n        [\n          'mode',\n          'baseColor',\n          'accentColor',\n          'darkAccentColor',\n          'chartColors',\n          'density',\n          'cornerRadius',\n          'elevation',\n          'typography',\n        ].includes(key)\n      ),\n    'Invalid appearance settings.'\n  );\n  const typography = value.typography;\n  const validFields =\n    (value.mode === undefined ||\n      oneOf(value.mode, ['light', 'dark', 'system'])) &&\n    (value.baseColor === undefined ||\n      oneOf(value.baseColor, ['neutral', 'slate', 'warm'])) &&\n    (value.accentColor === undefined || color(value.accentColor)) &&\n    (value.darkAccentColor === undefined || color(value.darkAccentColor)) &&\n    (value.chartColors === undefined ||\n      (Array.isArray(value.chartColors) &&\n        value.chartColors.length >= 1 &&\n        value.chartColors.length <= 8 &&\n        value.chartColors.every(color))) &&\n    (value.density === undefined ||\n      oneOf(value.density, ['compact', 'comfortable', 'spacious'])) &&\n    (value.cornerRadius === undefined ||\n      oneOf(value.cornerRadius, ['none', 'small', 'medium', 'large'])) &&\n    (value.elevation === undefined ||\n      oneOf(value.elevation, ['flat', 'subtle', 'raised'])) &&\n    (typography === undefined ||\n      (record(typography) &&\n        Object.keys(typography).every(\n          key => key === 'body' || key === 'heading'\n        ) &&\n        (typography.body === undefined || font(typography.body)) &&\n        (typography.heading === undefined || font(typography.heading))));\n  invariant(validFields, 'Invalid appearance settings.');\n\n  return {\n    mode: (value.mode ?? defaults.mode) as AppearanceSettings['mode'],\n    baseColor: (value.baseColor ??\n      defaults.baseColor) as AppearanceSettings['baseColor'],\n    accentColor: (value.accentColor ?? defaults.accentColor) as string,\n    darkAccentColor: (value.darkAccentColor ??\n      (value.accentColor === undefined\n        ? defaults.darkAccentColor\n        : undefined)) as string | undefined,\n    chartColors: (value.chartColors ?? defaults.chartColors) as string[],\n    density: (value.density ??\n      defaults.density) as AppearanceSettings['density'],\n    cornerRadius: (value.cornerRadius ??\n      defaults.cornerRadius) as AppearanceSettings['cornerRadius'],\n    elevation: (value.elevation ??\n      defaults.elevation) as AppearanceSettings['elevation'],\n    typography: {\n      body:\n        record(typography) && typeof typography.body === 'string'\n          ? typography.body\n          : defaults.typography.body,\n      heading:\n        record(typography) && typeof typography.heading === 'string'\n          ? typography.heading\n          : defaults.typography.heading,\n    },\n  };\n}\n\nconst palettes = {\n  neutral: {\n    light: ['#ffffff', '#ffffff', '#f6f7f7', '#202124', '#687078', '#e3e6e8'],\n    dark: ['#151719', '#202326', '#292d31', '#f2f3f4', '#aeb5bc', '#3b4248'],\n  },\n  slate: {\n    light: ['#f8fafc', '#ffffff', '#f1f5f9', '#17212f', '#607083', '#dce3ea'],\n    dark: ['#111820', '#1b2530', '#263340', '#f0f4f8', '#a8b5c3', '#3a4857'],\n  },\n  warm: {\n    light: ['#fbfaf8', '#ffffff', '#f5f2ed', '#292723', '#736e66', '#e8e2da'],\n    dark: ['#1b1916', '#25221e', '#302c27', '#f5f1eb', '#bcb3a8', '#494239'],\n  },\n} as const;\n\nconst spaces = {\n  compact: ['4px', '8px', '12px', '18px', '24px'],\n  comfortable: ['5px', '10px', '16px', '24px', '32px'],\n  spacious: ['6px', '12px', '20px', '30px', '40px'],\n} as const;\n\nconst radii = {\n  none: ['0px', '0px', '0px'],\n  small: ['4px', '7px', '9px'],\n  medium: ['7px', '12px', '16px'],\n  large: ['10px', '18px', '24px'],\n} as const;\n\nfunction fontStack(family: string): string {\n  return family === 'system'\n    ? \"-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, ui-sans-serif, sans-serif\"\n    : `${JSON.stringify(family)}, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, ui-sans-serif, sans-serif`;\n}\n\n/**\n * Install semantic tokens on the document root, including portaled UI. Returns a cleanup for\n * system-theme listening.\n */\nexport function applyAppearance(value: unknown): () => void {\n  const settings = parseAppearance(value);\n  const root = document.documentElement;\n  const preference = window.matchMedia('(prefers-color-scheme: dark)');\n  const [xs, sm, md, lg, xl] = spaces[settings.density];\n  const [control, surface, overlay] = radii[settings.cornerRadius];\n  const tokens: Record<string, string> = {\n    '--at-font': fontStack(settings.typography.body),\n    '--at-font-heading': fontStack(settings.typography.heading),\n    '--at-space-xs': xs,\n    '--at-space-sm': sm,\n    '--at-space-md': md,\n    '--at-space-lg': lg,\n    '--at-space-xl': xl,\n    '--at-layout-gap': `clamp(${md}, 2.5vw, ${lg})`,\n    '--at-radius-control': control,\n    '--at-radius-surface': surface,\n    '--at-radius-overlay': overlay,\n    '--at-shadow-overlay':\n      settings.elevation === 'flat'\n        ? 'none'\n        : settings.elevation === 'raised'\n          ? '0 24px 72px rgb(0 0 0 / 24%)'\n          : '0 18px 50px rgb(0 0 0 / 16%)',\n    '--at-shadow-surface':\n      settings.elevation === 'flat'\n        ? 'none'\n        : settings.elevation === 'raised'\n          ? '0 8px 28px rgb(20 28 40 / 10%)'\n          : '0 3px 16px rgb(20 28 40 / 5%)',\n  };\n\n  function applyColors(): void {\n    const dark =\n      settings.mode === 'dark' ||\n      (settings.mode === 'system' && preference.matches);\n    const [background, surfaceColor, subtle, text, muted, border] =\n      palettes[settings.baseColor][dark ? 'dark' : 'light'];\n    const accent = dark\n      ? (settings.darkAccentColor ??\n        `color-mix(in srgb, ${settings.accentColor} 50%, white)`)\n      : settings.accentColor;\n    settings.chartColors.forEach((chartColor, index) => {\n      tokens[`--at-chart-${index + 1}`] = dark\n        ? `color-mix(in srgb, ${chartColor} 60%, white)`\n        : chartColor;\n    });\n    Object.assign(tokens, {\n      '--at-background': background,\n      '--at-surface': surfaceColor,\n      '--at-subtle': subtle,\n      '--at-text': text,\n      '--at-muted': muted,\n      '--at-border': border,\n      '--at-accent': accent,\n      '--at-focus-color': muted,\n      '--at-control-hover-border': `color-mix(in srgb, ${muted} 45%, ${border})`,\n      '--at-accent-hover': `color-mix(in srgb, ${accent} 80%, ${dark ? 'white' : 'black'})`,\n      '--at-accent-subtle': `color-mix(in srgb, ${accent} ${dark ? 22 : 12}%, ${surfaceColor})`,\n      '--at-on-accent': dark ? background : '#ffffff',\n      '--at-danger': dark ? '#f97066' : '#b42318',\n      '--at-backdrop': dark ? 'rgb(0 0 0 / 55%)' : 'rgb(15 23 30 / 22%)',\n      '--at-code-surface': dark ? '#242a31' : '#f4f6f9',\n      '--at-code-text': dark ? '#e5e9ef' : '#273242',\n    });\n    root.style.colorScheme = dark ? 'dark' : 'light';\n    for (const [name, token] of Object.entries(tokens))\n      root.style.setProperty(name, token);\n  }\n  applyColors();\n  if (settings.mode === 'system')\n    preference.addEventListener('change', applyColors);\n\n  return () => {\n    preference.removeEventListener('change', applyColors);\n  };\n}\n\n/** Viewer color mode persists independently of app-authored brand tokens. */\nexport function createThemeController(value: unknown): ThemeController {\n  const settings = parseAppearance(value);\n  const storageKey = 'altertable.data-app.theme-mode';\n  let mode = settings.mode;\n  try {\n    const saved = window.localStorage.getItem(storageKey);\n    if (oneOf(saved, ['light', 'dark', 'system'])) mode = saved;\n  } catch {\n    // Storage can be unavailable in private browsing or embedded contexts.\n  }\n  let stopAppearance = applyAppearance({ ...settings, mode });\n  const listeners = new Set<() => void>();\n\n  return {\n    getMode() {\n      return mode;\n    },\n    setMode(nextMode) {\n      if (nextMode === mode) return;\n      stopAppearance();\n      mode = nextMode;\n      stopAppearance = applyAppearance({ ...settings, mode });\n      try {\n        window.localStorage.setItem(storageKey, mode);\n      } catch {\n        // The selection still applies to this page.\n      }\n      listeners.forEach(listener => listener());\n    },\n    subscribe(listener) {\n      listeners.add(listener);\n\n      return () => listeners.delete(listener);\n    },\n  };\n}\n"
-  ],
-  "mappings": "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",
-  "debugId": "88E94DEE7384735E64756E2164756E21",
-  "names": []
-}

package/dist/chunks/contract-jksbmt5q.js.map

@@ -1,10 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../src/core/messages.ts"],
-  "sourcesContent": [
-    "import type { TransportResponse } from '@/src/core/bridge';\nimport type { DisclosedQuery } from '@/src/core/contract';\n\nexport type MessageContext = { signal: AbortSignal };\nexport type RoutedMessage = { route: string; payload: unknown };\nexport type MessageDispatcher = (\n  message: unknown,\n  context: MessageContext\n) => Promise<unknown>;\nexport type MessageTransport = (\n  message: RoutedMessage,\n  signal?: AbortSignal\n) => Promise<unknown>;\nexport type MessageRoute<Input, Output> = {\n  input: (value: unknown) => Input;\n  output: (value: unknown, input: Input) => Output;\n};\nexport type MessageRoutes = Record<\n  string,\n  {\n    input: (value: unknown) => unknown;\n    output: (value: unknown, input: never) => unknown;\n  }\n>;\nexport type MessageInput<Route extends MessageRoutes[string]> = ReturnType<\n  Route['input']\n>;\nexport type MessageHandlers<Routes extends MessageRoutes> = {\n  [Name in keyof Routes]: (\n    payload: MessageInput<Routes[Name]>,\n    context: MessageContext\n  ) =>\n    | ReturnType<Routes[Name]['output']>\n    | Promise<ReturnType<Routes[Name]['output']>>;\n};\n\n// A bootstrap and its app may bundle independent copies in the same window.\nconst errorBrand = Symbol.for('@altertable/data-app/MessageRoutingError');\n\n/** Only these deliberate, public failures cross the message boundary. Other errors stay private. */\nexport class MessageRoutingError extends Error {\n  readonly [errorBrand] = true;\n\n  static [Symbol.hasInstance](value: unknown): boolean {\n    return (\n      value instanceof Error &&\n      (value as { [errorBrand]?: unknown })[errorBrand] === true\n    );\n  }\n\n  constructor(\n    public readonly code: string,\n    message: string,\n    public readonly requestId?: string\n  ) {\n    super(message);\n    this.name = 'MessageRoutingError';\n  }\n}\n\nexport function defineMessageRoute<Input, Output>(\n  route: MessageRoute<Input, Output>\n): MessageRoute<Input, Output> {\n  return route;\n}\n\n/** Contracts are shared; handlers are supplied by the host and never belong in the app bundle. */\nexport function createMessageRouter<const Routes extends MessageRoutes>(\n  routes: Routes,\n  handlers: MessageHandlers<NoInfer<Routes>>\n) {\n  const registered = new Map(\n    Object.entries(routes).map(([name, contract]) => {\n      const handler = handlers[name];\n      if (!name || name.length > 256 || typeof handler !== 'function')\n        throw new Error(\n          'Each message route requires a handler and a bounded name.'\n        );\n\n      return [name, { contract, handler }] as const;\n    })\n  );\n\n  async function dispatch(\n    value: unknown,\n    context: MessageContext\n  ): Promise<unknown> {\n    if (\n      !value ||\n      typeof value !== 'object' ||\n      typeof (value as RoutedMessage).route !== 'string'\n    )\n      throw new MessageRoutingError(\n        'invalid_message',\n        'Invalid routed message.'\n      );\n    const message = value as RoutedMessage;\n    const entry = registered.get(message.route);\n    if (!entry)\n      throw new MessageRoutingError('unknown_route', 'Unknown message route.');\n    let payload: unknown;\n    try {\n      payload = entry.contract.input(message.payload);\n    } catch {\n      throw new MessageRoutingError(\n        'invalid_payload',\n        'Invalid message payload.'\n      );\n    }\n    context.signal.throwIfAborted();\n    let result: unknown;\n    try {\n      result = await entry.handler(payload as never, context);\n    } catch (error) {\n      if (context.signal.aborted) throw context.signal.reason;\n      if (error instanceof MessageRoutingError) throw error;\n      throw new MessageRoutingError(\n        'request_failed',\n        'The message request failed. Retry the request.'\n      );\n    }\n    context.signal.throwIfAborted();\n    try {\n      return entry.contract.output(result, payload as never);\n    } catch (error) {\n      if (error instanceof MessageRoutingError) throw error;\n      throw new MessageRoutingError(\n        'invalid_response',\n        'Invalid message response.'\n      );\n    }\n  }\n\n  return { dispatch };\n}\n\nexport type OperationContracts = Record<\n  string,\n  {\n    input: (value: unknown) => unknown;\n    output: (value: unknown) => unknown;\n  }\n>;\nexport type DataQueryInput<Operations extends OperationContracts> = {\n  [Name in keyof Operations & string]: {\n    operation: Name;\n    input: ReturnType<Operations[Name]['input']>;\n  };\n}[keyof Operations & string];\nexport type DataQueryBody<Output> = {\n  data: Output;\n  requestId: string;\n  queriedAt: string;\n  queryIds: string[];\n  queries?: DisclosedQuery[];\n};\nexport type DataQueryRoute<Operations extends OperationContracts> =\n  MessageRoute<DataQueryInput<Operations>, TransportResponse> & {\n    operations: Operations | undefined;\n  };\nexport type MessageOutput<Route extends MessageRoutes[string], Input> =\n  Route extends DataQueryRoute<infer Operations>\n    ? Input extends { operation: infer Name extends keyof Operations }\n      ? {\n          status: number;\n          body: DataQueryBody<ReturnType<Operations[Name]['output']>>;\n        }\n      : never\n    : ReturnType<Route['output']>;\n\n/** Omit contracts only in generic hosts such as the CLI shell, where Bun validates operations. */\nexport function defineDataQueryRoute<\n  Operations extends OperationContracts = OperationContracts,\n>(operations?: Operations): DataQueryRoute<Operations> {\n  return {\n    operations,\n    input(value) {\n      if (!value || typeof value !== 'object')\n        throw new Error('Invalid query.');\n      const request = value as { operation?: unknown; input?: unknown };\n      if (\n        typeof request.operation !== 'string' ||\n        !request.operation ||\n        request.operation.length > 256 ||\n        request.operation.includes('/')\n      )\n        throw new Error('Invalid operation.');\n      const operation =\n        operations && Object.hasOwn(operations, request.operation)\n          ? operations[request.operation]\n          : undefined;\n      if (operations && !operation) throw new Error('Unknown operation.');\n\n      return {\n        operation: request.operation,\n        input: operation ? operation.input(request.input) : request.input,\n      } as DataQueryInput<Operations>;\n    },\n    output(value, input) {\n      if (!value || typeof value !== 'object')\n        throw new Error('Invalid data response.');\n      const response = value as TransportResponse;\n      if (\n        !Number.isInteger(response.status) ||\n        response.status < 100 ||\n        response.status > 599 ||\n        !response.body ||\n        typeof response.body !== 'object'\n      )\n        throw new Error('Invalid data response.');\n      const body = response.body as DataQueryBody<unknown> & {\n        error?: { code?: unknown; message?: unknown; requestId?: unknown };\n      };\n      if (response.status < 200 || response.status >= 300) {\n        const failure = body.error;\n        throw new MessageRoutingError(\n          typeof failure?.code === 'string' ? failure.code : 'request_failed',\n          typeof failure?.message === 'string'\n            ? failure.message\n            : 'Could not load data.',\n          typeof failure?.requestId === 'string' ? failure.requestId : undefined\n        );\n      }\n      if (\n        !('data' in body) ||\n        typeof body.requestId !== 'string' ||\n        typeof body.queriedAt !== 'string' ||\n        !Array.isArray(body.queryIds) ||\n        !body.queryIds.every(id => typeof id === 'string')\n      )\n        throw new Error('Invalid data envelope.');\n      if (\n        body.queries !== undefined &&\n        (!Array.isArray(body.queries) ||\n          !body.queries.every(\n            query =>\n              query &&\n              typeof query === 'object' &&\n              typeof query.name === 'string' &&\n              typeof query.statement === 'string' &&\n              (query.queryId === undefined || typeof query.queryId === 'string')\n          ))\n      )\n        throw new Error('Invalid query evidence.');\n      const operation = operations?.[input.operation];\n\n      return {\n        status: response.status,\n        body: {\n          ...body,\n          data: operation ? operation.output(body.data) : body.data,\n        },\n      };\n    },\n  };\n}\n\nexport type NavigationUpdate = {\n  search: string;\n  hash: string;\n  mode: 'push' | 'replace';\n  title?: string;\n};\nexport const navigationUpdateRoute = /* @__PURE__ */ defineMessageRoute({\n  input(value: unknown): NavigationUpdate {\n    if (!value || typeof value !== 'object')\n      throw new Error('Invalid navigation.');\n    const input = value as NavigationUpdate;\n    if (\n      typeof input.search !== 'string' ||\n      input.search.length > 16_384 ||\n      (input.search !== '' && !input.search.startsWith('?')) ||\n      typeof input.hash !== 'string' ||\n      input.hash.length > 4096 ||\n      (input.hash !== '' && !input.hash.startsWith('#')) ||\n      (input.mode !== 'push' && input.mode !== 'replace') ||\n      (input.title !== undefined &&\n        (typeof input.title !== 'string' || input.title.length > 512))\n    )\n      throw new Error('Invalid navigation.');\n\n    return {\n      search: input.search,\n      hash: input.hash,\n      mode: input.mode,\n      ...(input.title === undefined ? {} : { title: input.title }),\n    };\n  },\n  output(value: unknown): null {\n    if (value !== null) throw new Error('Invalid navigation response.');\n\n    return null;\n  },\n});\nexport const dataAppRoutes = {\n  'data.query': /* @__PURE__ */ defineDataQueryRoute(),\n  'navigation.update': navigationUpdateRoute,\n};\n"
-  ],
-  "mappings": "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",
-  "debugId": "6376725AC558B20364756E2164756E21",
-  "names": []
-}