@stealthscale/sdk-host 0.1.0 → 0.3.1

package/README.md

@@ -12,51 +12,218 @@ A product creates one host per page in the browser and one per request on a serv
 pnpm add @stealthscale/sdk-host
 ```
 
-The package peers on `react`, `react-dom`, `@tanstack/react-router-ssr-query`,
+The package peers on `react`, `react-dom`, `lucide-react`, `@tanstack/react-router-ssr-query`,
 `@stealthscale/sdk-plugin`, the providers it reads and the component packages it renders:
 
 - `provider-data`, `provider-router`, `provider-i18n`, `provider-hotkeys`, `provider-form`,
-  `settings` and `hooks`
-- `component-actions`, `component-feedback`, `component-forms`, `component-layout`,
-  `component-modals`, `component-navigation`, `component-screen` and `component-typography`
-
-The `./openfeature` entry peers on `@openfeature/web-sdk` as well, which is optional. The
-`./standalone/app` entry peers on `provider-color-mode`, `provider-locale` and `provider-shell`,
-which are optional for the other entries. The host's words are in the `host` catalogue namespace,
+  `provider-viewport`, `settings` and `hooks`
+- `component-a11y`, `component-actions`, `component-feedback`, `component-forms`,
+  `component-layout`, `component-media`, `component-modals`, `component-navigation`,
+  `component-screen` and `component-typography`
+
+The `./openfeature` entry peers on `@openfeature/web-sdk` as well, which is optional. The `./app`,
+`./releases` and `./standalone/app` entries peer on `provider-color-mode`, `provider-locale` and
+`provider-shell`, which are optional for the other entries. The `./deploy` entry imports
+`@stealthscale/sdk-core` alone. The host's words are in the `host` catalogue namespace,
 `locales/<language>/host.json`.
 
-## Compose the application
+## Render a product
 
-```tsx
+`renderProduct` from `@stealthscale/sdk-host/app` renders a product from its definition. It creates
+the host over the product's sources and the router with the host's frame at its root, and renders
+both inside the product's `Shell`.
+
+```ts
+import { catalogues } from "virtual:i18n";
 import { product } from "virtual:product";
 
-const routes = createHostRoutes(product);
-const root = createAppRootRoute<HostRouterContext>()({
-  component: () => (
-    <HostRoot>
-      <Frame />
-    </HostRoot>
-  ),
-  notFoundComponent: HostNotFound,
+import { renderProduct } from "@stealthscale/sdk-host/app";
+
+await renderProduct({ catalogues, product, themes: ["ink", "pine"] });
+```
+
+| Option       | Where left out                 | States                                                |
+| ------------ | ------------------------------ | ----------------------------------------------------- |
+| `product`    | Required                       | The resolved product, from `virtual:product`          |
+| `catalogues` | Every key renders as itself    | The catalogues, from `virtual:i18n`                   |
+| `themes`     | The application's one theme    | The themes the product offers, the first until a pick |
+| `glyphs`     | Lucide's icons                 | The glyphs the settings sections' forms render        |
+| `basepath`   | The site's root                | The base the product is served at, such as `/docs/`   |
+| `element`    | The element with the id `root` | The element the product renders into                  |
+| `refused`    | None                           | The releases the page refused before it rendered      |
+
+- The definition's `sources` imports the module that exports the host's `session`, `access`,
+  `flags`, `data` and `store`. Without a session nobody is signed in, and without a store a person's
+  choices are kept in the page's local storage.
+- The definition's `frame` states the frame's layout and options, or imports the product's own
+  frame, which the router then renders at its root.
+- `renderProduct` waits for `host.ready()`, renders into a React root that takes `onCaughtError`,
+  and resolves with that root.
+- The site root opens the first section the person may open. Without one it sends a person who is
+  not signed in to the sign-in route, and renders the not-found page otherwise. A plugin's route at
+  `/` takes the site root's place.
+- The host reports each entry of `refused` as `plugin-refused` when the page starts.
+
+## Load releases at run time
+
+`renderDeployed` from `@stealthscale/sdk-host/releases` loads the plugins that the page's deployment
+lists, then renders the product with them through `renderProduct`. The page that
+`product.app({ runtime: true })` of `@stealthscale/vite-config-product` generates calls it.
+
+```ts
+import { catalogues } from "virtual:i18n";
+import { definition, product } from "virtual:product";
+
+import { renderDeployed } from "@stealthscale/sdk-host/releases";
+
+await renderDeployed({ catalogues, definition, product, themes: ["ink"] });
+```
+
+`renderDeployed` takes the options of `renderProduct` except `refused`, and `definition`, the
+product's definition from `virtual:product`.
+
+- It reads the deployment from the document's `script` element with the id `stealth-deployment`. A
+  document without that element renders the build's product.
+- It registers the page's preloader with `registerPreloader` of `@stealthscale/sdk-core`. The
+  preloader runs when a release imports one of its modules lazily. It appends a module preload to
+  the document for each module that the imported module needs.
+- Before any request, it refuses a release whose requirements the page's versions do not meet. It
+  also refuses a release without a catalogue in the page's fallback language, and a release whose id
+  names a namespace of the page's catalogues.
+- It reads each release's words in the fallback language from the deployment and imports the
+  release's `manifest.js`. When the deployment lists a release without words, the loader fetches
+  them with their integrity while the page imports the manifest. The page fetches the release's
+  other languages when i18next requests them.
+- It adds the releases to the definition's plugins one at a time and resolves each step. A release
+  whose step reports a problem is refused, and the other releases render.
+- The host reports each refused release as `plugin-refused`. Its `reason` is `catalogue`,
+  `deployment`, `manifest`, `requires` or `resolution`, and its `detail` names the fault.
+
+The loader is an entry of its own, so a product that does not load a release does not download it.
+
+A page that a server rendered loads its releases with `deployedProduct` from the same entry before
+it hydrates. Create the host with the `product`, the `catalogues` and the `refused` releases that it
+returns.
+
+```ts
+import { deployedProduct } from "@stealthscale/sdk-host/releases";
+
+const deployed = await deployedProduct({ catalogues, definition, document, product });
+```
+
+- The product's `releases` contains the ids of the releases in the document. The list includes the
+  refused releases, and it is empty where the page cannot read the deployment.
+
+## Write a deployment's document
+
+`deployDocument` from `@stealthscale/sdk-host/deploy` writes the parts of a product's document that
+depend on its deployment. `documentWith` writes them into the document of the product's build.
+
+```ts
+import { deployDocument, documentWith } from "@stealthscale/sdk-host/deploy";
+
+const deployed = await deployDocument(deployment, provided);
+const html = documentWith(built, deployed);
+```
+
+- `deployment` lists each release by the URL of its directory, the integrity of its `plugin.json`
+  and the options the product installs it with. `provided` is the build's `.product/provided.json`.
+- The step fetches each `plugin.json`, checks its digest against the deployment and checks each
+  member. It leaves out a release that fails, and lists it in `refused` with its base and the fault.
+- For each release whose requirements the provided versions meet, the step fetches the release's
+  catalogue in the page's fallback language. It checks the catalogue's digest against `plugin.json`
+  and writes the words into the deployment. When the deployment lists a release without words, the
+  page fetches the words itself.
+- `importMap` maps the provided specifiers and lists the integrity of every file of every release.
+  `csp` is a `script-src` policy with the page's origin, each release's origin and the import map's
+  digest. `deployment` is the deployment that the page reads. It contains each release's description
+  and words, and the modules of the provided specifiers that the releases import.
+- `preloads` lists each module once. It contains the `manifest.js` of each loaded release, the
+  release modules and provided entries that the manifest imports, and the chunks that those entries
+  import. The preload of a release's module has the module's integrity.
+- `releases` contains the ids of the releases in the document. A server passes them to the host as
+  the product's `releases` (see "Server rendering").
+- `documentWith` puts the policy as a `meta` element, the import map, a module preload per entry of
+  `preloads` and the deployment's `script` element in place of the build's import map. It throws for
+  a document without an import map.
+- A server that writes its own document writes `importMap`, the preloads and `deployment` into it,
+  and sends `csp` as a header. `DEPLOYMENT_ELEMENT` is the id of the deployment's element.
+- The step uses `fetch` and Web Crypto alone, so it runs in Node and in any runtime that has both.
+  `fetching` replaces `fetch`.
+
+## The product's frame
+
+`ProductFrame` renders the frame the product's definition states, from data alone. `renderProduct`
+and `createProductRouter` render it at the router's root.
+
+| Layout              | Main menu                                    | Sidebar                                       |
+| ------------------- | -------------------------------------------- | --------------------------------------------- |
+| `sidebar` (default) | The sidebar's first block                    | The main menu, then every plugin's navigation |
+| `stacked`           | Links in the bar                             | None                                          |
+| `split`             | Links in the bar                             | The current section's navigation              |
+| `rail`              | Icons in a rail, and a dock on a narrow page | The current section's navigation              |
+
+- The sections are the main menu's top-level entries. The current section contains the address on
+  screen, or belongs to the plugin of the page on screen, so a plugin's settings pages keep its
+  section current.
+- A section's navigation is a block per menu of the section's plugin, the plugin's extensions in the
+  `navigation` region, and a block of its settings pages. A menu nests an entry under the entry of
+  its route's parent.
+- An entry with an icon renders lucide's icon from the entry's data. A top-level entry without one
+  renders the initials of its text.
+- A region nobody fills renders no part of the shell. The `aside` and `panel` regions render in
+  panels at the end side, each a complementary landmark named in the host's words.
+- The bar renders the sidebar's opener, the brand, the `header` region, a search that opens the
+  palette, the switchers and the panel's opener in one toolbar. The `userMenu` region renders after
+  the toolbar, or at the sidebar's foot.
+- The rail, the sidebar, the aside and the panel keep a person's open state and width under
+  `stealth.<productId>.<subject>.frame.<panel>`. A panel over a narrow page starts closed whatever
+  the stored state.
+- A skip link leads to the page, and one leads to each panel beside the page.
+- A part with a `mode` renders in that colour mode, such as a dark sidebar on a light page.
+
+## Compose the application yourself
+
+A product that renders on a server creates the host and the router itself. `createProductRouter`
+from `@stealthscale/sdk-host/app` returns the router with the frame and the site root:
+
+```ts
+const router = createProductRouter(host, product, {
+  history: createMemoryHistory({ initialEntries: [request.url] }),
+  shell: Document,
 });
-const tree = root.addChildren([...routes(root)]);
+```
+
+| Option     | Where left out   | States                                                                                |
+| ---------- | ---------------- | ------------------------------------------------------------------------------------- |
+| `basepath` | The site's root  | The base the product is served at                                                     |
+| `frame`    | The host's frame | The root route's component, for a product with a frame of its own                     |
+| `history`  | The browser's    | The history the router reads its address from                                         |
+| `shell`    | No document      | The document around the frame, the root route's `shellComponent`, for a server render |
+
+`GLYPHS` from the same entry contains the form glyphs `renderProduct` passes to the host, for a
+product that calls `createHost` itself.
 
