smoodly 0.0.62 → 0.0.63

package/dist/conditions.js

@@ -1,3 +1,4 @@
+import { isImagePlaceholder } from "./media.js";
 export function when(path) {
     if (typeof path !== "string" || path === "")
         throw new Error("smoodly: f.when() needs a field path.");
@@ -22,10 +23,12 @@ function lookup(path, scope) {
     const holder = ns === null ? scope.self : scope[ns];
     return holder?.[key];
 }
-/** Empty as the validator sees it, plus a media value with no asset. */
+/** Empty as the validator sees it, plus a media value with no asset: an image placeholder included, since a condition
+ *  follows what will be published (spec 2026-11-14 filled samples). */
 const isEmptyValue = (v) => v === undefined || v === null || v === "" || (Array.isArray(v) && v.length === 0) ||
     (typeof v === "object" && !Array.isArray(v) && Object.keys(v).length === 0) ||
-    (typeof v === "object" && !Array.isArray(v) && "asset" in v && typeof v.asset !== "string");
+    (typeof v === "object" && !Array.isArray(v) && "asset" in v && typeof v.asset !== "string") ||
+    isImagePlaceholder(v);
 export function evaluate(c, scope) {
     const v = lookup(c.path, scope);
     switch (c.op) {

package/dist/media.d.ts

@@ -137,6 +137,14 @@ export declare const cropAspect: (crop: Crop, imageAspect: number) => number;
 export declare const isMediaValue: (v: unknown) => v is {
     asset: string;
 };
+/** What a fresh node stores in an image field its `sample` leaves out (spec 2026-11-14 filled samples): no asset, so
+ *  no asset reference. A draft read draws it; a published read, publish and a condition take it as unset. */
+export type ImagePlaceholder = {
+    placeholder: true;
+};
+/** Frozen: a caller stores a copy (`{ ...IMAGE_PLACEHOLDER }`). */
+export declare const IMAGE_PLACEHOLDER: ImagePlaceholder;
+export declare const isImagePlaceholder: (v: unknown) => v is ImagePlaceholder;
 /** Every asset id a value set references, walking lists and objects —
  *  unlike refs, media may sit inside a container (spec §8). */
 export declare function collectAssetIds(values: Record<string, unknown> | undefined, descriptors: Record<string, Descriptor>, out: Set<string>, elements?: ElementSchemas): void;
@@ -153,11 +161,16 @@ export declare function isCrop(c: unknown): c is Crop;
 export declare function framedCrop(value: Pick<ImageValue, "crop" | "crops">, names: string[], name: string, ratio: string, imageAspect: number): Crop | undefined;
 /** What a crop nobody framed shows: the largest rectangle at its ratio around the hotspot, as fractions. */
 export declare function followingCrop(ratio: string, hotspot: Hotspot | undefined, width: number, height: number): Crop;
+/** What a draft read hands a view for a stored placeholder (spec 2026-11-14 filled samples): a picture at the field's
+ *  own aspect (its first named crop's, else its `aspect`, else 3:2), 1200 wide, with no `cut`: the view draws the
+ *  address as it is. A field with named crops carries every crop, as an unframed photo would. */
+export declare function placeholderImage(d: Descriptor, defaults?: ImageDefaults): ResolvedImage;
 /** Replace every media value in place with its resolved object — or delete
  *  it when the asset is missing or pending, so `image?.url` guards hold. With
  *  `cuts`, every raster image resolved pushes its cut request (signCuts fills them); `defaults` are the project's
- *  image quality and cap, under a field's own. */
-export declare function applyAssets(values: Record<string, unknown> | undefined, descriptors: Record<string, Descriptor>, assets: Map<string, AssetRecord>, elements?: ElementSchemas, cuts?: CutRequest[], defaults?: ImageDefaults): void;
+ *  image quality and cap, under a field's own. `placeholders` is the read's kind (spec 2026-11-14 filled samples):
+ *  true in a draft read, where a stored image placeholder becomes a picture; false, it is deleted like a gone asset. */
+export declare function applyAssets(values: Record<string, unknown> | undefined, descriptors: Record<string, Descriptor>, assets: Map<string, AssetRecord>, elements?: ElementSchemas, cuts?: CutRequest[], defaults?: ImageDefaults, placeholders?: boolean): void;
 /** Signs each distinct rectangle once and fills every request for it: two fields framing one photo the same way share a
  *  signature, an address and a cache entry. */
 export declare function signCuts(requests: CutRequest[], signer: CutSigner): Promise<void>;

package/dist/media.js

@@ -36,6 +36,10 @@ export function parseAspect(s) {
 /** The crop's own pixel ratio, given the image's. */
 export const cropAspect = (crop, imageAspect) => (crop.width * imageAspect) / crop.height;
 export const isMediaValue = (v) => typeof v === "object" && v !== null && !Array.isArray(v) && typeof v.asset === "string";
+/** Frozen: a caller stores a copy (`{ ...IMAGE_PLACEHOLDER }`). */
+export const IMAGE_PLACEHOLDER = Object.freeze({ placeholder: true });
+export const isImagePlaceholder = (v) => typeof v === "object" && v !== null && !Array.isArray(v) &&
+    v.placeholder === true && typeof v.asset !== "string";
 /** Every asset id a value set references, walking lists and objects —
  *  unlike refs, media may sit inside a container (spec §8). */
 export function collectAssetIds(values, descriptors, out, elements = {}) {
@@ -187,7 +191,60 @@ function resolvedImage(asset, value, d, cuts, defaults) {
         cuts.push({ path: asset.path, rect: cutRect(image), set: (cut) => { image.cut = cut; } });
     return image;
 }
-function resolveOne(value, d, assets, cuts, defaults) {
+const PLACEHOLDER_WIDTH = 1200;
+const PLACEHOLDER_ASPECT = "3:2";
+/** A neutral rectangle with a picture mark, as a `data:` address: nothing to fetch, and never the same as a photo. */
+function placeholderUrl(width, height) {
+    const m = Math.round(Math.min(width, height) / 5);
+    const x = Math.round(width / 2 - m), y = Math.round(height / 2 - m * 0.75);
+    const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}">` +
+        `<rect width="${width}" height="${height}" fill="#e4e4e7"/>` +
+        `<g transform="translate(${x} ${y})" fill="none" stroke="#a1a1aa" stroke-width="${Math.max(2, Math.round(m / 12))}" stroke-linejoin="round">` +
+        `<rect width="${m * 2}" height="${Math.round(m * 1.5)}" rx="${Math.round(m / 8)}"/>` +
+        `<circle cx="${Math.round(m * 0.55)}" cy="${Math.round(m * 0.45)}" r="${Math.round(m / 6)}"/>` +
+        `<path d="M0 ${Math.round(m * 1.2)} L${Math.round(m * 0.7)} ${Math.round(m * 0.75)} L${Math.round(m * 1.15)} ${Math.round(m * 1.1)} L${Math.round(m * 1.5)} ${Math.round(m * 0.85)} L${m * 2} ${Math.round(m * 1.25)}"/>` +
+        `</g></svg>`;
+    return `data:image/svg+xml,${encodeURIComponent(svg)}`;
+}
+/** What a draft read hands a view for a stored placeholder (spec 2026-11-14 filled samples): a picture at the field's
+ *  own aspect (its first named crop's, else its `aspect`, else 3:2), 1200 wide, with no `cut`: the view draws the
+ *  address as it is. A field with named crops carries every crop, as an unframed photo would. */
+export function placeholderImage(d, defaults) {
+    const named = namedCropsOf(d);
+    const declared = Array.isArray(d.aspect) ? d.aspect[0] : d.aspect;
+    const aspect = named ? Object.values(named)[0] : typeof declared === "string" ? declared : undefined;
+    let ratio;
+    try {
+        ratio = parseAspect(aspect ?? PLACEHOLDER_ASPECT);
+    }
+    catch {
+        ratio = parseAspect(PLACEHOLDER_ASPECT);
+    }
+    const width = PLACEHOLDER_WIDTH;
+    const height = Math.round(width / ratio);
+    const image = {
+        url: placeholderUrl(width, height), width, height, mime: "image/svg+xml", alt: "",
+        ...(aspect && !named ? { aspect } : {}),
+        ...delivery(d, defaults),
+    };
+    if (named) {
+        const crops = {};
+        Object.entries(named).forEach(([name, r], i) => {
+            const rect = hotspotRect(parseAspect(r), undefined, width, height);
+            crops[name] = { crop: { left: rect.left / width, top: rect.top / height, width: rect.width / width, height: rect.height / height }, aspect: r, width: rect.width, height: rect.height };
+            if (i === 0) {
+                image.crop = crops[name].crop;
+                image.aspect = r;
+            }
+        });
+        image.crops = crops;
+    }
+    return image;
+}
+function resolveOne(value, d, assets, cuts, defaults, placeholders = false) {
+    // A stored placeholder (spec 2026-11-14 filled samples): a picture in a read that asks for it, unset in any other.
+    if (d.type === "image" && isImagePlaceholder(value))
+        return placeholders ? placeholderImage(d, defaults) : undefined;
     if (!isMediaValue(value))
         return undefined;
     const asset = assets.get(value.asset);
@@ -214,8 +271,9 @@ function resolveOne(value, d, assets, cuts, defaults) {
 /** Replace every media value in place with its resolved object — or delete
  *  it when the asset is missing or pending, so `image?.url` guards hold. With
  *  `cuts`, every raster image resolved pushes its cut request (signCuts fills them); `defaults` are the project's
- *  image quality and cap, under a field's own. */
-export function applyAssets(values, descriptors, assets, elements = {}, cuts, defaults) {
+ *  image quality and cap, under a field's own. `placeholders` is the read's kind (spec 2026-11-14 filled samples):
+ *  true in a draft read, where a stored image placeholder becomes a picture; false, it is deleted like a gone asset. */
+export function applyAssets(values, descriptors, assets, elements = {}, cuts, defaults, placeholders = false) {
     if (!values)
         return;
     for (const [key, d] of Object.entries(descriptors)) {
@@ -223,7 +281,7 @@ export function applyAssets(values, descriptors, assets, elements = {}, cuts, de
         if (value == null)
             continue;
         if (MEDIA_TYPES.has(d.type)) {
-            const resolved = resolveOne(value, d, assets, cuts, defaults);
+            const resolved = resolveOne(value, d, assets, cuts, defaults, placeholders);
             if (resolved === undefined)
                 delete values[key];
             else
@@ -232,7 +290,7 @@ export function applyAssets(values, descriptors, assets, elements = {}, cuts, de
         else if (d.type === "richtext") {
             for (const node of richtextBlocks(value)) {
                 if (node.type === IMAGE_NODE) {
-                    const resolved = resolveOne(node.attrs.image, { type: "image" }, assets, cuts, defaults);
+                    const resolved = resolveOne(node.attrs.image, { type: "image" }, assets, cuts, defaults, placeholders);
                     if (resolved === undefined)
                         delete node.attrs.image;
                     else
@@ -242,27 +300,27 @@ export function applyAssets(values, descriptors, assets, elements = {}, cuts, de
                     const schema = elementOf(node, elements);
                     if (schema)
                         for (const set of elementSets(node, schema))
-                            applyAssets(set.values, set.descriptors, assets, elements, cuts, defaults);
+                            applyAssets(set.values, set.descriptors, assets, elements, cuts, defaults, placeholders);
                 }
             }
         }
         else if (d.type === "object" && typeof value === "object" && !Array.isArray(value)) {
-            applyAssets(value, d.fields, assets, elements, cuts, defaults);
+            applyAssets(value, d.fields, assets, elements, cuts, defaults, placeholders);
         }
         else if (d.type === "list" && Array.isArray(value)) {
             const item = d.item;
             if (MEDIA_TYPES.has(item.type)) {
-                values[key] = value.map((v) => resolveOne(v, item, assets, cuts, defaults)).filter((v) => v !== undefined);
+                values[key] = value.map((v) => resolveOne(v, item, assets, cuts, defaults, placeholders)).filter((v) => v !== undefined);
             }
             else if (item.type === "object") {
                 for (const v of value)
                     if (v && typeof v === "object")
-                        applyAssets(v, item.fields, assets, elements, cuts, defaults);
+                        applyAssets(v, item.fields, assets, elements, cuts, defaults, placeholders);
             }
             else if (item.type === "richtext") {
                 // Resolves in place inside the document object `v`; the wrapper is throwaway.
                 for (const v of value)
-                    applyAssets({ v }, { v: item }, assets, elements, cuts, defaults);
+                    applyAssets({ v }, { v: item }, assets, elements, cuts, defaults, placeholders);
             }
         }
     }

package/dist/next/page-renderer.js

@@ -8,7 +8,8 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
 import { Suspense } from "react";
 import { draftMode } from "next/headers";
 import { notFound, permanentRedirect, unstable_rethrow } from "next/navigation";
-import { markCanvasPath, readCanvasMarker } from "../canvas-marker.js";
+import { markCanvasPath, readCanvasMarker, SAMPLES_PARAM } from "../canvas-marker.js";
+import { samplesHit } from "../sample-tree.js";
 import { BRIDGE_CSS } from "../marks.js";
 import { CanvasBridgeSlot, CanvasNetSlot } from "./canvas-slot.js";
 import { DRAFT_META_NAME } from "../admin/editor/canvas-diagnosis.js";
@@ -115,7 +116,12 @@ export function createPageRenderer(options) {
         const editor = draft && (marker?.editor === true || params?.["smoodly-editor"] === "1");
         const version = !draft ? undefined
             : marker?.version ?? (typeof versionParam === "string" && versionParam !== "" ? versionParam : undefined);
-        const flags = marker?.editor ? { editor: true } : marker?.version ? { version: marker.version } : null;
+        // The picker's samples (spec 2026-11-14 add section previews): the zone's rows drawn in place of the page's content.
+        const samplesParam = params?.[SAMPLES_PARAM];
+        const samples = !draft ? undefined
+            : marker?.samples ?? (typeof samplesParam === "string" && samplesParam !== "" ? samplesParam : undefined);
+        const flags = marker?.editor ? { editor: true } : marker?.version ? { version: marker.version }
+            : marker?.samples ? { samples: marker.samples } : null;
         const target = await site.locate(locale, path);
         // No document to tag: a redirect row, a miss or a code-owned page. Next caches the response like a
         // page, so it hears the addresses tag (reads.ts missUnit, decision 4).
@@ -127,16 +133,17 @@ export function createPageRenderer(options) {
         if (!target)
             await tagAddress();
         // A code-owned address with no record yet is served from code (spec 2026-09-30 tester findings §2).
-        const hit = target ? await load(target, locale, path, version) : site.codePage(locale, path);
-        if (!hit || !accept(hit)) {
+        const loaded = target ? await load(target, locale, path, version) : site.codePage(locale, path);
+        if (!loaded || !accept(loaded)) {
             if (target)
                 await tagAddress();
             notFound();
         }
+        const hit = samples !== undefined ? await samplesHit(site, loaded, target, locale, path, samples) : loaded;
         // The draft marker tells the page editor's canvas diagnosis that Smoodly
         // rendered this response (spec 2026-09-27 shadowed-page detector §3);
         // React hoists the meta into the head. Never outside draft mode.
-        return (_jsxs(_Fragment, { children: [draft ? _jsx("meta", { name: DRAFT_META_NAME }) : null, editor ? _jsx("style", { "data-smoodly-bridge": "", children: BRIDGE_CSS }) : null, editor ? _jsx(CanvasBridgeSlot, {}) : null, draft && !editor && !version ? previewPill({ route: options.previewRoute }) : null, render(hit, editor, locale)] }));
+        return (_jsxs(_Fragment, { children: [draft ? _jsx("meta", { name: DRAFT_META_NAME }) : null, editor ? _jsx("style", { "data-smoodly-bridge": "", children: BRIDGE_CSS }) : null, editor ? _jsx(CanvasBridgeSlot, {}) : null, draft && !editor && !version && samples === undefined ? previewPill({ route: options.previewRoute }) : null, render(hit, editor, locale)] }));
     }
     async function metadata(pathFor, opts, accept) {
         // generateMetadata runs alongside the page render, so it gates too. It runs no miss unit: Next renders

package/dist/resolve.d.ts

@@ -47,6 +47,9 @@ type ResolveOptions = {
     page?: {
         fields: Record<string, Descriptor>;
     };
+    /** A draft read (spec 2026-11-14 filled samples): a stored image placeholder becomes a picture. Absent or false, a
+     *  published read, it is dropped like an image whose asset is gone. */
+    placeholders?: boolean;
     /** The custom section's columns toolset (spec 2026-09-14 §6); the default when absent. The schema is always in the map. */
     custom?: {
         toolset?: Toolset;
@@ -54,7 +57,7 @@ type ResolveOptions = {
 };
 export declare function resolveTree(tree: PageTree, options: ResolveOptions): Promise<PageTree>;
 /** One value set's media, resolved in place. Exported for the site layer's global-item settings. */
-export declare function resolveMedia(values: Record<string, unknown>, descriptors: Record<string, Descriptor>, fetch: AssetFetcher, elements?: ElementSchemas, signer?: CutSigner, defaults?: ImageDefaults): Promise<void>;
+export declare function resolveMedia(values: Record<string, unknown>, descriptors: Record<string, Descriptor>, fetch: AssetFetcher, elements?: ElementSchemas, signer?: CutSigner, defaults?: ImageDefaults, placeholders?: boolean): Promise<void>;
 export type ResolveFieldsOptions = {
     collections: CollectionSchema<any>[];
     fetch: EntryFetcher;
@@ -68,6 +71,8 @@ export type ResolveFieldsOptions = {
     /** Registered Elements a richtext document may embed (spec 2026-09-08 block nodes §2). */
     elements?: SectionLike[];
     maxDepth?: number;
+    /** A draft read: a stored image placeholder becomes a picture (spec 2026-11-14 filled samples). */
+    placeholders?: boolean;
 };
 /** One entry's fields, refs hydrated — the entry page's counterpart of
  *  resolveTree. Same rules, same batching, same cycle cut. */

package/dist/resolve.js

@@ -62,7 +62,7 @@ export async function resolveTree(tree, options) {
             sets.push({ values: resolved.fields, descriptors: options.page.fields });
         if (resolved.meta)
             sets.push({ values: resolved.meta, descriptors: META_DESCRIPTORS });
-        await resolveMediaSets([...sets, ...hydrated], options.assets, elementSchemas(options.elements), options.signer, options.images);
+        await resolveMediaSets([...sets, ...hydrated], options.assets, elementSchemas(options.elements), options.signer, options.images, options.placeholders);
     }
     return resolved;
 }
@@ -83,20 +83,20 @@ async function fetchAssets(fetch, ids) {
     return out;
 }
 /** One value set's media, resolved in place. Exported for the site layer's global-item settings. */
-export async function resolveMedia(values, descriptors, fetch, elements = {}, signer, defaults) {
-    await resolveMediaSets([{ values, descriptors }], fetch, elements, signer, defaults);
+export async function resolveMedia(values, descriptors, fetch, elements = {}, signer, defaults, placeholders) {
+    await resolveMediaSets([{ values, descriptors }], fetch, elements, signer, defaults, placeholders);
 }
 /** Many value sets, one asset round (plus one for posters): the tree's
  *  nodes and every entry hydrated through a ref, or a list page's items.
  *  Exported for the site layer's content API. */
-async function resolveMediaSets(sets, fetch, elements = {}, signer, defaults) {
+async function resolveMediaSets(sets, fetch, elements = {}, signer, defaults, placeholders = false) {
     const ids = new Set();
     for (const { values, descriptors } of sets)
         collectAssetIds(values, descriptors, ids, elements);
     const assets = await fetchAssets(fetch, ids);
     const cuts = signer ? [] : undefined;
     for (const { values, descriptors } of sets)
-        applyAssets(values, descriptors, assets, elements, cuts, defaults);
+        applyAssets(values, descriptors, assets, elements, cuts, defaults, placeholders);
     if (signer && cuts)
         await signCuts(cuts, signer);
 }
@@ -151,7 +151,7 @@ export async function resolveFields(fields, descriptors, options) {
     collectTasks(resolved, descriptors, tasks);
     const hydrated = await runResolution(tasks, { ...options, maxDepth: options.maxDepth ?? Infinity });
     if (options.assets)
-        await resolveMediaSets([{ values: resolved, descriptors }, ...hydrated], options.assets, elementSchemas(options.elements), options.signer, options.images);
+        await resolveMediaSets([{ values: resolved, descriptors }, ...hydrated], options.assets, elementSchemas(options.elements), options.signer, options.images, options.placeholders);
     return resolved;
 }
 /** Many value sets (a list's entries), one resolution: every ref batched per
@@ -162,7 +162,7 @@ export async function resolveFieldSets(sets, options) {
         collectTasks(values, descriptors, tasks);
     const hydrated = await runResolution(tasks, { ...options, maxDepth: options.maxDepth ?? Infinity });
     if (options.assets)
-        await resolveMediaSets([...sets, ...hydrated], options.assets, elementSchemas(options.elements), options.signer, options.images);
+        await resolveMediaSets([...sets, ...hydrated], options.assets, elementSchemas(options.elements), options.signer, options.images, options.placeholders);
 }
 /** Hydrates every task's refs in place and returns each hydrated entry
  *  copy with its collection's descriptors — the media pass walks those

package/dist/sample-fill.d.ts

@@ -0,0 +1,40 @@
+/** Collection name → entry ids, in the order to use them: the first published entries, read by the caller. */
+export type SamplePicks = Record<string, string[]>;
+/** `empty`: neither the sample nor generated values (the picker's switch, off). `images: false` stores no image
+ *  placeholder: a service older than the placeholder would refuse to publish it. */
+export type FreshOptions = {
+    picks?: SamplePicks;
+    empty?: boolean;
+    images?: boolean;
+};
+/** A field descriptor as registered or as serialized for the admin: the keys the rules read are the same in both. */
+export type FieldLike = {
+    type: string;
+    optional?: unknown;
+    default?: unknown;
+    min?: unknown;
+    max?: unknown;
+    item?: unknown;
+    fields?: unknown;
+    toolset?: unknown;
+    target?: unknown;
+    options?: unknown;
+};
+export declare const LOREM_TITLE = "Lorem ipsum dolor sit";
+export declare const LOREM_SENTENCE = "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor.";
+/** How many entries of a collection the picks hold: the site's read and the admin's operation ask for this many. */
+export declare const SAMPLE_PICK_LIMIT = 3;
+/** A required choice shows its first option (FieldWidget renders no blank one), so a new node stores it too, and
+ *  publish never says Required for a choice the editor sees made. */
+export declare const firstChoice: (d: FieldLike) => unknown;
+/** What is not content: a field's default, a required choice's first option, a boolean's false. */
+export declare const starting: (d: FieldLike) => unknown;
+/** The value for a field its sample and default leave out, or undefined to leave it as today. Text, richtext, a list
+ *  and an object are generated when required only; an image whether required or not; a list of references whether
+ *  required or not, a single reference when required. Every call builds new objects. */
+export declare function generated(key: string, d: FieldLike, options?: FreshOptions): unknown;
+/** The collections a top-level `ref` or `refList` field of these sections targets, unique, in first-seen order: what
+ *  the caller reads picks for (the resolver follows references at a node's top level only). */
+export declare function sampleCollections(sections: {
+    fields: Record<string, FieldLike>;
+}[]): string[];

package/dist/sample-fill.js

@@ -0,0 +1,145 @@
+// What a fresh node's field starts with when its `sample` and `default` are silent (spec 2026-11-14 filled samples).
+// Pure and synchronous, with no randomness: the site builds the picker's pictures and the admin the insert from the
+// same schema, and equal input must give equal values or the picture and the insert differ. `nodeFromSample`
+// (admin/tree-ops.ts) is the one caller that builds a node; nothing here reads a store.
+import { optionsOf } from "./fields.js";
+import { IMAGE_PLACEHOLDER } from "./media.js";
+import { allowedOf } from "./toolset.js";
+export const LOREM_TITLE = "Lorem ipsum dolor sit";
+export const LOREM_SENTENCE = "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor.";
+const LOREM_SECOND = "Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.";
+const LOREM_POINTS = ["Duis aute irure dolor", "Excepteur sint occaecat", "Sunt in culpa qui officia"];
+/** How many references or list items a filled field shows when nothing says otherwise. */
+const FILL_COUNT = 3;
+/** How many entries of a collection the picks hold: the site's read and the admin's operation ask for this many. */
+export const SAMPLE_PICK_LIMIT = FILL_COUNT;
+/** A key that reads as a title, in any casing or as part of the key (`cardTitle`, `buttonLabel`). */
+const TITLE_LIKE = /title|heading|headline|name|label|eyebrow|kicker|button|cta/i;
+const count = (v) => (typeof v === "number" && Number.isFinite(v) ? Math.floor(v) : undefined);
+/** Cut at a word boundary, without the punctuation the cut leaves hanging; a limit below one word cuts the word. */
+function fitted(text, max) {
+    if (max === undefined || text.length <= max)
+        return text;
+    if (max < 1)
+        return undefined;
+    const cut = text.slice(0, max);
+    // The cut ended a word exactly when the next character is a space.
+    const whole = text[max] === " " ? cut : cut.slice(0, Math.max(0, cut.lastIndexOf(" ")));
+    const trimmed = whole.replace(/[\s,.;:]+$/, "");
+    return trimmed !== "" ? trimmed : cut;
+}
+const textNode = (text) => ({ type: "text", text });
+const paragraph = (text) => ({ type: "paragraph", content: [textNode(text)] });
+/** A TipTap document as the admin's editor stores one, from the formats the toolset allows: with a block format
+ *  (a heading or a list) a heading, two paragraphs and a three-item list; with inline marks only, one paragraph. */
+function richtextFill(toolset) {
+    const allowed = allowedOf(toolset);
+    const level = allowed.headingLevels.length > 0 ? Math.min(...allowed.headingLevels) : undefined;
+    const list = allowed.nodes.has("bulletList") ? "bulletList" : allowed.nodes.has("orderedList") ? "orderedList" : undefined;
+    if (level === undefined && list === undefined)
+        return { type: "doc", content: [paragraph(LOREM_SENTENCE)] };
+    return {
+        type: "doc",
+        content: [
+            ...(level !== undefined ? [{ type: "heading", attrs: { level }, content: [textNode(LOREM_TITLE)] }] : []),
+            paragraph(LOREM_SENTENCE),
+            paragraph(LOREM_SECOND),
+            ...(list !== undefined ? [{ type: list, content: LOREM_POINTS.map((p) => ({ type: "listItem", content: [paragraph(p)] })) }] : []),
+        ],
+    };
+}
+/** The collection a reference field targets: a function on a registered schema, a name on a serialized one. */
+function targetName(d) {
+    const t = d.target;
+    if (typeof t === "string")
+        return t !== "" ? t : undefined;
+    if (typeof t !== "function")
+        return undefined;
+    try {
+        const name = t()?.name;
+        return typeof name === "string" && name !== "" ? name : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A required choice shows its first option (FieldWidget renders no blank one), so a new node stores it too, and
+ *  publish never says Required for a choice the editor sees made. */
+export const firstChoice = (d) => (d.type === "select" || d.type === "radio") && d.optional !== true ? optionsOf(d.options)[0]?.value : undefined;
+/** What is not content: a field's default, a required choice's first option, a boolean's false. */
+export const starting = (d) => d.default ?? firstChoice(d) ?? (d.type === "boolean" ? false : undefined);
+const subfields = (d) => d.fields && typeof d.fields === "object" ? d.fields : {};
+/** An object's members: each one's starting value, else its generated one; a member with neither is left out. */
+function members(d, options) {
+    const out = {};
+    for (const [key, sub] of Object.entries(subfields(d))) {
+        const v = starting(sub) ?? generated(key, sub, options);
+        if (v !== undefined)
+            out[key] = v;
+    }
+    return out;
+}
+/** The value for a field its sample and default leave out, or undefined to leave it as today. Text, richtext, a list
+ *  and an object are generated when required only; an image whether required or not; a list of references whether
+ *  required or not, a single reference when required. Every call builds new objects. */
+export function generated(key, d, options = {}) {
+    const required = d.optional !== true;
+    const max = count(d.max);
+    switch (d.type) {
+        case "text":
+            return required ? fitted(TITLE_LIKE.test(key) ? LOREM_TITLE : LOREM_SENTENCE, max) : undefined;
+        case "richtext":
+            return required ? richtextFill(d.toolset) : undefined;
+        case "image":
+            return options.images === false ? undefined : { ...IMAGE_PLACEHOLDER };
+        case "ref": {
+            if (!required)
+                return undefined;
+            const target = targetName(d);
+            return target !== undefined ? options.picks?.[target]?.[0] : undefined;
+        }
+        case "refList": {
+            const target = targetName(d);
+            const ids = (target !== undefined ? options.picks?.[target] : undefined) ?? [];
+            const picked = ids.slice(0, Math.max(0, Math.min(FILL_COUNT, max ?? FILL_COUNT)));
+            return picked.length > 0 ? picked : undefined;
+        }
+        case "list": {
+            if (!required || !d.item || typeof d.item !== "object")
+                return undefined;
+            const item = d.item;
+            const min = count(d.min);
+            const n = Math.min(min !== undefined && min > 0 ? min : FILL_COUNT, max ?? Infinity);
+            if (n < 1)
+                return undefined;
+            const items = [];
+            for (let i = 0; i < n; i++) {
+                // An item is always there, so its own `optional` says nothing; a plain item takes the list's key for its size.
+                const v = item.type === "object" ? members(item, options) : generated(key, { ...item, optional: false }, options);
+                if (v === undefined)
+                    return undefined;
+                items.push(v);
+            }
+            return items;
+        }
+        case "object":
+            return required ? members(d, options) : undefined;
+        default:
+            return undefined;
+    }
+}
+/** The collections a top-level `ref` or `refList` field of these sections targets, unique, in first-seen order: what
+ *  the caller reads picks for (the resolver follows references at a node's top level only). */
+export function sampleCollections(sections) {
+    const out = [];
+    for (const s of sections) {
+        for (const d of Object.values(s.fields)) {
+            if (d.type !== "ref" && d.type !== "refList")
+                continue;
+            const target = targetName(d);
+            if (target !== undefined && !out.includes(target))
+                out.push(target);
+        }
+    }
+    return out;
+}

package/dist/sample-tree.d.ts

@@ -0,0 +1,30 @@
+import type { AdminSection } from "./admin/serialize.ts";
+import type { PageTree } from "./page-context.ts";
+import type { PathTarget } from "./paths.ts";
+import type { ContentReads, SiteHit } from "./site.ts";
+import { type SamplePicks } from "./sample-fill.ts";
+import type { ZonePolicy } from "./zones.ts";
+/** What the tree is built from: a section's name, descriptors and sample (a registered schema or the admin's
+ *  serialized one: `nodeFromSample` reads the same keys of both), and each global item's name and section. */
+export type SampleSource = {
+    sections: Pick<AdminSection, "name" | "fields" | "settings" | "sample">[];
+    globals: {
+        name: string;
+        section?: string;
+    }[];
+};
+/** A sample node's id, fixed so the admin finds it without asking. The middle word keeps a section a developer
+ *  named `custom` (or `global-…`) apart from the Custom section and from a global item. */
+export declare function sampleNodeId(kind: "section" | "custom" | "global", name?: string): string;
+/** The collections a zone's offered sections reference (spec 2026-11-14 filled samples): what the picks are read for. */
+export declare const zoneSampleCollections: (source: SampleSource, policy: ZonePolicy | undefined) => string[];
+/** The zone's picker rows as nodes, in the picker's order: the sections its policy allows, the Custom section where
+ *  the zone takes one, the visual global items whose section it allows. Each is what an insert would create; a
+ *  placement names its item alone (the service finds the row, and drops an item that has none). No other zone is
+ *  in the tree. `picks` fill the sections' reference fields (spec 2026-11-14 filled samples); the tree is always the
+ *  filled one, whatever the picker's switch says. */
+export declare function sampleTree(source: SampleSource, policy: ZonePolicy | undefined, zone: string, picks?: SamplePicks): PageTree;
+/** What a samples address draws for a hit: the page with the zone's samples resolved by the service. A page the
+ *  service cannot answer for (no record yet, an older service, an outage) is drawn with its zones empty, so the
+ *  admin finds no node and every row keeps its icon; an entry has no zones and is returned as it is. */
+export declare function samplesHit(site: ContentReads, hit: SiteHit, target: PathTarget | null, locale: string, path: string, zone: string): Promise<SiteHit>;

package/dist/sample-tree.js

@@ -0,0 +1,76 @@
+// The picker's samples (spec 2026-11-14 add section previews): what a zone's "+" offers, as nodes the site can draw.
+// The admin's modal shows each row as the site itself renders it; the site builds this tree from its registry (the
+// service holds no samples), the service resolves it in place of the page's draft (ContentReads.loadSamples), and
+// the admin finds each row's node in the frame by the ids below. Framework-free: both adapters use it.
+import { allowsCustom } from "./admin/custom-section.js";
+import { nodeFromSample } from "./admin/tree-ops.js";
+import { CUSTOM_NODE_TYPE, defaultRow } from "./custom/index.js";
+import { GLOBAL_NODE_TYPE } from "./global.js";
+import { SAMPLE_PICK_LIMIT, sampleCollections } from "./sample-fill.js";
+/** A sample node's id, fixed so the admin finds it without asking. The middle word keeps a section a developer
+ *  named `custom` (or `global-…`) apart from the Custom section and from a global item. */
+export function sampleNodeId(kind, name) {
+    return kind === "custom" ? "sample-custom" : `sample-${kind}-${name}`;
+}
+/** The sections a zone's picker offers: none for a locked zone or one the page type does not have. */
+function offered(source, policy) {
+    if (!policy || policy.kind === "locked")
+        return [];
+    return source.sections.filter((s) => policy.allow === "*" || policy.allow.includes(s.name));
+}
+/** The collections a zone's offered sections reference (spec 2026-11-14 filled samples): what the picks are read for. */
+export const zoneSampleCollections = (source, policy) => sampleCollections(offered(source, policy));
+/** The zone's picker rows as nodes, in the picker's order: the sections its policy allows, the Custom section where
+ *  the zone takes one, the visual global items whose section it allows. Each is what an insert would create; a
+ *  placement names its item alone (the service finds the row, and drops an item that has none). No other zone is
+ *  in the tree. `picks` fill the sections' reference fields (spec 2026-11-14 filled samples); the tree is always the
+ *  filled one, whatever the picker's switch says. */
+export function sampleTree(source, policy, zone, picks) {
+    const nodes = [];
+    if (policy && policy.kind !== "locked") {
+        const allows = (section) => policy.allow === "*" || policy.allow.includes(section);
+        for (const s of offered(source, policy))
+            nodes.push(nodeFromSample(s, sampleNodeId("section", s.name), { picks }));
+        // As the admin's customNode: the registry's custom sample is one default row.
+        if (allowsCustom(policy))
+            nodes.push({ id: sampleNodeId("custom"), type: CUSTOM_NODE_TYPE, fields: { rows: [defaultRow()] } });
+        for (const item of source.globals) {
+            if (item.section !== undefined && allows(item.section))
+                nodes.push({ id: sampleNodeId("global", item.name), type: GLOBAL_NODE_TYPE, fields: { item: item.name } });
+        }
+    }
+    return { zones: { [zone]: nodes } };
+}
+/** The reference picks of a zone's samples (spec 2026-11-14 filled samples): the first published entries of each
+ *  collection its sections reference, one published read per collection in the page's locale: the read the admin's
+ *  `entries.samplePicks` makes for the insert. A read that fails leaves that collection's references unfilled. */
+async function samplePicks(site, template, zone, locale) {
+    const picks = {};
+    await Promise.all(site.sampleCollections(template, zone).map(async (collection) => {
+        try {
+            picks[collection] = (await site.getEntries(collection, { locale, limit: SAMPLE_PICK_LIMIT })).map((e) => e.id);
+        }
+        catch (e) {
+            console.error(`smoodly: the picker's sample entries of "${collection}" could not be read — ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }));
+    return picks;
+}
+/** What a samples address draws for a hit: the page with the zone's samples resolved by the service. A page the
+ *  service cannot answer for (no record yet, an older service, an outage) is drawn with its zones empty, so the
+ *  admin finds no node and every row keeps its icon; an entry has no zones and is returned as it is. */
+export async function samplesHit(site, hit, target, locale, path, zone) {
+    if (hit.kind !== "page")
+        return hit;
+    const emptied = { ...hit, tree: { ...hit.tree, zones: {} } };
+    if (!target)
+        return emptied;
+    try {
+        const resolved = await site.loadSamples(target, locale, path, site.sampleTree(hit.template, zone, await samplePicks(site, hit.template, zone, locale)));
+        return resolved?.kind === "page" ? resolved : emptied;
+    }
+    catch (e) {
+        console.error(`smoodly: the picker's samples could not be loaded — ${e instanceof Error ? e.message : String(e)}`);
+        return emptied;
+    }
+}