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

package/{context.d.ts → dist/context.d.ts}

@@ -10,7 +10,7 @@
  */
 import * as React from "react";
 import type { Cap } from "./schema/sources";
-import type { FieldAccess, FieldPath, FieldSchema, TypeSchema } from "./schema/types";
+import type { FieldAccess, FieldPath, FieldSchema, Fieldset, TypeSchema } from "./schema/types";
 import type { KitIssue } from "./lib/validate";
 import type { ControlProps } from "./types";
 import type { LinkTarget } from "./controls/link";
@@ -31,6 +31,23 @@ export interface KitMediaPickerProps {
     onPick: (assets: KitMediaAsset[]) => void;
     multiple?: boolean;
     accept?: ("image" | "video" | "file" | "svg")[];
+    /** What the dialog is for, in the author's words ("Replace icon"). Absent: the host's own title. */
+    title?: string;
+    /** An icon's Remove, in the dialog's footer (its row has no room for one). Absent: no Remove. */
+    onRemove?: () => void;
+    /**
+     * An icon's first tab: the icons already on this site, each with the value it is stored as. The field's own icon
+     * leads, marked `current`: picking it closes the dialog with no write. Absent: no such tab.
+     */
+    icons?: KitSiteIcon[];
+    onPickIcon?: (value: unknown) => void;
+}
+/** One icon already on the site (KitServices.useSiteIcons), as the picker's first tab draws it. */
+export interface KitSiteIcon {
+    url: string;
+    value: unknown;
+    assetId?: string;
+    current?: boolean;
 }
 export interface KitToastOptions {
     /** the second line under the message (V2 sonner `description`) */
@@ -65,6 +82,13 @@ export interface KitFieldCommentsProps {
     /** "Open in panel": set when the host has a comments panel (`env.onComment`) */
     onOpenPanel?: () => void;
 }
+/** One field's ⋯ menu, as the host's extra items see it (KitServices.FieldMenuExtras). */
+export interface KitFieldMenuExtrasProps {
+    field: FieldSchema;
+    path: FieldPath;
+    /** the field is read-only for the lens: a host offers nothing that edits */
+    readOnly: boolean;
+}
 export interface KitServices {
     /** The media library picker. */
     MediaPicker?: React.ComponentType<KitMediaPickerProps>;
@@ -96,6 +120,17 @@ export interface KitServices {
     }[];
     /** Toasts for Copy / Paste / Reset / AI (each with Undo). Absent → the action still runs, silently. */
     toast?: KitToast;
+    /**
+     * A slug's "Save new address" with "Redirect it to the new address" ticked (V2 SlugControl): the host files the
+     * redirect from the old slug to the new one. Absent → no checkbox is offered, and the toast says the old address
+     * will return "Not found", which is what happens. A rejection is named in a toast (the new slug is already saved).
+     */
+    redirectSlug?: (from: string, to: string) => void | Promise<void>;
+    /**
+     * A slug's "Save new address": the host writes the new address before any redirect is filed. Absent → the form's
+     * value is the save (V2). A rejection is named in a toast and the old-address box stays for another try.
+     */
+    saveSlug?: (to: string) => Promise<void>;
     /** Rewrite with AI. Absent → the ⋯ menu offers no rewrite. `attempt` counts "Try again" presses. */
     aiRewrite?: (text: string, preset: AiPreset, attempt: number) => string | Promise<string>;
     /** In-place field comments. Absent and no `env.onComment` → the field shows no add-comment control. */
@@ -111,6 +146,12 @@ export interface KitServices {
      * owns the label row and the help; the box is tagged `data-kit-legacy`. Absent → the field says why in words.
      */
     LegacyControl?: React.ComponentType<ControlProps>;
+    /**
+     * The host's own items for a field's ⋯ menu (the entry editor's Move up · Move down · Move to panel), drawn after
+     * History and before Rewrite with AI. It renders kit `MenuItem`s, with its own leading `MenuSeparator`, or null.
+     * Absent → the menu is exactly V2's.
+     */
+    FieldMenuExtras?: React.ComponentType<KitFieldMenuExtrasProps>;
     /**
      * A React HOOK: the project's pages and CMS items a link can point at (controls/link.tsx). The host passes the same
      * function for the life of the form (it is called on every render of a link control). Absent → the link picker says
@@ -122,7 +163,51 @@ export interface KitServices {
         loading?: boolean;
         error?: string;
     };
+    /**
+     * A React HOOK: every SVG the site already uses (its pages, header and footer, the library's SVGs), for an icon's
+     * picker. The host passes the same function for the life of the form. Absent → the picker has no site tab.
+     */
+    useSiteIcons?: () => KitSiteIcon[];
+    /**
+     * The entries a rich text's related posts or author bio block shows (kit-richtext-blocks-plan.md RT8). `ids`: the
+     * hand-picked entries (an author bio's one author, related posts in hand-picked mode), answered in that order with
+     * any the host cannot find left out. `query`: related posts chosen for the reader (owner 2026-10-24: `topic` = same
+     * tags or category, `newest` = the collection newest first; `count` of them, `excludeId` the entry being edited).
+     * Absent → the blocks show their empty state; a rejection's message is shown as said.
+     */
+    resolveRichTextRefs?: (req: KitRichTextRefRequest) => Promise<KitRichTextRef[]>;
 }
+/** What a related posts or author bio block asks the host for (KitServices.resolveRichTextRefs). */
+export interface KitRichTextRefRequest {
+    kind: "relatedPosts" | "authorBio";
+    ids?: string[];
+    query?: {
+        collection?: string;
+        mode: "topic" | "newest";
+        count: number;
+        excludeId?: string;
+    };
+}
+/** One resolved entry, as the block draws it: a post card (title, cover, category) or an author (avatar, title as name, bio). */
+export interface KitRichTextRef {
+    id: string;
+    title: string;
+    href?: string;
+    cover?: string;
+    category?: string;
+    avatar?: string;
+    bio?: string;
+}
+/**
+ * A React HOOK over KitServices.resolveRichTextRefs: `unavailable` when the host offers no resolver (draw the empty
+ * state), else `loading`, then `items` or `error` (a sentence). `req` null asks nothing (a block with nothing picked).
+ */
+export declare function useRichTextRefs(req: KitRichTextRefRequest | null): {
+    items: KitRichTextRef[];
+    loading: boolean;
+    error?: string;
+    unavailable: boolean;
+};
 /** Register app services once at module load (e.g. the Content feature registers its media library). */
 export declare function registerKitServices(s: KitServices): void;
 export declare function KitServicesProvider({ value, children }: {
@@ -162,6 +247,12 @@ export interface KitEnv {
     urlPrefix?: string;
     /** The document has been published (slug changes warn about the old address). */
     isPublished?: boolean;
+    /**
+     * The form's slug is the document's ADDRESS (a page's or an entry's URL). Only then does a changed slug on a published
+     * document say the old address will stop working and offer the redirect. A slug prop or a key is not an address, so
+     * it gets no such box (V2 draws it on document hosts only: its component-prop forms pass no published state).
+     */
+    slugIsAddress?: boolean;
     palette: Swatch[];
     /** The whole form is read-only for the lens (the host's content.edit rule, a generated twin…). */
     readOnly: boolean;
@@ -176,7 +267,8 @@ export interface KitEnv {
     /** pathKey → open comment threads */
     comments: Record<string, number>;
     /** Host comment panel. When absent, field comments live in the in-place popover only. */
-    onComment?: (path: FieldPath, field: FieldSchema) => void;
+    /** `quote`: the words selected in a rich text field when the comment came from its toolbar */
+    onComment?: (path: FieldPath, field: FieldSchema, quote?: string) => void;
     /** The whole form is a global block ("Navigation") — every field is synced. */
     syncedFrom?: string;
     /** "Open {title}" on a reference card: the host edits the referenced entry in place (stacked panel). */
@@ -187,7 +279,44 @@ export interface KitEnv {
     }) => void;
     /** CPO D39: "inline" (default) shows help under the label; "tooltip" moves it behind the ⓘ — for dense hosts (grid cells, popovers). */
     helpDisplay?: "inline" | "tooltip";
+    /** D61 Review changes: the host's change markers, present only while its History panel is open. */
+    review?: KitReview;
+    /**
+     * "quiet": a meta-form, like the schema editor's field settings (founder call, 2026-10-05). No comment, ⋯ or per-field
+     * undo on the fields, and an on/off field is a label-left row with its switch on the right (the inspector's PRow), not a
+     * switch card. "preview": the same chrome-free fields, controls exactly as editors see them (a schema preview, where a
+     * comment would land on a sample, never a real document). Default "full".
+     */
+    fieldChrome?: "full" | "preview" | "quiet";
+    /**
+     * A host's own control for one field, by its path key ("type", "options"), drawn inside the usual shell. The schema
+     * editor's field settings plug their Type, Options, Key and Show this field controls in here. Absent = kit controls only.
+     */
+    controls?: Record<string, React.ComponentType<ControlProps>>;
+    /**
+     * A collapsed fieldset's summary as chips, from the host (the schema editor's field settings: "Required", "3 options").
+     * `undefined` falls back to the kit's own one-line summary. Keep it stable (a new function re-renders the form).
+     */
+    sectionSummary?: (set: Fieldset, value: Record<string, unknown>) => string[] | undefined;
+}
+/**
+ * D61 Review changes, as the kit sees it. The host owns the history model; the kit only asks, per field path, whether
+ * it changed in the range, and renders the host's marker (a 2px bar in the author's colour at the field's left edge,
+ * with its hover card) where the at-rest "changed" dot would be.
+ */
+export interface KitReview {
+    /** changes at or inside this field in the range (0 = unchanged) */
+    count: (path: FieldPath) => number;
+    /** the presence colour of whoever changed it last (list rows draw their own bar) */
+    color: (path: FieldPath) => string | undefined;
+    /** the host's change bar and hover card for a changed field (null when unchanged) */
+    bar: (path: FieldPath, field: FieldSchema) => React.ReactNode;
+    /** Show only changes: unchanged fields fold into one quiet line each run */
+    onlyChanges: boolean;
 }
+/** The title of the fieldset a field sits in (null outside one). A quiet meta-form drops a field label that only repeats
+ *  its section's title ("Options" › "Options"): the section heading names it. */
+export declare const KitSectionTitle: React.Context<string | null>;
 export declare const DEFAULT_ENV: KitEnv;
 /** D58 field access: fields in the `seo` group default to `{ edit: "seo.edit" }`. */
 export declare const fieldAccessOf: (field: FieldSchema) => FieldAccess | undefined;

package/{context.js → dist/context.js}

@@ -1,6 +1,6 @@
 import * as React from "react";
 import { jsx } from "react/jsx-runtime";
-//#region src/kit/context.tsx
+//#region src/context.tsx
 /**
 * Kit runtime contexts (V2 HEAD 9829bf1 kit/context.tsx).
 *
@@ -37,6 +37,45 @@ var AI_PRESETS = [
 		label: "Translate to Spanish"
 	}
 ];
+/**
+* A React HOOK over KitServices.resolveRichTextRefs: `unavailable` when the host offers no resolver (draw the empty
+* state), else `loading`, then `items` or `error` (a sentence). `req` null asks nothing (a block with nothing picked).
+*/
+function useRichTextRefs(req) {
+	const { resolveRichTextRefs } = useKitServices();
+	const key = req ? JSON.stringify(req) : "";
+	const [state, setState] = React.useState(null);
+	React.useEffect(() => {
+		if (!resolveRichTextRefs || !key) return;
+		let live = true;
+		resolveRichTextRefs(JSON.parse(key)).then((items) => live && setState({
+			key,
+			items
+		}), (e) => live && setState({
+			key,
+			items: [],
+			error: e instanceof Error ? e.message : String(e)
+		}));
+		return () => void (live = false);
+	}, [resolveRichTextRefs, key]);
+	if (!resolveRichTextRefs) return {
+		items: [],
+		loading: false,
+		unavailable: true
+	};
+	if (!key) return {
+		items: [],
+		loading: false,
+		unavailable: false
+	};
+	const done = state?.key === key ? state : null;
+	return {
+		items: done?.items ?? [],
+		loading: !done,
+		error: done?.error,
+		unavailable: false
+	};
+}
 var registry = {};
 var listeners = /* @__PURE__ */ new Set();
 /** Register app services once at module load (e.g. the Content feature registers its media library). */
@@ -120,6 +159,9 @@ var SITE_PALETTE = [
 		token: "neutral.50"
 	}
 ];
+/** The title of the fieldset a field sits in (null outside one). A quiet meta-form drops a field label that only repeats
+*  its section's title ("Options" › "Options"): the section heading names it. */
+var KitSectionTitle = React.createContext(null);
 var DEFAULT_ENV = {
 	variant: "panel",
 	docId: "kit",
@@ -209,6 +251,6 @@ var FormCtx = React.createContext(null);
 var FormProvider = FormCtx.Provider;
 var useForm = () => React.useContext(FormCtx);
 //#endregion
-export { AI_PRESETS, DEFAULT_ENV, FieldHeaderSlot, FormProvider, KitEnvProvider, KitServicesProvider, SITE_PALETTE, fieldAccessOf, registerKitServices, resolveFieldAccess, seesDevSurfaces, useForm, useKitEnv, useKitServices, visibleFields, visibleSchema };
+export { AI_PRESETS, DEFAULT_ENV, FieldHeaderSlot, FormProvider, KitEnvProvider, KitSectionTitle, KitServicesProvider, SITE_PALETTE, fieldAccessOf, registerKitServices, resolveFieldAccess, seesDevSurfaces, useForm, useKitEnv, useKitServices, useRichTextRefs, visibleFields, visibleSchema };
 
 //# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","names":[],"sources":["../src/context.tsx"],"sourcesContent":["/**\n * Kit runtime contexts (V2 HEAD 9829bf1 kit/context.tsx).\n *\n *  - KitServices  — pluggable app services (media library picker, upload sink, toast, AI rewrite, comment threads).\n *                   Hosts register theirs once (`registerKitServices`) or provide them (`KitServicesProvider`); the kit\n *                   never imports a feature. A service that is absent hides the surface that needs it.\n *  - KitEnv       — the editing environment a control renders in: variant (panel | document), doc identity, site\n *                   palette, permissions, presence, comments. Has safe defaults so a control can render alone.\n *  - FormApi      — present only inside <SchemaForm>: value, writes, navigation, issues, baselines, history.\n */\nimport * as React from \"react\";\nimport type { Cap } from \"./schema/sources\";\nimport type { FieldAccess, FieldPath, FieldSchema, Fieldset, TypeSchema } from \"./schema/types\";\nimport type { KitIssue } from \"./lib/validate\";\nimport type { ControlProps } from \"./types\";\nimport type { LinkTarget } from \"./controls/link\";\n\n/* ── Services ─────────────────────────────────────────────────────────── */\n/** The media asset a picker hands back (the host's media library row, narrowed to what the kit reads). */\nexport interface KitMediaAsset {\n  id: string;\n  url: string;\n  name?: string;\n  alt?: string;\n  kind?: \"image\" | \"video\" | \"file\" | \"svg\";\n  width?: number;\n  height?: number;\n  size?: number;\n}\nexport interface KitMediaPickerProps {\n  open: boolean;\n  onOpenChange: (v: boolean) => void;\n  onPick: (assets: KitMediaAsset[]) => void;\n  multiple?: boolean;\n  accept?: (\"image\" | \"video\" | \"file\" | \"svg\")[];\n  /** What the dialog is for, in the author's words (\"Replace icon\"). Absent: the host's own title. */\n  title?: string;\n  /** An icon's Remove, in the dialog's footer (its row has no room for one). Absent: no Remove. */\n  onRemove?: () => void;\n  /**\n   * An icon's first tab: the icons already on this site, each with the value it is stored as. The field's own icon\n   * leads, marked `current`: picking it closes the dialog with no write. Absent: no such tab.\n   */\n  icons?: KitSiteIcon[];\n  onPickIcon?: (value: unknown) => void;\n}\n/** One icon already on the site (KitServices.useSiteIcons), as the picker's first tab draws it. */\nexport interface KitSiteIcon {\n  url: string;\n  value: unknown;\n  assetId?: string;\n  current?: boolean;\n}\nexport interface KitToastOptions {\n  /** the second line under the message (V2 sonner `description`) */\n  description?: string;\n  action?: { label: string; onClick: () => void };\n  duration?: number;\n  icon?: React.ReactNode;\n}\n/** The host's toaster. The kit has no toast dependency (V2 re-exported sonner's). */\nexport interface KitToast {\n  (message: string, opts?: KitToastOptions): void;\n  success: (message: string, opts?: KitToastOptions) => void;\n}\n/** Rewrite with AI presets (V2 lib/ai.ts). The host's `aiRewrite` service produces the text. */\nexport type AiPreset = \"improve\" | \"shorter\" | \"longer\" | \"simplify\" | \"grammar\" | \"translate\";\nexport const AI_PRESETS: { id: AiPreset; label: string }[] = [\n  { id: \"improve\", label: \"Improve\" },\n  { id: \"shorter\", label: \"Shorter\" },\n  { id: \"longer\", label: \"Longer\" },\n  { id: \"simplify\", label: \"Simplify\" },\n  { id: \"grammar\", label: \"Fix spelling & grammar\" },\n  { id: \"translate\", label: \"Translate to Spanish\" },\n];\n/** The in-place field comments popover (V2 FieldThreads over the comments store), drawn by the host. */\nexport interface KitFieldCommentsProps {\n  docId: string;\n  /** pathKey of the field (\"items.1.answer\") */\n  fieldKey: string;\n  label: string;\n  /** the field's text, first 80 characters */\n  quote?: string;\n  onClose: () => void;\n  /** \"Open in panel\": set when the host has a comments panel (`env.onComment`) */\n  onOpenPanel?: () => void;\n}\n/** One field's ⋯ menu, as the host's extra items see it (KitServices.FieldMenuExtras). */\nexport interface KitFieldMenuExtrasProps {\n  field: FieldSchema;\n  path: FieldPath;\n  /** the field is read-only for the lens: a host offers nothing that edits */\n  readOnly: boolean;\n}\n/* The popover around FieldComments keeps itself open on Escape while focus is on an element marked `data-esc-owner`\n   (V2 guardEscape): the composer marks its input so Escape clears or blurs the draft instead of losing it. */\nexport interface KitServices {\n  /** The media library picker. */\n  MediaPicker?: React.ComponentType<KitMediaPickerProps>;\n  /** Called after an upload so the host can file the assets into its media library. */\n  onUploaded?: (assets: KitMediaAsset[]) => void;\n  /**\n   * Image placements keep their edits BESIDE the url (`${name}Alt` · `${name}Focal` · `${name}Crop` ·\n   * `${name}Decorative`) instead of turning the value into an object — the Visuals block model.\n   */\n  imageSiblings?: boolean;\n  /** Real metadata for an image url (the host's media library), so captions never show placeholders. */\n  resolveImage?: (url: string) => { name?: string; width?: number; height?: number; size?: number } | undefined;\n  /** The host's full image editor (crop, rotate, focal, alt…), opened in place. */\n  editImage?: (req: { docId: string; path: FieldPath; title: string }) => void;\n  /** The project's forms for `reference: { to: [\"form\"] }` (the host's Forms store). */\n  forms?: () => { id: string; title: string; subtitle: string }[];\n  /** Toasts for Copy / Paste / Reset / AI (each with Undo). Absent → the action still runs, silently. */\n  toast?: KitToast;\n  /**\n   * A slug's \"Save new address\" with \"Redirect it to the new address\" ticked (V2 SlugControl): the host files the\n   * redirect from the old slug to the new one. Absent → no checkbox is offered, and the toast says the old address\n   * will return \"Not found\", which is what happens. A rejection is named in a toast (the new slug is already saved).\n   */\n  redirectSlug?: (from: string, to: string) => void | Promise<void>;\n  /**\n   * A slug's \"Save new address\": the host writes the new address before any redirect is filed. Absent → the form's\n   * value is the save (V2). A rejection is named in a toast and the old-address box stays for another try.\n   */\n  saveSlug?: (to: string) => Promise<void>;\n  /** Rewrite with AI. Absent → the ⋯ menu offers no rewrite. `attempt` counts \"Try again\" presses. */\n  aiRewrite?: (text: string, preset: AiPreset, attempt: number) => string | Promise<string>;\n  /** In-place field comments. Absent and no `env.onComment` → the field shows no add-comment control. */\n  FieldComments?: React.ComponentType<KitFieldCommentsProps>;\n  /**\n   * A React hook: open (unresolved) threads on one field, read from the same store FieldComments draws (V2 counted\n   * `useBlockThreads(docId, key)`). Used while the host has no `env.onComment`; absent → SchemaForm `comments` counts.\n   */\n  useFieldCommentCount?: (docId: string, fieldKey: string) => number;\n  /**\n   * The host's own control for a type (a FieldRenderer arm in the dashboard), drawn for a stored value a kit control\n   * hands off because it cannot carry it unchanged (rich text, LegacyFallback). Bare inside the kit FieldShell, which\n   * owns the label row and the help; the box is tagged `data-kit-legacy`. Absent → the field says why in words.\n   */\n  LegacyControl?: React.ComponentType<ControlProps>;\n  /**\n   * The host's own items for a field's ⋯ menu (the entry editor's Move up · Move down · Move to panel), drawn after\n   * History and before Rewrite with AI. It renders kit `MenuItem`s, with its own leading `MenuSeparator`, or null.\n   * Absent → the menu is exactly V2's.\n   */\n  FieldMenuExtras?: React.ComponentType<KitFieldMenuExtrasProps>;\n  /**\n   * A React HOOK: the project's pages and CMS items a link can point at (controls/link.tsx). The host passes the same\n   * function for the life of the form (it is called on every render of a link control). Absent → the link picker says\n   * page search isn't available and takes a typed path. `error` is a whole sentence naming what failed (\"Pages couldn't\n   * be loaded: …\", \"Items from Blog couldn't be loaded: …\"); the picker shows it under whatever did load.\n   */\n  useLinkTargets?: () => { targets: LinkTarget[]; loading?: boolean; error?: string };\n  /**\n   * A React HOOK: every SVG the site already uses (its pages, header and footer, the library's SVGs), for an icon's\n   * picker. The host passes the same function for the life of the form. Absent → the picker has no site tab.\n   */\n  useSiteIcons?: () => KitSiteIcon[];\n  /**\n   * The entries a rich text's related posts or author bio block shows (kit-richtext-blocks-plan.md RT8). `ids`: the\n   * hand-picked entries (an author bio's one author, related posts in hand-picked mode), answered in that order with\n   * any the host cannot find left out. `query`: related posts chosen for the reader (owner 2026-10-24: `topic` = same\n   * tags or category, `newest` = the collection newest first; `count` of them, `excludeId` the entry being edited).\n   * Absent → the blocks show their empty state; a rejection's message is shown as said.\n   */\n  resolveRichTextRefs?: (req: KitRichTextRefRequest) => Promise<KitRichTextRef[]>;\n}\n\n/** What a related posts or author bio block asks the host for (KitServices.resolveRichTextRefs). */\nexport interface KitRichTextRefRequest {\n  kind: \"relatedPosts\" | \"authorBio\";\n  ids?: string[];\n  query?: { collection?: string; mode: \"topic\" | \"newest\"; count: number; excludeId?: string };\n}\n/** One resolved entry, as the block draws it: a post card (title, cover, category) or an author (avatar, title as name, bio). */\nexport interface KitRichTextRef {\n  id: string;\n  title: string;\n  href?: string;\n  cover?: string;\n  category?: string;\n  avatar?: string;\n  bio?: string;\n}\n\n/**\n * A React HOOK over KitServices.resolveRichTextRefs: `unavailable` when the host offers no resolver (draw the empty\n * state), else `loading`, then `items` or `error` (a sentence). `req` null asks nothing (a block with nothing picked).\n */\nexport function useRichTextRefs(req: KitRichTextRefRequest | null): { items: KitRichTextRef[]; loading: boolean; error?: string; unavailable: boolean } {\n  const { resolveRichTextRefs } = useKitServices();\n  const key = req ? JSON.stringify(req) : \"\";\n  const [state, setState] = React.useState<{ key: string; items: KitRichTextRef[]; error?: string } | null>(null);\n  React.useEffect(() => {\n    if (!resolveRichTextRefs || !key) return;\n    let live = true;\n    resolveRichTextRefs(JSON.parse(key) as KitRichTextRefRequest).then(\n      (items) => live && setState({ key, items }),\n      (e: unknown) => live && setState({ key, items: [], error: e instanceof Error ? e.message : String(e) }),\n    );\n    return () => void (live = false);\n  }, [resolveRichTextRefs, key]);\n  if (!resolveRichTextRefs) return { items: [], loading: false, unavailable: true };\n  if (!key) return { items: [], loading: false, unavailable: false };\n  const done = state?.key === key ? state : null;\n  return { items: done?.items ?? [], loading: !done, error: done?.error, unavailable: false };\n}\nlet registry: KitServices = {};\nconst listeners = new Set<() => void>();\n/** Register app services once at module load (e.g. the Content feature registers its media library). */\nexport function registerKitServices(s: KitServices) {\n  registry = { ...registry, ...s };\n  listeners.forEach((l) => l());\n}\nconst ServicesCtx = React.createContext<KitServices | null>(null);\nexport function KitServicesProvider({ value, children }: { value: KitServices; children: React.ReactNode }) {\n  return <ServicesCtx.Provider value={value}>{children}</ServicesCtx.Provider>;\n}\nexport function useKitServices(): KitServices {\n  const local = React.useContext(ServicesCtx);\n  const global = React.useSyncExternalStore(\n    (cb) => {\n      listeners.add(cb);\n      return () => listeners.delete(cb);\n    },\n    () => registry,\n    () => registry,\n  );\n  return local ? { ...global, ...local } : global;\n}\n\n/** A host header element a top-level field (by path key) renders its actions into, instead of a label row. */\nexport const FieldHeaderSlot = React.createContext<{ key: string; el: HTMLElement } | null>(null);\n\n/* ── Environment ──────────────────────────────────────────────────────── */\nexport type KitVariant = \"panel\" | \"document\";\nexport interface KitPeer {\n  id?: string;\n  name: string;\n  avatar?: string;\n  /** presence colour (avatar ring, field border, caret flag) */\n  color?: string;\n  /** \"editing\" (soft lock + border) or \"viewing\" */\n  status?: \"editing\" | \"viewing\";\n}\nexport interface Swatch {\n  name: string;\n  value: string;\n  token?: string;\n}\n\n/** V2's demo site palette (Caldera). Hosts pass the project's brand palette through `env.palette`. */\nexport const SITE_PALETTE: Swatch[] = [\n  { name: \"Ember\", value: \"#E0663B\", token: \"brand.ember\" },\n  { name: \"Ochre\", value: \"#D97706\", token: \"brand.ochre\" },\n  { name: \"Moss\", value: \"#4F6B4A\", token: \"brand.moss\" },\n  { name: \"Lake\", value: \"#2563EB\", token: \"accent.lake\" },\n  { name: \"Dusk\", value: \"#7C3AED\", token: \"accent.dusk\" },\n  { name: \"Berry\", value: \"#DB2777\", token: \"accent.berry\" },\n  { name: \"Char\", value: \"#1E1B18\", token: \"neutral.900\" },\n  { name: \"Slate\", value: \"#4B5563\", token: \"neutral.600\" },\n  { name: \"Bone\", value: \"#E7E0D6\", token: \"neutral.200\" },\n  { name: \"Paper\", value: \"#F6F1EA\", token: \"neutral.50\" },\n];\n\nexport interface KitEnv {\n  variant: KitVariant;\n  /** Identity of the document/block being edited (rich-text sync, comments, history). */\n  docId: string;\n  /** The document's title — slug generation. */\n  docTitle?: string;\n  /** Public URL prefix for slug previews, e.g. \"caldera.bettercms.site/journal/\". */\n  urlPrefix?: string;\n  /** The document has been published (slug changes warn about the old address). */\n  isPublished?: boolean;\n  /**\n   * The form's slug is the document's ADDRESS (a page's or an entry's URL). Only then does a changed slug on a published\n   * document say the old address will stop working and offer the redirect. A slug prop or a key is not an address, so\n   * it gets no such box (V2 draws it on document hosts only: its component-prop forms pass no published state).\n   */\n  slugIsAddress?: boolean;\n  palette: Swatch[];\n  /** The whole form is read-only for the lens (the host's content.edit rule, a generated twin…). */\n  readOnly: boolean;\n  /**\n   * D58: the host's access check for the lens (`useCan` at the host). The kit never imports the store; it asks this for\n   * field-level `access` and for developer surfaces (field keys, IDs, API names: `schema.view` or `api.view`).\n   * Hosts that omit it (staff tools, demos) get allow-all.\n   */\n  can: (cap: Cap) => boolean;\n  /** pathKey → teammates in that field */\n  presence: Record<string, KitPeer[]>;\n  /** pathKey → open comment threads */\n  comments: Record<string, number>;\n  /** Host comment panel. When absent, field comments live in the in-place popover only. */\n  /** `quote`: the words selected in a rich text field when the comment came from its toolbar */\n  onComment?: (path: FieldPath, field: FieldSchema, quote?: string) => void;\n  /** The whole form is a global block (\"Navigation\") — every field is synced. */\n  syncedFrom?: string;\n  /** \"Open {title}\" on a reference card: the host edits the referenced entry in place (stacked panel). */\n  onOpenReference?: (ref: { collectionId: string; entryId: string; title: string }) => void;\n  /** CPO D39: \"inline\" (default) shows help under the label; \"tooltip\" moves it behind the ⓘ — for dense hosts (grid cells, popovers). */\n  helpDisplay?: \"inline\" | \"tooltip\";\n  /** D61 Review changes: the host's change markers, present only while its History panel is open. */\n  review?: KitReview;\n  /**\n   * \"quiet\": a meta-form, like the schema editor's field settings (founder call, 2026-10-05). No comment, ⋯ or per-field\n   * undo on the fields, and an on/off field is a label-left row with its switch on the right (the inspector's PRow), not a\n   * switch card. \"preview\": the same chrome-free fields, controls exactly as editors see them (a schema preview, where a\n   * comment would land on a sample, never a real document). Default \"full\".\n   */\n  fieldChrome?: \"full\" | \"preview\" | \"quiet\";\n  /**\n   * A host's own control for one field, by its path key (\"type\", \"options\"), drawn inside the usual shell. The schema\n   * editor's field settings plug their Type, Options, Key and Show this field controls in here. Absent = kit controls only.\n   */\n  controls?: Record<string, React.ComponentType<ControlProps>>;\n  /**\n   * A collapsed fieldset's summary as chips, from the host (the schema editor's field settings: \"Required\", \"3 options\").\n   * `undefined` falls back to the kit's own one-line summary. Keep it stable (a new function re-renders the form).\n   */\n  sectionSummary?: (set: Fieldset, value: Record<string, unknown>) => string[] | undefined;\n}\n\n/**\n * D61 Review changes, as the kit sees it. The host owns the history model; the kit only asks, per field path, whether\n * it changed in the range, and renders the host's marker (a 2px bar in the author's colour at the field's left edge,\n * with its hover card) where the at-rest \"changed\" dot would be.\n */\nexport interface KitReview {\n  /** changes at or inside this field in the range (0 = unchanged) */\n  count: (path: FieldPath) => number;\n  /** the presence colour of whoever changed it last (list rows draw their own bar) */\n  color: (path: FieldPath) => string | undefined;\n  /** the host's change bar and hover card for a changed field (null when unchanged) */\n  bar: (path: FieldPath, field: FieldSchema) => React.ReactNode;\n  /** Show only changes: unchanged fields fold into one quiet line each run */\n  onlyChanges: boolean;\n}\n\n/** The title of the fieldset a field sits in (null outside one). A quiet meta-form drops a field label that only repeats\n *  its section's title (\"Options\" › \"Options\"): the section heading names it. */\nexport const KitSectionTitle = React.createContext<string | null>(null);\nexport const DEFAULT_ENV: KitEnv = {\n  variant: \"panel\",\n  docId: \"kit\",\n  palette: [],\n  readOnly: false,\n  can: () => true,\n  presence: {},\n  comments: {},\n};\nconst EnvCtx = React.createContext<KitEnv>(DEFAULT_ENV);\n\n/** D58 field access: fields in the `seo` group default to `{ edit: \"seo.edit\" }`. */\nexport const fieldAccessOf = (field: FieldSchema): FieldAccess | undefined => field.access ?? (field.group === \"seo\" ? { edit: \"seo.edit\" } : undefined);\n\n/**\n * One field for the lens: hidden (no `view`), read-only (plain text: no `edit`, the field is `readOnly`, or the whole form\n * is read-only and the field has no edit cap of its own), or editable. An explicit `edit` cap wins over the form's\n * read-only rule, so an SEO specialist edits SEO fields inside a form they can't otherwise change.\n */\nexport function resolveFieldAccess(field: FieldSchema, env: Pick<KitEnv, \"can\" | \"readOnly\">): { hidden: boolean; readOnly: boolean } {\n  const a = fieldAccessOf(field);\n  if (a?.view && !env.can(a.view)) return { hidden: true, readOnly: true };\n  if (field.readOnly === true) return { hidden: false, readOnly: true };\n  if (a?.edit) return { hidden: false, readOnly: !env.can(a.edit) };\n  return { hidden: false, readOnly: env.readOnly };\n}\n/** Drop the fields the lens can't `view` (recursively), so they are neither rendered nor validated. Same object back when\n *  nothing is hidden. Values of dropped fields stay in the document untouched. */\nexport function visibleFields(fields: FieldSchema[], can: KitEnv[\"can\"]): FieldSchema[] {\n  let changed = false;\n  const out: FieldSchema[] = [];\n  for (const f of fields) {\n    const a = fieldAccessOf(f);\n    if (a?.view && !can(a.view)) {\n      changed = true;\n      continue;\n    }\n    let g = f;\n    if (f.fields) {\n      const n = visibleFields(f.fields, can);\n      if (n !== f.fields) g = { ...g, fields: n };\n    }\n    if (Array.isArray(f.of)) {\n      const n = visibleFields(f.of, can);\n      if (n !== f.of) g = { ...g, of: n };\n    }\n    if (f.slotSettings) {\n      const n = visibleFields(f.slotSettings, can);\n      if (n !== f.slotSettings) g = { ...g, slotSettings: n };\n    }\n    if (g !== f) changed = true;\n    out.push(g);\n  }\n  return changed ? out : fields;\n}\nexport function visibleSchema(schema: TypeSchema, can: KitEnv[\"can\"]): TypeSchema {\n  const fields = visibleFields(schema.fields, can);\n  return fields === schema.fields ? schema : { ...schema, fields };\n}\n\n/** Developer surfaces (field keys, API names, IDs): `schema.view` or `api.view`. */\nexport const seesDevSurfaces = (env: Pick<KitEnv, \"can\">) => env.can(\"schema.view\") || env.can(\"api.view\");\nexport const KitEnvProvider = EnvCtx.Provider;\nexport const useKitEnv = () => React.useContext(EnvCtx);\n\n/* ── Form runtime (inside <SchemaForm>) ──────────────────────────────── */\nexport interface HistoryEntry {\n  value: unknown;\n  at: number;\n  by: string;\n  label?: string;\n}\nexport interface FormApi {\n  schema: TypeSchema;\n  value: Record<string, unknown>;\n  /** write a value; `record: false` skips the field undo/history stack (e.g. programmatic sync) */\n  setAt: (path: FieldPath, v: unknown, opts?: { record?: boolean; label?: string }) => void;\n  getAt: (path: FieldPath) => unknown;\n  /** value when the form mounted (field undo baseline) */\n  baselineAt: (path: FieldPath) => unknown;\n  /** published value (changed dot, Reset to published); undefined when never published */\n  publishedAt: (path: FieldPath) => unknown;\n  hasPublished: boolean;\n  /** component instances (CPO D28): top-level fields inherit from a component unless overridden */\n  inherited?: { from: string; isOverridden: (key: string) => boolean; reset: (key: string) => void };\n  /** the current navigation path (drill-in stack) */\n  path: FieldPath;\n  navigate: (path: FieldPath) => void;\n  /** the form draws frames for a non-root path. False while SchemaForm renders only the root frame: History and\n   *  drill-in rows hide or go inert instead of navigating to a path nothing shows (no silent no-op). */\n  canNavigate: boolean;\n  resolveSchema?: (blockType: string) => TypeSchema | undefined;\n  /** blocks offered by \"+ Add block\" in slots (filtered by each slot's allow list) */\n  blockLibrary?: TypeSchema[];\n  /** all issues by pathKey */\n  issues: Map<string, KitIssue>;\n  /** the issue shown for a key (rules on blur, required after blur or a publish attempt) */\n  visibleIssue: (key: string) => KitIssue | undefined;\n  /** visible issues under a path prefix (rollup dots on rows, crumbs and tabs) */\n  rollup: (prefix: FieldPath) => { errors: number; warnings: number };\n  touch: (key: string) => void;\n  showAllErrors: boolean;\n  /** per-field undo (Undo last change to {label}) */\n  canUndo: (key: string) => boolean;\n  undo: (key: string) => void;\n  /** versions of a field this session (newest first) */\n  history: (key: string) => HistoryEntry[];\n  /** the last change to this field came from AI (⋯ shows \"Undo AI change\") */\n  aiKeys: Set<string>;\n  markAi: (key: string, on: boolean) => void;\n  /** remembered UI state per frame (selected group tab, open fieldsets) */\n  memory: Map<string, unknown>;\n}\nconst FormCtx = React.createContext<FormApi | null>(null);\nexport const FormProvider = FormCtx.Provider;\nexport const useForm = () => React.useContext(FormCtx);\n"],"mappings":"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"}

package/{controls → dist/controls}/button.d.ts

@@ -24,21 +24,24 @@ export declare function ButtonStyleGrid({ v, onPick, "aria-label": ariaLabel, si
     size?: "sm" | "md";
 }): import("react/jsx-runtime").JSX.Element;
 /**
- * The button as a shape: filled · soft · outlined · underlined. In kit ink by default; `site` draws it in the host's
- * site palette (--kit-preview-*), falling back to kit ink for each token the host leaves unset.
+ * The site's button as the site draws it (V2 link.tsx ButtonPreview: the site palette, not app tokens). On the preview
+ * paper it keeps the site's own colours in both themes; `chrome` = drawn on app chrome (the style grid), where the
+ * dark-ink styles flip so they still read on a dark panel. Prod looks beyond the four: brand as primary, dark as
+ * secondary, any other in the muted kit fill.
  */
-export declare function ButtonPreview({ v, className, small, site }: {
+export declare function ButtonPreview({ v, className, small, chrome }: {
     v: LinkValue;
     className?: string;
     small?: boolean;
-    site?: boolean;
+    chrome?: boolean;
 }): import("react/jsx-runtime").JSX.Element;
 /** A 16px neutral glyph of the style (filled · outlined · underlined) — brand-free, so the field stays calm. */
 export declare function StyleGlyph({ style, className }: {
     style?: string;
     className?: string;
 }): import("react/jsx-runtime").JSX.Element;
-/** The leading-icon picker: search + grid over BUTTON_ICONS, "No icon" first. */
+/** The leading-icon picker over BUTTON_ICONS, "No icon" first: V2's IconPickerGrid (icon.tsx) — search box, 8-column
+ *  grid in a 224px scroll. The tiles stay one radiogroup (the dash's semantics; V2 draws a listbox). */
 export declare function ButtonIconPicker({ value, onPick }: {
     value?: string;
     onPick: (icon: string | undefined) => void;
@@ -56,3 +59,14 @@ export declare function ButtonScreen({ value, onChange, readOnly, title }: {
  *   [page icon]   Title  /path                         → edits the link in place
  */
 export declare function ButtonControl({ value, onChange, readOnly, id, path, field }: ControlProps): import("react/jsx-runtime").JSX.Element;
+export declare function ButtonLinkEditor({ value, onChange, onSubmit, styles, labelFirst, }: {
+    value: LinkValue;
+    onChange: (v: LinkValue) => void;
+    onSubmit?: () => void;
+    /** null = a plain text link (nav, footer and legal links): no style row. */
+    styles?: {
+        value: ButtonStyle;
+        label: string;
+    }[] | null;
+    labelFirst?: boolean;
+}): import("react/jsx-runtime").JSX.Element;