@greensecurity/javascript-sdk 0.46.0 → 0.47.0-beta.0

package/src/apps/components.ts

@@ -163,11 +163,176 @@ const isConfirmCloseMessages = (v: unknown): v is ConfirmCloseMessages =>
 
 const TABLE_CELL = { align: p.enum(["start", "center", "end"] as const), width: p.enum(WIDTHS) };
 
+// ---------------------------------------------------------------------------------------------
+// Charts
+//
+// Charts take data only. Colours come from a named `theme`; there are no colour, font, size or
+// style props. Every value is a finite number >= 0 (v1 draws no negative axis), and every label
+// and series name is visible text the host draws on an axis, legend or tooltip.
+
+/** Named palettes the host draws charts with. The host uses `"green"` when `theme` is omitted. */
+export const CHART_THEMES = ["green", "grayscale", "vibrant"] as const;
+
+/** Most series a stacked, line or area chart may draw: one per palette colour. */
+export const MAX_CHART_SERIES = 6;
+/**
+ * Largest accepted chart value. Every chart caps its item and series counts, so with each value at
+ * most this, any total a chart computes (a stack, a pie) stays finite; two values near
+ * `Number.MAX_VALUE` would otherwise sum to `Infinity`.
+ */
+export const MAX_CHART_VALUE = Number.MAX_SAFE_INTEGER;
+
+/** Longest label or series name, in characters. */
+export const MAX_CHART_LABEL_LENGTH = 60;
+
+/** One bar or slice: `label` names it, `value` is its size. */
+export interface ChartDatum { label: string; value: number }
+/** A named series with one value per label of the chart it belongs to. */
+export interface ChartSeries { name: string; values: number[] }
+/** Labels along the category axis and the series drawn against them. */
+export interface SeriesChartData { labels: string[]; series: ChartSeries[] }
+/** Bars and a line drawn over the same labels. */
+export interface ComboChartData { labels: string[]; bars: ChartSeries; line: ChartSeries }
+/**
+ * The detail of a chart's `onClick`: the position and label of the pressed bar, point or slice,
+ * its value, and, on a multi-series chart, the name of its series.
+ */
+export interface ChartClickEvent { index: number; label: string; value: number; series?: string }
+
+/** Item-count bounds for {@link isChartData}. */
+export interface ChartDataLimits { minItems: number; maxItems: number }
+/** Label- and series-count bounds for {@link isSeriesChartData}; `maxSeries` defaults to {@link MAX_CHART_SERIES}. */
+export interface SeriesChartDataLimits { minLabels: number; maxLabels: number; maxSeries?: number }
+/** Label-count bounds for {@link isComboChartData}. */
+export interface ComboChartDataLimits { minLabels: number; maxLabels: number }
+
+/** The bounds each chart component's `data` is checked against. */
+export const CHART_DATA_LIMITS = {
+  BarChart: { minItems: 1, maxItems: 31 },
+  HorizontalBarChart: { minItems: 1, maxItems: 25 },
+  StackedBarChart: { minLabels: 1, maxLabels: 31, maxSeries: MAX_CHART_SERIES },
+  LineChart: { minLabels: 2, maxLabels: 60, maxSeries: MAX_CHART_SERIES },
+  AreaChart: { minLabels: 2, maxLabels: 60, maxSeries: MAX_CHART_SERIES },
+  ComboChart: { minLabels: 1, maxLabels: 31 },
+  // The host folds everything past the sixth slice into one "Other" slice.
+  PieChart: { minItems: 1, maxItems: 50 },
+} as const satisfies Record<string, ChartDataLimits | SeriesChartDataLimits | ComboChartDataLimits>;
+
+// Plain data only, as JSON and remote-dom carry it: no class instances (Date, Map, a subclassed
+// Array) whose prototype the host would otherwise have to trust.
+const isPlainObject = (v: unknown): v is Record<string, unknown> => {
+  if (typeof v !== "object" || v === null || Array.isArray(v)) return false;
+  const proto: unknown = Object.getPrototypeOf(v);
+  return proto === Object.prototype || proto === null;
+};
+const isPlainArray = (v: unknown): v is unknown[] => Array.isArray(v) && Object.getPrototypeOf(v) === Array.prototype;
+// Exactly these keys: the shapes are closed, which also bounds their nesting depth.
+const hasExactKeys = (v: Record<string, unknown>, keys: readonly string[]): boolean => {
+  const own = Object.keys(v);
+  return own.length === keys.length && keys.every((k) => Object.prototype.hasOwnProperty.call(v, k));
+};
+const isChartValue = (v: unknown): v is number =>
+  typeof v === "number" && Number.isFinite(v) && v >= 0 && v <= MAX_CHART_VALUE;
+const isChartLabel = (v: unknown): v is string => isVisibleText(v, MAX_CHART_LABEL_LENGTH);
+
+// Indexed loops rather than `every`, which skips the holes of a sparse array.
+function isLabelList(v: unknown, min: number, max: number): v is string[] {
+  if (!isPlainArray(v) || v.length < min || v.length > max) return false;
+  const seen = new Set<string>();
+  for (let i = 0; i < v.length; i++) {
+    const label = v[i];
+    if (!isChartLabel(label) || seen.has(label)) return false;
+    seen.add(label);
+  }
+  return true;
+}
+
+function isChartSeries(v: unknown, length: number): v is ChartSeries {
+  if (!isPlainObject(v) || !hasExactKeys(v, ["name", "values"]) || !isChartLabel(v["name"])) return false;
+  const values = v["values"];
+  if (!isPlainArray(values) || values.length !== length) return false;
+  for (let i = 0; i < values.length; i++) if (!isChartValue(values[i])) return false;
+  return true;
+}
+
+/**
+ * `ChartDatum[]` with between `minItems` and `maxItems` items, each a visible, unique label of at
+ * most {@link MAX_CHART_LABEL_LENGTH} characters and a value from 0 to {@link MAX_CHART_VALUE}.
+ */
+export function isChartData(value: unknown, limits: ChartDataLimits): value is ChartDatum[] {
+  if (!isPlainArray(value) || value.length < limits.minItems || value.length > limits.maxItems) return false;
+  const seen = new Set<string>();
+  for (let i = 0; i < value.length; i++) {
+    const item = value[i];
+    if (!isPlainObject(item) || !hasExactKeys(item, ["label", "value"])) return false;
+    const label = item["label"];
+    if (!isChartLabel(label) || seen.has(label) || !isChartValue(item["value"])) return false;
+    seen.add(label);
+  }
+  return true;
+}
+
+/** Label of the slice a pie chart creates when it combines items beyond {@link MAX_CHART_SERIES}. */
+export const CHART_OTHER_LABEL = "Other";
+
+/**
+ * Pie chart data: {@link isChartData} with `CHART_DATA_LIMITS.PieChart`. When there are more
+ * items than {@link MAX_CHART_SERIES}, the host combines the extras into a {@link CHART_OTHER_LABEL}
+ * slice, so a caller's own `Other` label (any case, ignoring surrounding spaces) is rejected:
+ * the chart would show two slices with that name and their click events could not be told apart.
+ */
+export function isPieChartData(value: unknown): value is ChartDatum[] {
+  if (!isChartData(value, CHART_DATA_LIMITS.PieChart)) return false;
+  if (value.length <= MAX_CHART_SERIES) return true;
+  const reserved = CHART_OTHER_LABEL.toLowerCase();
+  return value.every((item) => item.label.trim().toLowerCase() !== reserved);
+}
+
+/**
+ * `SeriesChartData` with between `minLabels` and `maxLabels` unique labels and between 1 and
+ * `maxSeries` uniquely named series, each with exactly one value from 0 to {@link MAX_CHART_VALUE} per label.
+ */
+export function isSeriesChartData(value: unknown, limits: SeriesChartDataLimits): value is SeriesChartData {
+  if (!isPlainObject(value) || !hasExactKeys(value, ["labels", "series"])) return false;
+  const labels = value["labels"];
+  const series = value["series"];
+  const maxSeries = limits.maxSeries ?? MAX_CHART_SERIES;
+  if (!isLabelList(labels, limits.minLabels, limits.maxLabels)) return false;
+  if (!isPlainArray(series) || series.length < 1 || series.length > maxSeries) return false;
+  const names = new Set<string>();
+  for (let i = 0; i < series.length; i++) {
+    const s = series[i];
+    if (!isChartSeries(s, labels.length) || names.has(s.name)) return false;
+    names.add(s.name);
+  }
+  return true;
+}
+
+/**
+ * `ComboChartData` with between `minLabels` and `maxLabels` unique labels, and a `bars` and a
+ * `line` series with different names, each with exactly one value from 0 to {@link MAX_CHART_VALUE} per label.
+ */
+export function isComboChartData(value: unknown, limits: ComboChartDataLimits): value is ComboChartData {
+  if (!isPlainObject(value) || !hasExactKeys(value, ["labels", "bars", "line"])) return false;
+  const labels = value["labels"];
+  const bars = value["bars"];
+  const line = value["line"];
+  return isLabelList(labels, limits.minLabels, limits.maxLabels) &&
+    isChartSeries(bars, labels.length) && isChartSeries(line, labels.length) && bars.name !== line.name;
+}
+
+const chart = <T>(check: (v: unknown) => v is T) => ({
+  props: { data: p.json(check, { required: true }), theme: p.enum(CHART_THEMES), interactive: p.boolean() },
+  events: { onClick: ev<ChartClickEvent>("click") },
+  children: [] as const,
+});
+
 // ---------------------------------------------------------------------------------------------
 // Catalog
 
 export const COMPONENTS = {
-  // View roots. An app's view component must render exactly one of these at its top level.
+  // View roots. An app's view component must render exactly one of these at its top level:
+  // ContextView on a surface, SettingsView on the settings page, PageView on an app page.
   ContextView: spec("ui-context-view", {
     root: true,
     props: { title: p.string({ required: true, maxLength: 100 }), description: p.string({ maxLength: 300 }), externalLink: p.json(isExternalLink) },
@@ -190,6 +355,13 @@ export const COMPONENTS = {
     // `values` maps every form field's `name` to its current value.
     events: { onSave: ev<Record<string, string>>("save") },
   }),
+  // An app page (`ui_extensions.routes`), rendered full width inside the portal's own chrome. The
+  // title is the page header; `actions` join the portal header's actions, `banner` sits above the body.
+  PageView: spec("ui-page-view", {
+    root: true,
+    props: { title: p.string({ required: true, maxLength: 100 }), description: p.string({ maxLength: 300 }) },
+    slots: ["actions", "banner"] as const,
+  }),
 
   // Layout
   Box: spec("ui-box", { props: { ...layout, ...typography }, text: true }),
@@ -368,6 +540,16 @@ export const COMPONENTS = {
   FormFieldGroup: spec("ui-form-field-group", {
     props: { legend: p.string({ maxLength: 200 }), description: p.string({ maxLength: 500 }), layout: p.enum(["row", "column"] as const) },
   }),
+
+  // Charts. Data only: `theme` picks the palette, `interactive` turns on press feedback and
+  // tooltips, and `onClick` receives a `ChartClickEvent`. Bounds are in `CHART_DATA_LIMITS`.
+  BarChart: spec("ui-bar-chart", chart((v): v is ChartDatum[] => isChartData(v, CHART_DATA_LIMITS.BarChart))),
+  HorizontalBarChart: spec("ui-horizontal-bar-chart", chart((v): v is ChartDatum[] => isChartData(v, CHART_DATA_LIMITS.HorizontalBarChart))),
+  StackedBarChart: spec("ui-stacked-bar-chart", chart((v): v is SeriesChartData => isSeriesChartData(v, CHART_DATA_LIMITS.StackedBarChart))),
+  LineChart: spec("ui-line-chart", chart((v): v is SeriesChartData => isSeriesChartData(v, CHART_DATA_LIMITS.LineChart))),
+  AreaChart: spec("ui-area-chart", chart((v): v is SeriesChartData => isSeriesChartData(v, CHART_DATA_LIMITS.AreaChart))),
+  ComboChart: spec("ui-combo-chart", chart((v): v is ComboChartData => isComboChartData(v, CHART_DATA_LIMITS.ComboChart))),
+  PieChart: spec("ui-pie-chart", chart(isPieChartData)),
 } as const;
 
 // Checked by assignment rather than `satisfies`: `satisfies` would hand `ComponentSpec` to every

package/src/apps/context.ts

@@ -14,6 +14,19 @@ export interface ObjectContext {
   id: number;
 }
 
+/**
+ * The app page a view is rendered on (`environment.surfaceId` is `"page"`). Paths are in the app's
+ * own space, without the host's `/{portal}/apps/{appId}/pages` prefix.
+ */
+export interface PageRoute {
+  /** The declared route path from `ui_extensions.routes`, e.g. `/reports/:id`. */
+  path: string;
+  /** The concrete path being shown, e.g. `/reports/7`. */
+  pathname: string;
+  /** Param values by name (`{ id: "7" }`), percent-decoded. Always strings. */
+  params: Record<string, string>;
+}
+
 export interface AppUserToken {
   /** `gsu_…`. Acts as the viewer, limited to the app's manifest permissions ∩ the viewer's role. */
   accessToken: string;
@@ -56,12 +69,24 @@ export interface ExtensionContext {
     portal: Portal;
     platform: "web" | "ios" | "android";
     objectContext?: ObjectContext;
+    /**
+     * The query string of the page's address. On an app page anyone can set these by sharing a
+     * link, so treat them as untrusted user input. Empty on drawer, inline and settings views.
+     */
     queryParams: Record<string, string>;
+    /**
+     * The `envParams` of the `HostApi.navigate` call, made by this app, that led to this view.
+     * Only this app can set them, they never appear in an address, and each navigation delivers
+     * them to one view once. Empty when the view did not open from a navigation.
+     */
+    navParams: Record<string, string>;
     constants: AppConstants;
     /** Base URL for `@greensecurity/javascript-sdk`, e.g. `https://www.greensecurityllc.com/api`. */
     apiBaseUrl: string;
     /** Set while the view is served by `apps-cli dev` instead of the published bundle. */
     devSessionId?: string;
+    /** Set on app pages only: which of the app's routes is shown, and its params. */
+    route?: PageRoute;
   };
   /** Injected by the host and replaced through `SandboxExports.updateContext` before expiry. */
   auth: AppTokens;

package/src/apps/devpreview.ts

@@ -11,6 +11,9 @@ import * as z from "zod/v4";
 import {
   addCspBudgetIssue,
   addDuplicateViewportIssues,
+  addRouteIssues,
+  APP_ROUTES_MAX,
+  appRouteSchema,
   CSP_SOURCES_MAX_TOTAL_CHARS,
   cspSourcesTotalChars,
   appConstantsSchema,
@@ -44,7 +47,9 @@ const devCspSourceSchema = z.union([
 ]);
 
 /**
- * `green-app.dev.json`. It may override constants, CSP sources and views while iterating.
+ * `green-app.dev.json`. It may override constants, CSP sources, views and routes (app pages) while
+ * iterating, so a new view or page can be previewed before it is published. Views and routes are
+ * UI placements and grant nothing, and a dev session is shown only to its developer.
  * Permissions and the bundle cannot be overridden: permissions are granted to the app's role on
  * `upload`, and the bundle comes from the dev server.
  */
@@ -54,24 +59,27 @@ export const devManifestSchema = z
     constants: appConstantsSchema.optional(),
     ui_extensions: z.strictObject({
       views: z.array(appViewSchema).max(200).optional(),
+      routes: z.array(appRouteSchema).max(APP_ROUTES_MAX).optional(),
       csp: z.strictObject({
         connect_src: z.array(devCspSourceSchema).max(CSP_SOURCES_MAX_PER_DIRECTIVE).optional(),
         image_src: z.array(devCspSourceSchema).max(CSP_SOURCES_MAX_PER_DIRECTIVE).optional(),
       }).optional(),
     }).optional(),
   })
-  // Same invariant as published manifests: dev views replace the published list, so a duplicate
-  // here would make view resolution order-dependent.
+  // Same invariants as published manifests: dev views and routes replace the published lists, so a
+  // duplicate here would make view resolution or route matching order-dependent.
   .superRefine((dev, ctx) => {
     addDuplicateViewportIssues(dev.ui_extensions?.views, ctx, ["ui_extensions", "views"]);
+    addRouteIssues(dev.ui_extensions?.routes, ctx, ["ui_extensions", "routes"]);
     addCspBudgetIssue(dev.ui_extensions?.csp, ctx, ["ui_extensions", "csp"]);
   });
 
 export type DevManifest = z.infer<typeof devManifestSchema>;
 
 /**
- * Applies a dev manifest over the published one. Object fields merge; arrays (`views`, CSP
- * sources) replace, so a developer can drop a view locally without editing the base file.
+ * Applies a dev manifest over the published one. Object fields merge; arrays (`views`, `routes`,
+ * CSP sources) replace, so a developer can drop a view or a page locally without editing the base
+ * file.
  * Throws {@link DevManifestError} if the merged CSP sources exceed the header budget.
  */
 export function mergeDevManifest(base: AppManifestV2, dev: DevManifest): AppManifestV2 {
@@ -85,14 +93,19 @@ export function mergeDevManifest(base: AppManifestV2, dev: DevManifest): AppMani
 
   if (base.ui_extensions === undefined && dev.ui_extensions === undefined) return merged;
 
-  // A preview renders views, and every rendered view needs a version (`ExtensionContext.app.version`).
-  // A dev file cannot supply one, so a versionless (v1) base cannot be previewed with views.
+  // A preview renders views and pages, and every rendered one needs a version
+  // (`ExtensionContext.app.version`). A dev file cannot supply one, so a versionless (v1) base
+  // cannot be previewed with views or routes.
   if (devUi.views !== undefined && devUi.views.length > 0 && base.version === undefined) {
     throw new DevManifestError("the base manifest needs a version before its views can be previewed");
   }
+  if (devUi.routes !== undefined && devUi.routes.length > 0 && base.version === undefined) {
+    throw new DevManifestError("the base manifest needs a version before its routes can be previewed");
+  }
 
   const ui: NonNullable<AppManifestV2["ui_extensions"]> = { ...baseUi };
   if (devUi.views !== undefined) ui.views = devUi.views;
+  if (devUi.routes !== undefined) ui.routes = devUi.routes;
   if (devUi.csp !== undefined) {
     ui.csp = {
       ...(baseUi.csp ?? { purpose: "Local development" }),

package/src/apps/hooks/index.ts

@@ -6,11 +6,13 @@
  */
 
 import { useContext } from "react";
-import type { ExtensionContext } from "../context.js";
+import type { ExtensionContext, PageRoute } from "../context.js";
 import { TOAST_MAX_LENGTH, type HostApi, type ToastType } from "../protocol.js";
 import { isRouteDescriptor, type RouteDescriptor } from "../route.js";
 import { AppSessionContext, currentSession, type AppSessionValue } from "../runtime/session.js";
 
+export { createAppStore, type AppStore, type AppStoreListener, type AppStoreUpdate } from "./store.js";
+
 const TOAST_TYPES: readonly ToastType[] = ["success", "caution", "pending"];
 
 function useSessionValue(hook: string): AppSessionValue {
@@ -26,6 +28,40 @@ export function useExtensionContext(): ExtensionContext {
   return useSessionValue("useExtensionContext").context;
 }
 
+/**
+ * The app page being shown, on views rendered as one of the app's `ui_extensions.routes`
+ * (`environment.route`): the declared `path` (`/reports/:id`), the concrete `pathname`
+ * (`/reports/7`) and the decoded `params` (`{ id: "7" }`, always strings). `undefined` on every
+ * other view. Re-renders with the new route when the host moves to another path of the same page
+ * (an `updateContext`), so read params here rather than once on mount.
+ *
+ * ```tsx
+ * const route = usePageRoute();
+ * const id = Number(route?.params["id"]);
+ * ```
+ */
+export function usePageRoute(): PageRoute | undefined {
+  return useSessionValue("usePageRoute").context.environment.route;
+}
+
+const NO_PARAMS: Readonly<Record<string, string>> = Object.freeze({});
+
+/**
+ * The `envParams` this app passed to the `navigate` call that opened this view
+ * (`environment.navParams`). Only this app can set them, and they never appear in an address, so
+ * they are the place for navigation data the view relies on. The page's URL query
+ * (`environment.queryParams`) is different: anyone can put anything in a link, so treat it as
+ * untrusted input. Empty (`{}`) when the view did not open from a navigation.
+ *
+ * ```tsx
+ * // VendorPanel: navigate({ type: "appPage", path: "/reports", envParams: { vendorId: "42" } })
+ * const { vendorId } = useNavParams();
+ * ```
+ */
+export function useNavParams(): Readonly<Record<string, string>> {
+  return useSessionValue("useNavParams").context.environment.navParams ?? NO_PARAMS;
+}
+
 /** The host API proxy for the view being rendered. Every method is async. */
 export function useHostApi(): HostApi {
   return useSessionValue("useHostApi").host;
@@ -68,7 +104,11 @@ export function showToast(message: string, opts: ShowToastOptions = {}): Promise
   }
 }
 
-/** Asks the host to navigate. Apps name a destination; the host owns its routes. */
+/**
+ * Asks the host to navigate. Apps name a destination; the host owns its routes. To open one of
+ * the app's own pages, pass a concrete path in the app's space:
+ * `navigate({ type: "appPage", path: "/reports/7" })` (not `/reports/:id`).
+ */
 export function navigate(to: RouteDescriptor, opts: { host?: HostApi } = {}): Promise<void> {
   if (!isRouteDescriptor(to)) return Promise.reject(new TypeError("navigate() needs a valid RouteDescriptor"));
   try {

package/src/apps/hooks/store.ts

@@ -0,0 +1,115 @@
+/*
+ * Hand-written (not generated by Speakeasy). Third-party app developer kit (C10); see
+ * docs/third-party-apps/plan.md.
+ *
+ * State shared by the views of one app. The host runs one sandbox (one worker) per app and mounts
+ * every view of that app into it, each as its own React root. React context therefore stops at a
+ * view's edge, but module state does not: a store created at module level is the same object in
+ * every view.
+ */
+
+import { useCallback, useRef, useSyncExternalStore } from "react";
+
+export type AppStoreListener<T> = (state: T, previous: T) => void;
+
+/** Fields to change, or a function of the current state that returns them. */
+export type AppStoreUpdate<T> = Partial<T> | ((state: T) => Partial<T>);
+
+export interface AppStore<T extends object> {
+  /** The current state. The same object until a `setState` changes a field. */
+  getState(): T;
+  /**
+   * Shallow-merges `update` into the state, like React's class `setState`: fields left out keep
+   * their values. A new state object is made, and listeners run, only when a field changes
+   * (`Object.is`), so setting a field to its current value re-renders nothing.
+   */
+  setState(update: AppStoreUpdate<T>): void;
+  /** Calls `listener` after each change, with the new and the previous state. Returns the unsubscribe. */
+  subscribe(listener: AppStoreListener<T>): () => void;
+  /**
+   * Reads the store in a component and re-renders it when the value changes. Without a selector
+   * the component re-renders on every change; with one, only when the selected value changes
+   * (`Object.is`), so select a field (or derive a primitive) rather than build a new object.
+   * The subscription ends when the component unmounts.
+   */
+  useStore(): T;
+  useStore<S>(selector: (state: T) => S): S;
+}
+
+/**
+ * Creates a store that every view of this app can read and update. Create it once, at module
+ * level, in a file the views import:
+ *
+ * ```ts
+ * // src/store.ts
+ * export const notes = createAppStore({ saved: 0 });
+ * // in a view
+ * const saved = notes.useStore((s) => s.saved);
+ * notes.setState((s) => ({ saved: s.saved + 1 }));
+ * ```
+ *
+ * What it guarantees, and what it does not:
+ * - Shared by every view of this app that is open in the same browser tab (web) or the same app
+ *   session (iOS, Android): a ContextView, its FocusView, the settings page and the app's pages
+ *   all see one state, and an update in one re-renders the others.
+ * - In memory only. Nothing is written to storage or sent anywhere.
+ * - Lost whenever the sandbox restarts: after a crash, a rebuild in a dev preview, sign-out, a
+ *   reload of the web page, or a restart of the mobile app. Each restart begins again from
+ *   `initial`. Keep anything that must last in your own backend or the Secret Store.
+ * - Never shared with other apps: each app has its own sandbox.
+ * - Not shared across devices, browser tabs or users.
+ */
+export function createAppStore<T extends object>(initial: T): AppStore<T> {
+  let state = initial;
+  const listeners = new Set<AppStoreListener<T>>();
+
+  const store: AppStore<T> = {
+    getState: () => state,
+
+    setState(update) {
+      const patch = typeof update === "function" ? update(state) : update;
+      const keys = Object.keys(patch) as Array<keyof T>;
+      if (!keys.some((key) => !Object.is(state[key], patch[key]))) return;
+      const previous = state;
+      state = { ...state, ...patch };
+      for (const listener of [...listeners]) listener(state, previous);
+    },
+
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+
+    useStore: function useStore<S>(selector?: (state: T) => S): S | T {
+      return useStoreValue(store, selector);
+    } as AppStore<T>["useStore"],
+  };
+  return store;
+}
+
+/**
+ * `useSyncExternalStore` over `store`. `store.subscribe` is read at render time, so it is the
+ * store's own function (or whatever replaced it), and the subscription follows it.
+ */
+function useStoreValue<T extends object, S>(store: AppStore<T>, selector?: (state: T) => S): S | T {
+  // The last selection, so a selector that derives a new object from an unchanged state still
+  // gives React the same snapshot (React requires a stable snapshot between changes).
+  const cache = useRef<{ state: T; selector: ((state: T) => S) | undefined; value: S | T } | null>(null);
+  const subscribe = store.subscribe;
+  const onStoreChange = useCallback((notify: () => void) => subscribe(() => notify()), [subscribe]);
+
+  const getSnapshot = (): S | T => {
+    const current = store.getState();
+    const cached = cache.current;
+    if (cached && cached.state === current && cached.selector === selector) return cached.value;
+    const value = selector ? selector(current) : current;
+    // A changed state whose selection is equal keeps the previous value, so the view skips a render.
+    const stable = cached && Object.is(cached.value, value) ? cached.value : value;
+    cache.current = { state: current, selector, value: stable };
+    return stable;
+  };
+
+  return useSyncExternalStore(onStoreChange, getSnapshot, getSnapshot);
+}