@stealthscale/sdk-host 0.1.0 → 0.3.1

package/dist/index.d.ts

@@ -1,92 +1,9 @@
-import { DataClientOptions, QueryClient } from "@stealthscale/provider-data";
-import { AccessSource, FlagSource, Product, SessionSource, When } from "@stealthscale/sdk-core";
-import { HostReport, HostStores, RenderTarget } from "@stealthscale/sdk-plugin";
-import { SettingStore } from "@stealthscale/settings";
+import { n as HostOptions, t as Host } from "./options-DBsArZKT.js";
+import { Product, When } from "@stealthscale/sdk-core";
+import { RenderTarget } from "@stealthscale/sdk-plugin";
 import { AnyRoute, AnyRouter, NotFoundRouteProps, RouteMap, RoutesContext } from "@stealthscale/provider-router";
 import { ReactNode } from "react";
 import { DataContext } from "@stealthscale/provider-data/router";
-import { FormGlyphs } from "@stealthscale/component-forms/form";
-//#region src/host/options.d.ts
-/**
- * Lists what a host is created from.
- */
-export interface HostOptions {
-  /**
-   * Source of decisions on single resources. Every decision is the tenant-wide one without it.
-   */
-  readonly access?: AccessSource | undefined;
-  /**
-   * The transport and the changes stream the host's data client runs on. A sampled transport over
-   * the contracts' samples where left out.
-   */
-  readonly data?: Pick<DataClientOptions, "changes" | "transport"> | undefined;
-  /**
-   * Source of flag values per session. Every flag has its product value or its default without
-   * one.
-   */
-  readonly flags?: FlagSource | undefined;
-  /**
-   * Milliseconds `ready` waits for the flag source's first `identify`. 1,000 by default.
-   */
-  readonly flagsTimeout?: number | undefined;
-  /**
-   * Glyphs the settings sections' forms render: the mark in a checked box, a select's chevron and
-   * the others the forms package names. A form renders no mark it has no glyph for.
-   */
-  readonly glyphs?: FormGlyphs | undefined;
-  /**
-   * Reads and writes flag overrides. On by default outside a production build.
-   */
-  readonly overrides?: boolean | undefined;
-  /**
-   * The resolved product with its plugins' manifests, from `virtual:product`.
-   */
-  readonly product: Product;
-  /**
-   * Failed renders in a row after which a route or an extension is quarantined. 3 by default.
-   */
-  readonly quarantineAfter?: number | undefined;
-  /**
-   * Receives every entry the host reports. Writes to the console by default.
-   */
-  readonly report?: ((entry: HostReport) => void) | undefined;
-  /**
-   * Source of the session.
-   */
-  readonly session: SessionSource;
-  /**
-   * Where the host keeps a person's switches, settings and placements.
-   */
-  readonly store: SettingStore;
-}
-/**
- * Describes a host: the state of one page, or of one request on a server.
- */
-export interface Host {
-  /**
-   * The data client of the page or the request, which the router's context contains.
-   */
-  readonly data: QueryClient;
-  /**
-   * Stops listening to the session source, the flag source, the access source and the setting
-   * store, and cancels the data client's fetches.
-   */
-  readonly dispose: () => void;
-  /**
-   * Resolves once the eager plugins' modules are imported and the flag source has identified the
-   * session, or once the flag timeout passes.
-   */
-  readonly ready: () => Promise<void>;
-  /**
-   * Lifts a target's quarantine and forgets its failures.
-   */
-  readonly retry: (target: RenderTarget) => void;
-  /**
-   * The host's stores, which `HostProvider` provides and the hooks of `sdk-plugin` read.
-   */
-  readonly stores: HostStores;
-}
-//#endregion
 //#region src/host/create-host.d.ts
 /**
  * Creates a host for one page, or for one request on a server.
@@ -130,6 +47,23 @@ export interface HostIntegrationOptions {
  */
 export declare function setupHostIntegration({ host, router }: HostIntegrationOptions): void;
 //#endregion
