@altertable/data-app 0.62.0 → 0.64.0

package/docs/react-embed.md

@@ -1,10 +1,10 @@
 # React embedding
 
-Import `DataAppBridge` from `@altertable/data-app/react/embed`. This entry depends
+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.
 
-The bridge owns iframe setup and `postMessage` communication. The consuming
+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.
 
@@ -63,7 +63,7 @@ including `className`, `style`, and `hidden`. The bridge controls `src`, `srcDoc
 
 ## Host-owned iframe
 
-Use the same `DataAppBridge` with `iframe` and `connection` when the host already
+Use the same `<DataAppBridge>` with `iframe` and `connection` when the host already
 owns a loaded iframe and its security policy:
 
 ```tsx
@@ -91,27 +91,18 @@ 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
+## Loading an embedded app
 
-`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.
+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.
+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
+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

@@ -1,75 +1,26 @@
 # React
 
 Import hooks, components, and UI helpers from `@altertable/data-app/react`.
-Import `@altertable/data-app/react/styles.css` once in the browser entry.
 React 19.2 or newer and React DOM 19.2 or newer are peer dependencies.
 
+## Mount the app
+
 `mountDataApp({ config, component })` mounts into `#root`, sets the document
 title and language, attaches navigation to an available iframe transport, and
-installs `DataAppProvider`. When mounting through another
-framework, wrap the app in `DataAppProvider` yourself.
-
-## Find UI by task
-
-All of these APIs are exported from `/react`. Each component's stylesheet lives beside its implementation.
-
-| Task                                              | Start here                                                                                                                                                                                                       | Related APIs                                                                                                                                                                                                                                       |
-| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Primary request and page shell                    | [DataApp](https://github.com/altertable-ai/data-app/blob/main/src/react/ui/DataApp.tsx)                                                                                                                          | AppLayout, AppHeader, AppToolbar, AppFooter, AppScope, ThemeToggle                                                                                                                                                                                 |
-| Initial connection check                          | [GettingStarted](https://github.com/altertable-ai/data-app/blob/main/src/react/ui/GettingStarted.tsx)                                                                                                            | Pair with `connectionCheck()` from `/contract`                                                                                                                                                                                                     |
-| Arrange content                                   | [Grid](https://github.com/altertable-ai/data-app/blob/main/src/react/ui/Grid.tsx), [Stack](https://github.com/altertable-ai/data-app/blob/main/src/react/ui/Stack.tsx)                                           | DataWidget                                                                                                                                                                                                                                         |
-| Show a key number                                 | [MetricWidget](https://github.com/altertable-ai/data-app/blob/main/src/react/ui/MetricWidget.tsx)                                                                                                                | ComparisonVisual                                                                                                                                                                                                                                   |
-| Show charts and collections                       | [VisualizationWidget](https://github.com/altertable-ai/data-app/blob/main/src/react/ui/VisualizationWidget.tsx), [TableWidget](https://github.com/altertable-ai/data-app/blob/main/src/react/ui/TableWidget.tsx) | DataTable, Ranking, Breakdown, chartColor                                                                                                                                                                                                          |
-| Handle a request's loading, error, and stale data | [DataSection](https://github.com/altertable-ai/data-app/blob/main/src/react/ui/DataSection.tsx)                                                                                                                  | DataBoundary, DataViewToast, EmptyState, StatusPanel, Skeleton                                                                                                                                                                                     |
-| Show freshness and refresh                        | [UpdatedAt](https://github.com/altertable-ai/data-app/blob/main/src/react/ui/UpdatedAt.tsx), [AppToolbar](https://github.com/altertable-ai/data-app/blob/main/src/react/ui/AppToolbar.tsx)                       | RefreshRegion, LiveControl                                                                                                                                                                                                                         |
-| Bind filters to the URL                           | [variables](https://github.com/altertable-ai/data-app/blob/main/src/react/ui/variables.ts), [DateRangePicker](https://github.com/altertable-ai/data-app/blob/main/src/react/ui/DateRangePicker.tsx)              | Combobox, PeriodSummary, Tabs, useViewTab                                                                                                                                                                                                          |
-| Search a loaded collection                        | [searchItems](https://github.com/altertable-ai/data-app/blob/main/src/react/ui/searchItems.ts), [SearchMatch](https://github.com/altertable-ai/data-app/blob/main/src/react/ui/SearchMatch.tsx)                  | SearchField                                                                                                                                                                                                                                        |
-| Explain context, glossary, and queries            | [AboutData](https://github.com/altertable-ai/data-app/blob/main/src/react/ui/AboutData.tsx), [DataContext](https://github.com/altertable-ai/data-app/blob/main/src/react/ui/data-context.ts)                     | [GlossaryDefinition](https://github.com/altertable-ai/data-app/blob/main/src/react/ui/GlossaryDefinition.tsx), GlossaryExplanation, [defineDataIdentifiers](https://github.com/altertable-ai/data-app/blob/main/src/react/ui/data-identifiers.tsx) |
-| 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.
+installs `<DataAppProvider>`. When mounting through another
+framework, wrap the app in `<DataAppProvider>` yourself.
 
 ```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
+import { injectDataAppStyles, mountDataApp } from '@altertable/data-app/react';
 
-| Definition        | Runtime owns                                                                                                                                     |
-| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `defineOperation` | Input/output validation, check inputs, query limits and cancellation; `query(name, sql)` accepts registered names and records executed evidence. |
-| `defineDataView`  | URL variables, operation input, emptiness and the primary date binding. `useView` connects the result and controls to `DataApp`.                 |
-| `DataApp`         | Header, variable bar, refresh state, stale-result notice and dimming, default inspection empty states.                                           |
-| `view.content`    | One loading/ready layout. `result.select` never evaluates loading data; `result.metric` binds comparisons to the displayed input.                |
-| `context.metric`  | Label, numeric format, glossary evidence and optional direction of improvement.                                                                  |
-| `WidgetViewTabs`  | Valid, unique selection IDs and a required empty state per tab.                                                                                  |
-
-SQL and business definitions belong to the app. Hosted adapters authorize every request; local development can use the CLI proxy. SQL disclosure also requires server permission.
+injectDataAppStyles();
+mountDataApp({ config, component: App });
+```
 
-A measured zero and unavailable data have different meanings. Metric readings use `null` for an unavailable previous value. The app defines whether a result is empty. `Breakdown` shows parts of a total; `Ranking` scales against its largest value. Percent formats accept ratios.
+Importing the package does not inject styles. For server rendering, call the
+injector on the client before mounting or hydrating. With a restrictive CSP,
+pass a permitted nonce; the first call sets it for the document. No CSS loader
+or separate stylesheet asset is needed.
 
 ## Bind a view
 
@@ -86,7 +37,7 @@ import {
 } from '@altertable/data-app/react';
 import type { operations } from '#app/operations.ts';
 import { calendar } from '#app/contracts.ts';
-import { dataContext, actions } from '#app/data-context.tsx';
+import { dataContext, trackedIdentities } from '#app/data-context.tsx';
 import config from '#config';
 
 const period = dateRangeVariable({
@@ -112,7 +63,7 @@ const featureEvidence = dataContext.evidence({
 const content = activityView.content(result => (
   <Grid columns={2}>
     <MetricWidget
-      metric={actions}
+      metric={trackedIdentities}
       reading={result.metric(data => ({
         current: data.count,
         previous: data.previousCount,
@@ -145,33 +96,62 @@ function App() {
 
 The `date` binding identifies the controlling variable and extracts its range from the operation input. Nested inputs use, for example, `input: (input) => input.period`. The runtime rejects mappings that silently change the selected range or comparison. Non-date views supply `describeInput`; date views can override it when other inputs also need describing.
 
-The shared calendar lives in a browser-safe module:
+Share the [date range contract](contract.md#shared-date-ranges) between the
+operation parser and the view.
 
-```ts
-import { defineDateRangeContract } from '@altertable/data-app/contract';
-export const calendar = defineDateRangeContract({
-  minDate: '2026-01-01',
-  maxRangeDays: 90,
-  timeZone: 'UTC',
-});
-// Server operation: input: calendar.parseRequest
-```
+`useView()` generates controls for date, text and fixed-option select variables; custom controls use `result.variables.bind(name)`. `input` chooses which variables reach the operation, so local search can stay local. Hooks belong in the enclosing component.
 
-`useView` generates controls for date, text and fixed-option select variables; custom controls use `result.variables.bind(name)`. `input` chooses which variables reach the operation, so local search can stay local. The callback in `view.content` receives the displayed result, including its original input during refreshes and failures. Hooks belong in the enclosing component.
+For large tables, use query-backed pagination with a stable sort and total
+count. Client pagination and search cover only the rows already returned.
 
-`TableWidget` also accepts `reading={result.select((data) => data.rows)}` and optional `skeletonRows`. Columns and empty states are declared once for both loading and ready layouts. Bounded tables default to 10 rows per page with a bottom footer shared with inspection. Set `pagination={{ pageSize: 8 }}` to change the page size or `pagination={false}` to show all rows. Search runs before pagination; the footer counts only the supplied rows. `limit` remains a separate, mutually exclusive display cap. Large catalogs need query-backed pagination with a stable sort and total count.
+Bound `<VisualizationWidget>` and `<TableWidget>` components require `evidence` from `context.evidence(...)`. A bound `<MetricWidget>` gets evidence from its metric definition. Evidence must name at least one glossary entry or query. Static widgets may omit it.
 
-Bound `VisualizationWidget` and `TableWidget` calls require `evidence` from `context.evidence(...)`. A bound `MetricWidget` gets evidence from its metric definition. Evidence must name at least one glossary entry or query. Static widgets may omit it.
+`<MetricWidget>` and `<ComparisonVisual>` both accept the same `metric` and `reading`. The comparison is enabled by the displayed result's range. The definition supplies formatting and evidence; a reading cannot override those or provide a second value. `favorableDirection` is optional; changes are neutral until the author defines whether up or down is favorable.
 
-`MetricWidget` and `ComparisonVisual` both accept the same `metric` and `reading`. The comparison is enabled by the displayed result's range. The definition supplies formatting and evidence; a reading cannot override those or provide a second value. `favorableDirection` is optional; changes are neutral until the author defines whether up or down is favorable.
+Use the [app helpers](#reuse-app-helpers) for metric formats and values in tables,
+charts, and custom views.
 
-`defineDataContent` remains available for manually managed requests. Its optional `{ date: (input) => rangeRequest }` binds comparison readings. `DataSection` handles independent requests. Low-level widgets, tabs and layout components remain available for custom interfaces.
+`defineDataContent()` remains available for manually managed requests. Its optional `{ date: (input) => rangeRequest }` binds comparison readings. `<DataSection>` handles independent requests. Low-level widgets, tabs and layout components remain available for custom interfaces.
 
-## Bind evidence
+## Narrative text
+
+Use `<TextContent>` for prose within a page or custom layout, and `<TextWidget>`
+when the explanation belongs in a titled panel alongside other widgets.
+
+Give text a purpose: frame the question, explain how to interpret a comparison,
+qualify a finding, or suggest what to explore next. Choose the content for the
+reader's question and the decisions the exploration supports.
+
+For data-dependent text, use `reading={result.select((data, input) => ...)}` and
+provide `evidence`. Derive both the explanation and its scope from those displayed
+values so it stays consistent with the visualizations while filters change.
+Static instructions can use ordinary children; local filters should feed the same
+filtered data to the text and its related visualization.
+
+## Reuse app helpers
+
+Use the shared helpers for common app tasks. Follow the entry points below to
+find their exports, types, and usage constraints.
+
+| Task                                                                                        | Entry point                                                                                       |
+| ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| Format numbers, counts, percentages, currency, date ranges, and plural labels (`pluralize`) | [Format helpers](https://github.com/altertable-ai/data-app/blob/main/src/core/format.ts)          |
+| Choose chart colors                                                                         | [Chart colors](https://github.com/altertable-ai/data-app/blob/main/src/react/ui/chartColor.ts)    |
+| Search items and highlight matches                                                          | [Search helpers](https://github.com/altertable-ai/data-app/blob/main/src/react/ui/searchItems.ts) |
+| Read and synchronize URL query state                                                        | [URL state helpers](https://github.com/altertable-ai/data-app/blob/main/src/react/ui/search.ts)   |
+| Render timestamps, freshness, table shares, periods, and metric comparisons                 | [React exports](https://github.com/altertable-ai/data-app/blob/main/src/react/index.ts)           |
+| Configure appearance and theme preferences                                                  | [Appearance helpers](https://github.com/altertable-ai/data-app/blob/main/src/core/appearance.ts)  |
+| Build the app's scoped document title                                                       | [Configuration helpers](https://github.com/altertable-ai/data-app/blob/main/src/core/config.ts)   |
+
+## Register source identifiers
+
+Use `defineDataIdentifiers()` from `/react` to register exact catalog, schema,
+table, and field names. Use `<DataIdentifier>` in descriptions and glossary
+entries to render those source references consistently.
 
 ```tsx
-const queries = defineQueryNames({ activity: 'feature-activity' });
-// In the server operation: queryNames: queries
+import { defineDataIdentifiers } from '@altertable/data-app/react';
+
 const identifiers = defineDataIdentifiers({
   tables: {
     events: {
@@ -183,6 +163,20 @@ const identifiers = defineDataIdentifiers({
   columns: { identity: { table: 'events', name: 'identity_uuid' } },
 });
 const { DataIdentifier } = identifiers;
+
+<DataIdentifier id="tables.events" />;
+<DataIdentifier id="columns.events.identity" />;
+```
+
+Pass `identifiers.definitions` to `createDataContext()` so the context carries the
+same source registry. Source identifiers name physical data; glossary entries
+explain its business meaning, and query evidence records how it was queried.
+
+## Bind evidence
+
+```tsx
+const queries = defineQueryNames({ activity: 'feature-activity' });
+// In the server operation: queryNames: queries
 const context = createDataContext(queries)({
   identifiers: identifiers.definitions,
   description: (
@@ -207,7 +201,7 @@ const evidence = context.evidence({
   glossaryIds: ['identities'],
   queryNames: [queries.activity],
 });
-const actions = context.metric({
+const trackedIdentities = context.metric({
   id: 'actions',
   glossaryId: 'identities',
   label: 'Tracked identities',
@@ -221,67 +215,27 @@ const finding = context.finding({
 });
 ```
 
-Import `defineQueryNames` from `/contract` and the context/identifier factories from `/react`. Use the same registry in `defineOperation({ queryNames: queries, ... })`. Unknown glossary/query references fail type checks and registry validation; the server also validates returned query names. Physical source identity stays in the identifier registry for future linking.
+Import `defineQueryNames()` from `/contract` and the context/identifier factories from `/react`. Use the same registry in `defineOperation({ queryNames: queries, ... })`. Unknown glossary/query references fail type checks and registry validation; the server also validates returned query names.
 
-## Authoring constraints
+## Time views and field filters
 
-- Date views declare `date: { variable: "period", input: (input) => input }`, or supply `describeInput` for a non-date view.
-- Numeric metrics use `value={count} format={{ kind: "count" }}`. Custom formatted JSX or strings use `content={...}` instead of `value`.
-- Supply `empty` to secondary `DataSection` requests or pass a bound `useView` result. A primary `DataApp` accepts it either from `useView` or as an explicit prop.
-- For alternate views of the same bound result, pass `views={[{ id, label, render }]}` and `viewLabel` to `VisualizationWidget`. Its required `isEmpty` and `empty` apply to the whole result; the widget owns selection. Use `WidgetViewTabs` directly only when views have independent empty states.
-- Variable URL keys cannot use `view`, `about`, `tab`, `present`, or `step`.
-
-## Time views and dimension filters
-
-`createDataHooks(client).defineTimeView` owns the `period` variable, calendar
+`createDataHooks(client).defineTimeView()` owns the `period` variable, calendar
 controls, and displayed-period label. Declare `time: { contract, defaultValue }`,
 an operation, `isEmpty`, and `empty`. With no additional variables, its default
 input is the calendar request. With additional variables, it is `{ period, ...variables }`.
 Supply an `input` mapper for a different operation shape and `bindings` to extract
-nested period or dimension inputs. Mappings must preserve the selected values.
+nested period or field-filter inputs. Mappings must preserve the selected values.
 
-`dimensionFilter` requires exactly one option source: fixed `options` or a `facet`.
-Use `defineFacetFilter` to bind a facet operation and its typed input. The generated
-`DimensionPicker` preserves cached options during refresh and failure, offers
+`dimensionFilter()` from `/contract` requires exactly one option source: fixed `options` or a `facet`.
+Use `defineFacetFilter()` to bind a facet operation and its typed input. The generated
+`<DimensionPicker>` preserves cached options during refresh and failure, offers
 missing values separately, and retains selected values absent from a result with
-zero counts. `SelectableBarChart` can share controlled selection with the picker.
-
-## Findings and inspection
-
-`DataWidget` composes a body, toolbar feedback, and footer. Widgets and their
-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.
+zero counts. `<SelectableBarChart>` can share controlled selection with the picker.
 
-`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;
-`context.finding` validates their evidence against the context registry.
+## Preserve displayed results
 
-### Migration from the earlier runtime
-
-- `DataWidget` replaces the internal `DataPanel` shell and `StorySection` layout.
-- `PresentStory` replaces `PlayStory`; provide `findings` with explicit `evidence`.
-- `context.finding` replaces `context.storyStep`.
-- Table pagination is enabled by default; use `pagination={false}` for complete tables.
-
-## Component gallery
-
-Contributors can preview `/gallery` on the browser fixture server with
-`bun browser-tests/server.ts`. The gallery covers control, widget, request,
-inspection, and narrow-layout defaults. `bun run test:browser` verifies desktop
-and phone interactions. Fixtures are excluded from the published package.
+The callback in `view.content()` receives the displayed result and its original
+input during refreshes and failures. Use that input when labeling the data.
 
 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
@@ -292,8 +246,28 @@ 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.
 
+## Findings and inspection
+
+`<DataWidget>` composes a body, toolbar feedback, and footer. Widgets and their
+inspection sheets render the same visual and controls. Keep interactive state
+above both mounts when authoring custom children.
+
 When a trusted parent supplies [parent presentation](embed.md#parent-presentation),
-`DataApp` follows its resolved theme and suppresses local theme controls,
+`<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.
+
+## Present data with stories
+
+Stories turn the exploration's findings into a presentation. Set the `story` prop on `<DataApp>`
+to enable **Present story** in the toolbar; use `<PresentStory>` directly for a
+custom shell. Start from the [data app starter](../examples/starter-data-app/index.tsx).
+
+Return one to four findings with a headline, a visual, and registered source
+evidence. Use `context.finding()` to bind the evidence.
+
+The callback receives the displayed data and its original input, including
+during refresh or failure. Derive the story from that snapshot so it agrees with
+the visible exploration. Initial loading, empty results, and initial errors have
+no story to present.

package/docs/server-bun.md

@@ -1,6 +1,9 @@
 # Local Bun server
 
-Import `serveLocalApp` and `localLakehouse` from
+Use this Bun server for local data apps. Start from the CLI scaffold or
+[local data app starter](https://github.com/altertable-ai/data-app/tree/main/examples/starter-local-data-app).
+
+Import `serveLocalApp()` and `localLakehouse()` from
 `@altertable/data-app/server/bun`. This entry requires Bun; install `@types/bun`
 when typechecking a Bun app.
 
@@ -24,8 +27,3 @@ 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/server.md

@@ -1,6 +1,6 @@
 # Server
 
-Import `createDataHandler` and the `RequestAccess` type from
+Import `createDataHandler()` and the `RequestAccess` type from
 `@altertable/data-app/server`. The handler accepts a Web `Request` and returns a
 `Promise<Response>`. This entry can be imported in Node and Bun without loading
 React or the Bun local-development adapter.
@@ -21,7 +21,7 @@ export const handleDataRequest = createDataHandler(
 );
 ```
 
-The app supplies `authenticate` and `lakehouseFor`, then routes `/api/data/*`
+The app supplies `authenticate()` and `lakehouseFor()`, then routes `/api/data/*`
 requests to the handler. Authorize every viewer and operation, and scope the
 returned lakehouse to the viewer's permitted data. Origin and Fetch Metadata
 checks reject cross-site browser requests; they do not authenticate viewers.

package/docs/worker.md

@@ -41,10 +41,8 @@ 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
+The Worker enforces a restrictive CSP with configured `frame-ancestors`,
+`no-referrer`, and `nosniff`. App scripts load through the authenticated bridge. 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.
@@ -53,5 +51,5 @@ 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
+Custom hosts that bundle their own bootstrap can use `startDataAppBootstrap()` from
 [/embed](embed.md#trusted-bootstrap).

package/examples/starter-data-app/index.tsx

@@ -0,0 +1,159 @@
+import { createDataClient } from '@altertable/data-app/client';
+import type { DataAppConfig } from '@altertable/data-app/config';
+import {
+  defineOperation,
+  defineQueryNames,
+  parseCount,
+} from '@altertable/data-app/contract';
+import {
+  createDataContext,
+  createDataHooks,
+  DataApp,
+  injectDataAppStyles,
+  mountDataApp,
+  MetricWidget,
+  textVariable,
+} from '@altertable/data-app/react';
+
+const queryNames = defineQueryNames({
+  sampleCountsByGroup: 'sample-counts-by-group',
+});
+function parseSampleCountFilter(value: unknown) {
+  if (
+    !value ||
+    typeof value !== 'object' ||
+    !('groupName' in value) ||
+    typeof value.groupName !== 'string' ||
+    value.groupName.length > 40
+  )
+    throw new Error('Expected a group name of at most 40 characters.');
+  return { groupName: value.groupName };
+}
+function parseSampleCounts(
+  value: unknown
+): { groupName: string; sampleCount: number }[] {
+  if (!Array.isArray(value))
+    throw new Error('Expected sample counts by group.');
+  return value.map(row => {
+    if (!row || typeof row !== 'object' || typeof row.groupName !== 'string')
+      throw new Error('Expected a group name.');
+    return {
+      groupName: row.groupName,
+      sampleCount: parseCount(row.sampleCount),
+    };
+  });
+}
+const operations = {
+  sampleCountsByGroup: defineOperation({
+    queryNames,
+    input: parseSampleCountFilter,
+    output: parseSampleCounts,
+    checks: [
+      { groupName: '' },
+      { groupName: 'Alpha' },
+      { groupName: 'missing' },
+    ],
+    policy: { maxQueryRows: 10, maxDurationMs: 15000, exposeSql: true },
+    async run({ query }, { groupName }) {
+      // Portable sample data, not a production table. Escape the validated SQL literal.
+      const escapedGroupName = groupName.replaceAll("'", "''");
+      const queryResult = await query(
+        queryNames.sampleCountsByGroup,
+        `
+WITH sample_counts(group_name, sample_count) AS (VALUES ('Alpha', 3), ('Beta', 0))
+SELECT group_name, sample_count FROM sample_counts
+WHERE '${escapedGroupName}' = '' OR group_name = '${escapedGroupName}'
+ORDER BY group_name LIMIT 10`
+      );
+      return parseSampleCounts(
+        queryResult.rows.map(([groupName, sampleCount]) => ({
+          groupName,
+          sampleCount,
+        }))
+      );
+    },
+  }),
+};
+const appConfig: DataAppConfig = {
+  title: 'Sample counts',
+  scope: { organization: 'demo', environment: 'sample' },
+  appearance: { theme: 'system' },
+};
+const sampleDataContext = createDataContext(queryNames)({
+  description:
+    'Two SQL VALUES rows demonstrate the host query path. Replace them with inspected source data before publishing findings.',
+  glossary: {
+    sampleCount: {
+      term: 'Sample count',
+      definition: 'A fixture value: Alpha is 3 and Beta is a measured zero.',
+      queryNames: [queryNames.sampleCountsByGroup],
+    },
+  },
+});
+const { defineDataView, useView } = createDataHooks(
+  createDataClient({ operations })
+);
+const sampleCountsView = defineDataView({
+  operation: 'sampleCountsByGroup',
+  variables: {
+    groupName: textVariable({ key: 'group', label: 'Group', defaultValue: '' }),
+  },
+  input: ({ groupName }) => ({ groupName }),
+  describeInput: ({ groupName }) =>
+    groupName ? `group ${groupName}` : 'all groups',
+  isEmpty: sampleCounts => sampleCounts.length === 0,
+  empty: {
+    title: 'No matching groups',
+    description: 'Try Alpha, Beta, or clear the group filter.',
+  },
+});
+function App() {
+  const sampleCountsRequest = useView(sampleCountsView);
+  return (
+    <DataApp
+      config={appConfig}
+      dataContext={sampleDataContext}
+      request={sampleCountsRequest}
+      story={
+        sampleCountsRequest.snapshot?.data.length
+          ? ({ data: sampleCounts, input: displayedInput }) =>
+              sampleCounts.map(({ groupName, sampleCount }) =>
+                sampleDataContext.finding({
+                  id: `sample-count-${groupName}`,
+                  headline: `${groupName} has ${sampleCount} samples`,
+                  context: `Demonstration values for ${displayedInput.groupName || 'all groups'}.`,
+                  visual: (
+                    <MetricWidget
+                      label="Sample count"
+                      value={sampleCount}
+                      format={{ kind: 'count' }}
+                    />
+                  ),
+                  visualKind: 'metric',
+                  evidence: {
+                    id: `sample-count-${groupName}`,
+                    glossaryIds: ['sampleCount'],
+                  },
+                })
+              )
+          : undefined
+      }
+    >
+      {(sampleCounts, displayedInput) => (
+        <section aria-label="Sample results">
+          <h2>Sample counts</h2>
+          <p>Showing {displayedInput.groupName || 'all groups'}</p>
+          <ul>
+            {sampleCounts.map(({ groupName, sampleCount }) => (
+              <li key={groupName}>
+                {groupName}: {sampleCount}
+              </li>
+            ))}
+          </ul>
+        </section>
+      )}
+    </DataApp>
+  );
+}
+injectDataAppStyles();
+mountDataApp({ config: appConfig, component: App });