@avocadostudio-ai/site-sdk 0.6.0 → 0.8.0

package/dist/lens/storyblok.d.ts

@@ -0,0 +1,28 @@
+import { changed } from "./scalar-codecs.ts";
+import type { ImageNaming, LocaleLens, Primitives } from "./types.ts";
+export declare function assetUrl(asset: unknown): string;
+export declare function assetAlt(asset: unknown): string;
+export declare function linkHref(link: unknown): string;
+/** A link that points at a story is a reference, whatever it renders as. */
+export declare function isStoryLink(link: unknown): boolean;
+/**
+ * The locale lens for Storyblok's field-level i18n.
+ *
+ * The default language lives in the bare key and every other language in
+ * `<key>__i18n__<lang>` beside it. Supplied rather than left to the integrator
+ * because the conditional is one line and getting it wrong is silent: a lens
+ * that reads `title__i18n__de` finds nothing, falls back to `title`, and looks
+ * correct until somebody edits the German page.
+ */
+export declare function storyblokLocale<L extends string>(defaultLang: L, languages: readonly L[]): LocaleLens<L>;
+/**
+ * Storyblok's answers, ready to hand to `createLens` and `registerFieldTable`.
+ *
+ * The default naming is the one a tri-lingual Storyblok site on Next 16
+ * arrived at: an image field `background_image` projects to
+ * `background_image` and `background_image_alt`.
+ */
+export declare function storyblokPrimitives(options?: {
+    imageNaming?: ImageNaming;
+}): Primitives;
+export { changed };

package/dist/lens/storyblok.js