+//#region src/parts/caught.d.ts
+/**
+ * Writes an error that a React error boundary caught to the console, and leaves the router's
+ * not-found out.
+ */
+/**
+ * Writes an error that an error boundary caught to the console, as React's default does in a
+ * production build, and returns without writing for the router's not-found.
+ *
+ * @remarks
+ *   A page throws the router's not-found for parameters it cannot resolve, and the router's
+ *   boundary renders the product's not-found page in the page's place. React reports every error a
+ *   boundary catches, so a root without this handler writes each such not-found to the console. A
+ *   product passes the handler to `createRoot` and `hydrateRoot` as `onCaughtError`.
+ */
+export declare function onCaughtError(error: unknown): void;
+//#endregion
 //#region src/parts/content.d.ts
 /**
  * Renders the root route's outlet inside the `content` region, so the region's extensions decorate
@@ -143,14 +77,15 @@ export declare function HostContent(): ReactNode;
 //#endregion
 //#region src/parts/not-found.d.ts
 /**
- * Renders the not-found page the router's data describes.
+ * Renders the not-found page that the router's data describes, or the loading page while the
+ * router loads the address again with the routes of the page's releases.
  *
  * @remarks
- *   A page whose plugin a switch turned off names the plugin and offers a button that turns it on.
- *   A page whose plugin a kill switch stopped names the plugin and offers nothing. A quarantined
- *   page offers a retry that lifts the quarantine. Data of another shape, or none, renders a plain
- *   not-found page, which states nothing about the address. The host runs the router's
- *   `beforeLoad` again after a switch or a retry, and the page renders again in this one's place.
+ *   The page treats the router's data as the host's own where the route evaluator threw it, and
+ *   ignores any other data. Where the page's document contains a deployment, a plain
+ *   not-found page renders the loading page on a server and while it hydrates. It renders the
+ *   loading page until the router loaded the address again. The heading takes focus where the page
+ *   renders in place of the page a person is on.
  */
 export declare function HostNotFound({ data }: NotFoundRouteProps): ReactNode;
 //#endregion
