smoodly 0.0.61 → 0.0.63

package/dist/admin/shell/health-list.js

@@ -2,7 +2,7 @@ import { SEVERITY, groupKey } from "../drift.js";
 import { driftHeadline } from "../drift-copy.js";
 /** A group shows this many rows, then "Show all N". */
 export const GROUP_PREVIEW = 10;
-const kindLabel = (doc, registry) => doc.kind === "page" ? "Page" : doc.kind === "global" ? "Site" : registry.collections.find((c) => c.name === doc.collection)?.title ?? doc.collection ?? "";
+const kindLabel = (doc, registry) => doc.kind === "page" ? "Page" : doc.kind === "global" ? "Globals" : registry.collections.find((c) => c.name === doc.collection)?.title ?? doc.collection ?? "";
 const href = (doc, locale) => {
     const q = `?locale=${encodeURIComponent(locale)}`;
     if (doc.kind === "page")

package/dist/admin/tree-ops.d.ts

@@ -1,6 +1,7 @@
 import type { PageTree, TreeNode } from "../page-context.ts";
 import type { ZonePolicy } from "../zones.ts";
 import type { AdminSection, AdminGlobal } from "./serialize.ts";
+import { type FreshOptions } from "../sample-fill.ts";
 export declare function zoneOf(tree: PageTree, id: string): string | null;
 export declare function findNode(tree: PageTree, id: string): TreeNode | null;
 export declare function insertNode(tree: PageTree, zone: string, index: number, node: TreeNode): PageTree;
@@ -24,15 +25,21 @@ export declare function allowedGlobals(policy: ZonePolicy | undefined, globals:
 /** A page places a visual item as this node (spec 2026-09-07 §6): `item`
  *  names the registration, `ref` is the item's row id. */
 export declare function placementNode(item: AdminGlobal, ref: string, id: string): TreeNode;
-/** Also fills an element node (an `AdminElement` is a section shape plus contexts). Never seeds `styles` or `css`: Default stores nothing (spec 2026-09-14 §2). */
-export declare function nodeFromSample(section: Pick<AdminSection, "name" | "fields" | "settings" | "sample">, id: string): TreeNode;
+/** The one builder of a fresh node (spec 2026-11-14 filled samples): the insert, a locked zone, a richtext element and
+ *  the picker's sample tree all take it from here, so the picture is the insert. Per field: the `sample` (taken whole,
+ *  nothing generated on it or inside it), then the `default`, a required choice's first option and a boolean's false,
+ *  then the generated value (sample-fill.ts), then the empty value by type. `empty` skips the sample and the generated
+ *  value. Settings are choices: sampled or defaulted, never generated.
+ *  Also fills an element node (an `AdminElement` is a section shape plus contexts). Never seeds `styles` or `css`: Default stores nothing (spec 2026-09-14 §2). */
+export declare function nodeFromSample(section: Pick<AdminSection, "name" | "fields" | "settings" | "sample">, id: string, options?: FreshOptions): TreeNode;
 /** A locked zone holds exactly one node the editor can never insert or
  * remove — so someone has to put it there. This does, from the component's
  * sample (or, for a zone bound to a global item, a placement), for every
  * locked zone that is empty or missing. Runs when the editor loads a draft,
  * which also covers pages that predate a locked zone being added to their
- * schema. Returns the same tree when nothing changed. */
-export declare function fillLockedZones(tree: PageTree, policies: Record<string, ZonePolicy>, sections: AdminSection[], globalIds?: Record<string, string>): PageTree;
+ * schema. Returns the same tree when nothing changed. `fresh` carries the
+ * space's reference picks and whether the service takes an image placeholder. */
+export declare function fillLockedZones(tree: PageTree, policies: Record<string, ZonePolicy>, sections: AdminSection[], globalIds?: Record<string, string>, fresh?: FreshOptions): PageTree;
 export declare function newNodeId(type: string): string;
 /** A page-level value — the template's page fields or the SEO meta (spec 2026-09-10 page fields §5). */
 export declare function patchPage(tree: PageTree, ns: "fields" | "meta", key: string, value: unknown): PageTree;

package/dist/admin/tree-ops.js

@@ -1,6 +1,6 @@
 import { GLOBAL_NODE_TYPE } from "../global.js";
 import { setAtPath, unsetAtPath } from "./field-paths.js";
-import { optionsOf } from "../fields.js";
+import { firstChoice, generated, starting } from "../sample-fill.js";
 export function zoneOf(tree, id) {
     for (const [zone, nodes] of Object.entries(tree.zones)) {
         if (nodes.some((n) => n.id === id))
@@ -119,32 +119,41 @@ export function placementNode(item, ref, id) {
 /** The empty value a fresh node's field starts at, by descriptor type.
  * Shape matters: a list-valued field seeded with "" is a type lie that
  * crashes the first section view that maps over it. */
-const EMPTY_BY_TYPE = { refList: [], object: {} };
+const EMPTY_BY_TYPE = { refList: () => [], list: () => [], tags: () => [], checkboxes: () => [], object: () => ({}) };
 /** Media/number fields have no honest empty value — "" renders as a
- * broken-image icon or a stray zero, worse than nothing at all. With no
- * sample, leave the key out of `fields` entirely rather than seed a lie. */
+ * broken-image icon or a stray zero, worse than nothing at all. With
+ * nothing to start from, leave the key out of `fields` entirely rather than seed a lie. */
 const ABSENT_WHEN_UNSAMPLED = new Set(["image", "video", "file", "number"]);
-/** A required choice shows its first option (FieldWidget renders no blank one), so a new node stores it too — as a
- *  list item does (forms/list.ts) — and publish never says Required for a choice the editor sees made. */
-const firstChoice = (d) => (d.type === "select" || d.type === "radio") && d.optional !== true ? optionsOf(d.options)[0]?.value : undefined;
-/** Also fills an element node (an `AdminElement` is a section shape plus contexts). Never seeds `styles` or `css`: Default stores nothing (spec 2026-09-14 §2). */
-export function nodeFromSample(section, id) {
+/** What the section's `sample` sets for a key: an empty array counts as left out (spec 2026-11-14 filled samples),
+ *  since "start with nothing" for a list is what leaving it out already means. */
+const sampledOf = (sample, key) => {
+    const v = sample?.[key];
+    return Array.isArray(v) && v.length === 0 ? undefined : v;
+};
+/** The one builder of a fresh node (spec 2026-11-14 filled samples): the insert, a locked zone, a richtext element and
+ *  the picker's sample tree all take it from here, so the picture is the insert. Per field: the `sample` (taken whole,
+ *  nothing generated on it or inside it), then the `default`, a required choice's first option and a boolean's false,
+ *  then the generated value (sample-fill.ts), then the empty value by type. `empty` skips the sample and the generated
+ *  value. Settings are choices: sampled or defaulted, never generated.
+ *  Also fills an element node (an `AdminElement` is a section shape plus contexts). Never seeds `styles` or `css`: Default stores nothing (spec 2026-09-14 §2). */
+export function nodeFromSample(section, id, options = {}) {
     const fields = {};
     const settings = {};
+    const sample = options.empty ? undefined : section.sample;
     for (const [key, d] of Object.entries(section.fields)) {
-        const sampled = section.sample?.[key] ?? d.default ?? firstChoice(d) ?? (d.type === "boolean" ? false : undefined);
-        if (sampled !== undefined)
-            fields[key] = sampled;
+        const value = sampledOf(sample, key) ?? starting(d) ?? (options.empty ? undefined : generated(key, d, options));
+        if (value !== undefined)
+            fields[key] = value;
         else if (ABSENT_WHEN_UNSAMPLED.has(d.type))
             continue;
         // An optional object with no sample is absent: `{}` would read as present, its members required at publish.
         else if (d.type === "object" && d.optional === true)
             continue;
         else
-            fields[key] = EMPTY_BY_TYPE[d.type] ?? "";
+            fields[key] = EMPTY_BY_TYPE[d.type]?.() ?? "";
     }
     for (const [key, d] of Object.entries(section.settings)) {
-        const v = section.sample?.[key] ?? d.default ?? firstChoice(d);
+        const v = sampledOf(sample, key) ?? d.default ?? firstChoice(d);
         if (v !== undefined)
             settings[key] = v;
     }
@@ -155,8 +164,9 @@ export function nodeFromSample(section, id) {
  * sample (or, for a zone bound to a global item, a placement), for every
  * locked zone that is empty or missing. Runs when the editor loads a draft,
  * which also covers pages that predate a locked zone being added to their
- * schema. Returns the same tree when nothing changed. */
-export function fillLockedZones(tree, policies, sections, globalIds = {}) {
+ * schema. Returns the same tree when nothing changed. `fresh` carries the
+ * space's reference picks and whether the service takes an image placeholder. */
+export function fillLockedZones(tree, policies, sections, globalIds = {}, fresh) {
     let next = null;
     for (const [zone, policy] of Object.entries(policies)) {
         if (policy.kind !== "locked")
@@ -177,7 +187,8 @@ export function fillLockedZones(tree, policies, sections, globalIds = {}) {
             const section = sections.find((s) => s.name === policy.component);
             if (!section)
                 continue;
-            node = nodeFromSample(section, newNodeId(section.name));
+            // Always the filled node (spec 2026-11-14 filled samples): a locked zone has no picker and no switch.
+            node = nodeFromSample(section, newNodeId(section.name), { ...fresh, empty: false });
         }
         next ?? (next = { ...tree, zones: { ...tree.zones } });
         next.zones[zone] = [node];

package/dist/admin/ui/primitives.js

@@ -40,7 +40,7 @@ export function ThemeToggle() {
         }
         catch { /* not remembered */ }
     };
-    return (_jsxs("button", { type: "button", role: "menuitem", className: "sm-rail__menu-item", onClick: toggle, children: [_jsxs("span", { className: "sm-when-light", children: [_jsx(Moon, { ...ICON }), "Dark mode"] }), _jsxs("span", { className: "sm-when-dark", children: [_jsx(Sun, { ...ICON }), "Light mode"] })] }));
+    return (_jsxs("button", { type: "button", role: "menuitem", className: "sm-navbar__menu-item", onClick: toggle, children: [_jsxs("span", { className: "sm-when-light", children: [_jsx(Moon, { ...ICON }), "Dark mode"] }), _jsxs("span", { className: "sm-when-dark", children: [_jsx(Sun, { ...ICON }), "Light mode"] })] }));
 }
 export function Button({ variant = "primary", size = "md", className, ...rest }) {
     return (_jsx("button", { type: "button", className: cx("sm-btn", `sm-btn--${variant}`, size === "lg" && "sm-btn--lg", size === "sm" && "sm-btn--sm", className), ...rest }));

package/dist/admin/ui/theme.js

@@ -26,7 +26,8 @@ const TOKENS_LIGHT = `
   /* The shell: navy frame, white sheet, grey tiles on the sheet, white fields on the tiles. */
   --frame:#151727; --sheet:${SHEET_LIGHT};
   --bg:var(--sheet); --canvas:#ECEDF1; --surface:#F6F6F6; --surface-form:#F6F6F6; --surface-inset:#FFFFFF;
-  --menu-bg:#FFFFFF;
+  --menu-bg:#FFFFFF; --menu-hover:var(--hover);
+  --avatar-hover:color-mix(in srgb,var(--accent-soft),#fff 60%);
   --input-bg:#FFFFFF; --input-hover-bg:#FFFFFF; --input-focus-bg:#FFFFFF; --input-border:var(--line);
   --line:#E4E5EA; --line-dashed:#CFD1D9; --line-soft:#ECEDF1;
   --text:#151727; --text-secondary:#454A5C; --text-muted:#6B6F80; --text-subtle:#9A9EAB; --text-disabled:#C5C8D2;
@@ -34,8 +35,8 @@ const TOKENS_LIGHT = `
   --selection-global:#C4620C;
   --hover:rgba(21,23,39,.05); --press:rgba(21,23,39,.09); --control-hover:#ECEDF1; --canvas-ground:#EDEDED;
   --btn-secondary-bg:var(--surface); --btn-secondary-hover:#ECEDF1;
-  /* The rail sits on the frame: its own greys, the active tile a white tint. */
-  --rail-fg:#B9BDCE; --rail-active-fg:#FFFFFF; --rail-active-bg:rgba(255,255,255,.14); --rail-hover-bg:rgba(255,255,255,.08);
+  /* The navigation bar sits on the frame: its own greys, the active item a white tint, its dark menus a step lighter than the frame. */
+  --navbar-fg:#B9BDCE; --navbar-active-fg:#FFFFFF; --navbar-active-bg:rgba(255,255,255,.14); --navbar-hover-bg:rgba(255,255,255,.08); --navbar-menu-bg:#242840;
   --bar-bg:transparent; --bar-border:0; --menu-border:0; --card-divider:0;
   --card-title-size:var(--text-md); --card-title-color:var(--text);
   /* In-card segmented (tabs, the span bar): white track, the chosen option in the tile grey. */
@@ -52,7 +53,7 @@ const TOKENS_LIGHT = `
      dark mode that washed out over the white page, 2026-09-10). */
   --plus-bg:#DDEBE4; --plus-hover:#D0E3D9; --plus-fg:#1C6E5B;
   --plus-icon-bg:#1C6E5B; --plus-icon-fg:#FFFFFF; --plus-shadow:none;
-  --logo-color:var(--accent); --logo-outer:#0B5A49; --logo-inner:#5FC9A0; /* the rail's app icon: deep green square, mint s (2026-10-23) */
+  --logo-color:var(--accent); --logo-outer:#0B5A49; --logo-inner:#5FC9A0; /* the bar's app icon: deep green square, mint s (2026-10-23) */
 
   --status-published-fg:var(--green-700); --status-published-bg:var(--green-50);
   --status-changes-fg:var(--amber-700); --status-changes-bg:var(--amber-50);
@@ -61,6 +62,7 @@ const TOKENS_LIGHT = `
   --status-saved-dot:var(--green-500);
   --warn:var(--amber-700); --warn-soft:var(--amber-50);
   --danger:var(--red-700); --danger-soft:var(--red-50);
+  --destructive-bg:var(--red-700); /* the filled destructive button: white text on it in both themes (2026-11-14) */
 
   /* The edited page inside the canvas stays light in both themes. */
   --page-bg:#FFFFFF; --page-text:#151727;
@@ -78,13 +80,13 @@ const TOKENS_LIGHT = `
 `;
 /* The handoff's dark proposal (VisualEditor.md, 8c right board): the frame
    and sheet a step darker, tiles a step lighter, fields in the sheet tone;
-   the rail and the logo unchanged. */
+   the bar and the logo unchanged. */
 const TOKENS_DARK = `
-  --accent:#6CC4A6; --accent-hover:#82D2B8; --accent-soft:rgba(108,196,166,.18); --accent-line:#6CC4A6; --on-accent:#151727;
+  --accent:#6CC4A6; --accent-hover:#82D2B8; --accent-soft:rgba(108,196,166,.18); --avatar-hover:rgba(108,196,166,.26); /* a step up from accent-soft: white over the tint read grey (2026-11-14) */ --accent-line:#6CC4A6; --on-accent:#151727;
   --selection-global:#F09A5C;
   --frame:#0F1120; --sheet:${SHEET_DARK};
   --canvas:#131526; --surface:#242840; --surface-form:#242840; --surface-inset:#1B1E30;
-  --menu-bg:#242840;
+  --menu-bg:#242840; --menu-hover:#2A2E47; /* a step off the menu, not the brighter --hover (2026-11-14) */
   /* A field's edge is drawn in dark: a dialog's fields take the card's own tone there (2026-11-13). */
   --input-bg:#1B1E30; --input-hover-bg:#1B1E30; --input-focus-bg:#1B1E30; --input-border:var(--line-dashed);
   --line:#33384F; --line-dashed:#444A63; --line-soft:#33384F;
@@ -126,19 +128,19 @@ const SCALE = `
 
   --radius-xs:2px; --radius-sm:6px; --radius-md:8px; --radius-lg:10px;
   --radius-card:16px; --radius-card-lg:16px; --radius-modal:20px; --radius-btn:999px; --radius-round:999px;
-  --page-radius:8px 8px 0 0; --selection-radius:2px; /* the canvas hover/selection ring: 2px (asked for 2026-09-26; 8px before) */
+  --page-radius:0; --selection-radius:2px; /* the canvas hover/selection ring: 2px (asked for 2026-09-26; 8px before) */
   --outline-row-radius:6px; --tabs-radius:10px; --tab-radius:6px; --row-radius:2px; --tag-radius:999px; /* list row hover fill: 2px (same day; 10px before) */
   --plus-radius:8px; --toolbar-radius:8px;
   --rtcard-bg:var(--surface); --rtcard-border:var(--line);
   --control-h:40px; --control-h-sm:34px; --control-h-lg:48px; --button-h:36px; --button-h-sm:28px; --row-h:48px; --topbar-h:64px;
   --outline-row-h:36px; --seg-pad-y:7px; --tabs-pad:3px;
   --plus-h:32px; --plus-pad:0 14px 0 6px; --plus-label:inline;
-  --nav-w:72px; --inspector-w:360px; --gutter:20px;
-  /* The frame is 8px above, right of and below the sheet (6px in the handoff, +2px 2026-10-23); the rail fills the left edge. */
-  --frame-pad:8px; --frame-pad-top:8px; --shell-gap:0px; --sheet-radius:20px; --sheet-pad:0 24px 24px;
-  --rail-pad:18px 6px 16px; --rail-logo:block; --rail-logo-opacity:1; --rail-tile-w:44px; --rail-tile-h:40px; --rail-tile-radius:12px;
+  --inspector-w:360px; --gutter:20px;
+  /* The frame is 8px left of, right of and below the sheet (6px in the handoff, +2px 2026-10-23); the bar fills the top edge. */
+  --frame-pad:8px; --shell-gap:0px; --sheet-radius:12px; --sheet-pad:0 24px 24px;
+  --navbar-h:64px; --navbar-pad-x:12px; --navbar-item-h:40px; --navbar-item-radius:10px;
   --topbar-pad:0; --back-size:32px; --back-bg:var(--surface);
-  --table-pad:8px 12px; --table-top:80px; --canvas-pad:28px 40px 0; --card-pad:16px 18px; --card-gap:12px; --form-pad:32px 40px;
+  --table-pad:8px 12px; --table-top:80px; --canvas-pad:28px 28px 0; --card-pad:16px 18px; --card-gap:12px; --form-pad:32px 40px;
   --border:1px solid var(--line);
   --outline-selection:2px solid var(--selection);
   --outline-selection-global:2px solid var(--selection-global);
@@ -182,106 +184,106 @@ html:has(.sm-admin),body:has(.sm-admin){overscroll-behavior:none}
 .sm-code{background:var(--surface);border-radius:8px;padding:10px 12px;margin:0;font:13px/1.5 var(--font-mono);overflow:auto}
 
 /* ── shell ─────────────────────────────────────────────────────────── */
-/* Rail | main. The shell is the frame (design_handoff_smoodly_neutral/
-   components/AppShell.html): navy, 8px above, right of and below the main
+/* Bar over main (2026-11-14; a 72px rail on the left before it). The shell is
+   the frame (design_handoff_smoodly_neutral/components/AppShell.html): navy,
+   the navigation bar across its top, 8px right of, left of and below the main
    column, which is the white sheet with a 20px radius and its own inner
-   padding; the rail fills the frame's left edge.
+   padding. The shell owns the viewport and the sheet scrolls inside itself,
+   so the bar stays put.
    The main column stacks the top bar over one tile-shaped region: list,
    form or editor. */
 .sm-shell{
-  display:grid;grid-template-columns:var(--nav-w) 1fr;column-gap:var(--shell-gap);
-  padding:var(--frame-pad-top) var(--frame-pad) var(--frame-pad) 0;height:100vh;height:100dvh;overflow:hidden;background:var(--frame);
+  display:grid;grid-template-rows:var(--navbar-h) minmax(0,1fr);grid-template-columns:minmax(0,1fr);row-gap:var(--shell-gap);
+  padding:0 var(--frame-pad) var(--frame-pad);height:100vh;height:100dvh;overflow:hidden;background:var(--frame);
 }
 .sm-shell>.sm-main{
   min-width:0;min-height:0;display:flex;flex-direction:column;overflow:hidden;
   background:var(--sheet);border-radius:var(--sheet-radius);padding:var(--sheet-pad);
 }
 .sm-wordmark{height:18px;width:auto;color:var(--logo-color);filter:var(--logo-filter);flex:none}
-/* The IconRail (design_handoff_smoodly_neutral/components/IconRail.html):
-   a 72px rail on the frame with the app icon on top, 18px Lucide icons
-   over a 10px label and a 44×40 active tile in a white tint — the rail's
-   own colour tokens, since the frame is navy in both themes. */
-.sm-rail{
-  width:var(--nav-w);height:100%;display:flex;flex-direction:column;align-items:center;gap:18px;
-  padding:var(--rail-pad);background:var(--bar-bg);border-right:var(--bar-border);color:var(--rail-fg);
-  font:500 10px/1 var(--font-sans);position:relative;
-}
+/* The navigation bar: the app icon on the left, the items centred, Deploy and
+   the avatar on the right. The rail's colours, icons and order: 18px Lucide
+   icons beside a 14px label, the active item a white-tint pill. */
+.sm-navbar{
+  display:grid;grid-template-columns:1fr auto 1fr;align-items:center;gap:16px;min-width:0;
+  padding:0 var(--navbar-pad-x);background:var(--bar-bg);color:var(--navbar-fg);
+  font:500 var(--text-md)/1 var(--font-sans);position:relative;z-index:30;
+}
+.sm-navbar__start{display:flex;align-items:center;justify-self:start}
+.sm-navbar__end{display:flex;align-items:center;gap:10px;justify-self:end}
 /* The app icon (the Smoodly menu's trigger): the deep green square with the
-   mint s, 26px wide (2026-10-23; the lozenge before it was 20px, asked for
-   2026-09-26, at .8 opacity). */
-.sm-rail__brand{appearance:none;background:none;border:0;padding:0;margin-bottom:6px;cursor:pointer;display:block;border-radius:6px;color:inherit}
+   mint s (2026-10-23). */
+.sm-navbar__brand{appearance:none;background:none;border:0;padding:0;cursor:pointer;display:block;border-radius:8px;color:inherit}
 /* Hover (2026-10-23): the app icon and the avatar brighten a touch. */
-.sm-rail__logo{transition:filter .15s}
-.sm-rail__brand:hover .sm-rail__logo{filter:brightness(1.3)}
-.sm-rail__user{transition:background .15s}
-.sm-rail__user:hover{background:color-mix(in srgb,var(--accent-soft),#fff 60%)}
-.sm-rail__brand:focus-visible{outline:2px solid var(--rail-active-fg);outline-offset:2px;box-shadow:none}
-.sm-rail__logo{width:26px;height:auto;display:var(--rail-logo);flex:none;opacity:var(--rail-logo-opacity)}
-.sm-rail__ext{width:13px;height:13px;flex:none;margin-left:12px;opacity:.45}
-.sm-rail__menu-item:hover .sm-rail__ext,.sm-rail__menu-item:focus-visible .sm-rail__ext{opacity:.8}
-.sm-rail__menu-version{font-size:var(--text-xs);color:var(--text-subtle);padding:7px 10px 4px;margin-top:3px;border-top:1px solid var(--line)}
-.sm-rail__list{display:flex;flex-direction:column;gap:8px;width:100%;margin:0;padding:0;list-style:none}
-.sm-rail__item{position:relative}
-.sm-rail__btn{
-  appearance:none;background:none;border:0;margin:0;padding:2px 0;width:100%;display:flex;flex-direction:column;
-  align-items:center;gap:6px;color:inherit;font:inherit;cursor:pointer;border-radius:var(--radius-md);text-decoration:none;
-}
-.sm-rail__btn:hover{color:inherit}
-.sm-rail__btn:focus-visible{outline:2px solid var(--rail-active-fg);outline-offset:-2px;box-shadow:none}
-.sm-rail__tile{position:relative;width:var(--rail-tile-w);height:var(--rail-tile-h);border-radius:var(--rail-tile-radius);display:grid;place-items:center;transition:background .12s}
-.sm-rail__btn:hover .sm-rail__tile{background:var(--rail-hover-bg)}
-.sm-rail__btn[aria-current="page"],.sm-rail__btn[aria-expanded="true"]{color:var(--rail-active-fg);font-weight:600}
-.sm-rail__btn[aria-current="page"]:hover,.sm-rail__btn[aria-expanded="true"]:hover{color:var(--rail-active-fg)}
-.sm-rail__btn[aria-current="page"] .sm-rail__tile,.sm-rail__btn[aria-expanded="true"] .sm-rail__tile{background:var(--rail-active-bg)}
-.sm-rail__tile svg{width:18px;height:18px;stroke:currentColor;fill:none;stroke-width:2;stroke-linecap:round;stroke-linejoin:round}
-/* A collection's own title can be long: it ends in an ellipsis inside the rail (2026-11-13). */
-.sm-rail__label{letter-spacing:.01em;white-space:nowrap;max-width:100%;overflow:hidden;text-overflow:ellipsis}
-/* Not greyed: the reference renders every inactive item at --text and marks
-   the unavailable ones only by being inert (no pointer, no hover). */
-.sm-rail__btn[aria-disabled="true"]{cursor:default}
-.sm-rail__btn[aria-disabled="true"]:hover .sm-rail__tile{background:transparent}
-/* The Deploy tile (spec 2026-10-09 static mode §6): above the avatar; the badge is the count waiting, the
-   lit tile a build in flight, the warning tile a build that has not landed or a site that did not answer. */
-.sm-rail__deploy{margin-top:auto}
-.sm-rail__deploy+.sm-rail__foot{margin-top:0}
-/* A publish on its way to the site (plan 2026-10-14 publish through the queue): a quiet line above the Deploy tile
-   and the avatar, the warning colour when a delivery landed late or with an error. */
-.sm-rail__badge{position:absolute;top:-4px;right:-6px;min-width:16px;height:16px;padding:0 4px;border-radius:var(--radius-round);background:var(--accent);color:#fff;font-size:10px;font-weight:600;line-height:16px;text-align:center}
-.sm-rail__tile--lit{background:var(--accent-soft);color:var(--accent);animation:sm-rail-pulse 1.6s ease-in-out infinite}
-.sm-rail__tile--warn{background:var(--warn-soft);color:var(--warn)}
-@keyframes sm-rail-pulse{0%,100%{opacity:1}50%{opacity:.55}}
-.sm-rail__menu-detail{font-size:var(--text-sm);color:var(--text);padding:6px 8px 4px;white-space:normal}
-.sm-rail__menu-note{font-size:var(--text-xs);color:var(--text-muted);padding:4px 8px 6px;white-space:normal}
-.sm-rail__menu-item:disabled{cursor:default;color:var(--text-muted)}
-.sm-rail__menu-item:disabled:hover{background:none}
-.sm-rail__foot{margin-top:auto;display:flex;flex-direction:column;align-items:center}
-.sm-rail__user{
-  width:28px;height:28px;border-radius:var(--radius-round);background:var(--accent-soft);color:var(--accent);
-  display:grid;place-items:center;font-size:var(--text-xs);font-weight:600;border:0;cursor:pointer;padding:0;
-}
-.sm-rail__user:focus-visible{outline:2px solid var(--rail-active-fg);outline-offset:1px;box-shadow:none}
-/* Flyout: 6px right of the rail, aligned with its item (the user menu aligns to the bottom).
+.sm-navbar__logo{width:30px;height:auto;display:block;flex:none;transition:filter .15s}
+.sm-navbar__brand:hover .sm-navbar__logo{filter:brightness(1.3)}
+.sm-navbar__brand:focus-visible{outline:2px solid var(--navbar-active-fg);outline-offset:2px;box-shadow:none}
+.sm-navbar__user{
+  width:32px;height:32px;border-radius:var(--radius-round);background:var(--accent-soft);color:var(--accent);
+  display:grid;place-items:center;font-size:var(--text-xs);font-weight:600;border:0;cursor:pointer;padding:0;transition:background .15s;
+}
+.sm-navbar__user:hover{background:var(--avatar-hover)}
+.sm-navbar__user:focus-visible{outline:2px solid var(--navbar-active-fg);outline-offset:2px;box-shadow:none}
+.sm-navbar__ext{width:13px;height:13px;flex:none;margin-left:12px;opacity:.45}
+.sm-navbar__menu-item:hover .sm-navbar__ext,.sm-navbar__menu-item:focus-visible .sm-navbar__ext{opacity:.8}
+.sm-navbar__menu-version{font-size:var(--text-xs);color:var(--text-subtle);padding:7px 10px 4px;margin-top:3px;border-top:1px solid var(--line)}
+.sm-navbar__list{display:flex;align-items:center;gap:4px;margin:0;padding:0;list-style:none;min-width:0}
+.sm-navbar__item{position:relative;list-style:none}
+.sm-navbar__btn{
+  appearance:none;background:none;border:0;margin:0;height:var(--navbar-item-h);padding:0 12px;display:flex;align-items:center;gap:8px;
+  color:inherit;font:inherit;cursor:pointer;border-radius:var(--navbar-item-radius);text-decoration:none;white-space:nowrap;transition:background .12s,color .12s;
+}
+.sm-navbar__btn--icon{padding:0;width:var(--navbar-item-h);justify-content:center}
+.sm-navbar__btn:hover{color:var(--navbar-active-fg);background:var(--navbar-hover-bg)}
+.sm-navbar__btn:focus-visible{outline:2px solid var(--navbar-active-fg);outline-offset:-2px;box-shadow:none}
+.sm-navbar__btn[aria-current="page"],.sm-navbar__btn[aria-expanded="true"]{color:var(--navbar-active-fg);background:var(--navbar-active-bg)}
+.sm-navbar__btn svg{flex:none;stroke:currentColor;fill:none;stroke-linecap:round;stroke-linejoin:round}
+.sm-navbar__chevron{margin-left:-2px;opacity:.8}
+/* A collection's own title can be long: it ends in an ellipsis (2026-11-13). */
+.sm-navbar__label{letter-spacing:.01em;white-space:nowrap;max-width:160px;overflow:hidden;text-overflow:ellipsis}
+/* A narrow window keeps the icons and drops the labels; each item keeps its name for a screen reader and a tooltip. */
+@media (max-width:820px){
+  .sm-navbar__list .sm-navbar__label,.sm-navbar__deploy .sm-navbar__label{position:absolute;width:1px;height:1px;overflow:hidden;clip-path:inset(50%)}
+  .sm-navbar__btn{padding:0 10px}
+}
+/* The Deploy item (spec 2026-10-09 static mode §6): next to the avatar; the badge is the count waiting, the
+   lit item a build in flight, the warning item a build that has not landed or a site that did not answer. */
+.sm-navbar__icon{position:relative;display:grid;place-items:center}
+.sm-navbar__badge{position:absolute;top:-7px;right:-9px;min-width:16px;height:16px;padding:0 4px;border-radius:var(--radius-round);background:var(--accent);color:#fff;font-size:10px;font-weight:600;line-height:16px;text-align:center}
+.sm-navbar__btn--lit,.sm-navbar__btn--lit:hover{background:var(--accent-soft);color:var(--accent);animation:sm-navbar-pulse 1.6s ease-in-out infinite}
+.sm-navbar__btn--warn,.sm-navbar__btn--warn:hover{background:var(--warn-soft);color:var(--warn)}
+@keyframes sm-navbar-pulse{0%,100%{opacity:1}50%{opacity:.55}}
+.sm-navbar__menu-detail{font-size:var(--text-sm);color:var(--text);padding:6px 8px 4px;white-space:normal}
+.sm-navbar__menu-note{font-size:var(--text-xs);color:var(--text-muted);padding:4px 8px 6px;white-space:normal}
+.sm-navbar__menu-item:disabled{cursor:default;color:var(--text-muted)}
+.sm-navbar__menu-item:disabled:hover{background:none}
+/* A menu drops 6px below its item, aligned with its left edge (the end group's with its right edge).
    Menus float on --menu-bg (the sheet white in the neutral look, so they read over the frame). */
-.sm-rail__menu{
-  position:absolute;left:calc(100% + 6px);top:0;z-index:20;width:168px;padding:6px;margin:0;list-style:none;
+.sm-navbar__menu{
+  position:absolute;left:0;top:calc(100% + 6px);z-index:20;width:200px;padding:6px;margin:0;list-style:none;
   background:var(--menu-bg);border:var(--menu-border);border-radius:var(--radius-md);box-shadow:var(--shadow-pop);
-  display:none;flex-direction:column;gap:1px;font-size:var(--text-md);font-weight:500;color:var(--text);
-}
-.sm-rail__menu[data-open="true"]{display:flex}
-.sm-rail__menu--up{top:auto;bottom:0}
-/* The Collections flyout opens on hover, so it is roomier (the names at --text-lg) and an invisible
-   bridge spans the 6px gap so the pointer can cross from the rail without closing it. */
-.sm-rail__menu--brand{width:220px}
-.sm-rail__menu--collections{width:208px;padding:8px;gap:2px;font-size:var(--text-lg)}
-.sm-rail__menu--collections::before{content:"";position:absolute;left:-8px;top:0;bottom:0;width:8px}
-.sm-rail__menu--collections .sm-rail__menu-item{padding:9px 12px}
-.sm-rail__menu-title{font-size:9px;font-weight:600;letter-spacing:var(--tracking-label);text-transform:uppercase;color:var(--text-muted);padding:6px 8px 4px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
-.sm-rail__menu-item{
+  display:none;flex-direction:column;gap:1px;font-size:var(--text-md);font-weight:500;line-height:1.4;color:var(--text);
+}
+.sm-navbar__menu[data-open="true"]{display:flex}
+.sm-navbar__menu--end{left:auto;right:0;width:240px}
+.sm-navbar__menu--brand{width:240px}
+/* An invisible bridge spans the 6px gap so the pointer can cross from Collections into its hover menu. */
+.sm-navbar__menu--collections::before{content:"";position:absolute;left:0;right:0;top:-8px;height:8px}
+.sm-navbar__menu-title{font-size:9px;font-weight:600;letter-spacing:var(--tracking-label);text-transform:uppercase;color:var(--text-muted);padding:6px 8px 4px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.sm-navbar__menu-item{
   appearance:none;background:none;border:0;width:100%;display:flex;align-items:center;justify-content:space-between;
   padding:7px 10px;border-radius:var(--radius-sm);color:inherit;font:inherit;cursor:pointer;text-align:left;text-decoration:none;
 }
-.sm-rail__menu-item:hover,.sm-rail__menu-item:focus-visible{background:var(--hover);color:inherit;outline:0;box-shadow:none}
-.sm-rail__menu-item[aria-current="page"],.sm-rail__menu-item[aria-current="page"]:hover{background:var(--nav-active-bg);color:var(--nav-active-fg);font-weight:600}
+.sm-navbar__menu-item:hover,.sm-navbar__menu-item:focus-visible{background:var(--menu-hover);color:inherit;outline:0;box-shadow:none}
+.sm-navbar__menu-item[aria-current="page"],.sm-navbar__menu-item[aria-current="page"]:hover{background:var(--nav-active-bg);color:var(--nav-active-fg);font-weight:600}
+.sm-navbar__menu-label{display:flex;align-items:center;gap:10px;min-width:0}
+.sm-navbar__menu-label>span{overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.sm-navbar__menu-label svg{flex:none;stroke:currentColor;fill:none}
+/* Collections and ⋮ are dark (2026-11-14): they carry the bar's own items, so they take its colours. */
+.sm-navbar__menu--dark{background:var(--navbar-menu-bg);color:var(--navbar-fg);border:0;padding:6px;gap:2px}
+.sm-navbar__menu--dark .sm-navbar__menu-item{padding:9px 12px}
+.sm-navbar__menu--dark .sm-navbar__menu-item:hover,.sm-navbar__menu--dark .sm-navbar__menu-item:focus-visible{background:var(--navbar-hover-bg);color:var(--navbar-active-fg)}
+.sm-navbar__menu--dark .sm-navbar__menu-item[aria-current="page"],.sm-navbar__menu--dark .sm-navbar__menu-item[aria-current="page"]:hover{background:var(--navbar-active-bg);color:var(--navbar-active-fg)}
 .sm-when-light{display:var(--when-light);align-items:center;gap:8px}
 .sm-when-dark{display:var(--when-dark);align-items:center;gap:8px}
 /* .sm-nav-item survives as the inspector's link style (EditorView). */
@@ -336,7 +338,7 @@ html:has(.sm-admin),body:has(.sm-admin){overscroll-behavior:none}
 .sm-btn--danger{background:var(--btn-secondary-bg);color:var(--danger)}
 .sm-btn--danger:hover{background:var(--danger-soft);color:var(--danger)}
 /* The confirm dialog's destructive primary: filled red (ConfirmModal.html). */
-.sm-btn--destructive{background:var(--danger);color:#fff;font-weight:600;padding:0 18px}
+.sm-btn--destructive{background:var(--destructive-bg);color:#fff;font-weight:600;padding:0 18px}
 .sm-btn--destructive:hover{filter:brightness(.94);color:#fff}
 .sm-btn--ok{background:var(--status-published-bg);color:var(--status-published-fg);font-weight:600;padding:0 18px}
 .sm-btn:disabled,.sm-btn[aria-disabled="true"]{opacity:.5;cursor:default;pointer-events:none}
@@ -455,12 +457,12 @@ html:has(.sm-admin),body:has(.sm-admin){overscroll-behavior:none}
 .sm-richtext__content ul,.sm-richtext__content ol{padding-left:20px}
 .sm-richtext__content li+li{margin-top:.25em}
 .sm-richtext__body{position:relative}
-/* The "+" menu floats under the toolbar's right end (the "+" is its last
+/* The "+" menu hangs right under the toolbar's right end, no gap (2026-11-14; the "+" is its last
    button) instead of pushing the content down; the picker inside drops
    its own chrome. The slash menu floats under the caret the same way. */
-.sm-richtext__head{position:relative}
+.sm-richtext__head{position:relative;width:fit-content;max-width:100%} /* as wide as the toolbar, so the menu hangs from the "+" (2026-11-14) */
 .sm-richtext__menu{
-  position:absolute;top:calc(100% + 6px);right:0;z-index:65;width:300px;max-width:100%;
+  position:absolute;top:100%;right:0;z-index:65;width:300px;max-width:calc(100vw - 32px);
   display:flex;flex-direction:column;gap:6px;padding:6px;
   background:var(--menu-bg);border:var(--menu-border);border-radius:var(--radius-md);box-shadow:var(--shadow-pop);
 }
@@ -488,6 +490,7 @@ html:has(.sm-admin),body:has(.sm-admin){overscroll-behavior:none}
 /* Inline editing in the canvas (spec 2026-09-10). The outlines are drawn in
    the overlay from the bridge's field rects; the toolbar floats above the
    selection. */
+.sm-dim{background:color-mix(in srgb,var(--canvas) 62%,transparent);pointer-events:none}
 .sm-fieldhover{outline:1px solid color-mix(in srgb,var(--selection) 55%,transparent);outline-offset:2px;border-radius:2px;pointer-events:none}
 .sm-fieldedit{outline:1.5px solid var(--selection);outline-offset:3px;border-radius:2px;pointer-events:none}
 .sm-floatbar{
@@ -563,7 +566,7 @@ html:has(.sm-admin),body:has(.sm-admin){overscroll-behavior:none}
 .sm-listnotice:empty{display:none}
 /* The rows sit in a centred column of at most 1200px inside the card,
    under --table-top of air reserved for the coming search and filters. */
-.sm-table{display:flex;flex-direction:column;padding:var(--table-pad);padding-top:var(--table-top);max-width:1200px;margin:0 auto}
+.sm-table{display:flex;flex-direction:column;padding:var(--table-pad);padding-top:var(--table-top);padding-bottom:100px;max-width:1200px;margin:0 auto}
 /* The filter sits in that air, so the column heads stay where they are on a list without one (2026-11-13). */
 .sm-table--tools{padding-top:20px}
 .sm-table__tools{display:flex;align-items:center;gap:12px;height:40px;margin-bottom:20px;padding:0 8px}
@@ -800,6 +803,13 @@ html:has(.sm-admin),body:has(.sm-admin){overscroll-behavior:none}
   min-width:0;min-height:0;overflow:hidden;
 }
 .sm-canvas__scroll{flex:1;min-height:0;overflow:auto;padding:var(--canvas-pad)}
+/* A global item's canvas (spec 2026-11-14): a row above the frame — where the item is used, and which page shows it. */
+.sm-globalcanvas{display:flex;flex-direction:column;min-width:0;min-height:0}
+.sm-globalcanvas>.sm-canvas{flex:1}
+.sm-globalcanvas__bar{flex:none;display:flex;align-items:center;justify-content:space-between;gap:12px;flex-wrap:wrap;padding:0 4px 8px;min-height:28px}
+.sm-globalcanvas__bar .sm-hint{margin:0}
+.sm-globalcanvas__pick{display:flex;align-items:center;gap:8px}
+.sm-globalcanvas__pick .sm-select{width:auto;height:30px;padding:0 10px}
 .sm-page{
   position:relative;background:var(--page-bg);border-radius:var(--page-radius);
   box-shadow:var(--shadow-page);min-height:100%;
@@ -955,6 +965,22 @@ html:has(.sm-admin),body:has(.sm-admin){overscroll-behavior:none}
   width:26px;height:26px;flex:none;border-radius:var(--radius-sm);background:var(--accent-soft);
   color:var(--accent);display:grid;place-items:center;font-size:13px;
 }
+/* The insert picker as a modal (spec 2026-11-14 add section previews): the rows keep the picker's item styles in a
+   plain column; beside them the current row as the site draws it, in one scaled, cropped frame. */
+.sm-insert{display:flex;flex:1;min-height:0}
+.sm-insert__list{width:auto;flex:1;min-width:0;overflow-y:auto;background:transparent;border:0;border-radius:0;box-shadow:none;padding:8px}
+.sm-insert__side{flex:1;min-width:0;min-height:0;display:flex;flex-direction:column}
+.sm-insert--pane .sm-insert__side{flex:none;width:300px;border-right:var(--card-divider)}
+.sm-insert__foot{flex:none;display:flex;align-items:center;gap:8px;padding:10px 16px;border-top:var(--card-divider);font-size:var(--text-sm);color:var(--text-muted);cursor:pointer}
+/* The preview pane is a small canvas (2026-11-14): the canvas tone, inset from the dialog's edges, its corners rounded. */
+.sm-insert__pane{flex:1;min-width:0;display:flex;flex-direction:column;gap:12px;padding:20px;margin:0 16px 16px 0;border-radius:12px;background:var(--canvas)}
+.sm-insert__preview{flex:1;min-height:0;display:flex;flex-direction:column;justify-content:center;overflow:hidden;padding:4px 4px 10px} /* room for the crop's shadow */
+.sm-insert__crop{position:relative;width:100%;overflow:hidden;border-radius:var(--radius-md);max-height:100%}
+/* A hairline and a small shadow keep a light section off a light pane. */
+.sm-insert__crop--shown{background:#fff;box-shadow:0 0 0 1px rgba(21,23,39,.1),0 2px 8px rgba(21,23,39,.1)}
+.sm-insert__fallback{flex:1;display:grid;place-items:center;border-radius:var(--radius-md);border:1px dashed var(--line)}
+.sm-insert__icon{width:72px;height:72px;border-radius:var(--radius-md);background:var(--accent-soft);color:var(--accent);display:grid;place-items:center;font-size:32px}
+.sm-insert__caption{flex:none;min-height:40px}
 /* Combobox (spec 2026-09-17 §1): the input owns the width, the list hangs under it —
    portaled and fixed at the input's width (--combo-w), above modals and below
    the confirm scrim (2026-09-27); inline under the input in static markup. */
@@ -1106,6 +1132,7 @@ html:has(.sm-admin),body:has(.sm-admin){overscroll-behavior:none}
 }
 .sm-media__thumb{position:relative;overflow:hidden;max-width:100%;max-height:300px;background:var(--surface-inset)}
 .sm-media__thumb>img,.sm-media__thumb>video{position:absolute;max-width:none;display:block}
+.sm-media__thumb--placeholder>img{inset:0;width:100%;height:100%}
 .sm-media__alt{font-size:var(--text-sm);color:var(--text-muted);overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
 .sm-media>.sm-media__alt{text-align:center}
 .sm-media__actions{display:flex;gap:6px}

package/dist/admin/validate.js

@@ -15,7 +15,7 @@ import { isCalendarDay, isInstant } from "./forms/date-picker.js";
 import { fits, misfitMessage } from "./drift.js";
 import { isSegment } from "../paths.js";
 import { safeHref } from "../richtext-href.js";
-import { isCrop } from "../media.js";
+import { isCrop, isImagePlaceholder } from "../media.js";
 /** A slug outside the path grammar, at publish (spec 2026-09-28 ASCII slugs §3). */
 export const SLUG_GRAMMAR_MESSAGE = "Use lowercase letters, digits and single hyphens, like my-post.";
 /** A link field takes only what the site renders (richtext-href.ts's rule): the widget says so as the editor types,
@@ -36,7 +36,8 @@ function validateValue(path, value, d, errors, elements, scope) {
     // An optional object with nothing filled in is absent (drafts inserted before 2026-09-26 carry `{}`).
     if (d.type === "object" && d.optional === true && isBlankObject(value))
         return;
-    if (isEmpty(value)) {
+    // An image placeholder is unset to publish (spec 2026-11-14 filled samples): Required on a required image.
+    if (isEmpty(value) || (d.type === "image" && isImagePlaceholder(value))) {
         if (!mayBeAbsent(d))
             errors.push({ field: path, message: "Required." });
         return;

package/dist/api-client.js

@@ -29,7 +29,8 @@ export function createSmoodlyApi(options) {
      *  server pushes its schema to the space it reads, so the developer must see when that space is production. */
     let pushed = null;
     const pushOnce = (body) => (pushed ?? (pushed = pushSchema({ apiUrl, spaceId: options.spaceId, key: options.key, fetch: doFetch }, body).then((result) => { const line = pushLine(options.spaceId, result); console.log(`smoodly: ${line[0].toLowerCase()}${line.slice(1)}`); }, (e) => console.error(`smoodly: the schema push failed — ${e instanceof Error ? e.message : String(e)}; the site runs against the schema the space has.`))));
-    async function call(path, params) {
+    /** `send`: a read that carries a body (the picker's samples) goes as a POST; every other read is a GET. */
+    async function call(path, params, send) {
         if (push)
             await pushOnce(push);
         countRead();
@@ -39,7 +40,9 @@ export function createSmoodlyApi(options) {
                 url.searchParams.set(k, v);
         let res;
         try {
-            res = await doFetch(url.toString(), { headers: { authorization: `Bearer ${options.key}`, accept: "application/json" } });
+            res = await doFetch(url.toString(), send === undefined
+                ? { headers: { authorization: `Bearer ${options.key}`, accept: "application/json" } }
+                : { method: "POST", headers: { authorization: `Bearer ${options.key}`, accept: "application/json", "content-type": "application/json" }, body: JSON.stringify(send) });
         }
         catch (e) {
             throw new TypeError(`smoodly: can't reach SMOODLY_API_URL (${apiUrl}): ${e instanceof Error ? e.message : String(e)}`);
@@ -60,6 +63,8 @@ export function createSmoodlyApi(options) {
         styles: statics.styles,
         custom: statics.custom,
         codePage: statics.codePage,
+        sampleTree: statics.sampleTree,
+        sampleCollections: statics.sampleCollections,
         async locate(locale, path) {
             return (await call("/locate", { locale, path })).data;
         },
@@ -71,6 +76,11 @@ export function createSmoodlyApi(options) {
             const r = await call("/load", { kind: target.kind, id: target.id, locale, path, draft: o?.draft ? "1" : undefined, version: o?.version });
             return withTags(r.data, r.tags, draft);
         },
+        async loadSamples(target, locale, path, tree) {
+            if (target.kind !== "page")
+                return null;
+            return (await call("/load-samples", {}, { id: target.id, locale, path, tree })).data;
+        },
         async lookup(locale, path) {
             const r = await call("/lookup", { locale, path });
             return withTags(r.data.hit, r.tags, false);

package/dist/astro/middleware.js

@@ -5,6 +5,7 @@
 // for the body is what makes a late read count. A preview response gains the draft marker and, in the
 // canvas, the bridge, when the shell rendered it; a live page gains nothing. Nothing under the preview
 // address is ever stored, and neither is a render a publish overtook or one a read failed in.
+import { SAMPLES_PARAM } from "../canvas-marker.js";
 import { defineMiddleware } from "astro:middleware";
 import { loadAdminFiles } from "../admin/files.js";
 import { ADMIN_INTERNAL } from "../admin/page-data.js";
@@ -32,6 +33,7 @@ export const onRequest = defineMiddleware(async (context, next) => {
         draft,
         editor: draft && searchParams.get("smoodly-editor") === "1",
         version: (draft && searchParams.get("smoodly-version")) || undefined,
+        samples: (draft && searchParams.get(SAMPLES_PARAM)) || undefined,
         cacheable: false,
         shell: false,
     };

package/dist/astro/shell.d.ts

@@ -14,6 +14,9 @@ export type SmoodlyLocals = {
     editor: boolean;
     /** History's stored version, inside a preview only. */
     version?: string;
+    /** The picker's zone (`smoodly-samples`), inside a preview only: its rows are drawn from their samples in place of
+     *  the page's content (spec 2026-11-14 add section previews). */
+    samples?: string;
     /** Set by the shell when it rendered a page read from the service: the response may be cached under its tags. */
     cacheable: boolean;
     /** Set by the shell when it rendered a page at all: in a preview, only that response is a canvas. */