@@ -0,0 +1,232 @@
+/*
+ * Storyblok's answers to the six questions a lens asks.
+ *
+ * Everything here is a fact about Storyblok rather than about a site: an asset
+ * is `{ fieldtype, filename, alt }`, a link is a multilink whose `linktype`
+ * decides whether its href is editable at all, a child row is a blok carrying
+ * `_uid` and `component`, and rich text is a ProseMirror document — the pivot
+ * itself, which is why the converter is a rename rather than a translation.
+ */
+import { fromStoryblok, toStoryblok, isEmptyRichText } from "@avocadostudio-ai/richtext";
+import { changed } from "./scalar-codecs.js";
+import { suffixNaming } from "./types.js";
+const isObj = (v) => v != null && typeof v === "object" && !Array.isArray(v);
+const str = (v) => (v == null ? "" : String(v));
+export function assetUrl(asset) {
+    if (!asset)
+        return "";
+    if (typeof asset === "string")
+        return asset;
+    return str(asset.filename);
+}
+export function assetAlt(asset) {
+    if (!isObj(asset))
+        return "";
+    return str(asset.alt);
+}
+export function linkHref(link) {
+    if (!link)
+        return "";
+    if (typeof link === "string")
+        return link;
+    const l = link;
+    return str(l.url || l.cached_url || l.href);
+}
+/** A link that points at a story is a reference, whatever it renders as. */
+export function isStoryLink(link) {
+    return isObj(link) && link.linktype === "story";
+}
+/**
+ * An asset object built from a URL, keeping whatever the source knew.
+ *
+ * The id must not be carried over when the URL did not come from Storyblok's
+ * asset service: there is no asset record behind it, and an id pointing at the
+ * image it replaced is worse than no id at all.
+ */
+function assetFrom(url, alt, before) {
+    const base = isObj(before) ? before : {};
+    return {
+        fieldtype: "asset",
+        ...base,
+        id: url.includes("a.storyblok.com") ? (base.id ?? null) : null,
+        filename: url,
+        ...(alt === undefined ? {} : { alt })
+    };
+}
+const imageCodec = (naming) => ({
+    project(key, raw) {
+        return { [naming.url(key)]: assetUrl(raw), [naming.alt(key)]: assetAlt(raw) };
+    },
+    merge(key, props, before) {
+        const urlKey = naming.url(key);
+        const altKey = naming.alt(key);
+        if (!(urlKey in props) && !(altKey in props))
+            return null;
+        const nextUrl = str(props[urlKey] ?? assetUrl(before));
+        const nextAlt = str(props[altKey] ?? assetAlt(before));
+        if (nextUrl === assetUrl(before) && nextAlt === assetAlt(before))
+            return null;
+        // Rule 2: clearing a field that was never set for this language is a diff
+        // with no visible effect. Clearing one that was set is real.
+        if (!nextUrl)
+            return assetUrl(before) ? { value: null } : null;
+        return { value: assetFrom(nextUrl, nextAlt, before) };
+    }
+});
+const fileCodec = {
+    project(key, raw) {
+        return { [key]: assetUrl(raw) };
+    },
+    merge(key, props, before) {
+        if (!(key in props))
+            return null;
+        const nextUrl = str(props[key]);
+        if (nextUrl === assetUrl(before))
+            return null;
+        if (!nextUrl && !assetUrl(before))
+            return null;
+        return { value: nextUrl ? assetFrom(nextUrl, undefined, before) : null };
+    }
+};
+/**
+ * A link, and the one shape of it that cannot be written.
+ *
+ * Storyblok stores a story link as `faq` and serves `/fr/faq` on the French
+ * page and `/faq` on the German one — the same stored value, two different
+ * strings, neither of them what is in the document. Flattening it to an href
+ * therefore cannot round-trip: the projection never equals the source, so every
+ * publish of a page nobody edited wants to rewrite every link on it, and
+ * writing the rendered href back replaces the reference with a hard-coded URL
+ * that stops following renames — the one thing the reference was for.
+ *
+ * External links have no such problem, because the stored value *is* the href.
+ * Those stay editable, which covers the case that actually matters: booking and
+ * shop URLs.
+ */
+const linkCodec = {
+    project(key, raw) {
+        return { [key]: linkHref(raw) };
+    },
+    merge(key, props, before, ctx) {
+        if (!(key in props))
+            return null;
+        const nextHref = str(props[key]);
+        if (nextHref === linkHref(before))
+            return null;
+        if (!nextHref && !linkHref(before))
+            return null;
+        if (isStoryLink(before)) {
+            return {
+                warning: `"${key}" points at a page in the CMS, not at a URL. Its address is derived from ` +
+                    `that page and cannot be edited here — move or rename the page in Storyblok instead.`
+            };
+        }
+        const base = isObj(before) ? before : {};
+        return { value: { fieldtype: "multilink", ...base, linktype: "url", url: nextHref, cached_url: nextHref } };
+    },
+    fieldKind: "link"
+};
+/** A reference is never written from a rendered href. It is read-only here. */
+const referenceCodec = {
+    project(key, raw) {
+        return { [key]: linkHref(raw) };
+    },
+    merge(key, props, before) {
+        if (!(key in props))
+            return null;
+        if (str(props[key]) === linkHref(before))
+            return null;
+        return {
+            warning: `"${key}" is a reference to another document. Its address is derived from that ` +
+                `document and cannot be edited here.`
+        };
+    },
+    fieldKind: "reference"
+};
+const richTextCodec = {
+    project(key, raw) {
+        return { [key]: fromStoryblok(raw) };
+    },
+    merge(key, props, before) {
+        if (!(key in props))
+            return null;
+        const nextDoc = toStoryblok(props[key]);
+        if (JSON.stringify(nextDoc) === JSON.stringify(before ?? {}))
+            return null;
+        // Two different spellings of "nothing" are not a change.
+        if (isEmptyRichText(nextDoc) && isEmptyRichText(before))
+            return null;
+        return { value: nextDoc };
+    }
+};
+const imageListCodec = {
+    project(key, raw) {
+        return {
+            [key]: (Array.isArray(raw) ? raw : []).map((a) => ({
+                image: assetUrl(a),
+                alt: assetAlt(a),
+                _uid: isObj(a) && a.id != null ? String(a.id) : undefined
+            }))
+        };
+    },
+    merge(key, props, before) {
+        if (!(key in props))
+            return null;
+        const items = Array.isArray(props[key]) ? props[key] : [];
+        const sourceItems = Array.isArray(before) ? before : [];
+        const merged = items.map((item, i) => {
+            const src = sourceItems[i] ?? {};
+            const url = str(item?.image);
+            const alt = str(item?.alt);
+            if (url === assetUrl(src) && alt === assetAlt(src))
+                return src;
+            return assetFrom(url, alt, src);
+        });
+        if (JSON.stringify(merged) === JSON.stringify(sourceItems))
+            return null;
+        return { value: merged };
+    }
+};
+/**
+ * The locale lens for Storyblok's field-level i18n.
+ *
+ * The default language lives in the bare key and every other language in
+ * `<key>__i18n__<lang>` beside it. Supplied rather than left to the integrator
+ * because the conditional is one line and getting it wrong is silent: a lens
+ * that reads `title__i18n__de` finds nothing, falls back to `title`, and looks
+ * correct until somebody edits the German page.
+ */
+export function storyblokLocale(defaultLang, languages) {
+    return {
+        default: defaultLang,
+        languages,
+        path: (key, lang) => (lang === defaultLang ? [key] : [`${key}__i18n__${lang}`])
+    };
+}
+/**
+ * Storyblok's answers, ready to hand to `createLens` and `registerFieldTable`.
+ *
+ * The default naming is the one a tri-lingual Storyblok site on Next 16
+ * arrived at: an image field `background_image` projects to
+ * `background_image` and `background_image_alt`.
+ */
+export function storyblokPrimitives(options) {
+    const imageNaming = options?.imageNaming ?? suffixNaming("", "_alt");
+    return {
+        imageNaming,
+        rowIdKey: "_uid",
+        rowTypeKey: "component",
+        newRowId: () => typeof crypto !== "undefined" && "randomUUID" in crypto
+            ? crypto.randomUUID()
+            : `uid_${Math.random().toString(36).slice(2, 12)}`,
+        codecs: {
+            image: imageCodec(imageNaming),
+            file: fileCodec,
+            link: linkCodec,
+            reference: referenceCodec,
+            richtext: richTextCodec,
+            imageList: imageListCodec
+        }
+    };
+}
+export { changed };

