@bettercms-ai/kit 1.0.0 → 2.0.0-next.0

package/README.md

@@ -0,0 +1,33 @@
+# @bettercms-ai/kit
+
+The BetterCMS V2 Block Kit: the schema language, the form engine that draws the Visual Editor's dock, its controls, and the design tokens. React 19, Base UI.
+
+```sh
+npm i @bettercms-ai/kit @base-ui/react @tabler/icons-react framer-motion react react-dom
+```
+
+## Styles
+
+- **Tailwind v4 app**: import the tokens and the utility names after Tailwind.
+  ```css
+  @import "tailwindcss";
+  @import "@bettercms-ai/kit/theme.css";
+  @import "@bettercms-ai/kit/tokens.css";
+  @source "../node_modules/@bettercms-ai/kit/dist";
+  ```
+- **No Tailwind** (a custom dock input's iframe): `import "@bettercms-ai/kit/styles.css"`, a precompiled sheet with the tokens and every utility the kit uses. Never import it next to your own Tailwind sheet.
+
+## Theme
+
+```tsx
+import { KitRoot, applyScheme } from "@bettercms-ai/kit/theme";
+
+applyScheme("dark"); // .dark on <html>: portalled layers follow it
+<KitRoot>{/* kit components */}</KitRoot>;
+```
+
+## Imports
+
+`@bettercms-ai/kit` re-exports the engine, the controls and the UI primitives. Every module is also importable by path, e.g. `@bettercms-ai/kit/ui/button`, `@bettercms-ai/kit/schema/scale`.
+
+0.1.x (the previous component kit) is deprecated; its source is kept at git tag `kit/0.1.1-sanity`.

package/dist/adapters/dock-values.d.ts

@@ -0,0 +1,28 @@
+/**
+ * DOCK VALUES — a component instance's prop values, prod ↔ V2, one top-level prop at a time (F12).
+ *
+ * The plans and the converters are schema.ts's own (`ToTypeSchemaOptions.plans`, `planFromProd`, `planToProd`), so a
+ * prop's value crosses exactly the way its default does when the schema is read. This module only gives the dock the
+ * two answers it needs in the shape it acts on:
+ *
+ *   propValueToProd(plan, v) → { value, lost }: `lost` names every V2 key prod cannot keep ("cta/style"); non-empty
+ *                              means the write is refused and named.
+ *   prodOnlyKeys(plan, v)    → keys a STORED value carries that the V2 value cannot hand back (a polymorphic
+ *                              reference's modelSlug); non-empty means the kit must not edit that value.
+ */
+import { type ValuePlan } from "./schema";
+export type DockValuePlan = ValuePlan;
+/** A stored prod value → the V2 value the kit edits. */
+export declare const propValueFromProd: (plan: DockValuePlan, v: unknown) => unknown;
+/** A V2 value → what prod stores, plus every V2 key prod cannot keep (paths under the value). */
+export declare function propValueToProd(plan: DockValuePlan, v: unknown): {
+    value: unknown;
+    lost: string[];
+};
+/** Paths under a stored value (no leading slash) whose keys the V2 value drops. */
+export declare function prodOnlyKeys(plan: DockValuePlan, v: unknown): string[];
+/** prodOnlyKeys with the reason schema.ts names for each path. */
+export declare function prodLosses(plan: DockValuePlan, v: unknown): {
+    path: string;
+    reason: string;
+}[];

package/dist/adapters/dock-values.js

@@ -0,0 +1,41 @@
+import { planFromProd, planToProd } from "./schema.js";
+//#region src/adapters/dock-values.ts
+/**
+* DOCK VALUES — a component instance's prop values, prod ↔ V2, one top-level prop at a time (F12).
+*
+* The plans and the converters are schema.ts's own (`ToTypeSchemaOptions.plans`, `planFromProd`, `planToProd`), so a
+* prop's value crosses exactly the way its default does when the schema is read. This module only gives the dock the
+* two answers it needs in the shape it acts on:
+*
+*   propValueToProd(plan, v) → { value, lost }: `lost` names every V2 key prod cannot keep ("cta/style"); non-empty
+*                              means the write is refused and named.
+*   prodOnlyKeys(plan, v)    → keys a STORED value carries that the V2 value cannot hand back (a polymorphic
+*                              reference's modelSlug); non-empty means the kit must not edit that value.
+*/
+/** A stored prod value → the V2 value the kit edits. */
+var propValueFromProd = (plan, v) => planFromProd(plan, v);
+/** A V2 value → what prod stores, plus every V2 key prod cannot keep (paths under the value). */
+function propValueToProd(plan, v) {
+	const lost = [];
+	return {
+		value: planToProd(plan, v, lost),
+		lost
+	};
+}
+/** Paths under a stored value (no leading slash) whose keys the V2 value drops. */
+function prodOnlyKeys(plan, v) {
+	return prodLosses(plan, v).map((l) => l.path);
+}
+/** prodOnlyKeys with the reason schema.ts names for each path. */
+function prodLosses(plan, v) {
+	const out = [];
+	planFromProd(plan, v, (rel, reason) => out.push({
+		path: rel.replace(/^\//, ""),
+		reason
+	}));
+	return out;
+}
+//#endregion
+export { prodLosses, prodOnlyKeys, propValueFromProd, propValueToProd };
+
+//# sourceMappingURL=dock-values.js.map

package/dist/adapters/dock-values.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dock-values.js","names":[],"sources":["../../src/adapters/dock-values.ts"],"sourcesContent":["/**\n * DOCK VALUES — a component instance's prop values, prod ↔ V2, one top-level prop at a time (F12).\n *\n * The plans and the converters are schema.ts's own (`ToTypeSchemaOptions.plans`, `planFromProd`, `planToProd`), so a\n * prop's value crosses exactly the way its default does when the schema is read. This module only gives the dock the\n * two answers it needs in the shape it acts on:\n *\n *   propValueToProd(plan, v) → { value, lost }: `lost` names every V2 key prod cannot keep (\"cta/style\"); non-empty\n *                              means the write is refused and named.\n *   prodOnlyKeys(plan, v)    → keys a STORED value carries that the V2 value cannot hand back (a polymorphic\n *                              reference's modelSlug); non-empty means the kit must not edit that value.\n */\nimport { planFromProd, planToProd, type ValuePlan } from \"./schema\";\n\nexport type DockValuePlan = ValuePlan;\n\n/** A stored prod value → the V2 value the kit edits. */\nexport const propValueFromProd = (plan: DockValuePlan, v: unknown): unknown => planFromProd(plan, v);\n\n/** A V2 value → what prod stores, plus every V2 key prod cannot keep (paths under the value). */\nexport function propValueToProd(plan: DockValuePlan, v: unknown): { value: unknown; lost: string[] } {\n  const lost: string[] = [];\n  const value = planToProd(plan, v, lost);\n  return { value, lost };\n}\n\n/** Paths under a stored value (no leading slash) whose keys the V2 value drops. */\nexport function prodOnlyKeys(plan: DockValuePlan, v: unknown): string[] {\n  return prodLosses(plan, v).map((l) => l.path);\n}\n\n/** prodOnlyKeys with the reason schema.ts names for each path. */\nexport function prodLosses(plan: DockValuePlan, v: unknown): { path: string; reason: string }[] {\n  const out: { path: string; reason: string }[] = [];\n  planFromProd(plan, v, (rel, reason) => out.push({ path: rel.replace(/^\\//, \"\"), reason }));\n  return out;\n}\n"],"mappings":";;;;;;;;;;;;;;;AAiBA,IAAa,qBAAqB,MAAqB,MAAwB,aAAa,MAAM,CAAC;;AAGnG,SAAgB,gBAAgB,MAAqB,GAAgD;CACnG,MAAM,OAAiB,CAAC;CAExB,OAAO;EAAE,OADK,WAAW,MAAM,GAAG,IACzB;EAAO;CAAK;AACvB;;AAGA,SAAgB,aAAa,MAAqB,GAAsB;CACtE,OAAO,WAAW,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,EAAE,IAAI;AAC9C;;AAGA,SAAgB,WAAW,MAAqB,GAAgD;CAC9F,MAAM,MAA0C,CAAC;CACjD,aAAa,MAAM,IAAI,KAAK,WAAW,IAAI,KAAK;EAAE,MAAM,IAAI,QAAQ,OAAO,EAAE;EAAG;CAAO,CAAC,CAAC;CACzF,OAAO;AACT"}