+A product that creates the host itself renders the same pieces `renderProduct` renders:
+
+```tsx
+import { product } from "virtual:product";
+
+const store = localStore();
 const host = createHost({
   data: { changes: changesSubscription, transport: gatewayTransport(gateway) },
   flags: openFeatureFlags(),
+  glyphs: GLYPHS,
   product,
   session: identitySession,
-  store: localStore(),
-});
-const router = createRouter({
-  ...routerOptions({ data: host.data, host, routes: routeMap(tree) }),
-  routeTree: tree,
+  store,
 });
+const router = createProductRouter(host, product);
 
 await host.ready();
 
-createRoot(element).render(
-  <Shell app={product.productId} catalogues={catalogues}>
+createRoot(element, { onCaughtError }).render(
+  <Shell app={product.productId} catalogues={catalogues} locales={product.locales} store={store}>
     <HostProvider host={host} router={router}>
       <RouterProvider router={router} />
     </HostProvider>
@@ -64,15 +231,19 @@ createRoot(element).render(
 );
 ```
 
-| Piece                  | Created                           | Renders or keeps                                                                       |
-| ---------------------- | --------------------------------- | -------------------------------------------------------------------------------------- |
-| `createHostRoutes`     | Once per route tree               | The plugins' routes, the settings route, its index and a route per settings page       |
-| `createHost`           | Once per page, once per request   | The stores, the event bus, the data client, the toaster, the quarantine, the reports   |
-| `HostRoot`             | The root route's component        | The `layout` region around the frame, the `overlay` region, the palette and the toasts |
-| `HostNotFound`         | The root's not-found component    | The not-found page, with the reason a plugin's page is not found                       |
-| `HostProvider`         | Once per render tree              | The host's context, `DataProvider` and the `root` region around the product's tree     |
-| `HostContent`          | In the frame, where the page goes | The `content` region around the matched page                                           |
-| `setupHostIntegration` | Once per router                   | The host's state in a server render, and the browser's host started from it            |
+A frame of the product's own renders `HostRoot` around its shell and `HostContent` where the page
+goes, and the definition's `frame` names it, or `createProductRouter` takes it as `frame`.
+
+| Piece                  | Created                                 | Renders or keeps                                                                            |
+| ---------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `createHostRoutes`     | Once per route tree                     | The plugins' routes, the settings route, its index and a route per settings page            |
+| `createHost`           | Once per page, once per request         | The stores, the event bus, the data client, the toaster, the quarantine, the reports        |
+| `HostRoot`             | The frame's outermost part              | The `layout` region around the frame, the `overlay` region, the palette and the toasts      |
+| `HostNotFound`         | The root's not-found component          | The not-found page, with the reason a plugin's page is not found                            |
+| `HostProvider`         | Once per render tree                    | The host's context, `DataProvider` and the `root` region around the product's tree          |
+| `HostContent`          | In the frame, where the page goes       | The `content` region around the matched page                                                |
+| `setupHostIntegration` | Once per router                         | The host's state in a server render, and the browser's host started from it                 |
+| `onCaughtError`        | Passed to `createRoot` or `hydrateRoot` | Every error a boundary catches, written with `console.error`, except the router's not-found |
 
 - Build the tree once. A plugin that turns off makes its routes not found, and the router keeps the
   tree it was built from.