package/dist/lens/types.d.ts

@@ -0,0 +1,279 @@
+import type { FieldKind, ImageSpec } from "@avocadostudio-ai/shared";
+/** Carried by every field kind. */
+type FieldCommon = {
+    /** What the property panel calls it. Defaults to a humanised key. */
+    label?: string;
+    /**
+     * The publisher needs it, the planner must never see it, nobody may edit it.
+     *
+     * A CMS row identity — `_uid`, `_key`, `_id` — is content-shaped and is not
+     * content. Declaring it keeps the merge able to match rows by it while
+     * keeping it out of the panel and out of the planner's view.
+     */
+    internal?: boolean;
+    /**
+     * A person edits it, but never on the page.
+     *
+     * A section anchor, a video poster, a layout switch: real content with no
+     * element that could carry an editable marker, so the property panel is the
+     * whole of its UI. `editableCoverage` reads this as "no marker expected",
+     * which is what makes the number reachable — without it a correct
+     * integration reports 88% and the integrator gating on coverage has to guess
+     * a threshold, at which point a real regression hides behind the guess.
+     *
+     * The weaker neighbour of `internal`: that one says the field has no
+     * audience, this one says it has no element.
+     */
+    panelOnly?: boolean;
+    /**
+     * `false` for a field with one value for every language.
+     *
+     * The default is `true`, which is right for a field-level-i18n CMS: most
+     * things are translated and the exceptions are declared.
+     *
+     * **It means the bare key, which is not the same as the default language.**
+     * The two coincide on a CMS that localises into a suffixed sibling
+     * (`title` and `title__i18n__fr`) and diverge on one that localises into an
+     * object under the key, where the default language lives at `title.de` and a
+     * non-localised field lives at `title` with no container at all.
+     *
+     * On the second kind of CMS this is not optional decoration. An image is one
+     * asset reference for every language and a list is one array; leave them
+     * declared as localised and the projection looks inside a container that is
+     * not there, so the image reads as empty and the list as having no rows.
+     * There is deliberately no implicit fallback to the bare key, because a read
+     * that fell back would pair with a write that did not — and reading one place
+     * while writing another is how a lens corrupts a document.
+     */
+    localized?: boolean;
+};
+/**
+ * How one CMS field becomes one or more Avocado props, and back.
+ *
+ * The kinds are the union of what two real integrations needed, mapped onto the
+ * `FieldKind` vocabulary the property panel already speaks — so a table entry
+ * is also the panel metadata, with no second mapping to keep in step.
+ */
+export type FieldSpec = 
+/** Plain string. `multiline` changes the control, not the storage. */
+(FieldCommon & {
+    kind: "text";
+    multiline?: boolean;
+    inlineEditable?: boolean;
+})
+/** A rich-text document, edited as a document rather than flattened. */
+ | (FieldCommon & {
+    kind: "richtext";
+    inline?: boolean;
+})
+/**
+ * A string of HTML — a prop the template renders with `set:html`,
+ * `dangerouslySetInnerHTML` or `v-html`.
+ *
+ * Stored as the string it is, edited as a document. Declaring one of these
+ * `richtext` is the mistake it exists to stop: `richtext` means a document,
+ * so the panel renders the markup literally and a person editing it writes
+ * broken markup back into the site's own source file. Tags outside the
+ * converter's vocabulary are preserved rather than dropped — see
+ * `@avocadostudio-ai/richtext`'s `fromHtml`.
+ */
+ | (FieldCommon & {
+    kind: "html";
+    inline?: boolean;
+    inlineEditable?: boolean;
+})
+/** An image. Projects to a URL string plus a companion alt prop. */
+ | (FieldCommon & {
+    kind: "image";
+    imageSpec?: ImageSpec;
+})
+/** A document asset — a menu PDF. Projects to a URL string, no alt. */
+ | (FieldCommon & {
+    kind: "file";
+})
+/** A link. Projects to an href string. */
+ | (FieldCommon & {
+    kind: "link";
+})
+/**
+ * A pointer to another document in the CMS.
+ *
+ * Distinct from `link` because the href is a *render* of it: the same stored
+ * reference serves `/faq` and `/fr/faq`, so a projection can never be the
+ * inverse of the source, and writing the rendered href back replaces the
+ * reference with a hard-coded URL that stops following renames.
+ */
+ | (FieldCommon & {
+    kind: "reference";
+}) | (FieldCommon & {
+    kind: "enum";
+    options: readonly string[];
+}) | (FieldCommon & {
+    kind: "boolean";
+}) | (FieldCommon & {
+    kind: "number";
+}) | (FieldCommon & {
+    kind: "headingLevel";
+})
+/** An array of plain strings — bullets. */
+ | (FieldCommon & {
+    kind: "stringList";
+})
+/** An array of bare images, not of documents — a logo strip, a gallery. */
+ | (FieldCommon & {
+    kind: "imageList";
+})
+/**
+ * An array of child rows.
+ *
+ * `of` names the child types admitted, for a CMS where each row is its own
+ * document and carries its own type; `itemFields` describes the row inline,
+ * for a CMS where the rows are plain objects. Exactly one of the two.
+ *
+ * Every type named in `of` must itself be in the table, and the pack must
+ * supply a `rowTypeKey`: the list's schema is a discriminated union over that
+ * key, with one branch per named type. A type the table does not describe is
+ * left out of the union rather than admitted as an empty shape, because
+ * `createLens` cannot project or merge a row of it either.
+ */
+ | (FieldCommon & {
+    kind: "list";
+    of: readonly string[];
+}) | (FieldCommon & {
+    kind: "list";
+    itemFields: Record<string, FieldSpec>;
+});
+/** One block type, as the site's own CMS names it. */
+export type BlockSpec = {
+    /** What the block is called in the editor. */
+    displayName: string;
+    /** Blocks that may appear directly in a page body. Child rows are not. */
+    topLevel?: boolean;
+    category?: "content" | "media" | "navigation" | "conversion" | "layout";
+    fields: Record<string, FieldSpec>;
+};
+/**
+ * The table: every type Avocado may edit on this site, keyed by the CMS's own
+ * name for it.
+ *
+ * Use the CMS's spelling — `hero_section`, not `SiteHeroSection`. `BlockType`
+ * is a free string, and keeping the name identical in the CMS, in the manifest
+ * and in a publish diff makes the adapter an identity map on the type instead
+ * of a translation nobody can grep for.
+ */
+export type FieldTable = Record<string, BlockSpec>;
+/**
+ * Where one language's value for a key is stored.
+ *
+ * Field-level i18n comes in two shapes and both fit here: a suffixed sibling
+ * key (`title__i18n__fr`, Storyblok) and a per-locale object under the key
+ * itself (`{de, fr, en}`, Sanity and Contentful) — the second by giving `path`
+ * a second segment.
+ */
+export type LocaleLens<L extends string = string> = {
+    /** The language whose value lives in the bare key. */
+    default: L;
+    /** Every language this site publishes. */
+    languages: readonly L[];
+    /**
+     * The path at which `lang`'s value for `key` is stored, as one or two
+     * segments: `["title__i18n__fr"]` or `["title", "fr"]`.
+     */
+    path(key: string, lang: L): readonly [string] | readonly [string, string];
+    /**
+     * `false` when the CMS itself says this field is not translatable.
+     *
+     * Storyblok leaves old translations in the document after a field stops being
+     * marked translatable, and the Delivery API ignores them — so a projection
+     * that reads them shows text the site has not rendered in years, and a merge
+     * that writes them produces a publish nobody can explain. Defaults to `true`.
+     */
+    translatable?(type: string, key: string, lang: L): boolean;
+};
+/** What a codec is told beyond the value itself. */
+export type CodecContext = {
+    /** The field's own declaration, for `options`, `of`, `itemFields`. */
+    spec: FieldSpec;
+    /** The language being read or written. */
+    lang: string;
+    /** The block type this field sits on, for messages. */
+    type: string;
+    /** A path like `/preise > hero_section > title`, for messages. */
+    where: string;
+};
+/**
+ * The outcome of merging one edited value back.
+ *
+ * `null` means *unchanged*, and it is the most important of the three. A CMS
+ * with per-language fallback resolves a missing translation to the default
+ * language, which is correct on screen and a lie in storage: merge a projection
+ * back wholesale and every one of those fallbacks becomes a real, fabricated
+ * translation — dozens per publish, each identical to what the page already
+ * showed, so nothing looks wrong. A codec returns a value only when the value
+ * really differs from what the source holds.
+ */
+export type MergeOutcome = null | {
+    value: unknown;
+}
+/** The edit cannot be stored, and the editor is owed the reason. */
+ | {
+    warning: string;
+};
+/**
+ * How one CMS reads and writes one kind of field.
+ *
+ * `project` returns the props this field contributes — more than one for a kind
+ * with a companion, like an image and its alt text — so the 1-to-2 case needs
+ * no special handling anywhere else.
+ */
+export type FieldCodec = {
+    project(key: string, raw: unknown, ctx: CodecContext): Record<string, unknown>;
+    merge(key: string, props: Record<string, unknown>, before: unknown, ctx: CodecContext): MergeOutcome;
+    /** The panel metadata for this kind, when it is not simply `kind`. */
+    fieldKind?: FieldKind;
+};
+/**
+ * What an image field's two props are called.
+ *
+ * An image contributes a URL and an alt text, and the names are load-bearing in
+ * a place nothing checks: the editor's asset picker keys on the `*imageUrl` /
+ * `*Image` name pattern rather than on any declaration. Two integrations chose
+ * differently — `image` + `image_alt` against `imageUrl` + `imageAlt` — and
+ * both were right for their site.
+ *
+ * It lives on `Primitives` so the projection and the panel registration read
+ * the same answer. Held separately they are two things that must agree with
+ * nothing checking that they do, which is the defect class this file exists to
+ * delete rather than reproduce.
+ */
+export type ImageNaming = {
+    url(key: string): string;
+    alt(key: string): string;
+};
+/** `suffixNaming("", "_alt")` gives `image` + `image_alt`. */
+export declare function suffixNaming(urlSuffix: string, altSuffix: string): ImageNaming;
+/**
+ * A CMS's answers, keyed by field kind.
+ *
+ * The scalar kinds have CMS-independent defaults, so a pack supplies only what
+ * its CMS actually shapes differently — in practice `image`, `file`, `link`,
+ * `reference`, `richtext`, `imageList` and `list`.
+ */
+export type Primitives = {
+    codecs: Partial<Record<FieldSpec["kind"], FieldCodec>>;
+    /**
+     * The key under which a child row carries its own identity (`_uid`, `_key`).
+     *
+     * The merge matches rows by it, which is what keeps a list edit a merge
+     * rather than a replace — and it is why row identity has to survive the round
+     * trip rather than being stripped as "not content".
+     */
+    rowIdKey: string;
+    /** The key under which a child row carries its own type, for `of` lists. */
+    rowTypeKey?: string;
+    /** A fresh row identity, for a row the editor added. */
+    newRowId(): string;
+    /** What an image field's URL and alt props are called. */
+    imageNaming: ImageNaming;
+};
+export {};

