@avocadostudio-ai/site-sdk 0.15.0 → 0.16.0

package/dist/lens/create-lens.js

@@ -183,19 +183,62 @@ export function createLens(options) {
             const byId = new Map(sourceRows.map((row) => [row[primitives.rowIdKey], row]));
             const seen = new Set();
             const merged = [];
-            for (const item of items) {
+            /*
+             * A list whose source rows carry no identity at all.
+             *
+             * It is not a rare shape: a CMS query written before Avocado existed
+             * selects the fields a template renders, and a row's `_key` is not one of
+             * them. Matching then finds nothing, and the old code read "matches
+             * nothing" as "every row is new" — so a projection merged straight back
+             * appended a second copy of every row and kept the originals. Two buttons
+             * became four on a no-op, and the fabricated rows were built from the
+             * projection, so they carried one language and none of the fields the
+             * table does not declare.
+             *
+             * Position is the only identity left, and using it is better than the
+             * alternatives: refusing makes the list uneditable, and fabricating makes
+             * it grow. It is also *wrong* for a reorder, silently — the rows swap
+             * their undeclared fields — so this writes and warns rather than writing
+             * quietly. The remedy is one line in the integrator's query, and the
+             * warning names it.
+             */
+            const keyless = sourceRows.length > 0 && sourceRows.every((row) => row[primitives.rowIdKey] === undefined);
+            let usedPositionalMatch = false;
+            const rowWarnings = [];
+            for (const [index, item] of items.entries()) {
                 const rowId = item[primitives.rowIdKey];
-                const source = rowId === undefined ? undefined : byId.get(rowId);
+                let source = rowId === undefined ? undefined : byId.get(rowId);
                 if (source)
                     seen.add(rowId);
+                if (!source && keyless && index < sourceRows.length) {
+                    source = sourceRows[index];
+                    usedPositionalMatch = true;
+                }
                 if ("itemFields" in spec) {
-                    const base = source ? { ...source } : { [primitives.rowIdKey]: primitives.newRowId() };
+                    /*
+                     * A row matched by position keeps the identity it had, which is none.
+                     * Stamping a fresh `rowIdKey` onto it would be this codec inventing a
+                     * field the document never had — a schema change smuggled in by an
+                     * edit to a label.
+                     */
+                    const base = source
+                        ? { ...source }
+                        : keyless
+                            ? {}
+                            : { [primitives.rowIdKey]: primitives.newRowId() };
                     let rowChanged = !source;
                     for (const [itemKey, itemSpec] of Object.entries(spec.itemFields)) {
                         const itemCtx = { spec: itemSpec, lang: ctx.lang, type: ctx.type, where: `${ctx.where}[] > ${itemKey}` };
                         const before = source ? readField(source, itemKey, ctx.lang, itemSpec, ctx.type) : undefined;
                         const outcome = codecFor(itemSpec).merge(itemKey, item, before, itemCtx);
-                        if (!outcome || "warning" in outcome)
+                        if (!outcome)
+                            continue;
+                        // A row's own hazards travel up with the list's. A nested list is
+                        // the case that matters: its rows are keyless far more often than a
+                        // top-level list's, and it is a level deeper than anyone looks.
+                        if (outcome.warning)
+                            rowWarnings.push(outcome.warning);
+                        if (!("value" in outcome))
                             continue;
                         writeField(base, itemKey, ctx.lang, itemSpec, ctx.type, outcome.value);
                         rowChanged = true;
@@ -221,16 +264,27 @@ export function createLens(options) {
                 const result = merge(source ?? { [typeKey]: rowType, [primitives.rowIdKey]: primitives.newRowId() }, item, rowType, ctx.lang, `${ctx.where}[]`);
                 merged.push(result.doc);
             }
-            // Rows the table does not describe keep their place rather than vanishing.
-            for (const [index, row] of sourceRows.entries()) {
-                const rowId = row[primitives.rowIdKey];
-                if (seen.has(rowId))
-                    continue;
-                const typeKey = primitives.rowTypeKey;
-                const described = typeKey ? specFor(String(row[typeKey])) !== undefined : true;
-                if (described)
-                    continue;
-                merged.splice(Math.min(index, merged.length), 0, row);
+            /*
+             * Rows the table does not describe keep their place rather than vanishing.
+             *
+             * Only `of` lists can hold such a row. An `itemFields` list describes
+             * every row it has by construction, so there is nothing here to rescue —
+             * and running this pass over one was the second half of the duplication
+             * bug: `specFor(String(undefined))` is undefined, every row read as
+             * undescribed, and each got re-inserted beside the copy the loop above
+             * had just built.
+             */
+            if (!("itemFields" in spec)) {
+                for (const [index, row] of sourceRows.entries()) {
+                    const rowId = row[primitives.rowIdKey];
+                    if (seen.has(rowId))
+                        continue;
+                    const typeKey = primitives.rowTypeKey;
+                    const described = typeKey ? specFor(String(row[typeKey])) !== undefined : true;
+                    if (described)
+                        continue;
+                    merged.splice(Math.min(index, merged.length), 0, row);
+                }
             }
             /*
              * Compared structurally, and deliberately not by counting rows.
@@ -242,7 +296,19 @@ export function createLens(options) {
              * reorder, add and delete, and says nothing about a list that only looks
              * shorter from Avocado's side.
              */
-            return JSON.stringify(merged) === JSON.stringify(sourceRows) ? null : { value: merged };
+            if (JSON.stringify(merged) === JSON.stringify(sourceRows))
+                return null;
+            const hazards = usedPositionalMatch
+                ? [
+                    `"${key}" holds rows with no "${primitives.rowIdKey}", so they were matched to the stored rows by ` +
+                        `position. An edit lands correctly, but a reorder or a deletion moves every row's undeclared fields ` +
+                        `onto its neighbour. Select "${primitives.rowIdKey}" for this list in the query that reads it.`,
+                    ...rowWarnings
+                ]
+                : rowWarnings;
+            if (hazards.length === 0)
+                return { value: merged };
+            return { value: merged, warning: [...new Set(hazards)].join(" ") };
         }
     };
     /**
@@ -294,10 +360,18 @@ export function createLens(options) {
             const outcome = codecFor(spec).merge(key, props, before, ctx);
             if (!outcome)
                 continue;
-            if ("warning" in outcome) {
+            if (!("value" in outcome)) {
                 warnings.push({ where: ctx.where, reason: outcome.warning });
                 continue;
             }
+            /*
+             * Reported whether or not the write goes on to happen. A codec that
+             * returns both has stored something *and* found a hazard in how it had to
+             * store it; swallowing the second half was how a list that doubled its
+             * rows came back `changed: true, warnings: []`.
+             */
+            if (outcome.warning)
+                warnings.push({ where: ctx.where, reason: outcome.warning });
             /*
              * Asked here, about a real change, and deliberately not earlier. The
              * first version of this re-projected the source and compared JSON before

package/dist/lens/index.d.ts

@@ -1,6 +1,6 @@
 export { createLens } from "./create-lens.ts";
 export type { Lens, LensOptions, MergeResult, MergeWarning, ProjectOptions } from "./create-lens.ts";
-export { registerFieldTable, topLevelTypes } from "./register.ts";
+export { registerFieldTable, registerLens, topLevelTypes } from "./register.ts";
 export type { RegisterOptions } from "./register.ts";
 export { suffixNaming } from "./types.ts";
 export type { BlockSpec, CodecContext, FieldCodec, FieldSpec, FieldTable, ImageNaming, LocaleLens, MergeOutcome, Primitives } from "./types.ts";

package/dist/lens/index.js

@@ -20,6 +20,6 @@
  * object you cannot build twice and make the order of two imports matter.
  */
 export { createLens } from "./create-lens.js";
-export { registerFieldTable, topLevelTypes } from "./register.js";
+export { registerFieldTable, registerLens, topLevelTypes } from "./register.js";
 export { suffixNaming } from "./types.js";
 export { changed } from "./scalar-codecs.js";

package/dist/lens/register.d.ts

@@ -23,6 +23,18 @@ export type RegisterOptions = {
     narrowCatalogue?: boolean;
 };
 export declare function registerFieldTable(table: FieldTable, options?: RegisterOptions): void;
+/**
+ * Register a lens's own table, with the lens's own primitives.
+ *
+ * The two-argument call is two declarations that have to agree; this is one
+ * that cannot disagree with itself. Prefer it. `registerFieldTable` remains for
+ * a table that has no lens — a site that registers blocks without projecting a
+ * CMS through them.
+ */
+export declare function registerLens(lens: {
+    table: FieldTable;
+    primitives: Pick<Primitives, "imageNaming"> & Partial<Pick<Primitives, "rowIdKey" | "rowTypeKey">>;
+}, options?: Omit<RegisterOptions, "primitives">): void;
 /**
  * The types a page body may hold, which is not every type in the table.
  *

package/dist/lens/register.js

@@ -177,12 +177,25 @@ function metaForField(key, spec) {
         meta.imageSpec = spec.imageSpec;
     return meta;
 }
-/** The same expansion as `shapeForFields`, as panel metadata rather than schema. */
+/**
+ * The same expansion as `shapeForFields`, as panel metadata rather than schema.
+ *
+ * Lists come back separately. `metaForField` renders a `list` as `kind: "text"`,
+ * which is harmless for a block's own list — that one travels `listFields` and
+ * the kind is never read — and destructive for a row's, which had no second
+ * channel to travel and so arrived at the panel as a text input pointed at an
+ * array of objects. Now it has one.
+ */
 function metaForFields(fields, ctx) {
     const out = {};
+    const lists = {};
     if (ctx.rowIdKey)
         out[ctx.rowIdKey] = { kind: "text", label: humanise(ctx.rowIdKey), internal: true };
     for (const [key, spec] of Object.entries(fields)) {
+        if (spec.kind === "list") {
+            lists[key] = listMetaFor(key, spec, ctx);
+            continue;
+        }
         if (spec.kind === "image") {
             out[ctx.naming.url(key)] = metaForField(key, spec);
             out[ctx.naming.alt(key)] = { kind: "imageAlt", label: `${spec.label ?? humanise(key)} alt` };
@@ -190,7 +203,7 @@ function metaForFields(fields, ctx) {
         }
         out[key] = metaForField(key, spec);
     }
-    return out;
+    return { fields: out, listFields: lists };
 }
 /**
  * A list's panel metadata.
@@ -204,24 +217,40 @@ function metaForFields(fields, ctx) {
  */
 function listMetaFor(key, spec, ctx) {
     const label = spec.label ?? humanise(key);
-    if ("itemFields" in spec)
-        return { label, itemFields: metaForFields(spec.itemFields, ctx) };
+    if ("itemFields" in spec) {
+        const row = metaForFields(spec.itemFields, ctx);
+        return {
+            label,
+            itemFields: row.fields,
+            ...(Object.keys(row.listFields).length > 0 ? { itemListFields: row.listFields } : {})
+        };
+    }
     const types = rowTypesFor(spec.of, ctx);
     if (types.length === 0)
         return { label, itemFields: {} };
     const itemFieldsByType = {};
     const merged = {};
+    const mergedLists = {};
     for (const type of types) {
-        const fields = metaForFields(ctx.table[type].fields, {
+        const row = metaForFields(ctx.table[type].fields, {
             ...ctx,
             visiting: new Set([...ctx.visiting, type])
         });
-        itemFieldsByType[type] = fields;
-        for (const [fieldKey, meta] of Object.entries(fields))
+        itemFieldsByType[type] = row.fields;
+        for (const [fieldKey, meta] of Object.entries(row.fields))
             if (!(fieldKey in merged))
                 merged[fieldKey] = meta;
+        for (const [fieldKey, meta] of Object.entries(row.listFields))
+            if (!(fieldKey in mergedLists))
+                mergedLists[fieldKey] = meta;
     }
-    return { label, itemFields: merged, discriminator: ctx.rowTypeKey, itemFieldsByType };
+    return {
+        label,
+        itemFields: merged,
+        discriminator: ctx.rowTypeKey,
+        itemFieldsByType,
+        ...(Object.keys(mergedLists).length > 0 ? { itemListFields: mergedLists } : {})
+    };
 }
 /**
  * Register every type in the table as an Avocado block type.
@@ -262,7 +291,47 @@ function assertDrawable(type, key, spec) {
  * no `FieldKind` spelling.
  */
 const KNOWN_KINDS = [...FIELD_KINDS, "list"];
+/** Does this field set declare an image anywhere, including inside a row? */
+function declaresAnImage(fields, seen = new Set()) {
+    for (const spec of Object.values(fields)) {
+        if (spec.kind === "image" || spec.kind === "imageList")
+            return true;
+        if (spec.kind === "list" && "itemFields" in spec && declaresAnImage(spec.itemFields, seen))
+            return true;
+    }
+    return false;
+}
+/**
+ * Refuse a table with images when nobody said what an image's props are called.
+ *
+ * `registerFieldTable` defaulted to `suffixNaming("", "_alt")` — Storyblok's
+ * answer — for every CMS, while `sanityPrimitives()` defaults to
+ * `suffixNaming("Url", "Alt")`. Same table, same package, two calls, and the
+ * defaults disagree: the panel drew `image` and `image_alt`, the projection
+ * emitted `imageUrl` and `imageAlt`, and every image on the site was both
+ * invisible and uneditable. Nothing errored, because neither half is wrong on
+ * its own.
+ *
+ * `RegisterOptions` has documented this exact symptom for as long as the
+ * option has existed, which is the point: an integration that never reads that
+ * doc gets the broken pairing by default, and the only evidence is an asset
+ * picker that never appears. So the default is withdrawn where it can do harm.
+ * A table with no image is unaffected.
+ */
+function assertImageNamingDeclared(table, options) {
+    if (options?.primitives?.imageNaming)
+        return;
+    for (const [type, blockSpec] of Object.entries(table)) {
+        if (!declaresAnImage(blockSpec.fields))
+            continue;
+        throw new Error(`registerFieldTable: ${type} declares an image, but no image naming was given. The panel and the ` +
+            `projection have to agree on what an image field's two props are called, and their defaults do not ` +
+            `match. Pass the same pack you gave createLens — registerFieldTable(table, { primitives: ` +
+            `sanityPrimitives() }) — or call registerLens(lens), which cannot get this wrong.`);
+    }
+}
 export function registerFieldTable(table, options) {
+    assertImageNamingDeclared(table, options);
     const naming = options?.primitives?.imageNaming ?? suffixNaming("", "_alt");
     const ctx = {
         naming,
@@ -309,6 +378,17 @@ export function registerFieldTable(table, options) {
             .map(([type]) => type));
     }
 }
+/**
+ * Register a lens's own table, with the lens's own primitives.
+ *
+ * The two-argument call is two declarations that have to agree; this is one
+ * that cannot disagree with itself. Prefer it. `registerFieldTable` remains for
+ * a table that has no lens — a site that registers blocks without projecting a
+ * CMS through them.
+ */
+export function registerLens(lens, options) {
+    registerFieldTable(lens.table, { ...options, primitives: lens.primitives });
+}
 /**
  * The types a page body may hold, which is not every type in the table.
  *

package/dist/lens/sanity.d.ts

@@ -8,7 +8,24 @@ import type { ImageNaming, LocaleLens, Primitives } from "./types.ts";
  * precisely the overwrite a field-level publish diff exists to prevent.
  */
 export declare function imageUrl(image: unknown): string;
-export declare function imageAlt(image: unknown): string;
+/**
+ * An image's alt text, in one language.
+ *
+ * Alt text is content, so a field-level-i18n CMS localises it like any other
+ * string: a tri-lingual Sanity site models it as `localeString`, i.e. `{de,fr,en}` on
+ * the image object. This used to be `String(image.alt)`, which rendered every
+ * such alt as the literal `"[object Object]"` in the property panel — and then
+ * an editor who corrected that garbage wrote a flat string over the container,
+ * deleting the other two languages with no warning.
+ *
+ * The container sits *inside* a field the table declares `localized: false`,
+ * because the asset reference really is shared across languages. So no
+ * declaration could have expressed this and none is asked for: an object here
+ * is read as a locale container, always. The one thing never done again is
+ * coercing it — an unreadable alt projects as empty, which is true, rather than
+ * as a string that looks like text and is not.
+ */
+export declare function imageAlt(image: unknown, lang?: string): string;
 /**
  * The locale lens for a site whose translatable fields are `{de, fr, en}`.
  *

package/dist/lens/sanity.js

@@ -34,8 +34,33 @@ export function imageUrl(image) {
     const asset = isObj(img.asset) ? img.asset : undefined;
     return str(asset?.url);
 }
-export function imageAlt(image) {
-    return isObj(image) ? str(image.alt) : "";
+/**
+ * An image's alt text, in one language.
+ *
+ * Alt text is content, so a field-level-i18n CMS localises it like any other
+ * string: a tri-lingual Sanity site models it as `localeString`, i.e. `{de,fr,en}` on
+ * the image object. This used to be `String(image.alt)`, which rendered every
+ * such alt as the literal `"[object Object]"` in the property panel — and then
+ * an editor who corrected that garbage wrote a flat string over the container,
+ * deleting the other two languages with no warning.
+ *
+ * The container sits *inside* a field the table declares `localized: false`,
+ * because the asset reference really is shared across languages. So no
+ * declaration could have expressed this and none is asked for: an object here
+ * is read as a locale container, always. The one thing never done again is
+ * coercing it — an unreadable alt projects as empty, which is true, rather than
+ * as a string that looks like text and is not.
+ */
+export function imageAlt(image, lang) {
+    if (!isObj(image))
+        return "";
+    const alt = image.alt;
+    if (typeof alt === "string")
+        return alt;
+    if (!isObj(alt))
+        return "";
+    const value = lang === undefined ? undefined : alt[lang];
+    return typeof value === "string" ? value : "";
 }
 /**
  * An image whose alt text is editable and whose asset is not.
@@ -45,19 +70,26 @@ export function imageAlt(image) {
  * repoint a reference at something the CMS has no record of.
  */
 const imageCodec = (naming) => ({
-    project(key, raw) {
-        return { [naming.url(key)]: imageUrl(raw), [naming.alt(key)]: imageAlt(raw) };
+    project(key, raw, ctx) {
+        return { [naming.url(key)]: imageUrl(raw), [naming.alt(key)]: imageAlt(raw, ctx.lang) };
     },
-    merge(key, props, before) {
+    merge(key, props, before, ctx) {
         const altKey = naming.alt(key);
         if (!(altKey in props))
             return null;
         const nextAlt = str(props[altKey]);
-        if (!changed(nextAlt, imageAlt(before)))
+        if (!changed(nextAlt, imageAlt(before, ctx.lang)))
             return null;
         if (!isObj(before))
             return null;
-        return { value: { ...before, alt: nextAlt } };
+        /*
+         * Written back into the language's slot, never over the container. The
+         * shape the source had is the shape it keeps: a localised alt stays
+         * localised and the untouched languages ride along, exactly as every other
+         * localised field in this lens behaves.
+         */
+        const alt = isObj(before.alt) ? { ...before.alt, [ctx.lang]: nextAlt } : nextAlt;
+        return { value: { ...before, alt } };
     }
 });
 const fileCodec = {
@@ -119,16 +151,16 @@ const richTextCodec = {
     }
 };
 const imageListCodec = () => ({
-    project(key, raw) {
+    project(key, raw, ctx) {
         return {
             [key]: (Array.isArray(raw) ? raw : []).map((img) => ({
                 image: imageUrl(img),
-                alt: imageAlt(img),
+                alt: imageAlt(img, ctx.lang),
                 _key: isObj(img) ? img._key : undefined
             }))
         };
     },
-    merge(key, props, before) {
+    merge(key, props, before, ctx) {
         if (!(key in props))
             return null;
         const items = Array.isArray(props[key]) ? props[key] : [];
@@ -137,9 +169,11 @@ const imageListCodec = () => ({
         const merged = items.map((item, i) => {
             const src = (item._key !== undefined ? byKey.get(item._key) : undefined) ?? sourceItems[i] ?? {};
             const alt = str(item.alt);
-            if (!isObj(src) || alt === imageAlt(src))
+            if (!isObj(src) || alt === imageAlt(src, ctx.lang))
                 return src;
-            return { ...src, alt };
+            // Same rule as the single image: into the language's slot, never over the
+            // container that holds the other languages.
+            return { ...src, alt: isObj(src.alt) ? { ...src.alt, [ctx.lang]: alt } : alt };
         });
         if (JSON.stringify(merged) === JSON.stringify(sourceItems))
             return null;

package/dist/lens/types.d.ts

@@ -212,8 +212,20 @@ export type CodecContext = {
  * 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 | {
+export type MergeOutcome = null
+/**
+ * A value to store, and optionally a reason the integrator is owed anyway.
+ *
+ * A merge that writes is not the same question as a merge that is safe. A
+ * list whose source rows carry no `rowIdKey` can only be matched by position,
+ * which is the right answer often enough to be worth doing and wrong in a way
+ * nobody can see — so it writes *and* says so. Without this the only way to
+ * report a hazard was to refuse the edit, so the codec that knew stayed
+ * silent and the corruption shipped.
+ */
+ | {
     value: unknown;
+    warning?: string;
 }
 /** The edit cannot be stored, and the editor is owed the reason. */
  | {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avocadostudio-ai/site-sdk",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -147,17 +147,17 @@
   ],
   "dependencies": {
     "zod": "^4.3.6",
-    "@avocadostudio-ai/blocks": "^0.15.0",
-    "@avocadostudio-ai/richtext": "^0.15.0",
-    "@avocadostudio-ai/preview-adapter": "^0.15.0",
-    "@avocadostudio-ai/shared": "^0.15.0"
+    "@avocadostudio-ai/blocks": "^0.16.0",
+    "@avocadostudio-ai/richtext": "^0.16.0",
+    "@avocadostudio-ai/preview-adapter": "^0.16.0",
+    "@avocadostudio-ai/shared": "^0.16.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.15.0"
+    "@avocadostudio-ai/orchestrator-core": "^0.16.0"
   },
   "peerDependenciesMeta": {
     "@avocadostudio-ai/orchestrator-core": {