@altertable/data-app 0.62.0 → 0.63.0

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

@@ -2,10 +2,9 @@ import { type ComponentPropsWithRef, type ReactNode } from 'react';
 import type { WidgetEvidence } from './WidgetEvidence.js';
 import type { WidgetStatus } from './RequestHint.js';
 import { type DataTableSearch } from './DataTable.js';
-import type { EmptyStateProps } from './EmptyState.js';
+import type { EmptyContent } from './presentation.js';
 import { type SearchHit, type SearchItemsOptions } from './searchItems.js';
 import type { DataReading } from '../../core/reading.js';
-
 export type TableWidgetColumn<Row> = {
     /** Stable, nonempty identity; unique within this table. */
     id: string;
@@ -28,7 +27,7 @@ type TableWidgetBaseProps<Row> = {
     evidence?: WidgetEvidence;
     search?: TableWidgetSearch<Row>;
     /** Valid result with no rows; the header remains visible. */
-    empty: Pick<EmptyStateProps, 'title' | 'description'>;
+    empty: EmptyContent;
 } & ({
     /** Positive integer preview cap after search; disables pagination. */
     limit: number;

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

@@ -1,5 +1,4 @@
 import { Tabs, TabList, Tab, TabPanels, TabPanel } from 'react-aria-components/Tabs';
-
 /** React Aria tabs with keyboard and ARIA behavior; pair each Tab and TabPanel by stable id. */
 export { Tabs, TabList, Tab, TabPanels, TabPanel };
 /** Keep a page-level tab in `?view=`; reserve `?tab=` for the inspect sheet. */

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

@@ -0,0 +1,4 @@
+import type { ComponentPropsWithRef } from 'react';
+export type TextContentProps = ComponentPropsWithRef<'div'>;
+/** Prose typography for page introductions, widget bodies, and inspection content. */
+export declare function TextContent({ className, ...props }: TextContentProps): import("react").JSX.Element;

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

@@ -0,0 +1,19 @@
+import type { ReactNode } from 'react';
+import type { DataReading } from '../../core/reading.js';
+import { type DataWidgetProps } from './DataWidget.js';
+import type { WidgetEvidence } from './WidgetEvidence.js';
+type TextWidgetBaseProps = Omit<Extract<DataWidgetProps, {
+    reading?: never;
+}>, 'reading' | 'children' | 'isEmpty' | 'empty' | 'skeleton' | 'bodyPadding'>;
+/** Framed narrative context. Bind claims and scope to the same displayed reading.
+ * The renderer handles every ready value, including zero and empty collections. */
+export type TextWidgetProps<Data = unknown> = TextWidgetBaseProps & ({
+    reading: DataReading<Data>;
+    evidence: WidgetEvidence;
+    children: (data: Data) => ReactNode;
+} | {
+    reading?: never;
+    children: ReactNode;
+});
+export declare function TextWidget<Data>(props: TextWidgetProps<Data>): import("react").JSX.Element;
+export {};

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

@@ -1,6 +1,5 @@
 import { type ComponentPropsWithRef, type ReactNode, type RefObject } from 'react';
 import type { ThemeController } from '../../core/appearance.js';
-
 export type ThemeSelectorProps = {
     theme: ThemeController;
     children?: ReactNode;

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

@@ -1,5 +1,4 @@
 import { type ComponentPropsWithRef, type ReactNode, type RefObject } from 'react';
-
 export type TooltipProviderProps = {
     children: ReactNode;
     delay?: number;

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

@@ -1,6 +1,5 @@
 import { type ReactNode } from 'react';
 import { type DateTimeTooltipProps } from './DateTimeTooltip.js';
-
 export type UpdatedAtProps = {
     timestamp: number;
     locale?: string;

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

@@ -1,5 +1,4 @@
 import type { ComponentPropsWithRef, ReactNode } from 'react';
-
 export type VariableBarProps = {
     children: ReactNode;
 } & Omit<ComponentPropsWithRef<'div'>, 'children'>;

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

@@ -1,18 +1,15 @@
 import { type ComponentPropsWithRef, type ReactNode } from 'react';
 import type { WidgetEvidence } from './WidgetEvidence.js';
-import { type DataWidgetProps } from './DataWidget.js';
-import type { EmptyStateProps } from './EmptyState.js';
-import type { DataReading } from '../../core/reading.js';
-import { type ContentSkeletonProps } from './ContentSkeleton.js';
-
+import type { WidgetStatus } from './RequestHint.js';
+import type { EmptyContent, BoundWidgetReading } from './presentation.js';
 type VisualizationWidgetBaseProps = {
     title: ReactNode;
     description?: ReactNode;
     insight?: ReactNode;
     action?: ReactNode;
     evidence?: WidgetEvidence;
-    status?: DataWidgetProps['status'];
-    empty?: Pick<EmptyStateProps, 'title' | 'description'>;
+    status?: WidgetStatus;
+    empty?: EmptyContent;
 } & Omit<ComponentPropsWithRef<'section'>, 'about' | 'title' | 'children'>;
 type UnboundVisualizationWidgetProps = VisualizationWidgetBaseProps & ({
     loading: true;
@@ -27,12 +24,7 @@ export type VisualizationWidgetView<Data> = {
     label: ReactNode;
     render: (data: Data) => ReactNode;
 };
-type BoundVisualizationWidgetBase<Data> = VisualizationWidgetBaseProps & {
-    evidence: WidgetEvidence;
-    reading: DataReading<Data>;
-    isEmpty: (data: Data) => boolean;
-    empty: Pick<EmptyStateProps, 'title' | 'description'>;
-    skeleton?: Pick<ContentSkeletonProps, 'variant' | 'rows'>;
+type BoundVisualizationWidgetBase<Data> = VisualizationWidgetBaseProps & BoundWidgetReading<Data> & {
     visual?: never;
     loading?: never;
 };

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

@@ -1,5 +1,4 @@
 import type { ComponentPropsWithRef, ReactNode } from 'react';
-
 export type WidgetDisclosureProps = {
     label: ReactNode;
     children: ReactNode;

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

@@ -1,11 +1,10 @@
 import type { ComponentPropsWithRef, ReactNode } from 'react';
-import { type EmptyStateProps } from './EmptyState.js';
-
+import type { EmptyContent } from './presentation.js';
 export type WidgetView = {
     id: string;
     label: ReactNode;
     content: ReactNode;
-    empty: Pick<EmptyStateProps, 'title' | 'description'>;
+    empty: EmptyContent;
     isEmpty: boolean;
 };
 export type WidgetViewTabsProps<Views extends readonly WidgetView[] = readonly WidgetView[]> = {

package/dist/types/react/ui/data-identifiers.d.ts

@@ -1,4 +1,3 @@
-
 export type TableIdentifier = {
     catalog: string;
     schema: string;

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

@@ -0,0 +1,19 @@
+import type { ReactNode } from 'react';
+import type { DataReading } from '../../core/reading.js';
+import type { WidgetEvidence } from './WidgetEvidence.js';
+export type EmptyContent = {
+    title: ReactNode;
+    description?: ReactNode;
+};
+export type SkeletonContent = {
+    variant: 'metric' | 'panel' | 'ranking';
+    rows?: number;
+};
+/** A bound widget must explain empty results and link the reading to its evidence. */
+export type BoundWidgetReading<Data> = {
+    reading: DataReading<Data>;
+    isEmpty: (data: Data) => boolean;
+    empty: EmptyContent;
+    evidence: WidgetEvidence;
+    skeleton?: SkeletonContent;
+};

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

@@ -6,7 +6,7 @@ export declare function useViewVariables<Variables extends VariableCollection>(d
     values: AppVariableValues<Variables>;
     set: <Key extends keyof Variables & string>(name: Key, value: AppVariableValues<Variables>[Key]) => void;
     reset: <Key extends keyof Variables & string>(name: Key) => void;
-    update: (next: Partial<AppVariableValues<Variables>>, history?: import("../core/variables.js").HistoryMode) => void;
+    update: (next: Partial<AppVariableValues<Variables>>, history?: import("../core/navigation.js").HistoryMode) => void;
     bind: <Key extends keyof Variables & string>(name: Key) => {
         value: AppVariableValues<Variables>[Key];
         onChange(value: AppVariableValues<Variables>[Key]): void;

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/docs/app-authoring.md

@@ -1,46 +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) in the execution runtime. Put shared input
-   contracts in a browser-safe module and validate outputs before returning them.
-3. For HTTP apps, use a [server handler](server.md) that authorizes each request, or the
-   [Bun adapter](server-bun.md) for local development.
-4. Create a typed [client](client.md) and compose [React views](react.md). Import
-   the operation registry with `import type` for HTTP apps, or as a value for bundle apps.
-5. Define glossary and query evidence, handle empty results, and preserve the
-   displayed input while a request refreshes or fails. A measured zero and an
-   unavailable value must remain distinct.
-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`.
-For HTTP apps, SQL, credentials, and viewer authorization belong on the server.
-For bundle apps, define operations in the browser and pass them to
-`createDataClient({ operations })`; SQL travels through the authorized
-[SQL bridge](embed.md#sql-query-route). Credentials, viewer authorization, and
-enforced query limits remain backend-owned.
-
-## Execution ownership
-
-The client selects one of two paths when it is created:
-
-| App model  | Operation execution                                                                                      | Query delivery                                                                                        |
-| ---------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
-| HTTP app   | The browser sends a name and input; the server authorizes the request and runs its registered operation. | A server-owned lakehouse adapter executes SQL.                                                        |
-| Bundle app | The browser directly runs the registry passed to `createDataClient({ operations })`.                     | `bridge.lakehouse` sends SQL to the host, which authorizes each query and supplies a backend adapter. |
-
-Both paths use the same internal operation executor for input/output validation,
-query names, row bounds, deadlines, evidence, and response serialization limits.
-The executor accepts a `Lakehouse` and never chooses a transport or authorizes a
-viewer. Each adapter owns its boundary: HTTP owns request parsing and responses;
-the bridge owns message delivery; the SQL host owns authorization and public query
-errors. Backend permissions and resource limits apply independently of app policy.
-
-For agent-assisted authoring, see the [starter AGENTS.md template](starter-agent-instructions.md).
+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';
@@ -36,6 +38,8 @@ See [contracts](contract.md), [server handlers](server.md), and
 
 ## 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
@@ -49,8 +53,7 @@ const response = await client.query('connection', {});
 ```
 
 The client runs input parsing, operation logic, and output parsing in the browser.
-It uses the same executor as the server handler for query names, row and duration
-bounds, response size, and query evidence. Each query sends `{ statement, limit }`
+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.
@@ -72,7 +75,7 @@ the host through the existing bridge cancellation protocol.
 `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:
 
@@ -93,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 {
@@ -129,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.
 
@@ -137,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
@@ -152,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

@@ -7,8 +7,8 @@ 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 executor records the SQL and query ID when execution occurs, so evidence does not need a separate result field. 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.
+`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

package/docs/embed.md

@@ -6,7 +6,7 @@ app UI stylesheet.
 
 ## Sources
 
-`attachDataAppBridge` in source mode 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
@@ -67,13 +67,13 @@ 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` also supports connection mode 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. Both modes use the same transport. It returns `{ dispose, setPresentation }` and owns source/origin checks, request
+`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.
@@ -97,14 +97,6 @@ The source bridge's `startupTimeoutMs` defaults to 30 seconds.
 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:
@@ -127,16 +119,16 @@ const router = createMessageRouter(
 // Supply router.dispatch as the shell's onMessage handler.
 ```
 
-The host supplies `authorizedLakehouseForCurrentViewer`. Its backend must enforce
+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
+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
+`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
@@ -167,27 +159,16 @@ 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
+`/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
+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.
+`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/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).