package/{adapters → dist/adapters}/icons.js

@@ -1,5 +1,5 @@
 import { DOCK_ICON_NAME_SET } from "./prod-types.js";
-//#region src/kit/adapters/icons.ts
+//#region src/adapters/icons.ts
 /**
 * ICONS — the kit's Tabler names ↔ the dock's closed icon vocabulary (DOCK_ICON_NAMES).
 *
@@ -22,6 +22,6 @@ function dockIconOf(tabler) {
 /** The Tabler name a stored dock icon reads back as (a dock name with no row reads as itself). */
 var tablerIconOf = (dock) => DOCK_TO_TABLER.get(dock) ?? dock;
 //#endregion
-export { dockIconOf, tablerIconOf };
+export { TABLER_TO_DOCK, dockIconOf, tablerIconOf };
 
 //# sourceMappingURL=icons.js.map

package/dist/adapters/icons.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"icons.js","names":[],"sources":["../../src/adapters/icons.ts"],"sourcesContent":["/**\n * ICONS — the kit's Tabler names ↔ the dock's closed icon vocabulary (DOCK_ICON_NAMES).\n *\n * Since e126bf33d the dock vocabulary carries every distinct V2 corpus icon under its own Tabler name, so a Tabler name\n * that is a dock name is stored as itself. The one exception is `map` (a reserved subpath in the icons package), stored\n * as `earth-americas`, the nearest dock glyph. The map stays ONE-TO-ONE so the read side names the Tabler icon back\n * exactly: a dock name some row maps onto reads back as that row's Tabler name, never as itself. A Tabler name with no\n * row and no dock name of its own has no prod form.\n */\nimport { DOCK_ICON_NAME_SET, type DockIconName } from \"./prod-types\";\n\nexport const TABLER_TO_DOCK: Readonly<Record<string, DockIconName>> = Object.freeze({\n  map: \"earth-americas\", // approximate: `map` is a reserved subpath of @bettercms-ai/icons\n});\n\n/** dock name → the one Tabler name that maps to it. */\nconst DOCK_TO_TABLER: ReadonlyMap<string, string> = new Map(Object.entries(TABLER_TO_DOCK).map(([t, d]) => [d, t]));\n\n/** The dock name a Tabler icon is stored as, or undefined when it has none. */\nexport function dockIconOf(tabler: string | undefined): DockIconName | undefined {\n  if (tabler === undefined) return undefined;\n  const mapped = TABLER_TO_DOCK[tabler];\n  if (mapped) return mapped;\n  // a Tabler name that is also a dock name is kept as itself, unless a mapped name already reads back from it\n  return DOCK_ICON_NAME_SET.has(tabler) && !DOCK_TO_TABLER.has(tabler) ? (tabler as DockIconName) : undefined;\n}\n\n/** The Tabler name a stored dock icon reads back as (a dock name with no row reads as itself). */\nexport const tablerIconOf = (dock: string): string => DOCK_TO_TABLER.get(dock) ?? dock;\n"],"mappings":";;;;;;;;;;;AAWA,IAAa,iBAAyD,OAAO,OAAO,EAClF,KAAK,iBACP,CAAC;;AAGD,IAAM,iBAA8C,IAAI,IAAI,OAAO,QAAQ,cAAc,CAAC,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;;AAGlH,SAAgB,WAAW,QAAsD;CAC/E,IAAI,WAAW,KAAA,GAAW,OAAO,KAAA;CACjC,MAAM,SAAS,eAAe;CAC9B,IAAI,QAAQ,OAAO;CAEnB,OAAO,mBAAmB,IAAI,MAAM,KAAK,CAAC,eAAe,IAAI,MAAM,IAAK,SAA0B,KAAA;AACpG;;AAGA,IAAa,gBAAgB,SAAyB,eAAe,IAAI,IAAI,KAAK"}

