@happyvertical/smrt-svelte 0.55.10 → 0.55.11

package/AGENTS.md

@@ -19,6 +19,7 @@ subpath you are editing. This file keeps what holds in every module.
 | `src/components/app/` (`./app`) | `AppShell` (Provider + ThemeProvider + theme CSS + AdminShell + nav/dock slots), `OwnerSetupForm` (props-driven first-run owner form), `ShellSettingsPage`, `RuntimeDiagnosticsWebMcp`. Browser-only; no `$app/*` or server imports | [agents/workspace.md](agents/workspace.md#app-shell-and-owner-setup-app) |
 | `src/components/workspace/` (`./workspace` + `./web`) | the AdminShell family and its principles, the legacy ToolsDock surface, the `./web` activity-feed and `updateAvailable` adapters, and server-side dock gates | [agents/workspace.md](agents/workspace.md) |
 | `src/components/command-palette/` (`./command-palette`) | `CommandPalette` trigger + dialog, `PaletteProvider` contract, nav and manifest providers (#3713) | [agents/command-palette.md](agents/command-palette.md) |
+| `src/components/cookbook/` (`./cookbook` + `./cookbook/server`) | cookbook-driven app shell: pure `buildCookbookShell` (cookbook + recipe catalog to `AppShell` sections, entries, layout, theme, section overviews, recipe surfaces), `CookbookApp` / `CookbookSectionPage`, and the server `loadCookbookApp` (file + installed manifests + validation); ported from smrt-planner (#3749) | [agents/cookbook-shell.md](agents/cookbook-shell.md) |
 | `src/components/overview/` (`./overview` + `./overview/server`) | customizable overview surfaces: `OverviewGrid` flow grid (span 1-4, keyboard reorder/resize) joined to the shell's layout edit mode, host-owned `createOverview` controller, widget registry with versioned option schemas validated on save and load, the server `load(options, ctx)` contract (`loadOverview`), the metric/chart/records/shortcuts/note core widgets, and `registerRecipeWidgets` (recipe `widget` surfaces to registry registrations, injected module resolver) (#3727); production persistence is `@happyvertical/smrt-preferences` (kind `overview`) | [agents/overview-surfaces.md](agents/overview-surfaces.md) |
 | `src/web/remote-query.svelte.ts` | Svelte 5 binding for query-shaped remote pages: rows, page, totals, loading/refreshing/stale/error, retry, last-updated, and query-scoped live subscriptions (#2445) | — |
 | `src/web/list-data-surface.svelte.ts` (`mountListDataSurface`) | Registers an existing non-`DataTable` list (mirroring a `DataTableController`) as a mounted `DataSurfaceDescriptor`; a same-behavior port of `registerContentListDataSurface`, not yet unified behind smrt-ui (#2917). The module doc comment is the authoritative list of divergences (#2906) | — |

package/agents/cookbook-shell.md

@@ -0,0 +1,176 @@
+# smrt-svelte/cookbook
+
+Module semantics for `src/components/cookbook/` (`./cookbook` and
+`./cookbook/server`, #3749). Package orientation and cross-module invariants are
+in [../AGENTS.md](../AGENTS.md); the document it reads is the cookbook v1
+contract ([core cookbook.md](../../core/agents/cookbook.md)).
+
+A **cookbook-driven app shell**: given `smrt.cookbook.json` and the installed
+packages' recipes, render the navigation sections, recipe entries, layout, theme
+and section overview pages that smrt-planner showed, so a generated app and the
+planner preview draw the same shell. Logic ported from smrt-planner
+(`+layout.svelte`, `recipes/sections.ts`, `sections/*`, `overviews/*`,
+`theme/*`); the planner-only editor, option/help pages, package browser and
+sample data source are not part of it.
+
+## Entries
+
+| Entry | Contents |
+|---|---|
+| `./cookbook/server` | Svelte-free and Node-safe. `loadCookbookApp` (file + manifests + validation), `readInstalledManifests`, `hasCookbook`, and the pure builder/catalog/theme functions and types. Use it in `+layout.server.ts`. |
+| `./cookbook` | Everything above that is browser-safe, plus `CookbookApp`, `CookbookSectionPage`, `applyCookbookTheme`, `createCookbookRegistry`, `createSectionOverview`. |
+
+## Pure core (no DOM, Node-testable)
+
+- **`catalogFromManifests(manifests)`** turns package `manifest.json` objects
+  into a `CookbookCatalog` (`recipes` trimmed to what the shell reads, `models`
+  with package id, description and `exposed`). Recipe order is manifest order;
+  a repeated id keeps the first. `narrowCatalog(catalog, cookbook)` keeps only
+  the selected recipes and the models they or the cookbook's `features` name, so
+  a load serializes a few KB instead of the whole workspace.
+- **`buildCookbookShell({ cookbook, catalog, ... })`** returns a `CookbookShell`:
+  `navGroups` for `AppShell` (`navMode: 'sections'`, one group per suggested
+  section, icon and section-page `href`), `layout` (the cookbook's, passed to
+  the shell, which applies order/hidden/labels itself), `sections` and `entries`
+  (every entry by stable id), `theme`, `overviews`, recipe surfaces
+  (`shellWidgets`, `routes`, `settingsPanels`, `widgets`), `policies`, and
+  `issues`. It never throws for cookbook content: an unknown recipe, a nav model
+  the catalog lacks or a feature that is not exposed becomes an `issues` entry
+  and is left out.
+- **Ids are the contract.** Section layout ids are `section:<id>` (a recipe's
+  `section`, else its `group`, else the recipe) or `custom:<slug>` (the layout's
+  own); entries are `item:<package>:<Model>[:<key>]`. They never name labels or
+  hrefs, so renames and route changes keep a saved layout valid. Do not change
+  `navItemId`/`buildNavSections` without the planner: both read the same
+  cookbooks.
+- **Section order** follows the first recipe of each section in **catalog
+  order** (not the cookbook's sorted list), then the cookbook layout's
+  `sectionOrder`. Pass `recipeOrder` to pin it (the planner's overlay order).
+- **Entries**: label, icon (`fileText` when the recipe names none), description
+  (recipe text, else the model description, else a plain fallback), `noun` and
+  `filter` carried through. Feature models share the `More` section after the
+  recipes' sections.
+- **Paths** are options: `entryPath` (default `/m/<package>/<Model>/[<key>/]`),
+  `sectionPath` (default `/s/<slug>/`, slug = layout id with the first `:`
+  turned into `-`), and `href` (a prefix or query helper applied to both).
+- **Overviews**: one definition per suggested section and per layout custom
+  section (`defineOverview`), id = the section's layout id, so a cookbook's
+  `overviews` key survives a section rename. Defaults are a `shortcuts` widget;
+  with `dataWidgets: true` they add a `metric` count and `records` list of the
+  section's lead model (first nav model of its first recipe), which need the
+  host's loaders. The cookbook's stored override is carried untouched
+  (untrusted JSON, `null` when absent or empty) for `resolveOverview` /
+  `createOverview` to validate; an override for an unknown page, or a malformed
+  one, is an `issues` entry.
+- **Theme**: `resolveCookbookTheme` is lenient (a bad colour or font is ignored;
+  `validateCookbook` is where it is rejected). A brand colour becomes the preset
+  id `cookbook-brand-<hex>[-<font>]`; the colour/font pair is encoded in the id
+  because `ThemeProvider` looks a registered theme up once per id.
+- **Recipe surfaces**: `shell-widget` surfaces are returned with their slot (a
+  smrt-svelte `ShellSlot`; the equality with `RecipeShellSlot` is a typechecked
+  assertion), `route` and `settings-panel` as data, `widget` surfaces grouped by
+  recipe for `registerRecipeWidgets`. The builder never imports a component.
+
+## `CookbookApp`
+
+`AppShell` with the builder's output. Props: `cookbook`, `catalog`, any
+`AppShell` prop (title, logo, `storageKey`, `user`, `permissions`, `dock`,
+`slotItems`, `settingsHref`, ...), and:
+
+- `loaders` (`metric` / `records` / `chart` data loaders; with `metric` and
+  `records` the section pages add the count and latest records),
+- `widgetContext` (host capabilities for browser-side widget loads),
+- `resolveExport` (a static map of dynamic imports; turns a recipe export
+  reference into a component, used for `shell-widget` slot items and recipe
+  `widget` registration; without it those surfaces are ignored),
+- `oncookbookchange(cookbook)` called with the full cookbook after a layout or
+  overview edit (layout edits come from the shell's pencil toggle, enabled with
+  `layoutEditing`). Without it edits live in memory. Persisting them is the
+  host's job; feeding the result back as `cookbook` is safe.
+
+Layout and overview edits are kept in local `$state.raw` copies that follow the
+`cookbook` prop whenever it changes. The widget registry is rebuilt only when
+the recipes' widget surfaces change by content, not on every edit.
+
+Theme: `applyCookbookTheme` registers a brand colour with smrt-ui
+(`createThemeFromColor` + `registerTheme`) and returns the preset for
+`ThemeProvider`; an unknown preset name falls back to `smrt`.
+
+**SSR**: the shell, nav, title and theme render on the server. The widget
+registry, recipe widgets and slot items are resolved in effects (a bundled
+`resolveExport` is async), so a section page's overview appears after hydration,
+not in the server HTML.
+
+## `CookbookSectionPage`
+
+A section's own page: title, icon and description (the user's renames win over
+the suggestion), the overview grid, and, in the shell's layout edit mode, the
+section's entries as a sortable menu. A section without an overview (a custom id
+outside the overview id pattern) shows its menu as cards. Mount it from one
+route: `s/[slug]/+page.svelte` renders
+`<CookbookSectionPage slug={page.params.slug} />`. It must be inside
+`CookbookApp`.
+
+## Using it in an app
+
+```ts
+// +layout.server.ts
+import { loadCookbookApp } from '@happyvertical/smrt-svelte/cookbook/server';
+export const load = async () => loadCookbookApp(); // { cookbook, catalog, warnings }
+```
+
+```svelte
+<!-- +layout.svelte -->
+<script lang="ts">
+import { CookbookApp } from '@happyvertical/smrt-svelte/cookbook';
+let { data, children } = $props();
+</script>
+<CookbookApp cookbook={data.cookbook} catalog={data.catalog} layoutEditing>
+  {@render children()}
+</CookbookApp>
+```
+
+`loadCookbookApp` reads `smrt.cookbook.json`, reads the `manifest.json` of the
+project's dependencies that export one, validates with `validateCookbook` from
+`@happyvertical/smrt-core/cookbook` (resolved at call time: the app depends on
+core; smrt-svelte does not, `validate` can be injected), and throws one error
+listing every problem, including a recipe no installed package declares.
+
+## Not done here
+
+- **Field policies** (`cookbook.policies`) are returned as `policies` but not
+  applied; applying them to the runtime is `smrt cookbook apply` and the
+  runtime's job. The shell does not render a settings page; pass `settingsHref`.
+- **Entry pages** (`/m/<package>/<Model>/`) are the app's routes; `./screens`
+  (`RecipeScreens`) is the default content for them. Their data comes from the
+  package model's generated REST route and its `@smrt/web` definition (#3749).
+  The app does nothing beyond listing the package in `smrt.config.ts`
+  `consumer.packages`: the `smrt()` Vite preset hosts the models of the
+  cookbook's recipes and `features` (core
+  [build-knowledge.md](../../core/agents/build-knowledge.md), "Package models
+  over REST"), skipping `api: false` models and any the cookbook's `exposure`
+  turns off for `api`. In the entry route, take
+  `collectionDefinitions[<collection>]` from `@smrt/web` (not
+  `@happyvertical/smrt-virt-web`, which holds only the app's own models) as the
+  `definition`, and build the `RecipeScreensSource` over
+  `GET /api/<collection>` and `/api/<collection>/<id>` (offer writes only when
+  the definition's `actions` include them). A model with no definition is not
+  exposed over the API; show the notice.
+- **Options/Help gear** on a recipe's first entry (the planner's `action`) is
+  planner-only and not emitted.
+- **Legacy id migrations** (`migrateLegacySections`/`NavItemIds`) stay in the
+  planner; they depend on its recipe catalog.
+
+## Tests
+
+`src/components/cookbook/__tests__/`: `build.test.ts` builds the four fixture
+cookbooks in `packages/core/src/cookbook/__fixtures__/` against the real
+workspace recipes (every package that declares a `SmrtRecipe`, scanned and
+converted to manifests the way the build does, in `workspace-catalog.ts`, so no
+sibling `dist/` is needed), asserts no issues, that every layout id resolves,
+and the exact bakery sections and labels. `contract-types.ts` (not a `*.test.ts`:
+tsc excludes test files) holds the type assertions that smrt-types'
+`CookbookLayout`/`CookbookOverviewOverride` equal `ShellLayout`/
+`OverviewOverride`. `CookbookApp.test.ts` mounts the shell with the bakery
+cookbook (nav, section page, brand theme, edit callback); `server.test.ts` runs
+the loader over a temp project with a fake installed package.

package/agents/overview-presentation.md

@@ -0,0 +1,8 @@
+# SMRT #3759 test design
+| Behavior | Trigger | Positive | Negative/default | Actor/context | Executor | Runtime | Edge | Level | Command |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| Accessible host heading | heading snippet | linked h3 names article | omitted snippet retains title | browser reader | N/A presentation | Svelte5/browser+SSR | optional snippet | component+a11y | pnpm --filter @happyvertical/smrt-svelte exec vitest run src/components/overview/__tests__/OverviewGrid.test.ts |
+| Plain view, editable frame | presentation plain/editing toggle | plain attribute, toolbar and inert edit preview | default card unchanged | authorized editor | N/A presentation | Svelte5/browser | optional enum typed | component | same |
+No persistence/auth/executor changes. Existing grid suite covers denied editor, widget failures, keyboard edits. New behavior is additive, no bug-fix base comparison required.
+
+Validation: OverviewGrid component suite passed on this change (includes linked article headings, a11y, edit chrome and existing default regressions). Package typecheck and aggregate release checks are recorded in release evidence.

package/agents/overview-surfaces.md

@@ -358,3 +358,14 @@ and the person can undo the change.
   `createOverviewAssistantSurface` is wired to the stored user tier through
   `createOverviewStore(...).save` as shown there.
 - **Not built:** the activity widget (Track B, #3710) and agenda.
+
+## Host section presentation
+
+`OverviewGrid` defaults to framed cards. Pass `presentation="plain"` for
+unframed page sections; editing restores the visible tile frame and controls.
+The optional `heading(widget, title)` snippet supplies heading content, such as
+an application-owned link. The grid still renders its `headingLevel` element
+and generated id used by the article's accessible name; the snippet must not
+supply another heading. Use trusted application routes for links. Widget bodies
+should omit duplicate section headings. Default titles remain unchanged when
+no snippet is supplied.

package/agents/screens.md

@@ -55,3 +55,8 @@ stays below the domain layer, and the app passes both in as props.
   default and does not replace it. Not wired into recipe surfaces yet (#3708).
 - Component props live in `types.ts`, not in the `.svelte` files, so the barrel
   never re-exports types from a component.
+- **Where a package model's definition and data come from (#3749).** A cookbook
+  app's `smrt()` preset hosts the cookbook's package models; the definition is
+  `collectionDefinitions[<collection>]` from `@smrt/web` and the source is the
+  model's `/api/<collection>` route (see [cookbook-shell.md](cookbook-shell.md)).
+  A model the API does not expose has neither, so the entry page shows its notice.

package/dist/components/cookbook/CookbookApp.svelte

@@ -0,0 +1,236 @@
+<script lang="ts">
+/**
+ * `CookbookApp` (#3749): `AppShell` driven by a cookbook. A generated app
+ * needs a layout that renders this with `smrt.cookbook.json` (validated) and
+ * the catalog the server helper loads, plus one route that renders
+ * `CookbookSectionPage`.
+ *
+ * It builds the navigation, layout, theme and section overviews with
+ * `buildCookbookShell`, keeps layout and overview edits in memory, and hands
+ * each edit to `oncookbookchange` for the host to persist.
+ */
+import { createRawSnippet, mount, unmount, untrack } from 'svelte';
+import AppShell from '../app/AppShell.svelte';
+import type { ShellSlotItem } from '../app/slot-item.js';
+import { parseRecipeExportRef } from '../overview/recipe-widgets.js';
+import {
+  resolveWidgetComponents,
+  type WidgetComponents,
+  type WidgetRegistry,
+} from '../overview/registry.js';
+import type { OverviewOverride } from '../overview/types.js';
+import {
+  isShellLayoutEmpty,
+  type ShellLayout,
+} from '../workspace/admin-shell/layout.js';
+import { applyCookbookTheme } from './brand-theme.js';
+import { buildCookbookShell, humanize, pluralize } from './build.js';
+import { type CookbookContext, setCookbookContext } from './context.js';
+import { createCookbookRegistry } from './registry.js';
+import type { CookbookAppProps } from './types.js';
+
+let {
+  cookbook,
+  catalog,
+  loaders,
+  widgetContext,
+  resolveExport,
+  oncookbookchange,
+  recipeOrder,
+  entryPath,
+  sectionPath,
+  href,
+  title,
+  slotItems = [],
+  children,
+  ...shellProps
+}: CookbookAppProps = $props();
+
+const shell = $derived(
+  buildCookbookShell({
+    cookbook,
+    catalog,
+    ...(title ? { title } : {}),
+    ...(recipeOrder ? { recipeOrder } : {}),
+    ...(entryPath ? { entryPath } : {}),
+    ...(sectionPath ? { sectionPath } : {}),
+    ...(href ? { href } : {}),
+    dataWidgets: Boolean(loaders?.metric && loaders?.records),
+  }),
+);
+
+// Local copies the user edits; they follow the cookbook whenever it changes.
+let layout = $state.raw<ShellLayout | null>(untrack(() => shell.layout));
+let overrides = $state.raw<Record<string, unknown>>(
+  untrack(() => storedOverrides()),
+);
+
+function storedOverrides(): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(shell.overviews)
+      .filter(([, page]) => page.override != null)
+      .map(([id, page]) => [id, page.override]),
+  );
+}
+
+$effect(() => {
+  layout = shell.layout;
+  overrides = storedOverrides();
+});
+
+function emit() {
+  if (!oncookbookchange) return;
+  const next = { ...cookbook };
+  if (isShellLayoutEmpty(layout)) delete next.layout;
+  else next.layout = layout as ShellLayout;
+  if (Object.keys(overrides).length > 0) {
+    next.overviews = overrides as NonNullable<typeof next.overviews>;
+  } else delete next.overviews;
+  oncookbookchange(next);
+}
+
+const preset = $derived(applyCookbookTheme(shell.theme));
+
+// Widget registry: core widgets plus the recipes' `widget` surfaces.
+let registry = $state.raw<WidgetRegistry | null>(null);
+let components = $state.raw<WidgetComponents>(new Map());
+
+// Keyed by content: an edit rebuilds `shell` but must not rebuild the registry.
+const widgetsKey = $derived(JSON.stringify(shell.widgets));
+const shellWidgetsKey = $derived(JSON.stringify(shell.shellWidgets));
+
+$effect(() => {
+  void widgetsKey;
+  const widgets = untrack(() => shell.widgets);
+  const resolve = resolveExport;
+  const dataLoaders = loaders;
+  let cancelled = false;
+  void (async () => {
+    const created = await createCookbookRegistry({
+      ...(dataLoaders ? { loaders: dataLoaders } : {}),
+      widgets,
+      ...(resolve ? { resolveExport: resolve } : {}),
+    });
+    const resolved = await resolveWidgetComponents(
+      created.registry.list().map((def) => def.type),
+      created.registry,
+    );
+    if (cancelled) return;
+    components = resolved;
+    registry = created.registry;
+  })();
+  return () => {
+    cancelled = true;
+  };
+});
+
+// Recipe `shell-widget` surfaces become movable slot items.
+let recipeSlotItems = $state.raw<ShellSlotItem[]>([]);
+
+$effect(() => {
+  void shellWidgetsKey;
+  const widgets = untrack(() => shell.shellWidgets);
+  const resolve = resolveExport;
+  if (!resolve || widgets.length === 0) {
+    recipeSlotItems = [];
+    return;
+  }
+  let cancelled = false;
+  void (async () => {
+    const items: ShellSlotItem[] = [];
+    for (const widget of widgets) {
+      const ref = parseRecipeExportRef(widget.export);
+      if (!ref) continue;
+      try {
+        const loaded = (await resolve(ref.specifier, ref.exportName)) as
+          | { default?: unknown }
+          | ((...args: never[]) => unknown)
+          | undefined;
+        const component =
+          loaded && typeof loaded === 'object' && 'default' in loaded
+            ? loaded.default
+            : loaded;
+        if (typeof component !== 'function') continue;
+        items.push({
+          id: `recipe:${widget.recipeId}:${ref.exportName}`,
+          label: widget.label,
+          slot: widget.slot,
+          render: createRawSnippet(() => ({
+            render: () => '<span data-cookbook-slot-widget></span>',
+            setup: (node: Element) => {
+              const instance = mount(component as never, {
+                target: node as HTMLElement,
+              });
+              return () => {
+                void unmount(instance);
+              };
+            },
+          })),
+        });
+      } catch {
+        // A widget that cannot load is left out; the shell still renders.
+      }
+    }
+    if (!cancelled) recipeSlotItems = items;
+  })();
+  return () => {
+    cancelled = true;
+  };
+});
+
+const models = $derived.by(() => {
+  const seen = new Set<string>();
+  const choices: { value: string; label: string }[] = [];
+  for (const entry of shell.entries.values()) {
+    if (seen.has(entry.model.id)) continue;
+    seen.add(entry.model.id);
+    choices.push({
+      value: entry.model.id,
+      label: pluralize(humanize(entry.model.name)),
+    });
+  }
+  return choices;
+});
+
+setCookbookContext({
+  get shell() {
+    return shell;
+  },
+  get registry() {
+    return registry;
+  },
+  get components() {
+    return components;
+  },
+  get models() {
+    return models;
+  },
+  overrideFor: (id) => overrides[id] ?? null,
+  setOverride: (id, override: OverviewOverride | null) => {
+    const next = { ...overrides };
+    if (override === null) delete next[id];
+    else next[id] = override;
+    overrides = next;
+    emit();
+  },
+  widgetContext: () => widgetContext?.() ?? {},
+} satisfies CookbookContext);
+</script>
+
+<AppShell
+  {...shellProps}
+  title={shell.title}
+  navMode="sections"
+  navGroups={shell.navGroups}
+  {layout}
+  onlayoutchange={(next) => {
+    layout = next;
+    emit();
+  }}
+  {preset}
+  colorScheme={shell.theme.colorScheme}
+  sectionHref={(id) => shell.sectionPath(id)}
+  slotItems={[...slotItems, ...recipeSlotItems]}
+>
+  {@render children()}
+</AppShell>

package/dist/components/cookbook/CookbookApp.svelte.d.ts

@@ -0,0 +1,5 @@
+import type { CookbookAppProps } from './types.js';
+declare const CookbookApp: import("svelte").Component<CookbookAppProps, {}, "">;
+type CookbookApp = ReturnType<typeof CookbookApp>;
+export default CookbookApp;
+//# sourceMappingURL=CookbookApp.svelte.d.ts.map

package/dist/components/cookbook/CookbookApp.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CookbookApp.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/cookbook/CookbookApp.svelte.ts"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAsNnD,QAAA,MAAM,WAAW,sDAAwC,CAAC;AAC1D,KAAK,WAAW,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC;AAClD,eAAe,WAAW,CAAC"}

package/dist/components/cookbook/CookbookSectionOverview.svelte

@@ -0,0 +1,71 @@
+<script lang="ts">
+/**
+ * A section page's editable overview (#3749): `OverviewGrid` over the
+ * section's definition. The cookbook owns the override (the controller reads
+ * it and writes each edit back). Mount it under `{#key}` on the section id.
+ */
+import { onDestroy, untrack } from 'svelte';
+import type { OverviewModelChoice } from '../overview/grid-types.js';
+import OverviewGrid from '../overview/OverviewGrid.svelte';
+import type { WidgetComponents, WidgetRegistry } from '../overview/registry.js';
+import type { OverviewDefinition } from '../overview/types.js';
+import { useShellLayout } from '../workspace/admin-shell/layout-context.js';
+import { type CookbookOverviewStore, createSectionOverview } from './page.js';
+import type { CookbookEntry } from './types.js';
+
+interface Props {
+  definition: OverviewDefinition;
+  registry: WidgetRegistry;
+  store: CookbookOverviewStore;
+  entries: ReadonlyMap<string, CookbookEntry>;
+  components: WidgetComponents;
+  models: readonly OverviewModelChoice[];
+  /** Host capabilities for widget loaders. */
+  hostContext: () => Record<string, unknown>;
+  label: string;
+}
+
+let {
+  definition,
+  registry,
+  store,
+  entries,
+  components,
+  models,
+  hostContext,
+  label,
+}: Props = $props();
+
+const layout = useShellLayout();
+
+const controller = createSectionOverview(
+  untrack(() => definition),
+  untrack(() => registry),
+  untrack(() => store),
+  () => ({
+    ...hostContext(),
+    sections: layout.sections,
+    entries,
+  }),
+);
+
+// The shortcuts follow the menu (renames, hides, moves); the grid already
+// requested the first load, so skip that run.
+let first = true;
+$effect(() => {
+  void JSON.stringify(layout.sections);
+  if (first) {
+    first = false;
+    return;
+  }
+  untrack(() => {
+    for (const widget of controller.document.widgets) {
+      controller.reload(widget.id);
+    }
+  });
+});
+
+onDestroy(() => controller.destroy());
+</script>
+
+<OverviewGrid {controller} {components} {models} {label} />

package/dist/components/cookbook/CookbookSectionOverview.svelte.d.ts

@@ -0,0 +1,20 @@
+import type { OverviewModelChoice } from '../overview/grid-types.js';
+import type { WidgetComponents, WidgetRegistry } from '../overview/registry.js';
+import type { OverviewDefinition } from '../overview/types.js';
+import { type CookbookOverviewStore } from './page.js';
+import type { CookbookEntry } from './types.js';
+interface Props {
+    definition: OverviewDefinition;
+    registry: WidgetRegistry;
+    store: CookbookOverviewStore;
+    entries: ReadonlyMap<string, CookbookEntry>;
+    components: WidgetComponents;
+    models: readonly OverviewModelChoice[];
+    /** Host capabilities for widget loaders. */
+    hostContext: () => Record<string, unknown>;
+    label: string;
+}
+declare const CookbookSectionOverview: import("svelte").Component<Props, {}, "">;
+type CookbookSectionOverview = ReturnType<typeof CookbookSectionOverview>;
+export default CookbookSectionOverview;
+//# sourceMappingURL=CookbookSectionOverview.svelte.d.ts.map

package/dist/components/cookbook/CookbookSectionOverview.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CookbookSectionOverview.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/cookbook/CookbookSectionOverview.svelte.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAErE,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAChF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE/D,OAAO,EAAE,KAAK,qBAAqB,EAAyB,MAAM,WAAW,CAAC;AAC9E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAGhD,UAAU,KAAK;IACb,UAAU,EAAE,kBAAkB,CAAC;IAC/B,QAAQ,EAAE,cAAc,CAAC;IACzB,KAAK,EAAE,qBAAqB,CAAC;IAC7B,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IAC5C,UAAU,EAAE,gBAAgB,CAAC;IAC7B,MAAM,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACvC,4CAA4C;IAC5C,WAAW,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3C,KAAK,EAAE,MAAM,CAAC;CACf;AA4DD,QAAA,MAAM,uBAAuB,2CAAwC,CAAC;AACtE,KAAK,uBAAuB,GAAG,UAAU,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAC1E,eAAe,uBAAuB,CAAC"}