package/dist/lens/types.js

@@ -0,0 +1,28 @@
+/*
+ * One table describing the fields a CMS-backed site lets Avocado edit — and
+ * the four things derived from it.
+ *
+ * Two integrations reached this design independently, for different CMSes, and
+ * each opened its own file by explaining it in near-identical words: four
+ * things have to agree about every block — the Zod schema the operations engine
+ * validates against, the field metadata the property panel draws, the
+ * projection that turns a CMS document into props, and the merge that writes
+ * edited props back — and if they are written four times they disagree within a
+ * week.
+ *
+ * Both were right about the remedy and both had to build it themselves, in
+ * mutually unreadable vocabularies (`{ t: "asset" }` against
+ * `{ kind: 'image' }`), so nothing carried from the first integration to the
+ * second. The derivation is the same program either way: what differs between
+ * two CMSes is how one value of a given kind is read and written, which is the
+ * `FieldCodec` below, and where a language's value is stored, which is the
+ * `LocaleLens`.
+ *
+ * What stays site-specific is the table. It is the content model, it is
+ * irreducible, and it is the whole of what an adopter on a CMS we already know
+ * should have to write.
+ */
+/** `suffixNaming("", "_alt")` gives `image` + `image_alt`. */
+export function suffixNaming(urlSuffix, altSuffix) {
+    return { url: (key) => `${key}${urlSuffix}`, alt: (key) => `${key}${altSuffix}` };
+}