package/{adapters → dist/adapters}/lossy.d.ts

@@ -17,15 +17,21 @@ export interface LossyItem {
  * satisfy: rename, shorten, reorder, drop a key the type cannot use), `dashboard:F12` (prod stores it; only the dock's
  * DockFieldTabs drops it, and the kit's GroupTabs replaces that at the dock cutover), `wontfix:depth` (a prod rule kept
  * on purpose: the backend refuses an 11th level with field_depth_exceeded), `wontfix:item-config` (the backend refuses
- * per-item config on a list of scalars on purpose, array_config_key_unknown). corpus-fix items are V2 corpus defects, an
+ * per-item config on a list of scalars on purpose, array_config_key_unknown), `wontfix:nesting` (the backend keeps a
+ * slot's settings leaf fields, on purpose: slot_settings_invalid), `deferred:shopify` (owner 2026-10-11: a Shopify
+ * reference stays locked text until the Shopify integration pipeline is built; allowed-deviations.json "deferred"). Owner 2026-10-11 (C11): the backend keeps a scalar list's
+ * item settings (config.item), a list's bounds to 500, openMode on code, a slot's allow names (config.allow), a dotted
+ * document preview path, the tabs no top-level prop sits in (components.tabs) and a nested field's tab (ui.tab { id }).
+ * corpus-fix items are V2 corpus defects, an
  * owner note for the demo repo: the sandbox renders them from the V2 schema, seeding skips them.
  *
