@avocadostudio-ai/site-sdk 0.6.0 → 0.7.0

package/dist/lens/types.d.ts

@@ -0,0 +1,243 @@
+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;
+    /**
+     * `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;
+})
+/** 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.
+ */
+ | (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/markers.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/markers.test.js

@@ -0,0 +1,35 @@
+import { strict as assert } from "node:assert";
+import { test } from "node:test";
+import { editableProps, editableScopeProps, getPreviewWrapperProps } from "./markers.js";
+test("editableProps defaults the label to the path and omits kind when unset", () => {
+    assert.deepEqual(editableProps("cards[0].title"), {
+        "data-editable-target": "cards[0].title",
+        "data-editable-target-label": "cards[0].title"
+    });
+});
+test("editableProps carries an explicit label and kind", () => {
+    assert.deepEqual(editableProps("photoUrl", { label: "Photo", kind: "image" }), {
+        "data-editable-target": "photoUrl",
+        "data-editable-target-label": "Photo",
+        "data-editable-kind": "image"
+    });
+});
+test("editableScopeProps writes only the scope by default", () => {
+    assert.deepEqual(editableScopeProps("items[3]"), { "data-editable-scope": "items[3]" });
+});
+/*
+ * A scope wants a DOM ancestor, and a list that maps its rows straight into a
+ * flex container has none — so the wrapper you add to hold it becomes the flex
+ * item and the layout moves. `display: contents` keeps the element in the tree
+ * the overlay walks and out of the box tree that lays the rows out.
+ */
+test("editableScopeProps can make its wrapper vanish from layout", () => {
+    assert.deepEqual(editableScopeProps("items[3]", { display: "contents" }), {
+        "data-editable-scope": "items[3]",
+        style: { display: "contents" }
+    });
+});
+test("getPreviewWrapperProps renders nothing outside editor mode", () => {
+    assert.deepEqual(getPreviewWrapperProps(false, "b1", "Hero"), {});
+    assert.equal(getPreviewWrapperProps(true, "b1", "Hero")["data-block-id"], "b1");
+});

package/dist/proxy.js

@@ -1,5 +1,6 @@
 import { NextResponse } from "next/server";
 import { DEFAULT_PREVIEW_ROUTE, buildEditorMatcher } from "./editor-matcher.js";
+import { EDITOR_RENDER_HEADER } from "./editor-render.js";
 export { DEFAULT_PREVIEW_ROUTE, buildEditorMatcher } from "./editor-matcher.js";
 /**
  * Create a Next.js proxy function that rewrites editor/draft requests
@@ -118,5 +119,20 @@ export function editorPreviewRewrite(request, options) {
         return null;
     const url = request.nextUrl.clone();
     url.pathname = `${previewRoute}${url.pathname}`;
-    return NextResponse.rewrite(url);
+    /*
+     * The one fact a layout can get at.
+     *
+     * A page learns it is being previewed from `resolveEditorContext(searchParams)`.
+     * A layout receives no `searchParams`, and the root layout is exactly where a
+     * site mounts its consent banner, analytics and tag manager — so every
+     * integration loads all three into the editor iframe until somebody notices
+     * the pageviews. Stamping the rewritten request lets `isEditorRender()` answer
+     * in a layout without the site threading anything down to it.
+     *
+     * Set, not appended: a client-supplied header of the same name is replaced, so
+     * what a layout reads here is the proxy's own answer.
+     */
+    const headers = new Headers(request.headers);
+    headers.set(EDITOR_RENDER_HEADER, "1");
+    return NextResponse.rewrite(url, { request: { headers } });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avocadostudio-ai/site-sdk",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -26,6 +26,21 @@
       "import": "./dist/markers.js",
       "default": "./dist/markers.js"
     },
+    "./lens": {
+      "types": "./dist/lens/index.d.ts",
+      "import": "./dist/lens/index.js",
+      "default": "./dist/lens/index.js"
+    },
+    "./lens/storyblok": {
+      "types": "./dist/lens/storyblok.d.ts",
+      "import": "./dist/lens/storyblok.js",
+      "default": "./dist/lens/storyblok.js"
+    },
+    "./lens/sanity": {
+      "types": "./dist/lens/sanity.d.ts",
+      "import": "./dist/lens/sanity.js",
+      "default": "./dist/lens/sanity.js"
+    },
     "./blocks": {
       "types": "./dist/blocks.d.ts",
       "import": "./dist/blocks.js",
@@ -122,16 +137,17 @@
   ],
   "dependencies": {
     "zod": "^4.3.6",
-    "@avocadostudio-ai/blocks": "^0.6.0",
-    "@avocadostudio-ai/preview-adapter": "^0.6.0",
-    "@avocadostudio-ai/shared": "^0.6.0"
+    "@avocadostudio-ai/blocks": "^0.7.0",
+    "@avocadostudio-ai/richtext": "^0.7.0",
+    "@avocadostudio-ai/shared": "^0.7.0",
+    "@avocadostudio-ai/preview-adapter": "^0.7.0"
   },
   "peerDependencies": {
     "next": ">=15.0.0",
     "react": ">=19.0.0",
     "react-dom": ">=19.0.0",
     "better-sqlite3": ">=12.0.0",
-    "@avocadostudio-ai/orchestrator-core": "^0.6.0"
+    "@avocadostudio-ai/orchestrator-core": "^0.7.0"
   },
   "peerDependenciesMeta": {
     "@avocadostudio-ai/orchestrator-core": {