@@ -84,19 +255,20 @@ createRoot(element).render(
 
 ## Create a host
 
-| Option            | Where left out                                    | States                                                                       |
-| ----------------- | ------------------------------------------------- | ---------------------------------------------------------------------------- |
-| `product`         | Required                                          | The resolved product with its plugins' manifests, from `virtual:product`     |
-| `session`         | Required                                          | The `SessionSource` the session comes from                                   |
-| `store`           | Required                                          | The `SettingStore` a person's switches, settings and placements are kept in  |
-| `access`          | Every decision is the tenant-wide one             | The `AccessSource` of decisions on single resources                          |
-| `data`            | A transport over the contracts' samples           | The transport and the changes subscription the data client runs on           |
-| `flags`           | Every flag has the product's value or its default | The `FlagSource` of flag values per session                                  |
-| `flagsTimeout`    | 1,000 ms                                          | How long `ready` waits for the flag source's first `identify`                |
-| `glyphs`          | No glyphs                                         | The glyphs the settings sections' forms render, such as a checked box's mark |
-| `overrides`       | On outside a production build                     | Whether the tab's flag overrides are read and written                        |
-| `quarantineAfter` | 3                                                 | Failed renders in a row after which a route or an extension is quarantined   |
-| `report`          | The console                                       | The function that receives every `HostReport` entry                          |
+| Option            | Where left out                                    | States                                                                                           |
+| ----------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `product`         | Required                                          | The resolved product with its plugins' manifests, from `virtual:product`                         |
+| `session`         | Required                                          | The `SessionSource` the session comes from                                                       |
+| `store`           | Required                                          | The `SettingStore` a person's switches, settings and placements are kept in                      |
+| `access`          | Every decision is the tenant-wide one             | The `AccessSource` of decisions on single resources                                              |
+| `data`            | A transport over the contracts' samples           | The transport and the changes subscription the data client runs on                               |
+| `flags`           | Every flag has the product's value or its default | The `FlagSource` of flag values per session                                                      |
+| `flagsTimeout`    | 1,000 ms                                          | How long `ready` waits for the flag source's first `identify`                                    |
+| `glyphs`          | No glyphs                                         | The glyphs the settings sections' forms render, such as a checked box's mark                     |
+| `overrides`       | On outside a production build                     | Whether the tab's flag overrides are read and written, as `useFlagActions().overridable` reports |
+| `quarantineAfter` | 3                                                 | Failed renders in a row after which a route or an extension is quarantined                       |
+| `refused`         | None                                              | The releases the page refused, which the host reports as `plugin-refused` when it is created     |
+| `report`          | The console                                       | The function that receives every `HostReport` entry                                              |
 
 - `createHost` throws where a manifest lacks code for a declared name, and names the plugin and the
   name.
@@ -114,25 +286,44 @@ in one `compileRoutes` call:
 
 - A plugin route loads its page with the modules of the plugins in its `loads`, loads its declared
   data through the data client, and validates its search with its contract's validator.
+- Where a condition requires a signed-in person and nobody is signed in, the route redirects to the
+  product's sign-in route, with the entered address as the `redirect` search. The redirect comes
+  before the plugin's availability, which can read the entitlements of a session that does not exist
+  yet.
 - Its condition is evaluated against the host in the router's context. A route whose plugin is off,
   stopped by its kill switch or quarantined is not found, with `NotFoundData` that states the
   reason: `PluginUnavailable` or `PageQuarantined`.
-- Where a condition that requires a signed-in person is false for a person who is not signed in, the
-  route redirects to the product's sign-in route, with the entered address as the `redirect` search.
+- Each plugin route renders the root's `notFoundComponent` in its own place, inside the frame. A
+  page that throws the router's `notFound()` while it renders, for parameters no record matches,
+  renders it there and counts no failure. React reports every error a boundary catches, so a root
+  without `onCaughtError` writes that not-found to the console.
 - A page that throws renders its manifest's fallback, or the host's error page. Each error counts
   once towards the route's quarantine.
+- A page whose module failed to import renders the host's error page with a button that reloads the
+  page, in place of its fallback, and does not count towards the quarantine.
 
 `HostNotFound` renders the not-found page. For a plugin a switch turned off it offers a button that
 turns the plugin on, and for a quarantined page a retry. Where the page replaced the page a person
-was on, focus moves to its heading.
+was on and focus was in that page, focus moves to its heading. A control outside the page keeps
+focus, and a server-rendered not-found page takes none while it hydrates.
+
+Where the page's document contains a deployment, a plain not-found page renders the loading page on
+a server and while it hydrates. Once the page hydrated, the host loads the address again with the
+router. A release's page that matches the address then renders without taking focus, because it is
+the first page of the load. The not-found page renders where the routes do not match the address.
 
-## The frame
+## The parts of every frame
 
 - `HostProvider` renders the host's context, `DataProvider` and the `root` region around the
   product's tree. It invalidates the router after a change a route condition reads, emits
   `host/navigated`, and titles the document with the product's name.
 - `HostRoot` renders the frame inside the `layout` region, then the `overlay` region with the
   command palette and the toast region, and binds the commands' keys. `Mod+K` opens the palette.
+- The palette lists each command a key could run under its plugin's name, and the main menu's pages
+  under `Go to`. While a query matches them, it also lists the entries of every other menu and the
+  pages of every plugin's page index. A settings page is listed under the settings menu's heading,
+  every other row under its plugin's name. The palette imports the indexes the first time it opens,
+  and reports an index that fails as `index-failed`.
 - `HostContent` renders the matched page inside the `content` region. Render it in the frame where
   the page belongs.
 - `HostProvider` and `HostRoot` each render a last boundary. An error outside every plugin renders a
@@ -154,13 +345,15 @@ Pass `glyphs` to `createHost`, or the sections' forms render no marks.
 ## A chunk that no longer exists
 
 A page loaded before a deployment requests chunks that the deployment replaced. The host reloads the
-page once per build version, the product's `version`:
+page once per key. The key is the product's `version`, followed by `+` and the deployment's id on a
+page that loads releases:
 
 - A plugin's module that fails to import starts the recovery, and so does Vite's `vite:preloadError`
   while `HostProvider` is mounted. The import does not settle, so no error renders while the page
   reloads.
-- The version is recorded under `stealth.<productId>.reloaded` in session storage. A second failure
-  for the same version renders the error.
+- The key is recorded under `stealth.<productId>.reloaded` in session storage. A second failure for
+  the same key rejects with `PluginImportError`, whose `cause` is the import's error, and the
+  route's error component renders it without a second reload.
 - A server, and a page whose storage the browser refuses, render the error without a reload.
 
 Each plugin's first import is measured as `stealth:load:<plugin id>`.
@@ -181,10 +374,26 @@ setupHostIntegration({ host, router });
   server's flags until `HostProvider` mounts, and takes the decisions where the browser's subject is
   the server's, so the first render matches the server's.
 - `HostProvider`'s first effect applies the tab's overrides and the browser's flag source.
+- A boundary that hydrates after that effect, such as the router's matches once a lazy page loads,
+  reads the server's flags and the availability they give as React's server snapshot. It hydrates
+  against the server's HTML, and React renders it again with the browser's values.
 
 Create a host per request on a server, with `constantSession` and a setting store over the request's
 cookies.
 
+A product that loads releases renders their pages in the browser alone. Its server passes the
+`releases` that `deployDocument` returned as the product's `releases`, and the page loads them with
+`deployedProduct` before it hydrates:
+
+- Inside a server snapshot the availability store withholds the plugin of each release. Each such
+  plugin is off with the reason `unavailable`. The menus, the settings sections and
+  `usePluginStatuses` read the store, so the frame hydrates without the releases' entries, sections
+  and rows. React renders them once the page hydrated.
+- The server sends `csp` as a header with a nonce of the response in `script-src`, and sets the
+  nonce as the router's `ssr.nonce`. It writes the import map as the first child of the document's
+  head, because React writes every `link` of the head before the head's inline scripts.
+- `examples/app-plugins` serves the notes release this way.
+
 ## A plugin on its own
 
 `@stealthscale/sdk-host/standalone` builds the product a plugin runs in on its own, for its tests
@@ -223,16 +432,21 @@ into the element with the id `root`, or `element`, and resolves with its React r
 | `themes`     | The application's one theme | The themes the page offers                                |
 
 The page opens at the plugin's first menu entry, else at the first route a sample fills. It renders
-a frame of every region the plugins fill and the development panel over it. The panel is a floating
-panel at the bottom-end corner, with one group of controls each:
+the product's frame in the `sidebar` layout, and the development panel over it. The panel is a
+floating panel at the bottom-end corner, with one group of controls each:
 
 - Page: every route a sample fills, by its id.
-- Session: signed in, and a switch per declared permission and entitlement.
+- Session: signed in, and a switch per declared permission and entitlement. Signing out writes
+  `NOBODY`, whose permission and entitlement lists are empty. The permission and entitlement
+  switches are disabled until somebody signs in. Signing in again restores the session they showed
+  before.
 - Checks on one resource: Allow, Deny and Pending.
 - Feature flags: a switch per boolean flag and a picker per experiment, through `flags.override`.
+  The group is left out where no plugin declares a flag.
 - Plugin: the plugin's switch, and its kill switch.
 - Operations: a picker per query and mutation: the sample, the sample after 2 seconds, or a refusal
-  of each kind a `DataError` states. A query's pick loads the page's data again.
+  of each kind a `DataError` states. A query's pick loads the page's data again. The group is left
+  out where the product declares neither a query nor a mutation.
 - Display: the language, the theme and the color mode.
 
 ## OpenFeature
@@ -242,6 +456,7 @@ the OpenFeature client of a domain, `stealth.host` by default.
 
 ```ts
 import { OpenFeature } from "@openfeature/web-sdk";
+
 import { openFeatureFlags } from "@stealthscale/sdk-host/openfeature";
 
 await OpenFeature.setProviderAndWait("stealth.host", provider);

package/dist/app.d.ts

@@ -0,0 +1,79 @@
+import { n as renderProduct, t as ProductRenderOptions } from "./render-DRndY-TD.js";
+import { t as Host } from "./options-DBsArZKT.js";
+import { Product, ResolvedProduct } from "@stealthscale/sdk-core";
+import { HostStores } from "@stealthscale/sdk-plugin";
+import { AnyRoute, AnyRouter, RouterHistory } from "@stealthscale/provider-router";
+import { FunctionComponent, ReactElement, ReactNode } from "react";
+import { FormGlyphs } from "@stealthscale/component-forms/form";
+//#region src/app/frame.d.ts
+/**
+ * Renders the shell inside the host's root, around the page the router matched.
+ *
+ * @remarks
+ *   The frame reads the resolved frame, the main menu's sections and the filled regions, so it
+ *   renders a part only while the layout calls for it and a plugin fills it. The skip links come
+ *   first, then the bar across the top, the body, and the bars at the foot. The `stacked` and
+ *   `split` layouts list the sections in the bar.
+ * @returns The host's root around the shell.
+ * @throws {@link Error} Where the product renders its own frame.
+ */
+export declare function ProductFrame(): ReactElement;
+//#endregion
+//#region src/app/glyphs.d.ts
+/**
+ * The marks of the settings forms: a check in a checked box and beside a picked option, a select's
+ * chevron, a number field's steppers, and the mark before an error.
+ */
+export declare const GLYPHS: FormGlyphs;
+//#endregion
+//#region src/app/tree.d.ts
+/**
+ * Describes the props of the document around the frame.
+ */
+interface ProductShellProps {
+  /**
+   * The frame.
+   */
+  readonly children: ReactNode;
+}
+/**
+ * Renders the document around the frame, for a page a server renders and its hydration.
+ */
+type ProductShell = (props: ProductShellProps) => ReactNode;
+//#endregion
+//#region src/app/router.d.ts
+/**
+ * Lists what a product's router is created with beside the host and the product.
+ */
+export interface ProductRouterOptions {
+  /**
+   * The base the product is served at, such as `/docs/`. The site's root where left out.
+   */
+  readonly basepath?: string | undefined;
+  /**
+   * The component of the root route, for a product that renders its own frame. The host's frame
+   * where left out.
+   */
+  readonly frame?: FunctionComponent | undefined;
+  /**
+   * The history the router reads its address from, such as a memory history on a server. The
+   * browser's where left out.
+   */
+  readonly history?: RouterHistory | undefined;
+  /**
+   * The document around the frame, the root route's `shellComponent`, for a page a server renders
+   * and its hydration. The frame renders alone where left out.
+   */
+  readonly shell?: ProductShell | undefined;
+}
+/**
+ * Returns a product's router: the frame at the root, the site root, and the plugins' routes, with
+ * the host and its data client in the router's context.
+ *
+ * @param host - The host the router's context contains.
+ * @param product - The product, whose routes the host compiles.
+ * @param options - The base path, the frame, the history and the document around the frame.
+ */
+export declare function createProductRouter(host: Host, product: Product, options?: ProductRouterOptions): AnyRouter;
+//#endregion
+export { ProductRenderOptions, renderProduct };

package/dist/app.js

@@ -0,0 +1,3 @@
+import { t as ProductFrame } from "./frame-alSrG57-.js";
+import { n as createProductRouter, r as GLYPHS, t as renderProduct } from "./render-CGRJqVed.js";
+export { GLYPHS, ProductFrame, createProductRouter, renderProduct };