@altertable/data-app 0.65.0 → 0.67.0

package/docs/app-authoring.md

@@ -7,6 +7,13 @@ queries, definitions, and evidence.
 
 ## Inspect the data
 
+Declare the query source of truth with `defineDataApp()`. Generate
+operations with `dataApp.defineOperation()` and execute queries by
+name with parameter values. When a query registry is supplied, use only its queries
+and preserve its SQL. Otherwise, inspect the data and declare the queries the app needs.
+Derive displays, exports, and findings from their results. See
+[named queries](contract.md#execute-named-queries).
+
 Inspect the relevant catalogs, tables, and fields, their time coverage, and
 existing definitions. Choose a question the available data can answer.
 
@@ -21,69 +28,84 @@ Choose the execution path:
 
 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.
+
+Use relevant user-controlled query parameters as app filters. Map filter values to
+declared parameters through operation inputs, and reuse query defaults when they
+match the initial selection. One filter may supply several parameters, such as a
+date range supplying `start` and `end`. Keep protected parameters, such as `orgId`,
+and internal execution settings out of filter controls.
+
 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)   |
-| Export displayed data as CSV               | [CSV export](react.md#export-displayed-data-as-csv)        |
-| Bind definitions and source evidence       | [Data context](react.md#bind-evidence)                     |
-
-Use the exported types for configuration, appearance, formatting, and component
-options. Declare configuration with `satisfies DataAppConfig` so appearance
-fields and values are checked before bundling.
-
-## Compose the layout
-
-See the [layout contract](layout.md).
-
-## Export the displayed results
-
-Provide `DataApp.csvExport` in every analytical app. The request-backed API
-requires a callback that selects an explicit filename and named datasets with ordered columns and raw
-rows from the displayed snapshot. Follow [CSV export](react.md#export-displayed-data-as-csv)
-and the [starter](../examples/starter-data-app/index.tsx); use the built-in toolbar
-action rather than adding a custom download button.
-
-Export every distinct analytical dataset at its displayed grain, including relevant
-dimensions and measures. Reuse one dataset for charts or metrics derived from the
-same rows. One dataset downloads as CSV; multiple datasets offer individual CSVs
-and **Export all** as a ZIP archive. Use the displayed input for scope labels and filenames. Export the
-bounded result the app already has; do not issue a different query or mix pending
-filters into the visible result. Setup and static screens may omit export.
-
-## 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.
+borderless prose. Render the app title, description, and instructions immediately. Use metric and dataset
+bindings for dynamic values and `<DataValue>` for values within static prose.
+Skeletonize only the content that needs data. Reuse bindings and the displayed
+source in narrative so values, formatting, and evidence follow filter changes,
+refresh, and failure.
+
+| Task                                             | Documentation                                                     |
+| ------------------------------------------------ | ----------------------------------------------------------------- |
+| Choose components, CSS tokens, and styling hooks | [Styling](styling.md)                                             |
+| Define queries, inputs, and result parsing       | [Operations](contract.md)                                         |
+| Build views, filters, and request states         | [Views](views.md)                                                 |
+| Introduce and explain visualizations             | [Narrative text](widgets.md#narrative-text)                       |
+| Find formatters and presentation helpers         | [App helpers](formatting-and-appearance.md)                       |
+| Register source names                            | [Source identifiers](data-context.md#register-source-identifiers) |
+| Choose date and field filters                    | [Filter variables](variables.md)                                  |
+| Handle refresh and stale results                 | [Displayed results](views.md#preserve-displayed-results)          |
+| Export displayed data as CSV                     | [CSV export](stories-and-export.md#export-displayed-data-as-csv)  |
+| Render widgets and custom visuals                | [Widgets](widgets.md)                                             |
+| Bind definitions and source evidence             | [Data context](data-context.md#bind-evidence)                     |
+
+Declare reusable [datasets and metrics](widgets.md#declare-datasets-and-metrics)
+on the view so tables, exports, and stories share values and evidence.
+
+Every data app supplies a [story and CSV export](stories-and-export.md)
+from the displayed result. Export all distinct datasets at their displayed grain;
+reuse a dataset when several visuals derive from the same rows. Present the
+findings that answer the reader's question, rather than every row or chart.
+Use the [standard layout](layout.md) and built-in toolbar actions.
+
+### Organize the exploration
+
+Use sections for a focused question and for findings readers should compare
+side by side. Add app-level `<Tabs>` from `/react/ui` when the exploration has
+distinct analytical questions, such as Overview, Retention, and Segments, each
+with its own context and group of widgets. Lead with the most useful overview
+and label tabs by the question or subject they explore.
+
+Use `<VisualizationWidget>`'s `views` for alternate representations of the same
+dataset, such as a chart and its rows. Keep these choices within the widget;
+use filter variables when the reader is changing the data scope.
+
+Navigation tabs, widget views, and declared data views have different roles.
+A declared view owns inputs, requests, and displayed results; a tab does not
+require a separate data view. Keep related datasets in one view for a coherent
+snapshot. Use independent views and `<DataSection>` boundaries when content
+needs separate requests. Keep filter placement consistent across tabs and make
+each filter's scope clear. Derive findings, story, and export from the displayed
+results and their inputs.
+
+Choose each visual for the question it answers; see
+[visualization selection](widgets.md#choose-a-visualization).
 
 ## Verify the app
 
+Follow the [UI quality contract](ui-quality.md) for hierarchy, responsive
+composition, typography, and control states.
+
 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. Download CSV from the
 standalone and embedded toolbar and verify its filename, columns, raw values,
 and filter scope against the displayed result. Export and Present story must be
-available once analytical results are shown; initial loading, empty, and initial
-errors have neither action. Inspect both experiences
+available once results are shown; initial loading, empty, and initial
+errors keep both actions visible and disabled. 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.
+Keep credentials, authorization, and enforced query limits in the host/backend.
+Edit app-owned files; installed package files are dependencies.

package/docs/client.md

@@ -15,8 +15,9 @@ const response = await client.query('activity', input, { signal });
 ```
 
 The app defines `operations`, `input`, and an optional cancellation `signal`.
-Operation input and output types are inferred from the server registry. Keep the
-registry import type-only so its SQL and implementation stay on the server.
+Operation input and output types are inferred from the server operation map. Keep the
+server operation map import type-only so its implementations stay on the server.
+The shared app declaration contains the query registry and is browser-safe.
 
 The default endpoint is `/api/data`. Override it with
 `createDataClient({ endpoint, fetch })` to change the base URL or supply a Fetch
@@ -24,8 +25,7 @@ implementation. Calls POST JSON to `/api/data/:operation`; the client sends
 operation inputs rather than SQL or credentials.
 
 `DataResponse` contains `data`, the exact request `input`, `requestId`,
-`queriedAt`, and `queryIds`. `queries` is present when the operation exposes SQL
-and the execution runtime permits disclosure. Use the returned input when labeling stale data during a refresh.
+`queriedAt`, `queryIds`, and executed `queries`. Use the returned input when labeling stale data during a refresh.
 HTTP and iframe delivery validate the same success envelope: data, request ID,
 query timestamp, query IDs, and optional query evidence. Malformed responses
 reject with `invalid_response`.
@@ -46,17 +46,17 @@ Bundle apps pass their operation registry as a value:
 import { connectionCheck } from '@altertable/data-app/contract';
 import { createDataClient } from '@altertable/data-app/client';
 
+// dataApp declares a connection query.
 const client = createDataClient({
-  operations: { connection: connectionCheck() },
+  operations: { connection: connectionCheck(dataApp.queries) },
 });
 const response = await client.query('connection', {});
 ```
 
 The client runs input parsing, operation logic, and output parsing in the browser.
-Operation policy bounds rows, duration, and response size and records query evidence. Each query sends `{ statement, limit }`
+Operation policy bounds rows, duration, and response size and records query evidence. Each query sends `{ statement, limit, params? }`
 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.
+registry. Results include query evidence. Credentials remain backend-owned.
 
 The trusted bootstrap installs the bridge for bundle apps. A custom runtime must
 install it before querying. An explicit `lakehouse` can supply another authorized

package/docs/contract.md

@@ -2,35 +2,58 @@
 
 Import operation definitions, parsers, and shared types from
 `@altertable/data-app/contract`. This entry is safe to import in browser and server
-modules. For HTTP apps, keep SQL and operation implementations on the server; browser modules
-should import their operation types using `import type`.
+modules. The app declaration is browser-safe and includes its SQL registry. For HTTP apps,
+keep operation implementations, credentials, and authorization on the server; browser modules
+import operation types using `import type`.
 
 ## Execute named queries
 
-The app supplies `calendar`, `parseActivity()`, `checkInput`, `buildActivitySql()`,
-and `parseActivityRows()` in this example.
+Declare SQL once with `defineDataApp()` to preserve exact query and parameter
+names. Use stable `lowerCamelCase` IDs describing the result, such as `products`,
+`productsByCategory`, or `dailyRevenue`. Use plural names for row lists; keep parameter
+values in `params`.
+The app owns an immutable registry snapshot. Define operations with
+`dataApp.defineOperation()`.
 
 ```ts
-import {
-  defineOperation,
-  defineQueryNames,
-} from '@altertable/data-app/contract';
+import { defineDataApp } from '@altertable/data-app';
+import { rowsAsRecords } from '@altertable/data-app/contract';
+
+const dataApp = defineDataApp({
+  title: 'Products',
+  description: 'Explore products for the selected organization.',
+  scope: { organization: 'demo', environment: 'production' },
+  appearance: { theme: 'system' },
+  queries: {
+    products: {
+      statement: 'SELECT * FROM products WHERE org_id = $orgId LIMIT $limit',
+      params: { orgId: {}, limit: { defaultValue: 10 } },
+    },
+  },
+});
 
-const queries = defineQueryNames({ activity: 'feature-activity' });
-const activity = defineOperation({
-  queryNames: queries,
-  input: calendar.parseRequest,
-  output: parseActivity,
-  checks: [checkInput],
-  policy: { maxQueryRows: 100, maxDurationMs: 15000, exposeSql: true },
+const products = dataApp.defineOperation({
+  input: parseProductInput,
+  output: parseProducts,
+  checks: [{}],
+  policy: { maxQueryRows: 100, maxDurationMs: 15000 },
   async run({ query }, input) {
-    const result = await query(queries.activity, buildActivitySql(input));
-    return parseActivityRows(result);
+    const result = await query('products', input);
+    return rowsAsRecords(result, ['org_id']);
   },
 });
 ```
 
-`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.
+`parseProductInput()` and `parseProducts()` are app-owned example functions, not
+package exports. Validate
+filter values in the input parser. `{}` declares a required parameter; `{ defaultValue }` supplies
+a fallback. `query(name, params, { limit })` executes only registered queries and
+inherits the operation's row limit and cancellation signal.
+
+SQL and resolved parameter values pass unchanged to the backend. Results include
+query evidence; use `products.queryNames` with `createDataContext()` to bind it.
+For HTTP apps, authorization can supply protected `queryParams`, such as `orgId`.
+The host/backend enforces data access and limits.
 
 ## Shared date ranges
 
@@ -50,8 +73,7 @@ export const calendar = defineDateRangeContract({
 ```
 
 `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
+common inputs and results. `connectionCheck(dataApp.queries)` runs the registered `connection` query. A successful connectivity check confirms access; it is not an
 analysis result.
 
 See [server authorization](server.md) and [React views](react.md) for the two

package/docs/data-context.md

@@ -0,0 +1,91 @@
+# Data context and evidence
+
+Set `dataContext: context` in each view for source descriptions, glossary, and
+permitted query evidence. App inspection and the view's sections use that context.
+Render registered identifiers where `<DataIdentifier>` is used.
+
+Physical source identifiers name inspected tables and columns. Glossary entries
+explain business meaning. Query names link those definitions and displayed claims
+to their execution evidence. Keep all three explicit.
+
+## 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
+import { defineDataIdentifiers } from '@altertable/data-app/react';
+
+const identifiers = defineDataIdentifiers({
+  tables: {
+    events: {
+      catalog: 'product_analytics',
+      schema: 'analytics',
+      name: 'events',
+    },
+  },
+  columns: { identity: { table: 'events', name: 'identity_uuid' } },
+});
+const { DataIdentifier } = identifiers;
+
+<DataIdentifier id="tables.events" />;
+<DataIdentifier id="columns.events.identity" />;
+```
+
+Pass `identifiers.definitions` to `createDataContext()` to reuse the source
+registry.
+
+## Bind evidence
+
+```tsx
+const queries = activity.queryNames;
+const context = createDataContext(queries)({
+  identifiers: identifiers.definitions,
+  description: (
+    <>
+      Explore activity in <DataIdentifier id="tables.events" />.
+    </>
+  ),
+  glossary: {
+    identities: {
+      term: 'Tracked identities',
+      definition: (
+        <>
+          Distinct <DataIdentifier id="columns.events.identity" /> values.
+        </>
+      ),
+      queryNames: [queries.activity],
+    },
+  },
+});
+const evidence = context.evidence({
+  id: 'identities',
+  glossaryIds: ['identities'],
+  queryNames: [queries.activity],
+});
+// activityView is declared with dataContext: context.
+const trackedIdentities = activityView.metric(
+  {
+    id: 'identities',
+    glossaryId: 'identities',
+    format: { kind: 'count', compact: true },
+  },
+  data => ({ current: data.count })
+);
+const finding = context.finding({
+  id: 'activity',
+  headline: 'What people do',
+  visual: <ActivityChart />,
+  evidence: { id: 'activity-evidence', queryNames: [queries.activity] },
+});
+```
+
+Query inspection shows the executed SQL and resolved parameters; copy actions include both.
+
+Import context and identifier factories from `/react`. Use the operation’s derived `queryNames` for evidence.
+
+Use `view.metric(definition, select)` to register and bind a metric in one call.
+Declare dataset evidence references inside `view.dataset()`; the view registers
+and validates them too.
+Widgets and stories share its values and evidence; see [datasets and metrics](widgets.md#declare-datasets-and-metrics).

package/docs/embed.md

@@ -31,11 +31,18 @@ A bundle source has this shape:
 ```ts
 const source = {
   type: 'bundle' as const,
-  bootstrapUrl: 'https://my-report-app-1.apps.example.net/',
   javascript: bundle.javascript,
 };
 ```
 
+Omit `bootstrapUrl` to load the SDK's packaged bootstrap as a `data:` document.
+This supports MCP hosts that permit opaque child frames but block remote frame
+URLs. The SDK embeds the exact host origin and applies a CSP that prohibits
+direct network access. Data requests go through the host's dispatcher.
+
+Supply an HTTP(S) `bootstrapUrl` to use an externally served trusted bootstrap,
+such as the [Worker asset](worker.md).
+
 The host provides a self-contained JavaScript bundle. React bridges replace the
 iframe whenever its JavaScript content changes. Serve the bootstrap page with a CSP compatible with the bundle.
 Bundle mode uses `sandbox="allow-scripts"` and an opaque origin; it cannot read
@@ -129,7 +136,8 @@ as public `source_*` errors with request IDs. Authorization failures return
 public failures with `MessageRoutingError`.
 
 `SqlQueryInput` (exported from `/contract`) carries
-`{ statement: string, limit: number }`; responses are
+`{ statement: string, limit: number, params?: QueryParameters }`; the backend
+interprets the unchanged statement and parameter values. Responses are
 `{ columns: { name: string, type?: string }[], rows: unknown[][], queryId?: string }`.
 The route rejects empty statements, unsafe or nonpositive limits, malformed
 results, and results exceeding the requested limit. The bridge's existing payload

package/docs/formatting-and-appearance.md

@@ -0,0 +1,68 @@
+# Formatting and appearance
+
+Use package helpers so a value has the same meaning in prose, tables, charts,
+and stories. TypeScript and JSDoc describe options and supported values.
+
+## Format values
+
+Import formatting helpers from `@altertable/data-app/format`.
+
+| Helper              | Use                                                    |
+| ------------------- | ------------------------------------------------------ |
+| `formatNumber()`    | General numerical values                               |
+| `formatCount()`     | Nonnegative integer counts, optionally compact         |
+| `formatPercent()`   | Ratios represented as a fraction, such as 0.12 for 12% |
+| `formatMetric()`    | A metric definition's count, ratio, or currency format |
+| `formatDateRange()` | Inclusive calendar ranges                              |
+| `pluralize()`       | Count-dependent labels                                 |
+
+Missing values render distinctly from measured zero. Declare formatting once on
+`view.metric()` so widgets, comparisons, and narrative share it; reuse the
+definition with `formatMetric()` in story headlines.
+
+Use compact counts for headline metrics and chart labels. Declare count metrics
+with `format: { kind: 'count', compact: true }`. Keep full counts in tables used
+for precise comparisons and raw numeric values in datasets for CSV export.
+
+```ts
+formatCount(2_200_000, { compact: true }); // "2.2M"
+formatCount(2_200_000); // "2,200,000"
+```
+
+For signed or fractional measures, use `formatNumber()` with
+`notation: 'compact'` and preserve the measure's units.
+
+Import `chartColor()` from `/react` to select colors from the configured palette.
+`<PeriodSummary>` describes reporting periods; `<UpdatedAt>` and
+`<DateTimeTooltip>` expose readable timestamps with exact-date details.
+`<DataTableTimestamp>` and `<DataTableShare>` format custom table cells.
+
+## Configure identity and appearance
+
+```ts
+import { defineDataApp } from '@altertable/data-app';
+
+const dataApp = defineDataApp({
+  title: 'Product activity',
+  description: 'Explore product usage and trends.',
+  scope: { organization: 'Acme', environment: 'Production' },
+  appearance: {
+    theme: 'system',
+    accentColor: '#405d47',
+    density: 'comfortable',
+  },
+  queries: {},
+});
+```
+
+Scope labels describe the configured connection; they do not grant access.
+`dataAppTitle()` produces the scoped document title used by `mountDataApp()`.
+
+Title and description explain the app and can be revised when regenerating it.
+Omit appearance to use the standard defaults.
+
+Appearance controls the brand palette, typography, density, corner radius, and
+elevation. Those settings apply consistently to the app instead of tuning each
+widget. Theme preference is reader-owned in standalone apps. A trusted parent's
+resolved theme takes precedence and hides local theme controls; see
+[parent presentation](embed.md#parent-presentation).

package/docs/hosted-apps.md

@@ -4,7 +4,14 @@ Follow the [shared authoring flow](app-authoring.md) using [index.tsx](../exampl
 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, CSV export, story, and configuration with
+Declare exactly one top-level const initialized with `defineDataApp({ ... })`, imported
+from `@altertable/data-app`. Keep executable composition outside its literal argument.
+For the future backend extractor, use schema-valid literals without spreads, computed keys,
+references, calls, or template interpolation. Extraction will read and validate the argument
+before bundling, without evaluating app code or parsing SQL. Import aliases and any variable
+name are allowed; export only for other modules. Static apps use `queries: {}`.
+
+Replace the sample app declaration, operations, filters, data context, CSV export, and story with
 an exploration of the source data you inspected. The starter uses two SQL
 `VALUES` rows, so it needs no production table.
 
@@ -13,7 +20,7 @@ For execution details, see [browser-owned operations](client.md#browser-owned-op
 ## Convert a local data app
 
 1. Combine the app's operations and parsers, data context, views, story,
-   CSV export, configuration, and browser entry into one `index.tsx`, following the
+   CSV export, app declaration, 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)
@@ -24,16 +31,3 @@ For execution details, see [browser-owned operations](client.md#browser-owned-op
 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/layout.md

@@ -6,9 +6,11 @@ for sections, `<Grid>` for peer widgets, and `<GridItem>` for spans. Use
 external spacing. Keep widget customization inside the widget so its parent can maintain consistent
 spacing between sections and cards.
 
-By default, section and widget gaps use `--at-layout-gap`, with density configured once
-in `DataAppConfig.appearance`. The package owns wrapping and span collapse based
-on the available container width.
+By default, section and widget gaps use `--atbl-layout-gap`, with density configured once
+in `app.appearance`. The package owns wrapping and span collapse based
+on the available container width and configured gap. Custom length values for
+`--atbl-layout-gap`, `--atbl-space-sm`, and `--atbl-space-md` also drive span
+collapse; a two-column span activates only when two minimum-width tracks fit.
 
 ```tsx
 <Stack>

package/docs/react-embed.md

@@ -45,10 +45,11 @@ The local URL must have a different origin from its shell. For hosted bundles,
 replace `source` with:
 
 ```tsx
-source={{ type: 'bundle', bootstrapUrl, javascript }}
+source={{ type: 'bundle', javascript }}
 ```
 
-The host supplies those bundle values. See [embedding](embed.md) for trust,
+The host supplies the JavaScript bundle. Omit `bootstrapUrl` for the packaged
+opaque bootstrap, or supply an HTTP(S) URL for an external bootstrap. See [embedding](embed.md) for trust,
 sandbox, CSP, and bootstrap setup.
 
 Source URL or JavaScript content changes replace the entire iframe. Change the
@@ -93,8 +94,8 @@ are mutually exclusive.
 
 ## Loading an embedded app
 
-Use `<DataAppSkeleton>` from `/react` while the host builds or starts an app.
-Call `injectDataAppShellStyles()` from `/react` before rendering the placeholder.
+Use `<DataAppSkeleton>` from `/react/ui` while the host builds or starts an app.
+Call `injectDataAppShellStyles()` from `/react/ui` 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.