@bettercms-ai/kit 0.1.1 → 2.0.0

package/README.md

@@ -1,27 +1,33 @@
 # @bettercms-ai/kit
 
-The BetterCMS component kit for React: layout and text primitives, buttons, inputs, menus,
-dialogs, popovers, toasts, a theme builder (`@bettercms-ai/kit/theme`) and the workshop stories
-the dashboard's style guide renders. Icons come from `@bettercms-ai/icons`.
+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 install @bettercms-ai/kit @bettercms-ai/icons styled-components
+npm i @bettercms-ai/kit @base-ui/react @tabler/icons-react framer-motion react react-dom
 ```
 
-| Import | What you get |
-| --- | --- |
-| `@bettercms-ai/kit` | Primitives, components, `ThemeProvider`, hooks. |
-| `@bettercms-ai/kit/theme` | `buildTheme`, the theme types and colour helpers. |
+## Styles
 
-The theme lives under the `bcms` key of the styled-components theme. React 18 or 19,
-`react-dom`, `react-is` and styled-components 5.2+ or 6 are peer dependencies.
+- **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.
 
-## How it is built
+## Theme
 
-`scripts/build.mjs` rebuilds `src/`, `exports/` and `dist/` offline from two sha256-pinned
-tarballs in `vendor/` and one rename table with an exact count per entry. `scripts/vendor-gate.mjs`
-is the release gate: `node scripts/vendor-gate.mjs <tgz | dir | lockfile>...` must print 0 hits.
+```tsx
+import { KitRoot, applyScheme } from "@bettercms-ai/kit/theme";
 