- * Landed on origin/dev and mapped here, so they name no feature any more: prop-reference (73a120c50), validation-parity
+ * Landed on origin/dev and mapped here, so they name no feature any more: prop-reference (73a120c50), prop reference targets + filter (a4ce1ae95; shopify stays named), validation-parity
  * (dd021ceba), option-meta (ab15fe893), chrome-keys (98e48b9e3, 324580b2e), adapter:icons (the V2 icon vocabulary,
- * e126bf33d), localized-flag (279a10490). What those keys still cannot hold is a value the backend refuses, named
- * below as corpus-fix.
+ * e126bf33d), localized-flag (279a10490), table / polymorphic list nesting (B1/B2: a data table or a polymorphic list at
+ * any depth, in an object, a list's rows or an item type), slot nesting (C1/C2: a slot prop at any depth). What those
+ * keys still cannot hold is a value the backend refuses, named below as corpus-fix.
  */
-export type Backlog = "reference-targets" | "table" | "slot" | "block-model-fields" | "corpus-fix" | "dashboard:F12" | "wontfix:depth" | "wontfix:item-config";
+export type Backlog = "reference-targets" | "table" | "slot" | "block-model-fields" | "corpus-fix" | "dashboard:F12" | "wontfix:depth" | "wontfix:nesting" | "wontfix:item-config" | "deferred:shopify";
 export declare const FEATURES: {
     readonly "type:table": {
         readonly backlog: "table";
@@ -33,11 +39,15 @@ export declare const FEATURES: {
     };
     readonly "type:slot": {
         readonly backlog: "slot";
-        readonly reason: "Blocks inside a block have no field: modular needs separate block models and stores {__id,__type,data}. Stored as json.";
+        readonly reason: "Blocks inside a block on a content model: the backend's slot field (kind:'block' models by blockSlugs) is not mapped by this adapter yet, so it is stored as json. A component's top-level slot is a slot prop.";
     };
     readonly "type:polymorphic-array": {
         readonly backlog: "slot";
-        readonly reason: "An array of several item types: a model stores it as modular (item types of object only), props have no modular. Stored as json.";
+        readonly reason: "An array of several item types: a model stores it as modular and a prop as a polymorphic list (table, config.mode \"types\"), both of object item types only. A list mixing scalar item types is stored as json.";
+    };
+    readonly "item chrome (types)": {
+        readonly backlog: "slot";
+        readonly reason: "A polymorphic list's item type is { name, label?, fields, icon?, preview? } (item_types_invalid): it keeps its dock icon and row preview, and no other chrome.";
     };
     readonly "type:primitive-array": {
         readonly backlog: "wontfix:item-config";
@@ -51,9 +61,13 @@ export declare const FEATURES: {
         readonly backlog: "corpus-fix";
         readonly reason: "The schema name is stored as a kebab-case slug, which does not read back as this name.";
     };
-    readonly "group name>20": {
+    readonly "group name>40": {
+        readonly backlog: "corpus-fix";
+        readonly reason: "A tab name is at most 40 characters; truncated.";
+    };
+    readonly "group title": {
         readonly backlog: "corpus-fix";
-        readonly reason: "A tab name is at most 20 characters; truncated.";
+        readonly reason: "A prop tab's label is the group title trimmed (1–20 characters): a blank title defines no tab, so the group is not stored and its props sit in the default tab; spaces around a title are not kept.";
     };
     readonly "group default": {
         readonly backlog: "corpus-fix";
@@ -65,7 +79,7 @@ export declare const FEATURES: {
     };
     readonly "group (nested)": {
         readonly backlog: "corpus-fix";
-        readonly reason: "Only top-level fields can sit in a tab.";
+        readonly reason: "A nested field names its tab as ui.tab { id } only when the tab is stored: this group is not (named on the group itself).";
     };
     readonly "groups>3": {
         readonly backlog: "dashboard:F12";
@@ -75,9 +89,9 @@ export declare const FEATURES: {
         readonly backlog: "corpus-fix";
         readonly reason: "Two tabs share an id, or a stored name (the first 20 characters, trimmed, any case): the backend refuses that (tab_name, fieldset ids), so the later tab is not stored.";
     };
-    readonly "group (props)": {
-        readonly backlog: "dashboard:F12";
-        readonly reason: "The dock shows no prop tabs today; the kit GroupTabs renders prop groups as tabs at the dock cutover.";
+    readonly "prop tab limit": {
+        readonly backlog: "corpus-fix";
+        readonly reason: "A component holds at most 8 tabs, each with an id of 1–40 characters (the backend's ui.tab rule): this group is not stored and its props sit in the default tab.";
     };
     readonly "fieldset spans groups": {
         readonly backlog: "corpus-fix";
@@ -99,6 +113,10 @@ export declare const FEATURES: {
         readonly backlog: "corpus-fix";
         readonly reason: "Two sibling fields share a name; prod keys are unique per level, so the later one is renamed.";
     };
+    readonly "reserved name": {
+        readonly backlog: "corpus-fix";
+        readonly reason: "A model field's key is not one a resolver would misread (KEY_RESERVED: derived, layout, page, or a leading _) and starts with a letter (KEY_FORMAT): this one is stored renamed.";
+    };
     readonly rows: {
         readonly backlog: "corpus-fix";
         readonly reason: "ui.rows is a whole number from 1 to 40, on a text or long text field only.";
@@ -116,8 +134,8 @@ export declare const FEATURES: {
         readonly reason: "This initial value holds what the prod value cannot keep (named under it): a crop preset with no image size, a datetime without seconds, a button icon outside the dock vocabulary…";
     };
     readonly slotSettings: {
-        readonly backlog: "slot";
-        readonly reason: "Per-child slot settings belong to the slot, which prod cannot hold.";
+        readonly backlog: "wontfix:nesting";
+        readonly reason: "A slot's per-child settings are at most 20 leaf fields (slot_settings_invalid): this setting is an object, a list, a table, a slot or a form, or past the 20th, or the field holding them is not a slot.";
     };
     readonly icon: {
         readonly backlog: "corpus-fix";
@@ -127,10 +145,6 @@ export declare const FEATURES: {
         readonly backlog: "corpus-fix";
         readonly reason: "This layout does not fit the field in prod: ui.control is dropdown / radio / grid on a select, cards on a select or multiselect, checkbox on a boolean or multiselect, switch on a boolean, segmented on a select of 2–4 options, slider on a number with min < max (≤ 1000 stops); a list of scalars or entries lays out as rows or a gallery.";
     };
-    readonly "segmented>4": {
-        readonly backlog: "corpus-fix";
-        readonly reason: "Prod's segmented control holds 2–4 options (control_segmented): a segmented select with 5 or 6 is stored as radio, with more as dropdown (which V2 itself draws, since it does not fit).";
-    };
     readonly "help>limit": {
         readonly backlog: "corpus-fix";
         readonly reason: "Help text is at most 500 characters on a field and 200 on a prop (a placeholder 120, a prop group description 200); truncated.";
@@ -145,7 +159,7 @@ export declare const FEATURES: {
     };
     readonly condition: {
         readonly backlog: "corpus-fix";
-        readonly reason: "This condition has no prod showIf form: it names something that is not a sibling (the block's _variant is one only for a top-level prop: show_if_variant_field), or tests a value showIf cannot.";
+        readonly reason: "This condition has no prod showIf form: it names something that is not a sibling (the block's _variant is one only for a top-level prop: show_if_variant_field), names it by `scope` (prod resolves a rule at the nearest level that declares its field), or tests a value showIf cannot.";
     };
     readonly access: {
         readonly backlog: "corpus-fix";
@@ -155,13 +169,21 @@ export declare const FEATURES: {
         readonly backlog: "corpus-fix";
         readonly reason: "A field's time zone is true, false, \"site\" or an IANA zone name, on a date or datetime.";
     };
+    readonly "shopify reference": {
+        readonly backlog: "deferred:shopify";
+        readonly reason: "A prop reference to Shopify: no Shopify integration backs one (reference_target_unsupported), so a Shopify-only reference is locked text holding the product id (SHOPIFY_REF_LOCK) and a mixed one keeps its other targets. Owner 2026-10-11: deferred until the Shopify integration pipeline is built (allowed-deviations.json status deferred).";
+    };
     readonly "reference target": {
         readonly backlog: "reference-targets";
-        readonly reason: "Prod references point at content models only (no page, form, shopify or collection targets); a reference prop with none of them is stored as json.";
+        readonly reason: "A prop reference keeps entry models (contentModelId / allowedModelSlugs) and page, form and collection (config.targets, backend a4ce1ae95); Shopify has no integration behind it (reference_target_unsupported), so a shopify target is dropped and a reference with only shopify is stored as json. A content-model field keeps entry models only.";
+    };
+    readonly "reference order": {
+        readonly backlog: "corpus-fix";
+        readonly reason: "Prod keeps a reference's entry models apart from its page / form / collection targets: the list reads back entry models first, then the targets.";
     };
     readonly "reference filter": {
         readonly backlog: "reference-targets";
-        readonly reason: "Prod references have no filter.";
+        readonly reason: "A prop reference keeps its filter as config.filter (1–500 characters, no $parameters or ^ parent: reference_filter_invalid); a content-model field keeps none.";
     };
     readonly "numeric unit": {
         readonly backlog: "corpus-fix";
@@ -189,7 +211,7 @@ export declare const FEATURES: {
     };
     readonly "validation.items": {
         readonly backlog: "corpus-fix";
-        readonly reason: "Item limits are whole numbers ≥ 0 on a list, min ≤ max: a tags max 1–500 and min 0–500, a prop's own list (table, array) at most 50 (SLOT_ITEMS_CAP).";
+        readonly reason: "Item limits are whole numbers ≥ 0 on a list, min ≤ max: a tags max 1–500 and min 0–500, a prop's own list (table, array) at most 500 (LIST_ITEMS_CAP), a slot's at most 50 (SLOT_ITEMS_CAP).";
     };
     readonly "validation.unique": {
         readonly backlog: "corpus-fix";
@@ -204,8 +226,8 @@ export declare const FEATURES: {
         readonly reason: "A list item's name is an identifier (a letter, then letters, digits or _; ≤ 64) and its title 1–60 characters (ui.itemName / ui.itemTitle); an object item keeps no other key.";
     };
     readonly "item settings": {
-        readonly backlog: "wontfix:item-config";
-        readonly reason: "A list of scalars stores its item type only (config.itemType): the item's own validation, description, localized flag or multi-line variant has no prod key (array_config_key_unknown).";
+        readonly backlog: "corpus-fix";
+        readonly reason: "A list of scalars keeps its item's description (1–200 characters), localized flag, required, a text or rich text item's length and a text item's pattern (config.item, array_item_settings_invalid): this setting is none of those, or out of their bounds (a multi-line text item reads back single-line).";
     };
     readonly itemNoun: {
         readonly backlog: "corpus-fix";
@@ -217,7 +239,7 @@ export declare const FEATURES: {
     };
     readonly "item icon": {
         readonly backlog: "corpus-fix";
-        readonly reason: "Prod keeps one icon per list (ui.icon, a dock name): the list has its own icon, or this name is not a dock icon.";
+        readonly reason: "Prod keeps one icon per list (ui.icon, a dock name) and one per polymorphic item type: the list has its own icon, or this name is not a dock icon.";
     };
     readonly "preview icon": {
         readonly backlog: "corpus-fix";
@@ -225,11 +247,11 @@ export declare const FEATURES: {
     };
     readonly "preview path": {
         readonly backlog: "corpus-fix";
-        readonly reason: "A row preview names a child key, or a dotted path whose later segments are children or keys of an image, video, link, button, file, location, json, code or reference value (preview_path_unknown).";
+        readonly reason: "A row preview names a child key, or a dotted path whose later segments are children or keys of an image, video, link, button, file, location, json, code or reference value, or a data table's caption or notes (preview_path_unknown).";
     };
     readonly openMode: {
         readonly backlog: "corpus-fix";
-        readonly reason: "openMode is for object, array and table fields only.";
+        readonly reason: "openMode is for object, array, table and code fields only (openMode_leaf).";
     };
     readonly "unsupported key": {
         readonly backlog: "corpus-fix";
@@ -247,9 +269,10 @@ export interface CatalogItem {
     reason: string;
 }
 export declare const CATALOG: {
-    readonly "block icon": "The block picker's icon belongs to the catalog entry; models and components carry none.";
+    readonly "block icon": "The block picker's icon belongs to the catalog entry; a model carries none (a component stores it as component.icon, a dock icon, so only one with no dock name for it lands here).";
     readonly category: "The block picker's category is catalog metadata. A component takes the nearest prod category (CATEGORY_TO_PROD) when there is one; a model has none.";
-    readonly "document preview": "The document-level preview is catalog metadata; models and components carry none.";
+    readonly "document preview": "The document-level preview (how a row of this type reads in a parent's list) has no place on a model; a component stores it as component.preview.";
+    readonly "document preview path": "component.preview names a top-level prop key or a dotted path into one (`slides.0.heading`, componentPreviewRefusals); a key no prop has, or a path through a renamed value key (`image.alt`), is not stored (preview_key_unknown), so the slot row reads the child's first text instead.";
     readonly "kind:block (fields)": "A section's fields are stored as a model (kind model): which host places it is set at seeding.";
     readonly "kind:global": "A global (synced) block is a host-level placement; its fields are stored as a model or a component.";
     readonly "kind:page": "A page schema is stored as a model; the host makes it a page.";
@@ -259,9 +282,45 @@ export declare const CATALOG: {
     readonly ai: "The AI-assist sparkle is a host setting, not stored on the field.";
     readonly "item openMode": "Prod keeps one openMode per list, the array's own; the V2 engine reads only that one too (lib/schema.ts itemOpenMode ignores the item's), so the item's changes nothing the dock shows.";
     readonly "itemNoun (derived)": "A list with no itemNoun whose item title is not the field title's singular: ui.itemLabel keeps the item title, and the read side names the noun from it, which is the noun the V2 engine already falls back to (lib/schema.ts itemNoun).";
+    readonly "fieldset (derived)": "A field names a fieldset the schema does not declare: the V2 engine draws it as a section titled by its name (engine/field-list.tsx arrange), so it is stored as that prop group and the read side declares it. Not a loss.";
     readonly "prop target": "A V2 prop has no binding path, so fromTypeSchema('props') returns none: seeding binds each prop to its target. Not a loss.";
     readonly "block placement": "Where a block fits (inline / section / page) is the host's: the block picker and a body's Insert menu place it; a model or component carries none.";
-    readonly "seeded instance": "A starting value the host writes into a new instance when it seeds or places one: a schema-level initialValue, or a reference prop's default (a definition holds none: reference_in_definition).";
+    readonly "slot allow": "A slot keeps its V2 allow list as config.allow (1–50 block names of 1–64 characters, no repeats: slot_allow_invalid), which the dock resolves to the project's components; this list breaks those bounds, so the slot takes any component.";
+    readonly "segmented fallback": "A segmented select of 5+ options: V2 draws the dropdown (D46, choice.tsx fitsSegmented) and prod stores the select with no control (control_segmented holds 2–4), which the dock draws as the same dropdown. Nothing drawn differs.";
+    readonly "seeded instance": "A starting value the host writes into a new instance when it seeds or places one: a schema-level initialValue, a reference prop's default (a definition holds none: reference_in_definition), or a slot's children (they name V2 block types, which become component instances at seeding).";
     readonly "not applicable (props)": "unique on a scalar prop, or on a sub-field outside a table: each placement holds its own value, so there is nothing to be unique across (unique_prop_scope). The instance is the whole document.";
+    readonly "host config": "A prod-only prop config key the host reads, not the V2 schema: a rich text's Accept list, its one-paragraph flags (allowMultipleParagraphs, the older inline), allowTargetBlank and component allowlist (the dock's rich-text codec and insert menu read them from the stored prop: dock-v2 richTextCodec configAt, kitServices insertableComponents), a section label, and the import's write-back metadata no editor reads (SERVER_CONFIG_KEYS). Read back, it names no loss: the kit never writes a definition, so the config rides untouched.";
 };
 export type CatalogFeature = keyof typeof CATALOG;
+/**
+ * Keys the import (BE derive-schema.ts, register-editable-pages.ts, template-copy.ts) writes onto a field for the
+ * SERVER: how publish writes a value back into the site's own HTML (`attr`, `numeric`, `iconFont`, `htmlClasses`,
+ * `units`, `lead`), which band a field belongs to (`band`, `family`, `shape`), and import markers (`seeded`, `shared`,
+ * `sharedValue`). No form reads them, so no form loses anything by leaving them alone, and no agent may write them: the
+ * backend MCP drops them from what an agent sends, and its contract test fails on any key the import writes that is
+ * neither here, a host key, nor read by the kit (kit-catalog.json `fieldConfig`).
+ */
+export declare const SERVER_CONFIG_KEYS: ReadonlySet<string>;
+/** The prop config keys CATALOG "host config" covers: any type's, then a rich text's (richtext, document) own. */
+export declare const HOST_CONFIG_KEYS: {
+    any: ReadonlySet<string>;
+    richtext: ReadonlySet<string>;
+};
+export declare const isHostConfigKey: (type: string, key: string) => boolean;
+/**
+ * The prod config keys the kit adapter READS, per prod field type (`*` = every type): what an agent may write on a
+ * field and still edit it in the kit. Exported to the backend with the host and server keys (kit-catalog.json
+ * `fieldConfig`), where the MCP warns on any other key and its contract test checks what the import writes.
+ * field-config-contract.test.ts proves each entry against `toTypeSchema`, so this list cannot claim a key the
+ * adapter drops; a key missing here only costs a warning.
+ */
+export declare const KIT_READ_CONFIG_KEYS: Readonly<Record<string, readonly string[]>>;
+/** The field-config contract the backend reads (kit-catalog.json `fieldConfig`). */
+export declare const fieldConfigContract: () => {
+    read: Readonly<Record<string, readonly string[]>>;
+    host: {
+        any: string[];
+        richtext: string[];
+    };
+    server: string[];
+};