@altertable/data-app 0.61.0 → 0.63.0

package/docs/react.md

@@ -1,47 +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                                                                                                                                                                                                              |
-
-## Bound views and widgets
-
-| 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.
-
-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.
+installs `<DataAppProvider>`. When mounting through another
+framework, wrap the app in `<DataAppProvider>` yourself.
+
+```tsx
+import { injectDataAppStyles, mountDataApp } from '@altertable/data-app/react';
+
+injectDataAppStyles();
+mountDataApp({ config, component: App });
+```
+
+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
 
@@ -58,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({
@@ -84,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,
@@ -117,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: {
@@ -155,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: (
@@ -179,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',
@@ -193,56 +215,59 @@ 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.
-
-## Authoring constraints
+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.
 
-- 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 field filters
 
-## 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.
+zero counts. `<SelectableBarChart>` can share controlled selection with the picker.
+
+## Preserve displayed results
+
+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
+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.
 
 ## Findings and inspection
 
-`DataWidget` composes a body, toolbar feedback, and footer. Widgets and their
+`<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.
 
-`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.
-
-### Migration from the earlier runtime
+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.
 
-- `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.
+## Present data with stories
 
-## Component gallery
+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).
 
-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.
+Return one to four findings with a headline, a visual, and registered source
+evidence. Use `context.finding()` to bind the evidence.
 
-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.
+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.
 

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

@@ -0,0 +1,55 @@
+# 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 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.
+
+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/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 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@altertable/data-app",
-  "version": "0.61.0",
+  "version": "0.63.0",
   "description": "Contracts, transport, and React UI for Altertable data apps",
   "keywords": [
     "altertable",
@@ -23,16 +23,18 @@
     "url": "git+https://github.com/altertable-ai/data-app.git"
   },
   "workspaces": [
-    "examples/starter"
+    "examples/starter-local-data-app"
   ],
   "files": [
     "dist",
     "docs",
+    "examples/starter-data-app",
     "README.md",
     "CONTRIBUTING.md",
     "AGENTS.md"
   ],
   "type": "module",
+  "sideEffects": false,
   "exports": {
     "./contract": {
       "types": "./dist/types/core/contract.d.ts",
@@ -66,16 +68,12 @@
       "types": "./dist/types/react/index.d.ts",
       "import": "./dist/react/index.js"
     },
-    "./react/styles.css": {
-      "types": "./dist/react.css.d.ts",
-      "default": "./dist/react/index.css"
-    },
     "./embed": {
       "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",
@@ -88,17 +86,20 @@
   },
   "scripts": {
     "build": "bun run scripts/build.ts && tsc -p tsconfig.build.json && bun run scripts/build-declarations.ts",
-    "typecheck": "tsc --noEmit",
-    "lint": "oxlint --type-aware src tests scripts browser-tests",
+    "typecheck": "bun install --frozen-lockfile && tsc --noEmit",
+    "lint": "oxlint --type-aware src tests scripts browser-tests examples/starter-data-app",
     "format": "oxfmt .",
     "format:check": "oxfmt --check .",
     "test": "bun test ./tests",
-    "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",
+    "check": "bun run build && bun run typecheck && bun run lint && bun run lint:md && bun run check:links && 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",
-    "test:starter": "bun run scripts/check-starter.ts"
+    "test:starter": "bun run scripts/check-starter.ts",
+    "lint:md": "markdownlint-cli2",
+    "check:links": "remark . --ext md --rc-path .remarkrc.json --frail --no-stdout",
+    "check:links:external": "remark . --ext md --rc-path .remarkrc-external.json --frail --no-stdout"
   },
   "dependencies": {
     "@floating-ui/react": "0.27.20",
@@ -113,11 +114,16 @@
     "@types/bun": "1.4.2",
     "@types/react": "19.3.0",
     "@types/react-dom": "19.3.0",
+    "markdownlint-cli2": "0.23.3",
     "oxfmt": "0.70.0",
     "oxlint": "1.85.0",
     "oxlint-tsgolint": "7.0.2003",
     "react": "19.3.0",
     "react-dom": "19.3.0",
+    "remark-cli": "12.0.1",
+    "remark-gfm": "4.0.1",
+    "remark-lint-no-dead-urls": "2.0.1",
+    "remark-validate-links": "13.1.0",
     "typescript": "7.0.2"
   },
   "peerDependencies": {