package/dist/markers.d.ts

@@ -104,7 +104,43 @@ export declare function editableProps(path: string, options?: {
  * `sections[0]` scope makes a child's `text` into `sections[0].left[1].text`.
  * A block boundary ends the composition, so a scope outside a block never
  * reaches into it.
+ *
+ * **The scope needs an element, and the element needs to not be there.** A
+ * scope is a DOM attribute, so it wants an ancestor to sit on — and a list
+ * whose rows map straight into a flex or grid container has none to offer.
+ * Adding a plain wrapper around each row gives the scope its element and makes
+ * the wrapper the flex item, so the layout the rows had is now the layout of a
+ * column of wrappers: gaps land in different places, `align-items` applies to
+ * the wrong box, and a grid's rows stop being the grid's children at all.
+ *
+ * `display: contents` is the whole answer — the element stays in the tree for
+ * anything walking it, and lays out as if it were not there, so the rows go on
+ * being their parent's children. Pass `{ display: "contents" }` and the helper
+ * writes it:
+ *
+ * ```tsx
+ * <div className="flex flex-col gap-6">
+ *   {props.items.map((item, i) => (
+ *     <div key={item.id} {...editableScopeProps(`items[${i}]`, { display: "contents" })}>
+ *       <FaqRow item={item} />
+ *     </div>
+ *   ))}
+ * </div>
+ * ```
+ *
+ * Leave it off when the wrapper is one you were going to render anyway — a
+ * row that already has a `<li>` or a card `<div>` around it should carry the
+ * scope on that, not gain a second element to hold it.
  */
-export declare function editableScopeProps(scope: string): {
+export declare function editableScopeProps(scope: string, options?: {
+    /**
+     * `"contents"` adds `style={{ display: "contents" }}`, for a wrapper that
+     * exists only to carry the scope and must not become a box.
+     */
+    display?: "contents";
+}): {
+    readonly style?: {
+        display: "contents";
+    } | undefined;
     readonly "data-editable-scope": string;
 };

package/dist/markers.js

@@ -113,7 +113,37 @@ export function editableProps(path, options) {
  * `sections[0]` scope makes a child's `text` into `sections[0].left[1].text`.
  * A block boundary ends the composition, so a scope outside a block never
  * reaches into it.
+ *
+ * **The scope needs an element, and the element needs to not be there.** A
+ * scope is a DOM attribute, so it wants an ancestor to sit on — and a list
+ * whose rows map straight into a flex or grid container has none to offer.
+ * Adding a plain wrapper around each row gives the scope its element and makes
+ * the wrapper the flex item, so the layout the rows had is now the layout of a
+ * column of wrappers: gaps land in different places, `align-items` applies to
+ * the wrong box, and a grid's rows stop being the grid's children at all.
+ *
+ * `display: contents` is the whole answer — the element stays in the tree for
+ * anything walking it, and lays out as if it were not there, so the rows go on
+ * being their parent's children. Pass `{ display: "contents" }` and the helper
+ * writes it:
+ *
+ * ```tsx
+ * <div className="flex flex-col gap-6">
+ *   {props.items.map((item, i) => (
+ *     <div key={item.id} {...editableScopeProps(`items[${i}]`, { display: "contents" })}>
+ *       <FaqRow item={item} />
+ *     </div>
+ *   ))}
+ * </div>
+ * ```
+ *
+ * Leave it off when the wrapper is one you were going to render anyway — a
+ * row that already has a `<li>` or a card `<div>` around it should carry the
+ * scope on that, not gain a second element to hold it.
  */
-export function editableScopeProps(scope) {
-    return { "data-editable-scope": scope };
+export function editableScopeProps(scope, options) {
+    return {
+        "data-editable-scope": scope,
+        ...(options?.display === "contents" ? { style: { display: "contents" } } : {})
+    };
 }

package/dist/page-metadata.d.ts

@@ -64,3 +64,24 @@ export type BuildPageMetadataOptions = {
  * image to put in it.
  */
 export declare function buildPageMetadata(page: Pick<PageDoc, "title" | "meta" | "blocks">, options?: BuildPageMetadataOptions): PageMetadata;
+/**
+ * Render {@link PageMetadata} as the head tags it describes.
+ *
+ * Next consumes the object directly — a route exports `metadata` and the
+ * framework emits the tags — so nothing in this repo needed this until now.
+ * Every other host writes its own `<head>`, and an integrator left to do that
+ * by hand reproduces a subset: the title and description usually, Open Graph
+ * sometimes, `twitter:card` almost never, and the canonical link not at all.
+ * That is how `test:build` came to exist — three of those omissions had already
+ * shipped from the one route that built its head by hand.
+ *
+ * Returns a string because the alternative is a shape per templating language.
+ * The values are attribute-escaped; the caller inserts it as raw HTML
+ * (`set:html` in Astro, `v-html` in Vue, `{@html}` in Svelte).
+ *
+ * `og:image` and `twitter:image` are emitted exactly as given. A relative path
+ * is legal in the document but most crawlers will not resolve it, so pass
+ * absolute URLs — the same rule that applies to `buildPageMetadata`'s
+ * `canonical`.
+ */
+export declare function renderPageMetadata(metadata: PageMetadata): string;