-## License
+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`.
 
-MIT. The code keeps its original MIT copyright notice; see `LICENSE`.
+0.1.x (the previous component kit) is deprecated; its source is kept at git tag `kit/0.1.1-sanity`.

package/dist/_virtual/_rolldown/runtime.js

@@ -0,0 +1,13 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+export { __exportAll };

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/dist/adapters/icons.d.ts

@@ -0,0 +1,15 @@
+/**
+ * ICONS — the kit's Tabler names ↔ the dock's closed icon vocabulary (DOCK_ICON_NAMES).
+ *
+ * Since e126bf33d the dock vocabulary carries every distinct V2 corpus icon under its own Tabler name, so a Tabler name
+ * that is a dock name is stored as itself. The one exception is `map` (a reserved subpath in the icons package), stored
+ * as `earth-americas`, the nearest dock glyph. The map stays ONE-TO-ONE so the read side names the Tabler icon back
+ * exactly: a dock name some row maps onto reads back as that row's Tabler name, never as itself. A Tabler name with no
+ * row and no dock name of its own has no prod form.
+ */
+import { type DockIconName } from "./prod-types";
+export declare const TABLER_TO_DOCK: Readonly<Record<string, DockIconName>>;
+/** The dock name a Tabler icon is stored as, or undefined when it has none. */
+export declare function dockIconOf(tabler: string | undefined): DockIconName | undefined;
+/** The Tabler name a stored dock icon reads back as (a dock name with no row reads as itself). */
+export declare const tablerIconOf: (dock: string) => string;

package/dist/adapters/icons.js

@@ -0,0 +1,27 @@
+import { DOCK_ICON_NAME_SET } from "./prod-types.js";
+//#region src/adapters/icons.ts
+/**
+* ICONS — the kit's Tabler names ↔ the dock's closed icon vocabulary (DOCK_ICON_NAMES).
+*
+* Since e126bf33d the dock vocabulary carries every distinct V2 corpus icon under its own Tabler name, so a Tabler name
+* that is a dock name is stored as itself. The one exception is `map` (a reserved subpath in the icons package), stored
+* as `earth-americas`, the nearest dock glyph. The map stays ONE-TO-ONE so the read side names the Tabler icon back
+* exactly: a dock name some row maps onto reads back as that row's Tabler name, never as itself. A Tabler name with no
+* row and no dock name of its own has no prod form.
+*/
+var TABLER_TO_DOCK = Object.freeze({ map: "earth-americas" });
+/** dock name → the one Tabler name that maps to it. */
+var DOCK_TO_TABLER = new Map(Object.entries(TABLER_TO_DOCK).map(([t, d]) => [d, t]));
+/** The dock name a Tabler icon is stored as, or undefined when it has none. */
+function dockIconOf(tabler) {
+	if (tabler === void 0) return void 0;
+	const mapped = TABLER_TO_DOCK[tabler];
+	if (mapped) return mapped;
+	return DOCK_ICON_NAME_SET.has(tabler) && !DOCK_TO_TABLER.has(tabler) ? tabler : void 0;
+}
+/** 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 { 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/dist/adapters/lossy.d.ts

@@ -0,0 +1,326 @@
+/**
+ * LOSSY ITEMS — every V2 schema feature the production language cannot hold is named, never dropped silently.
+ * CATALOG ITEMS (below) are the V2 metadata a host sets at seeding time, which the dock never stores.
+ *
+ * `path` is a JSON pointer into the V2 TypeSchema ("/fields/3/of/0/fields/1/localized"). `feature` is a stable name
+ * from FEATURES (what the lossy ledger counts), `reason` says why prod cannot keep it, and FEATURES[feature].backlog
+ * names what removes the loss.
+ */
+export interface LossyItem {
+    path: string;
+    feature: LossyFeature;
+    reason: string;
+}
+/**
+ * What removes a lossy feature: a named backend backlog item (its receipt is this feature's lossy count reaching 0), or
+ * an explicit disposition that is not backend work: `corpus-fix` (the V2 schema breaks a prod rule the author can
+ * 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), `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), 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), 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:nesting" | "wontfix:item-config" | "deferred:shopify";
+export declare const FEATURES: {
+    readonly "type:table": {
+        readonly backlog: "table";
+        readonly reason: "Prod has no table field type (BE: a new type): the TableValue is stored verbatim in a json field.";
+    };
+    readonly "type:slot": {
+        readonly backlog: "slot";
+        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 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";
+        readonly reason: "A list of this item type has no prod array form: config.itemType is text, number, date, image, link or richtext. Stored as json.";
+    };
+    readonly "depth>10": {
+        readonly backlog: "wontfix:depth";
+        readonly reason: "Prod allows 10 field levels: the object at level 10 that would nest an 11th is stored as json.";
+    };
+    readonly "type name": {
+        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>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 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";
+        readonly reason: "The default tab is always the first one in prod.";
+    };
+    readonly "group icon": {
+        readonly backlog: "corpus-fix";
+        readonly reason: "A tab icon is a dock icon name (DOCK_ICON_NAMES); this name is not one.";
+    };
+    readonly "group (nested)": {
+        readonly backlog: "corpus-fix";
+        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";
+        readonly reason: "The dock shows at most 3 tabs (DockFieldTabs), so the adapter keeps 3 until the kit GroupTabs replaces DockFieldTabs at the dock cutover: later groups' fields land in the default tab meanwhile.";
+    };
+    readonly "group name collision": {
+        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 "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";
+        readonly reason: "A prod fieldset sits in one tab; this field's tab differs from its fieldset's.";
+    };
+    readonly "fieldset (props)": {
+        readonly backlog: "corpus-fix";
+        readonly reason: "A prop group is defined on the first prop that uses it: a fieldset no prop uses is not stored (and the ones after it move up a place).";
+    };
+    readonly "fieldset name>limit": {
+        readonly backlog: "corpus-fix";
+        readonly reason: "A fieldset name is at most 60 characters (a prop group label 32); truncated.";
+    };
+    readonly "fieldset collision": {
+        readonly backlog: "corpus-fix";
+        readonly reason: "A fieldset shares its id with a group, or this field names a fieldset the schema does not define.";
+    };
+    readonly "duplicate name": {
+        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.";
+    };
+    readonly synced: {
+        readonly backlog: "corpus-fix";
+        readonly reason: "ui.synced names its global in 1–64 characters (trimmed).";
+    };
+    readonly valueShape: {
+        readonly backlog: "corpus-fix";
+        readonly reason: "ui.valueShape is for a link, image or button field only.";
+    };
+    readonly "default value": {
+        readonly backlog: "corpus-fix";
+        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: "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";
+        readonly reason: "A field icon is ui.icon, a dock icon name, on a nesting field only (an object, a list of objects, a modular list); this field is a leaf, or the name is not a dock icon.";
+    };
+    readonly layout: {
+        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 "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.";
+    };
+    readonly "option icon": {
+        readonly backlog: "corpus-fix";
+        readonly reason: "Option icons are dock icon names, all or none per list: an icon in this list is not a dock name, so the list stores none (option_icon_unknown).";
+    };
+    readonly "option description": {
+        readonly backlog: "corpus-fix";
+        readonly reason: "An option description is one line of 1–140 characters (option_description_invalid).";
+    };
+    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), 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";
+        readonly reason: "ui.access takes view \"schema.view\" and edit \"schema.manage\" only (access_cap_unknown), and a developer lock (readOnly \"developer\") is not also a plain read-only flag.";
+    };
+    readonly timezone: {
+        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: "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: "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";
+        readonly reason: "config.unit is a number's (1–24 characters); a rating has no unit.";
+    };
+    readonly "rating bounds": {
+        readonly backlog: "corpus-fix";
+        readonly reason: "A prod rating runs from config.min (≥ 0) to config.max (a whole 1–10) in steps of config.step, min < max and at most 100 whole steps apart.";
+    };
+    readonly "scale rules": {
+        readonly backlog: "corpus-fix";
+        readonly reason: "This scale breaks prod's scale rules: token values 1–32 characters and distinct, labels 1–24, at most 50 steps and 20 presets, a token preset naming a step, a { value, unit } preset needing allowCustom.";
+    };
+    readonly "validation.patternMessage": {
+        readonly backlog: "corpus-fix";
+        readonly reason: "A pattern message needs a stored pattern and is 1–200 characters.";
+    };
+    readonly "validation.pattern": {
+        readonly backlog: "corpus-fix";
+        readonly reason: "A pattern is kept on text, long text and url values, a regex of at most 200 characters that compiles.";
+    };
+    readonly "validation.length": {
+        readonly backlog: "corpus-fix";
+        readonly reason: "Length limits are whole numbers ≥ 0, on text, long text, url and rich text values.";
+    };
+    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 500 (LIST_ITEMS_CAP), a slot's at most 50 (SLOT_ITEMS_CAP).";
+    };
+    readonly "validation.unique": {
+        readonly backlog: "corpus-fix";
+        readonly reason: "unique is for text, long text, slug, email, phone, link, number, select, date and single-model reference fields, and lists; a polymorphic reference has no one id to compare.";
+    };
+    readonly "validation.recommendedMax": {
+        readonly backlog: "corpus-fix";
+        readonly reason: "A soft limit is a positive whole number in prod.";
+    };
+    readonly "item identity": {
+        readonly backlog: "corpus-fix";
+        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: "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";
+        readonly reason: "The item noun is ui.itemLabel, capitalised, at most 24 characters.";
+    };
+    readonly "block model field": {
+        readonly backlog: "block-model-fields";
+        readonly reason: "A modular item type is a kind:'block' model, which holds only fields a block primitive renders (text, long text, rich text, image, link, slug, email, phone, color, select, number, rating, date, datetime, boolean): this field is not stored.";
+    };
+    readonly "item icon": {
+        readonly backlog: "corpus-fix";
+        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";
+        readonly reason: "A row preview's icon is a dock icon name.";
+    };
+    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, or a data table's caption or notes (preview_path_unknown).";
+    };
+    readonly openMode: {
+        readonly backlog: "corpus-fix";
+        readonly reason: "openMode is for object, array, table and code fields only (openMode_leaf).";
+    };
+    readonly "unsupported key": {
+        readonly backlog: "corpus-fix";
+        readonly reason: "This V2 key has no prod mapping.";
+    };
+};
+export type LossyFeature = keyof typeof FEATURES;
+/**
+ * CATALOG ITEMS — V2 metadata the dock never stores, set when a schema is seeded or placed by its host: not a loss of
+ * stored content. Reported apart from LossyItem so the lossy ledger counts only what prod drops.
+ */
+export interface CatalogItem {
+    path: string;
+    feature: CatalogFeature;
+    reason: string;
+}
+export declare const CATALOG: {
+    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 (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.";
+    readonly "kind:object": "An object type is stored as a model.";
+    readonly "kind:entry (props)": "Only blocks become components; the host decides what an entry schema is placed as.";
+    readonly variants: "Variants are separate components sharing a sectionType in prod: the host seeds one per variant.";
+    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 "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[];
+};