@@ -201,7 +136,8 @@ export interface HostRootProps {
  * @remarks
  *   The router renders the root route's component inside a catch boundary of its own, so the
  *   component renders the host's last boundary around the frame, and an error in the frame
- *   renders the failure page and is reported with the target `host`.
+ *   renders the failure page and is reported with the target `host`. The component provides the
+ *   palette's open state, so a control in the frame opens the palette that `Mod+K` opens.
  */
 export declare function HostRoot({ children }: HostRootProps): ReactNode;
 //#endregion
@@ -278,11 +214,14 @@ export type NotFoundData = PageQuarantined | PluginUnavailable;
  *   The routes compile in one call, so the compiler sees every path at once. Each route loads its
  *   page with the modules of the plugins in its `loads`, loads its `data` through the data client
  *   in the router's context, validates its search with its contract's validator, and evaluates its
- *   condition against the host in the router's context. The settings route renders the settings
- *   frame, its index opens the first settings page, and each settings page renders its sections.
- *   The pages import through the manifests' importers as `instrumented` wraps them.
+ *   condition against the host in the router's context. Each route renders the root's not-found
+ *   page in its own place, so a page that throws the router's not-found shows it inside the frame
+ *   and counts no failure. The settings route renders the settings frame, its index opens the first
+ *   settings page, and each settings page renders its sections. The pages import through the
+ *   manifests' importers as `instrumented` wraps them.
  * @param product - The product, with each installed plugin's manifest.
  * @returns The function that compiles the routes under the root, for the root's `addChildren`.
  */
 export declare function createHostRoutes(product: Product): (root: AnyRoute) => readonly AnyRoute[];
-//#endregion
+//#endregion
+export { Host, HostOptions };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { a as HostContent, i as HostNotFound, n as HostRoot, o as createHost, r as HostProvider, s as internalsOf, t as createHostRoutes } from "./create-routes-CkgZV-dU.js";
+import { c as HostProvider, d as HostContent, f as onCaughtError, l as HostNotFound, m as internalsOf, n as HostRoot, p as createHost, t as createHostRoutes } from "./create-routes-D4iCBYZe.js";
 import { subjectOf } from "@stealthscale/sdk-core";
 //#region src/hydration/integration.ts
 /**
@@ -78,4 +78,4 @@ function setupHostIntegration({ host, router }) {
 	else hydrating(host, router);
 }
 //#endregion
-export { HostContent, HostNotFound, HostProvider, HostRoot, createHost, createHostRoutes, setupHostIntegration };
+export { HostContent, HostNotFound, HostProvider, HostRoot, createHost, createHostRoutes, onCaughtError, setupHostIntegration };

package/dist/options-DBsArZKT.d.ts

@@ -0,0 +1,91 @@
+import { DataClientOptions, QueryClient } from "@stealthscale/provider-data";
+import { AccessSource, FlagSource, Product, SessionSource } from "@stealthscale/sdk-core";
+import { HostReport, HostStores, PluginRefused, RenderTarget } from "@stealthscale/sdk-plugin";
+import { SettingStore } from "@stealthscale/settings";
+import { FormGlyphs } from "@stealthscale/component-forms/form";
+//#region src/host/options.d.ts
+/**
+ * Lists what a host is created from.
+ */
+interface HostOptions {
+  /**
+   * Source of decisions on single resources. Every decision is the tenant-wide one without it.
+   */
+  readonly access?: AccessSource | undefined;
+  /**
+   * The transport and the changes stream the host's data client runs on. A sampled transport over
+   * the contracts' samples where left out.
+   */
+  readonly data?: Pick<DataClientOptions, "changes" | "transport"> | undefined;
+  /**
+   * Source of flag values per session. Every flag has its product value or its default without
+   * one.
+   */
+  readonly flags?: FlagSource | undefined;
+  /**
+   * Milliseconds `ready` waits for the flag source's first `identify`. 1,000 by default.
+   */
+  readonly flagsTimeout?: number | undefined;
+  /**
+   * Glyphs the settings sections' forms render: the mark in a checked box, a select's chevron and
+   * the others the forms package names. A form renders no mark it has no glyph for.
+   */
+  readonly glyphs?: FormGlyphs | undefined;
+  /**
+   * Reads and writes flag overrides. On by default outside a production build.
+   */
+  readonly overrides?: boolean | undefined;
+  /**
+   * The resolved product with its plugins' manifests, from `virtual:product`.
+   */
+  readonly product: Product;
+  /**
+   * Failed renders in a row after which a route or an extension is quarantined. 3 by default.
+   */
+  readonly quarantineAfter?: number | undefined;
+  /**
+   * Releases the page did not load at run time, which the host reports as it is created.
+   */
+  readonly refused?: readonly PluginRefused[] | undefined;
+  /**
+   * Receives every entry the host reports. Writes to the console by default.
+   */
+  readonly report?: ((entry: HostReport) => void) | undefined;
+  /**
+   * Source of the session.
+   */
+  readonly session: SessionSource;
+  /**
+   * Where the host keeps a person's switches, settings and placements.
+   */
+  readonly store: SettingStore;
+}
+/**
+ * Describes a host: the state of one page, or of one request on a server.
+ */
+interface Host {
+  /**
+   * The data client of the page or the request, which the router's context contains.
+   */
+  readonly data: QueryClient;
+  /**
+   * Stops listening to the session source, the flag source, the access source and the setting
+   * store, and cancels the data client's fetches.
+   */
+  readonly dispose: () => void;
+  /**
+   * Resolves once the eager plugins' modules are imported and the flag source has identified the
+   * session, or once the flag timeout passes.
+   */
+  readonly ready: () => Promise<void>;
+  /**
+   * Lifts a target's quarantine and forgets its failures.
+   */
+  readonly retry: (target: RenderTarget) => void;
+  /**
+   * The host's stores, which `HostProvider` provides and the hooks of `sdk-plugin` read.
+   */
+  readonly stores: HostStores;
+}
+//#endregion
+export { HostOptions as n, Host as t };

package/dist/{page-7ScZC_LI.js → page-DzeycJUh.js}

@@ -11,7 +11,7 @@ import { Heading } from "@stealthscale/component-typography";
 /**
 * The props a slot without a sample renders with.
 */
-const NONE = {};
+const NONE$1 = {};
 /**
 * Returns the values a slot renders with: each value the extensions placed in a keyed slot match,
 * and no value for a slot that is not keyed.
@@ -52,7 +52,7 @@ function placeholderPageOf(routeId, contract) {
 				children: slot.id
 			}), matchesOf(slot, extensions).map((match) => /* @__PURE__ */ jsx(Slot, {
 				match,
-				props: slot.sample ?? NONE,
+				props: slot.sample ?? NONE$1,
 				slot
 			}, match ?? ""))]
 		}, slot.id))] });

package/dist/releases.d.ts

@@ -0,0 +1,131 @@
+import { t as ProductRenderOptions } from "./render-DRndY-TD.js";
+import { Product, ProductDefinition } from "@stealthscale/sdk-core";
+import { PluginRefused } from "@stealthscale/sdk-plugin";
+import { Catalogues } from "@stealthscale/provider-i18n";
+import { Root } from "react-dom/client";
+//#region src/app/render-deployed.d.ts
+/**
+ * Lists what a product whose page loads releases renders with.
+ */
+export interface DeployedRenderOptions extends Omit<ProductRenderOptions, "refused"> {
+  /**
+   * The product's definition, from `virtual:product`, which the page resolves again with the
+   * releases of its document's deployment.
+   */
+  readonly definition: ProductDefinition;
+}
+/**
+ * Loads the releases the document's deployment lists, and renders the product resolved with them
+ * once the host is ready.
+ *
+ * @remarks
+ *   The host reports each release the page refused. A document without a deployment renders the
+ *   build's product.
+ * @param options - The definition, and what `renderProduct` renders with.
+ * @returns The React root the product renders in, which `unmount` takes down.
+ */
+export declare function renderDeployed({ catalogues, definition, product, ...options }: DeployedRenderOptions): Promise<Root>;
+//#endregion
+//#region src/releases/catalogues.d.ts
+/**
+ * Describes the part of a response a catalogue's fetch reads.
+ */
+interface Fetched {
+  /**
+   * Resolves with the body read as JSON.
+   */
+  readonly json: () => Promise<unknown>;
+  /**
+   * True for a status from 200 to 299.
+   */
+  readonly ok: boolean;
+  /**
+   * The response's status.
+   */
+  readonly status: number;
+}
+/**
+ * Describes how a catalogue's fetch is asked for: with the integrity of the file.
+ */
+interface FetchInit {
+  /**
+   * The file's integrity, in the form `sha384-<base64>`, which the browser checks.
+   */
+  readonly integrity: string;
+}
+/**
+ * Fetches a URL with the integrity of its file.
+ */
+type Fetching = (url: string, init: FetchInit) => Promise<Fetched>;
+//#endregion
+//#region src/releases/preload.d.ts
+/**
+ * Describes the part of a document that the preloader reads and writes.
+ */
+type PreloadDocument = Pick<Document, "baseURI" | "createElement" | "head" | "querySelectorAll">;
+//#endregion
+//#region src/releases/deployed.d.ts
+/**
+ * Lists what a page loads its releases with.
+ */
+export interface DeployedOptions {
+  /**
+   * The page's catalogues, from `virtual:i18n`.
+   */
+  readonly catalogues: Catalogues;
+  /**
+   * The product's definition, from `virtual:product`.
+   */
+  readonly definition: ProductDefinition;
+  /**
+   * The page's document. It contains the deployment, and the preloader writes the preloads of the
+   * releases' modules into it.
+   */
+  readonly document: Pick<Document, "querySelector"> & PreloadDocument;
+  /**
+   * Fetches a release's catalogue with its integrity. The page's `fetch` where left out.
+   */
+  readonly fetching?: Fetching | undefined;
+  /**
+   * Imports a release's `manifest.js` by its absolute URL. The page's `import()` where left out.
+   */
+  readonly importing?: ((url: string) => Promise<unknown>) | undefined;
+  /**
+   * The product the build resolved, from `virtual:product`.
+   */
+  readonly product: Product;
+}
+/**
+ * Describes what a page renders after it loaded the releases of its deployment.
+ */
+export interface Deployed {
+  /**
+   * The page's catalogues with the namespace of each admitted release.
+   */
+  readonly catalogues: Catalogues;
+  /**
+   * The product with the plugin of each admitted release.
+   */
+  readonly product: Product;
+  /**
+   * Each release the page did not load: the loader's refusals, then the resolution's.
+   */
+  readonly refused: readonly PluginRefused[];
+}
+/**
+ * Loads the releases in a page's document and resolves the product with them.
+ *
+ * @remarks
+ *   A document without a deployment renders the build's product. Where the page cannot read the
+ *   deployment, the page refuses every release with the reason `deployment`, and the build's
+ *   product renders with an empty list of releases. The product's `releases` contains the id of
+ *   every release in the document, so the page's first render withholds the same plugins as the
+ *   server's render. After the function reads a deployment, it registers the preloader of the
+ *   document. The preloader writes the preloads of a release's module when the release imports that
+ *   module.
+ * @param options - The page's document and catalogues, the definition, the build's product, and how
+ *   to fetch and to import.
+ * @returns The catalogues and the product to render, and each release the page refused.
+ */
+export declare function deployedProduct(options: DeployedOptions): Promise<Deployed>;
+//#endregion