canopycms 0.0.68-int.94 → 0.0.68-int.96

package/dist/config/schemas/config.d.ts

@@ -237,10 +237,10 @@ export declare const CanopyConfigSchema: z.ZodObject<{
 /**
  * Default workspace path for prod mode (used when CANOPYCMS_WORKSPACE_ROOT is not set).
  *
- * WARNING: this fallback assumes a worker-style ROOT mount of EFS at /mnt/efs.
- * The CanopyCmsService Lambda mounts EFS THROUGH an access point already rooted
- * at /workspace and therefore sets CANOPYCMS_WORKSPACE_ROOT=/mnt/efs explicitly;
- * if that env were ever unset on the Lambda this default would resolve to
+ * WARNING: this fallback assumes a ROOT mount of EFS at /mnt/efs. CanopyCmsService
+ * mounts EFS in both the Lambda and the worker THROUGH an access point already
+ * rooted at /workspace and therefore sets CANOPYCMS_WORKSPACE_ROOT=/mnt/efs
+ * explicitly; if that env were ever unset this default would resolve to
  * /mnt/efs/workspace = EFS:/workspace/workspace (a wrong, nested dir). The CDK
  * always sets the env, so this only bites a hand-rolled misconfiguration.
  */

package/dist/config/schemas/config.js

@@ -113,10 +113,10 @@ export const CanopyConfigSchema = z
 /**
  * Default workspace path for prod mode (used when CANOPYCMS_WORKSPACE_ROOT is not set).
  *
- * WARNING: this fallback assumes a worker-style ROOT mount of EFS at /mnt/efs.
- * The CanopyCmsService Lambda mounts EFS THROUGH an access point already rooted
- * at /workspace and therefore sets CANOPYCMS_WORKSPACE_ROOT=/mnt/efs explicitly;
- * if that env were ever unset on the Lambda this default would resolve to
+ * WARNING: this fallback assumes a ROOT mount of EFS at /mnt/efs. CanopyCmsService
+ * mounts EFS in both the Lambda and the worker THROUGH an access point already
+ * rooted at /workspace and therefore sets CANOPYCMS_WORKSPACE_ROOT=/mnt/efs
+ * explicitly; if that env were ever unset this default would resolve to
  * /mnt/efs/workspace = EFS:/workspace/workspace (a wrong, nested dir). The CDK
  * always sets the env, so this only bites a hand-rolled misconfiguration.
  */

package/dist/editor/FormRenderer.js

@@ -15,6 +15,7 @@ import { ReferenceField } from './fields/ReferenceField.js';
 import { CodeField } from './fields/CodeField.js';
 import { ImageField } from './fields/ImageField.js';
 import { ObjectField } from './fields/ObjectField.js';
+import { FieldDescription, groupDescriptionProps } from './fields/FieldDescription.js';
 import { InlineGroupField } from './fields/InlineGroupField.js';
 import { formatCanopyPath, normalizeCanopyPath } from './canopy-path.js';
 import { FieldWrapper } from './comments/FieldWrapper.js';
@@ -87,28 +88,28 @@ export const FormRenderer = ({ fields, value, onChange, customRenderers, branch
         switch (field.type) {
             case 'string':
                 if (field.list) {
-                    return wrapWithComments(_jsx(StringListField, { id: fieldId, label: label, value: Array.isArray(currentValue) ? currentValue : [], onChange: (v) => update(v), dataCanopyField: normalizeCanopyPath(path) }, fieldKey(path)));
+                    return wrapWithComments(_jsx(StringListField, { id: fieldId, label: label, description: field.description, value: Array.isArray(currentValue) ? currentValue : [], onChange: (v) => update(v), dataCanopyField: normalizeCanopyPath(path) }, fieldKey(path)));
                 }
-                return wrapWithComments(_jsx(TextField, { id: fieldId, label: label, value: currentValue ?? '', onChange: update, dataCanopyField: normalizeCanopyPath(path) }, fieldKey(path)));
+                return wrapWithComments(_jsx(TextField, { id: fieldId, label: label, description: field.description, value: currentValue ?? '', onChange: update, dataCanopyField: normalizeCanopyPath(path) }, fieldKey(path)));
             case 'boolean':
-                return wrapWithComments(_jsx(ToggleField, { id: fieldId, label: label, value: Boolean(currentValue), onChange: (v) => update(Boolean(v)), dataCanopyField: normalizeCanopyPath(path), testId: `field-toggle-${field.name}` }, fieldKey(path)));
+                return wrapWithComments(_jsx(ToggleField, { id: fieldId, label: label, description: field.description, value: Boolean(currentValue), onChange: (v) => update(Boolean(v)), dataCanopyField: normalizeCanopyPath(path), testId: `field-toggle-${field.name}` }, fieldKey(path)));
             case 'number':
                 if (field.list) {
-                    return wrapWithComments(_jsx(NumberListField, { id: fieldId, label: label, value: Array.isArray(currentValue)
+                    return wrapWithComments(_jsx(NumberListField, { id: fieldId, label: label, description: field.description, value: Array.isArray(currentValue)
                             ? currentValue.filter((v) => typeof v === 'number')
                             : [], onChange: (v) => update(v), dataCanopyField: normalizeCanopyPath(path) }, fieldKey(path)));
                 }
-                return wrapWithComments(_jsx(NumberField, { id: fieldId, label: label, value: typeof currentValue === 'number' ? currentValue : undefined, onChange: (v) => update(v), dataCanopyField: normalizeCanopyPath(path) }, fieldKey(path)));
+                return wrapWithComments(_jsx(NumberField, { id: fieldId, label: label, description: field.description, value: typeof currentValue === 'number' ? currentValue : undefined, onChange: (v) => update(v), dataCanopyField: normalizeCanopyPath(path) }, fieldKey(path)));
             case 'datetime':
-                return wrapWithComments(_jsx(DateTimeField, { id: fieldId, label: label, value: typeof currentValue === 'string' ? currentValue : '', onChange: (v) => update(v), dataCanopyField: normalizeCanopyPath(path) }, fieldKey(path)));
+                return wrapWithComments(_jsx(DateTimeField, { id: fieldId, label: label, description: field.description, value: typeof currentValue === 'string' ? currentValue : '', onChange: (v) => update(v), dataCanopyField: normalizeCanopyPath(path) }, fieldKey(path)));
             case 'markdown':
             case 'mdx':
-                return wrapWithComments(_jsx(MarkdownField, { id: fieldId, label: label, value: currentValue ?? '', onChange: (v) => update(v), dataCanopyField: normalizeCanopyPath(path) }, fieldKey(path)));
+                return wrapWithComments(_jsx(MarkdownField, { id: fieldId, label: label, description: field.description, value: currentValue ?? '', onChange: (v) => update(v), dataCanopyField: normalizeCanopyPath(path) }, fieldKey(path)));
             case 'select': {
                 const selectField = field;
                 const options = normalizeOptions(selectField.options);
                 const isMulti = Boolean(selectField.list);
-                return wrapWithComments(_jsx(SelectField, { id: fieldId, label: label, options: options, value: isMulti
+                return wrapWithComments(_jsx(SelectField, { id: fieldId, label: label, description: field.description, options: options, value: isMulti
                         ? Array.isArray(currentValue)
                             ? currentValue
                             : []
@@ -120,7 +121,7 @@ export const FormRenderer = ({ fields, value, onChange, customRenderers, branch
                     ? normalizeOptions(referenceField.options)
                     : undefined;
                 const isMulti = Boolean(referenceField.list);
-                return wrapWithComments(_jsx(ReferenceField, { id: fieldId, label: label, options: staticOptions?.map((opt) => ({
+                return wrapWithComments(_jsx(ReferenceField, { id: fieldId, label: label, description: field.description, options: staticOptions?.map((opt) => ({
                         label: opt.label,
                         value: opt.value,
                     })), collections: referenceField.collections, entryTypes: referenceField.entryTypes, displayField: referenceField.displayField, branch: branch, value: isMulti
@@ -131,7 +132,7 @@ export const FormRenderer = ({ fields, value, onChange, customRenderers, branch
             }
             case 'image': {
                 const imageField = field;
-                return wrapWithComments(_jsx(ImageField, { id: fieldId, label: label, value: currentValue, onChange: (next) => update(next), aspect: imageField.aspect, altOptional: imageField.altOptional, dataCanopyField: canopyPath, errors: {
+                return wrapWithComments(_jsx(ImageField, { id: fieldId, label: label, description: field.description, value: currentValue, onChange: (next) => update(next), aspect: imageField.aspect, altOptional: imageField.altOptional, dataCanopyField: canopyPath, errors: {
                         src: fieldErrors?.[`${canopyPath}.src`],
                         alt: fieldErrors?.[`${canopyPath}.alt`],
                         crop: fieldErrors?.[`${canopyPath}.crop`],
@@ -139,7 +140,7 @@ export const FormRenderer = ({ fields, value, onChange, customRenderers, branch
             }
             case 'block': {
                 const blockField = field;
-                return wrapWithComments(_jsx(BlockField, { label: label, templates: blockField.templates, value: (Array.isArray(currentValue) ? currentValue : []), onChange: (next) => update(next), renderField: renderField, path: path, dataCanopyField: normalizeCanopyPath(path) }, fieldKey(path)));
+                return wrapWithComments(_jsx(BlockField, { label: label, description: field.description, templates: blockField.templates, value: (Array.isArray(currentValue) ? currentValue : []), onChange: (next) => update(next), renderField: renderField, path: path, dataCanopyField: normalizeCanopyPath(path) }, fieldKey(path)));
             }
             case 'object': {
                 const objectField = field;
@@ -147,7 +148,7 @@ export const FormRenderer = ({ fields, value, onChange, customRenderers, branch
                     const items = Array.isArray(currentValue)
                         ? currentValue
                         : [];
-                    return wrapWithComments(_jsx(Paper, { withBorder: true, radius: "md", p: "md", shadow: "xs", children: _jsxs(Stack, { gap: "sm", children: [_jsxs(Group, { justify: "space-between", children: [_jsx(Text, { size: "sm", fw: 600, children: label }), _jsx(Button, { size: "xs", variant: "light", onClick: () => update([...items, {}]), children: "Add item" })] }), _jsxs(Stack, { gap: "sm", children: [items.map((item, idx) => {
+                    return wrapWithComments(_jsx(Paper, { withBorder: true, radius: "md", p: "md", shadow: "xs", ...groupDescriptionProps(fieldId, field.description), children: _jsxs(Stack, { gap: "sm", children: [_jsxs(Group, { justify: "space-between", children: [_jsx(Text, { size: "sm", fw: 600, children: label }), _jsx(Button, { size: "xs", variant: "light", onClick: () => update([...items, {}]), children: "Add item" })] }), _jsx(FieldDescription, { baseId: fieldId, description: field.description }), _jsxs(Stack, { gap: "sm", children: [items.map((item, idx) => {
                                             const itemTitle = listItemTitle(item, objectField.itemTitleField, `${label} #${idx + 1}`);
                                             return (_jsx(Paper, { role: "group", "aria-label": itemTitle, withBorder: true, radius: "md", p: "sm", shadow: "xs", children: _jsxs(Stack, { gap: "xs", children: [_jsxs(Group, { justify: "space-between", children: [_jsx(Text, { size: "xs", fw: 700, children: itemTitle }), _jsx(Button, { size: "xs", variant: "subtle", color: "red", onClick: () => update(items.filter((_, i) => i !== idx)), children: "Remove" })] }), _jsx(ObjectField, { fields: objectField.fields, value: item, onChange: (next) => {
                                                                 const nextItems = [...items];
@@ -166,10 +167,10 @@ export const FormRenderer = ({ fields, value, onChange, customRenderers, branch
                 // doesn't read as deleting the field from the schema.
                 const hasValue = currentValue !== undefined && currentValue !== null;
                 const canClear = objectField.required !== true && hasValue;
-                return wrapWithComments(_jsx(ObjectField, { label: label, fields: objectField.fields, value: currentValue, onChange: (next) => update(next), onRemove: canClear ? () => update(undefined) : undefined, renderField: renderField, path: path, dataCanopyField: normalizeCanopyPath(path) }, fieldKey(path)));
+                return wrapWithComments(_jsx(ObjectField, { label: label, description: field.description, fields: objectField.fields, value: currentValue, onChange: (next) => update(next), onRemove: canClear ? () => update(undefined) : undefined, renderField: renderField, path: path, dataCanopyField: normalizeCanopyPath(path) }, fieldKey(path)));
             }
             case 'code':
-                return wrapWithComments(_jsx(CodeField, { id: fieldId, label: label, value: typeof currentValue === 'string' ? currentValue : '', onChange: (v) => update(v), dataCanopyField: normalizeCanopyPath(path) }, fieldKey(path)));
+                return wrapWithComments(_jsx(CodeField, { id: fieldId, label: label, description: field.description, value: typeof currentValue === 'string' ? currentValue : '', onChange: (v) => update(v), dataCanopyField: normalizeCanopyPath(path) }, fieldKey(path)));
             default:
                 return (_jsxs(Text, { size: "xs", c: "dimmed", children: ["Unsupported field: ", field.type] }, fieldKey(path)));
         }

package/dist/editor/fields/BlockField.d.ts

@@ -7,6 +7,7 @@ export interface BlockInstance {
 type RenderField = (field: FieldConfig, value: unknown, onChange: (v: unknown) => void, path: Array<string | number>) => React.ReactNode;
 export interface BlockFieldProps {
     label?: string;
+    description?: string;
     templates: BlockConfig[];
     value: BlockInstance[];
     onChange: (blocks: BlockInstance[]) => void;

package/dist/editor/fields/BlockField.js

@@ -1,12 +1,13 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import React, { useMemo, useState } from 'react';
+import React, { useId, useMemo, useState } from 'react';
 let blockKeyCounter = 0;
 import { ActionIcon, Button, Group, Paper, Select, Stack, Text } from '@mantine/core';
 import { DndContext, KeyboardSensor, PointerSensor, useSensor, useSensors, } from '@dnd-kit/core';
 import { SortableContext, arrayMove, sortableKeyboardCoordinates, useSortable, verticalListSortingStrategy, } from '@dnd-kit/sortable';
 import { CSS } from '@dnd-kit/utilities';
 import { formatCanopyPath } from '../canopy-path.js';
+import { FieldDescription, groupDescriptionProps } from './FieldDescription.js';
 const findTemplate = (templates, name) => templates.find((t) => t.name === name);
 const SortableBlock = ({ id, children }) => {
     const { attributes, listeners, setNodeRef, transform, transition, isDragging } = useSortable({
@@ -19,7 +20,8 @@ const SortableBlock = ({ id, children }) => {
     };
     return (_jsx(Paper, { ref: setNodeRef, withBorder: true, radius: "md", p: "sm", shadow: "xs", style: style, children: _jsxs(Group, { align: "flex-start", gap: "sm", children: [_jsx(ActionIcon, { variant: "subtle", "aria-label": "Drag to reorder", ...attributes, ...listeners, style: { cursor: 'grab' }, children: "\u21C5" }, "drag-handle"), _jsx("div", { style: { flex: 1, minWidth: 0, width: '100%' }, children: children }, "content")] }) }));
 };
-export const BlockField = ({ label, templates, value, onChange, renderField, path, dataCanopyField, }) => {
+export const BlockField = ({ label, description, templates, value, onChange, renderField, path, dataCanopyField, }) => {
+    const descriptionBaseId = useId();
     const [itemKeys, setItemKeys] = useState(() => value.map(() => `block-${blockKeyCounter++}`));
     const [pendingTemplate, setPendingTemplate] = useState(null);
     // Keeps itemKeys in sync with value's length; setState runs directly in render, not an effect.
@@ -69,12 +71,12 @@ export const BlockField = ({ label, templates, value, onChange, renderField, pat
         moveBlock(oldIndex, newIndex);
     };
     const selectableTemplates = useMemo(() => templates.map((t) => ({ value: t.name, label: t.label ?? t.name })), [templates]);
-    return (_jsx(Paper, { withBorder: true, radius: "md", p: "md", bg: "gray.0", "data-canopy-field": dataCanopyField ?? formatCanopyPath(path), shadow: "xs", children: _jsxs(Stack, { gap: "sm", children: [_jsxs(Group, { justify: "space-between", children: [_jsx(Text, { size: "xs", fw: 700, c: "dimmed", children: label ?? 'Blocks' }), _jsx(Select, { "aria-label": "Add block", placeholder: "Add block...", data: selectableTemplates, value: pendingTemplate, onChange: (next) => {
+    return (_jsx(Paper, { withBorder: true, radius: "md", p: "md", bg: "gray.0", "data-canopy-field": dataCanopyField ?? formatCanopyPath(path), shadow: "xs", ...groupDescriptionProps(descriptionBaseId, description), children: _jsxs(Stack, { gap: "sm", children: [_jsxs(Group, { justify: "space-between", children: [_jsx(Text, { size: "xs", fw: 700, c: "dimmed", children: label ?? 'Blocks' }), _jsx(Select, { "aria-label": "Add block", placeholder: "Add block...", data: selectableTemplates, value: pendingTemplate, onChange: (next) => {
                                 if (next) {
                                     addBlock(next);
                                 }
                                 setPendingTemplate(null);
-                            }, allowDeselect: true, size: "xs", w: 180 })] }), _jsx(DndContext, { sensors: sensors, onDragEnd: handleDragEnd, children: _jsx(SortableContext, { items: itemKeys, strategy: verticalListSortingStrategy, children: _jsx(Stack, { gap: "sm", children: value.map((block, idx) => {
+                            }, allowDeselect: true, size: "xs", w: 180 })] }), _jsx(FieldDescription, { baseId: descriptionBaseId, description: description }), _jsx(DndContext, { sensors: sensors, onDragEnd: handleDragEnd, children: _jsx(SortableContext, { items: itemKeys, strategy: verticalListSortingStrategy, children: _jsx(Stack, { gap: "sm", children: value.map((block, idx) => {
                                 const template = findTemplate(templates, block.template);
                                 const currentPath = [...path, idx];
                                 return (_jsx(SortableBlock, { id: itemKeys[idx], children: _jsxs(Stack, { gap: "xs", children: [_jsxs(Group, { justify: "space-between", align: "flex-start", children: [_jsx(Text, { size: "sm", fw: 600, children: template?.label ?? block.template ?? 'Unknown block' }), _jsxs(Group, { gap: 4, children: [_jsx(ActionIcon, { variant: "light", "aria-label": "Move block up", disabled: idx === 0, onClick: () => moveBlock(idx, idx - 1), children: "\u2191" }), _jsx(ActionIcon, { variant: "light", "aria-label": "Move block down", disabled: idx === value.length - 1, onClick: () => moveBlock(idx, idx + 1), children: "\u2193" }), _jsx(Button, { variant: "subtle", color: "red", size: "xs", onClick: () => removeBlock(idx), children: "Remove" })] })] }), template ? (_jsx(Stack, { gap: "sm", children: template.fields.map((f) => (_jsx(React.Fragment, { children: renderField(f, block.value?.[f.name], (next) => updateBlockValue(idx, {

package/dist/editor/fields/CodeField.d.ts

@@ -2,6 +2,7 @@ import React from 'react';
 export interface CodeFieldProps {
     id?: string;
     label?: string;
+    description?: string;
     value: string;
     onChange: (value: string) => void;
     language?: string;

package/dist/editor/fields/CodeField.js

@@ -2,8 +2,8 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { useId } from 'react';
 import { Textarea } from '@mantine/core';
 // Placeholder for Monaco integration; host app can provide custom renderer for production.
-export const CodeField = ({ id, label, value, onChange, language, dataCanopyField, }) => {
+export const CodeField = ({ id, label, description, value, onChange, language, dataCanopyField, }) => {
     const generatedId = useId();
     const inputId = id ?? generatedId;
-    return (_jsx(Textarea, { id: inputId, label: label, value: value, onChange: (e) => onChange(e.currentTarget.value), placeholder: language ? `Code (${language})` : 'Code', autosize: true, minRows: 6, size: "sm", "data-canopy-field": dataCanopyField, styles: { input: { fontFamily: 'Menlo, Consolas, monospace' } } }));
+    return (_jsx(Textarea, { id: inputId, label: label, description: description, value: value, onChange: (e) => onChange(e.currentTarget.value), placeholder: language ? `Code (${language})` : 'Code', autosize: true, minRows: 6, size: "sm", "data-canopy-field": dataCanopyField, styles: { input: { fontFamily: 'Menlo, Consolas, monospace' } } }));
 };

package/dist/editor/fields/DateTimeField.d.ts

@@ -2,6 +2,7 @@ import React from 'react';
 export interface DateTimeFieldProps {
     id?: string;
     label?: string;
+    description?: string;
     value: string;
     onChange: (value: string) => void;
     dataCanopyField?: string;

package/dist/editor/fields/DateTimeField.js

@@ -49,8 +49,8 @@ export function datetimeLocalValueToIso(local) {
  * round-trip; sub-second precision is not preserved (no milliseconds field),
  * so a value with non-zero milliseconds is zeroed out once resaved.
  */
-export const DateTimeField = ({ id, label, value, onChange, dataCanopyField, }) => {
+export const DateTimeField = ({ id, label, description, value, onChange, dataCanopyField, }) => {
     const generatedId = useId();
     const inputId = id ?? generatedId;
-    return (_jsx(Input.Wrapper, { id: inputId, label: label, size: "sm", children: _jsx(Input, { type: "datetime-local", step: 1, size: "sm", value: isoToDatetimeLocalValue(value), onChange: (e) => onChange(datetimeLocalValueToIso(e.currentTarget.value)), "data-canopy-field": dataCanopyField }) }));
+    return (_jsx(Input.Wrapper, { id: inputId, label: label, description: description, size: "sm", children: _jsx(Input, { type: "datetime-local", step: 1, size: "sm", value: isoToDatetimeLocalValue(value), onChange: (e) => onChange(datetimeLocalValueToIso(e.currentTarget.value)), "data-canopy-field": dataCanopyField }) }));
 };

package/dist/editor/fields/FieldDescription.d.ts

@@ -0,0 +1,16 @@
+import React from 'react';
+/** The id Mantine gives a native input's description, so custom fields match it. */
+export declare const fieldDescriptionId: (baseId: string) => string;
+/**
+ * Guidance text for fields that don't use a Mantine input's native `description` prop.
+ * Renders nothing for an absent or empty description.
+ */
+export declare const FieldDescription: React.FC<{
+    baseId: string;
+    description?: string;
+}>;
+/** Props that tie a custom field's container to its `FieldDescription`; empty without one. */
+export declare const groupDescriptionProps: (baseId: string, description: string | undefined) => {
+    role?: "group";
+    "aria-describedby"?: string;
+};

package/dist/editor/fields/FieldDescription.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Input } from '@mantine/core';
+/** The id Mantine gives a native input's description, so custom fields match it. */
+export const fieldDescriptionId = (baseId) => `${baseId}-description`;
+/**
+ * Guidance text for fields that don't use a Mantine input's native `description` prop.
+ * Renders nothing for an absent or empty description.
+ */
+export const FieldDescription = ({ baseId, description, }) => description ? (_jsx(Input.Description, { id: fieldDescriptionId(baseId), children: description })) : null;
+/** Props that tie a custom field's container to its `FieldDescription`; empty without one. */
+export const groupDescriptionProps = (baseId, description) => description ? { role: 'group', 'aria-describedby': fieldDescriptionId(baseId) } : {};

package/dist/editor/fields/ImageField.d.ts

@@ -8,6 +8,7 @@ interface ImageFieldErrors {
 export interface ImageFieldProps {
     id?: string;
     label?: string;
+    description?: string;
     value: ImageFieldValue | undefined;
     onChange: (value: ImageFieldValue | undefined) => void;
     /** "W:H" aspect ratio - when set, picking/uploading a new image opens the crop step before the value commits, and a "Crop" button appears on the filled state. */

package/dist/editor/fields/ImageField.js

@@ -11,8 +11,9 @@ import { parseAspectRatio } from '../media/crop-math.js';
 import { MediaLibrary } from '../media/MediaLibrary.js';
 import { useAssetUpload } from '../media/useAssetUpload.js';
 import { ACCEPTED_IMAGE_MIME_TYPES, MAX_UPLOAD_BYTES } from '../media/upload-constants.js';
+import { FieldDescription, groupDescriptionProps } from './FieldDescription.js';
 const PREVIEW_WIDTH = 320;
-export const ImageField = ({ id, label, value, onChange, aspect, altOptional, dataCanopyField, errors, }) => {
+export const ImageField = ({ id, label, description, value, onChange, aspect, altOptional, dataCanopyField, errors, }) => {
     const generatedId = useId();
     const inputId = id ?? generatedId;
     const { baseUrl } = useAssetContext();
@@ -101,7 +102,7 @@ export const ImageField = ({ id, label, value, onChange, aspect, altOptional, da
             ? assetUrl({ src: value.src }, { baseUrl })
             : '';
     const cropInitial = cropRequest?.kind === 'existing' ? value?.crop : undefined;
-    return (_jsxs(Stack, { gap: 4, "data-canopy-field": dataCanopyField, "data-testid": `image-field-${dataCanopyField}`, children: [label && (_jsx(Text, { size: "sm", fw: 500, children: label })), !hasValue ? (_jsxs(Stack, { gap: "xs", children: [_jsx(Dropzone, { onDrop: (files) => void handleDrop(files), onReject: handleReject, maxSize: MAX_UPLOAD_BYTES, accept: ACCEPTED_IMAGE_MIME_TYPES, loading: upload.uploading, multiple: false, "data-testid": `image-field-dropzone-${dataCanopyField}`, children: _jsxs(Group, { justify: "center", gap: "xs", py: "xs", style: { pointerEvents: 'none' }, children: [_jsx(IconUpload, { size: 18 }), _jsx(Text, { size: "xs", children: "Drop an image here, or click to browse" })] }) }), _jsx(Group, { justify: "center", children: _jsx(Button, { variant: "light", size: "xs", leftSection: _jsx(IconPhoto, { size: 14 }), onClick: () => setPickerOpen(true), "data-testid": `image-field-browse-library-${dataCanopyField}`, children: "Browse library" }) }), (upload.error || dropError) && (_jsx(Alert, { icon: _jsx(IconAlertCircle, { size: 16 }), color: "red", children: upload.error || dropError })), errors?.src && (_jsx(Text, { size: "xs", c: "red", children: errors.src }))] })) : (_jsxs(Stack, { gap: "xs", children: [previewFailed ? (_jsxs("div", { "data-testid": `image-field-preview-fallback-${dataCanopyField}`, style: {
+    return (_jsxs(Stack, { gap: 4, "data-canopy-field": dataCanopyField, "data-testid": `image-field-${dataCanopyField}`, ...groupDescriptionProps(inputId, description), children: [label && (_jsx(Text, { size: "sm", fw: 500, children: label })), _jsx(FieldDescription, { baseId: inputId, description: description }), !hasValue ? (_jsxs(Stack, { gap: "xs", children: [_jsx(Dropzone, { onDrop: (files) => void handleDrop(files), onReject: handleReject, maxSize: MAX_UPLOAD_BYTES, accept: ACCEPTED_IMAGE_MIME_TYPES, loading: upload.uploading, multiple: false, "data-testid": `image-field-dropzone-${dataCanopyField}`, children: _jsxs(Group, { justify: "center", gap: "xs", py: "xs", style: { pointerEvents: 'none' }, children: [_jsx(IconUpload, { size: 18 }), _jsx(Text, { size: "xs", children: "Drop an image here, or click to browse" })] }) }), _jsx(Group, { justify: "center", children: _jsx(Button, { variant: "light", size: "xs", leftSection: _jsx(IconPhoto, { size: 14 }), onClick: () => setPickerOpen(true), "data-testid": `image-field-browse-library-${dataCanopyField}`, children: "Browse library" }) }), (upload.error || dropError) && (_jsx(Alert, { icon: _jsx(IconAlertCircle, { size: 16 }), color: "red", children: upload.error || dropError })), errors?.src && (_jsx(Text, { size: "xs", c: "red", children: errors.src }))] })) : (_jsxs(Stack, { gap: "xs", children: [previewFailed ? (_jsxs("div", { "data-testid": `image-field-preview-fallback-${dataCanopyField}`, style: {
                             width: PREVIEW_WIDTH,
                             height: 160,
                             display: 'flex',

package/dist/editor/fields/InlineGroupField.js

@@ -1,8 +1,11 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from 'react';
 import { Paper, Stack, Text } from '@mantine/core';
 import { formatCanopyPath } from '../canopy-path.js';
+import { FieldDescription, groupDescriptionProps } from './FieldDescription.js';
 export const InlineGroupField = ({ label, description, fields, value, onChange, renderField, path, }) => {
-    return (_jsx(Paper, { withBorder: true, radius: "md", p: "md", bg: "gray.0", shadow: "xs", children: _jsxs(Stack, { gap: "sm", children: [(label || description) && (_jsxs(Stack, { gap: 2, children: [label && (_jsx(Text, { size: "xs", fw: 700, c: "dimmed", children: label })), description && (_jsx(Text, { size: "xs", c: "dimmed", children: description }))] })), _jsx(Stack, { gap: "sm", children: fields.map((field) => {
+    const descriptionBaseId = useId();
+    return (_jsx(Paper, { withBorder: true, radius: "md", p: "md", bg: "gray.0", shadow: "xs", ...groupDescriptionProps(descriptionBaseId, description), children: _jsxs(Stack, { gap: "sm", children: [(label || description) && (_jsxs(Stack, { gap: 2, children: [label && (_jsx(Text, { size: "xs", fw: 700, c: "dimmed", children: label })), _jsx(FieldDescription, { baseId: descriptionBaseId, description: description })] })), _jsx(Stack, { gap: "sm", children: fields.map((field) => {
                         // Nested inline groups are also transparent — pass the same parent value/onChange
                         if (field.type === 'group') {
                             const childGroup = field;

package/dist/editor/fields/MarkdownField.d.ts

@@ -2,6 +2,7 @@ import React from 'react';
 export interface MarkdownFieldProps {
     id?: string;
     label?: string;
+    description?: string;
     value: string;
     onChange: (value: string) => void;
     dataCanopyField?: string;

package/dist/editor/fields/MarkdownField.js

@@ -6,6 +6,7 @@ import { InsertEntryLink } from './entry-link/index.js';
 import { MdxImageDialog } from './MdxImageDialog.js';
 import { useApiClient } from '../context/index.js';
 import { uploadAsset } from '../media/upload-asset.js';
+import { FieldDescription, groupDescriptionProps } from './FieldDescription.js';
 const MDXEditorLazy = React.lazy(async () => {
     const [{ MDXEditor }, { headingsPlugin, listsPlugin, quotePlugin, thematicBreakPlugin, markdownShortcutPlugin, linkPlugin, linkDialogPlugin, imagePlugin, tablePlugin, toolbarPlugin, codeBlockPlugin, codeMirrorPlugin, BoldItalicUnderlineToggles, BlockTypeSelect, ListsToggle, CreateLink, InsertImage, InsertTable, InsertThematicBreak, CodeToggle, InsertCodeBlock, UndoRedo, Separator, insertMarkdown$, usePublisher, useCellValues, saveImage$, closeImageDialog$, imageDialogState$, },] = await Promise.all([import('@mdxeditor/editor'), import('@mdxeditor/editor')]);
     const EntryLinkToolbarButton = () => {
@@ -94,7 +95,7 @@ const EditorContentStyles = () => (_jsx("style", { children: `
     .canopy-mdx-content img { max-width: 100%; height: auto; }
   ` }));
 const FallbackTextarea = ({ value, onChange, }) => (_jsx(Textarea, { value: value, onChange: (e) => onChange(e.currentTarget.value), placeholder: "Loading markdown editor...", autosize: true, minRows: 6, size: "sm", readOnly: true }));
-export const MarkdownField = ({ id, label, value, onChange, dataCanopyField, }) => {
+export const MarkdownField = ({ id, label, description, value, onChange, dataCanopyField, }) => {
     const generatedId = useId();
     const inputId = id ?? generatedId;
     const editorRef = useRef(null);
@@ -119,5 +120,5 @@ export const MarkdownField = ({ id, label, value, onChange, dataCanopyField, })
         lastExternalValue.current = newValue;
         onChange(newValue);
     }, [onChange]);
-    return (_jsxs("div", { id: inputId, "data-canopy-field": dataCanopyField, className: "canopy-markdown-field", children: [label && (_jsx(Text, { size: "sm", fw: 500, mb: 4, children: label })), _jsx(EditorContentStyles, {}), _jsx("div", { style: editorWrapperStyle, children: _jsx(Suspense, { fallback: _jsx(FallbackTextarea, { value: value, onChange: onChange }), children: _jsx(MDXEditorLazy, { markdown: value, onChange: handleChange, editorRef: editorRef, imageUploadHandler: imageUploadHandler }) }) })] }));
+    return (_jsxs("div", { id: inputId, "data-canopy-field": dataCanopyField, className: "canopy-markdown-field", ...groupDescriptionProps(inputId, description), children: [label && (_jsx(Text, { size: "sm", fw: 500, mb: 4, children: label })), _jsx(FieldDescription, { baseId: inputId, description: description }), _jsx(EditorContentStyles, {}), _jsx("div", { style: editorWrapperStyle, children: _jsx(Suspense, { fallback: _jsx(FallbackTextarea, { value: value, onChange: onChange }), children: _jsx(MDXEditorLazy, { markdown: value, onChange: handleChange, editorRef: editorRef, imageUploadHandler: imageUploadHandler }) }) })] }));
 };

package/dist/editor/fields/NumberField.d.ts

@@ -2,6 +2,7 @@ import React from 'react';
 export interface NumberFieldProps {
     id?: string;
     label?: string;
+    description?: string;
     value: number | undefined;
     onChange: (value: number | undefined) => void;
     dataCanopyField?: string;

package/dist/editor/fields/NumberField.js

@@ -27,14 +27,14 @@ const toNumericValue = (raw) => {
  * would silently store `0.5` after the second keystroke. See
  * NumberField.test.tsx's keystroke matrix.
  */
-export const NumberField = ({ id, label, value, onChange, dataCanopyField, }) => {
+export const NumberField = ({ id, label, description, value, onChange, dataCanopyField, }) => {
     const generatedId = useId();
     const inputId = id ?? generatedId;
     const [inputValue, setInputValue] = useState(value ?? '');
     // Shows the in-progress text only while it still matches the parent's
     // value; once the parent's value diverges (load, discard, reload), that value wins.
     const displayValue = toNumericValue(inputValue) === value ? inputValue : (value ?? '');
-    return (_jsx(NumberInput, { id: inputId, label: label, value: displayValue, size: "sm", onChange: (next) => {
+    return (_jsx(NumberInput, { id: inputId, label: label, description: description, value: displayValue, size: "sm", onChange: (next) => {
             setInputValue(next);
             onChange(toNumericValue(next));
         }, "data-canopy-field": dataCanopyField }));

package/dist/editor/fields/NumberListField.d.ts

@@ -2,6 +2,7 @@ import React from 'react';
 export interface NumberListFieldProps {
     id?: string;
     label?: string;
+    description?: string;
     value: number[];
     onChange: (value: number[]) => void;
     dataCanopyField?: string;

package/dist/editor/fields/NumberListField.js

@@ -27,11 +27,11 @@ const parseTag = (tag) => {
  * on Enter indistinguishably from being accepted, with nothing to tell a
  * typo from a broken field — so rejected text is named in the error slot.
  */
-export const NumberListField = ({ id, label, value, onChange, dataCanopyField, }) => {
+export const NumberListField = ({ id, label, description, value, onChange, dataCanopyField, }) => {
     const generatedId = useId();
     const inputId = id ?? generatedId;
     const [rejected, setRejected] = useState([]);
-    return (_jsx(TagsInput, { id: inputId, label: label, value: value.map(String), size: "sm", error: rejected.length > 0
+    return (_jsx(TagsInput, { id: inputId, label: label, description: description, value: value.map(String), size: "sm", error: rejected.length > 0
             ? `Not ${rejected.length === 1 ? 'a number' : 'numbers'}: ${rejected.join(', ')}`
             : undefined, onChange: (next) => {
             const parsed = [];

package/dist/editor/fields/ObjectField.d.ts

@@ -3,6 +3,7 @@ import type { FieldConfig } from '../../config/index.js';
 export type RenderField = (field: FieldConfig, value: unknown, onChange: (v: unknown) => void, path: Array<string | number>) => React.ReactNode;
 export interface ObjectFieldProps {
     label?: string;
+    description?: string;
     fields: FieldConfig[];
     value: Record<string, unknown> | undefined;
     onChange: (value: Record<string, unknown>) => void;

package/dist/editor/fields/ObjectField.js

@@ -1,9 +1,12 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from 'react';
 import { Button, Group, Paper, Stack, Text } from '@mantine/core';
 import { formatCanopyPath } from '../canopy-path.js';
-export const ObjectField = ({ label, fields, value, onChange, renderField, path, dataCanopyField, onRemove, }) => {
+import { FieldDescription, groupDescriptionProps } from './FieldDescription.js';
+export const ObjectField = ({ label, description, fields, value, onChange, renderField, path, dataCanopyField, onRemove, }) => {
     const current = value ?? {};
-    return (_jsx(Paper, { withBorder: true, radius: "md", p: "md", bg: "gray.0", "data-canopy-field": dataCanopyField ?? formatCanopyPath(path), shadow: "xs", children: _jsxs(Stack, { gap: "sm", children: [(label || onRemove) && (_jsxs(Group, { justify: "space-between", children: [label && (_jsx(Text, { size: "xs", fw: 700, c: "neutral.8", children: label })), onRemove && (_jsx(Button, { size: "xs", variant: "subtle", color: "red", onClick: onRemove, children: "Clear" }))] })), _jsx(Stack, { gap: "sm", children: fields.map((field) => {
+    const descriptionBaseId = useId();
+    return (_jsx(Paper, { withBorder: true, radius: "md", p: "md", bg: "gray.0", "data-canopy-field": dataCanopyField ?? formatCanopyPath(path), shadow: "xs", ...groupDescriptionProps(descriptionBaseId, description), children: _jsxs(Stack, { gap: "sm", children: [(label || onRemove) && (_jsxs(Group, { justify: "space-between", children: [label && (_jsx(Text, { size: "xs", fw: 700, c: "neutral.8", children: label })), onRemove && (_jsx(Button, { size: "xs", variant: "subtle", color: "red", onClick: onRemove, children: "Clear" }))] })), _jsx(FieldDescription, { baseId: descriptionBaseId, description: description }), _jsx(Stack, { gap: "sm", children: fields.map((field) => {
                         const fieldPath = [...path, field.name];
                         return (_jsx("div", { children: renderField(field, current[field.name], (next) => onChange({ ...current, [field.name]: next }), fieldPath) }, formatCanopyPath(fieldPath)));
                     }) })] }) }));

package/dist/editor/fields/ReferenceField.d.ts

@@ -7,6 +7,7 @@ export interface ReferenceOption {
 export interface ReferenceFieldProps {
     id?: string;
     label?: string;
+    description?: string;
     options?: ReferenceOption[];
     collections?: string[];
     entryTypes?: string[];

package/dist/editor/fields/ReferenceField.js

@@ -6,7 +6,8 @@ import { IconAlertCircle } from '@tabler/icons-react';
 import { createApiClient } from '../../api/client.js';
 import { useOptionalApiClient } from '../context/index.js';
 import { getErrorMessage } from '../../utils/error.js';
-export const ReferenceField = ({ id, label, options: staticOptions, collections, entryTypes, displayField = 'title', branch = 'main', value, onChange, multiple, dataCanopyField, }) => {
+import { FieldDescription, groupDescriptionProps } from './FieldDescription.js';
+export const ReferenceField = ({ id, label, description, options: staticOptions, collections, entryTypes, displayField = 'title', branch = 'main', value, onChange, multiple, dataCanopyField, }) => {
     // Configured with the deployment's basePath when rendered inside an
     // ApiClientProvider (always true in the real Editor tree); `null` outside one
     // (e.g. FormRenderer.stories.tsx), so the fetch effect falls back to a
@@ -101,10 +102,10 @@ export const ReferenceField = ({ id, label, options: staticOptions, collections,
         setRetryCount((count) => count + 1);
     };
     if (loading) {
-        return (_jsxs(Stack, { gap: 4, "data-canopy-field": dataCanopyField, "data-testid": `reference-field-${dataCanopyField}`, children: [_jsx(Text, { size: "sm", fw: 500, children: label }), _jsx(Loader, { size: "sm", "data-testid": `reference-loading-${dataCanopyField}` })] }));
+        return (_jsxs(Stack, { gap: 4, "data-canopy-field": dataCanopyField, "data-testid": `reference-field-${dataCanopyField}`, ...groupDescriptionProps(inputId, description), children: [_jsx(Text, { size: "sm", fw: 500, children: label }), _jsx(FieldDescription, { baseId: inputId, description: description }), _jsx(Loader, { size: "sm", "data-testid": `reference-loading-${dataCanopyField}` })] }));
     }
     if (error) {
-        return (_jsxs(Stack, { gap: 4, "data-canopy-field": dataCanopyField, "data-testid": `reference-field-${dataCanopyField}`, children: [_jsx(Text, { size: "sm", fw: 500, children: label }), _jsx(Alert, { icon: _jsx(IconAlertCircle, { size: 16 }), color: "red", title: "Error", "data-testid": `reference-error-${dataCanopyField}`, children: _jsxs(Stack, { gap: 4, children: [_jsx(Text, { size: "sm", children: error }), _jsx(Button, { size: "xs", variant: "light", onClick: handleRetry, "data-testid": `reference-retry-${dataCanopyField}`, children: "Retry" })] }) })] }));
+        return (_jsxs(Stack, { gap: 4, "data-canopy-field": dataCanopyField, "data-testid": `reference-field-${dataCanopyField}`, ...groupDescriptionProps(inputId, description), children: [_jsx(Text, { size: "sm", fw: 500, children: label }), _jsx(FieldDescription, { baseId: inputId, description: description }), _jsx(Alert, { icon: _jsx(IconAlertCircle, { size: 16 }), color: "red", title: "Error", "data-testid": `reference-error-${dataCanopyField}`, children: _jsxs(Stack, { gap: 4, children: [_jsx(Text, { size: "sm", children: error }), _jsx(Button, { size: "xs", variant: "light", onClick: handleRetry, "data-testid": `reference-retry-${dataCanopyField}`, children: "Retry" })] }) })] }));
     }
-    return (_jsx(Stack, { gap: 4, "data-canopy-field": dataCanopyField, "data-testid": `reference-field-${dataCanopyField}`, children: multiple ? (_jsx(MultiSelect, { id: inputId, label: label, data: options, value: normalizedValue, onChange: (next) => onChange(next), searchable: true, placeholder: "Select reference\u2026", size: "sm" })) : (_jsx(Select, { id: inputId, label: label, data: options, value: normalizedValue, onChange: (next) => onChange(next ?? ''), searchable: true, clearable: true, placeholder: "Select reference\u2026", size: "sm" })) }));
+    return (_jsx(Stack, { gap: 4, "data-canopy-field": dataCanopyField, "data-testid": `reference-field-${dataCanopyField}`, children: multiple ? (_jsx(MultiSelect, { id: inputId, label: label, description: description, data: options, value: normalizedValue, onChange: (next) => onChange(next), searchable: true, placeholder: "Select reference\u2026", size: "sm" })) : (_jsx(Select, { id: inputId, label: label, description: description, data: options, value: normalizedValue, onChange: (next) => onChange(next ?? ''), searchable: true, clearable: true, placeholder: "Select reference\u2026", size: "sm" })) }));
 };

package/dist/editor/fields/SelectField.d.ts

@@ -6,6 +6,7 @@ interface SelectOption {
 export interface SelectFieldProps {
     id?: string;
     label?: string;
+    description?: string;
     options: SelectOption[];
     value: string | string[];
     onChange: (value: string | string[]) => void;

package/dist/editor/fields/SelectField.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useId } from 'react';
 import { MultiSelect, Select, Stack, Text } from '@mantine/core';
-export const SelectField = ({ id, label, options, value, onChange, multiple, placeholder = 'Select…', dataCanopyField, }) => {
+export const SelectField = ({ id, label, description, options, value, onChange, multiple, placeholder = 'Select…', dataCanopyField, }) => {
     const normalizedValue = multiple
         ? Array.isArray(value)
             ? value
@@ -11,5 +11,5 @@ export const SelectField = ({ id, label, options, value, onChange, multiple, pla
             : '';
     const generatedId = useId();
     const inputId = id ?? generatedId;
-    return (_jsxs(Stack, { gap: 4, "data-canopy-field": dataCanopyField, children: [multiple ? (_jsx(MultiSelect, { id: inputId, label: label, data: options, value: normalizedValue, onChange: (next) => onChange(next), searchable: true, placeholder: placeholder, size: "sm" })) : (_jsx(Select, { id: inputId, label: label, data: options, value: normalizedValue, onChange: (next) => onChange(next ?? ''), searchable: true, clearable: true, placeholder: placeholder, size: "sm" })), multiple && (_jsx(Text, { size: "xs", c: "dimmed", children: "Searchable multi-select; start typing to filter." }))] }));
+    return (_jsxs(Stack, { gap: 4, "data-canopy-field": dataCanopyField, children: [multiple ? (_jsx(MultiSelect, { id: inputId, label: label, description: description, data: options, value: normalizedValue, onChange: (next) => onChange(next), searchable: true, placeholder: placeholder, size: "sm" })) : (_jsx(Select, { id: inputId, label: label, description: description, data: options, value: normalizedValue, onChange: (next) => onChange(next ?? ''), searchable: true, clearable: true, placeholder: placeholder, size: "sm" })), multiple && (_jsx(Text, { size: "xs", c: "dimmed", children: "Searchable multi-select; start typing to filter." }))] }));
 };

package/dist/editor/fields/StringListField.d.ts

@@ -2,6 +2,7 @@ import React from 'react';
 export interface StringListFieldProps {
     id?: string;
     label?: string;
+    description?: string;
     value: string[];
     onChange: (value: string[]) => void;
     dataCanopyField?: string;

package/dist/editor/fields/StringListField.js

@@ -7,10 +7,10 @@ import { TagsInput } from '@mantine/core';
  * Uses Mantine's TagsInput: type + Enter adds an item, each item renders as a
  * removable pill, and Backspace on an empty input removes the last item.
  */
-export const StringListField = ({ id, label, value, onChange, dataCanopyField, }) => {
+export const StringListField = ({ id, label, description, value, onChange, dataCanopyField, }) => {
     const generatedId = useId();
     const inputId = id ?? generatedId;
-    return (_jsx(TagsInput, { id: inputId, label: label, value: value, size: "sm", onChange: onChange, 
+    return (_jsx(TagsInput, { id: inputId, label: label, description: description, value: value, size: "sm", onChange: onChange, 
         // Faithful generic-list semantics, not tag ergonomics: no comma-splitting
         // ("New York, NY" stays one item) and duplicates are legitimate list
         // data — TagsInput's defaults would break both, so existing file data

package/dist/editor/fields/TextField.d.ts

@@ -2,6 +2,7 @@ import React from 'react';
 export interface TextFieldProps {
     id?: string;
     label?: string;
+    description?: string;
     value: string;
     onChange: (value: string) => void;
     dataCanopyField?: string;

package/dist/editor/fields/TextField.js

@@ -1,8 +1,8 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useId } from 'react';
 import { TextInput } from '@mantine/core';
-export const TextField = ({ id, label, value, onChange, dataCanopyField, }) => {
+export const TextField = ({ id, label, description, value, onChange, dataCanopyField, }) => {
     const generatedId = useId();
     const inputId = id ?? generatedId;
-    return (_jsx(TextInput, { id: inputId, label: label, value: value, size: "sm", onChange: (e) => onChange(e.currentTarget.value), "data-canopy-field": dataCanopyField }));
+    return (_jsx(TextInput, { id: inputId, label: label, description: description, value: value, size: "sm", onChange: (e) => onChange(e.currentTarget.value), "data-canopy-field": dataCanopyField }));
 };

package/dist/editor/fields/ToggleField.d.ts

@@ -2,6 +2,7 @@ import React from 'react';
 export interface ToggleFieldProps {
     id?: string;
     label?: string;
+    description?: string;
     value: boolean;
     onChange: (value: boolean) => void;
     dataCanopyField?: string;

package/dist/editor/fields/ToggleField.js

@@ -1,8 +1,11 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useId } from 'react';
-import { Switch } from '@mantine/core';
-export const ToggleField = ({ id, label, value, onChange, dataCanopyField, testId, }) => {
+import { Stack, Switch } from '@mantine/core';
+import { FieldDescription, fieldDescriptionId } from './FieldDescription.js';
+export const ToggleField = ({ id, label, description, value, onChange, dataCanopyField, testId, }) => {
     const generatedId = useId();
     const inputId = id ?? generatedId;
-    return (_jsx(Switch, { id: inputId, label: label, checked: value, onChange: (e) => onChange(e.currentTarget.checked), size: "md", "data-canopy-field": dataCanopyField, wrapperProps: testId ? { 'data-testid': testId } : undefined }));
+    // A Switch's `description` sits inside its <label> and so joins the accessible name;
+    // rendering it as a sibling keeps the name to the label alone.
+    return (_jsxs(Stack, { gap: 4, children: [_jsx(Switch, { id: inputId, label: label, "aria-describedby": description ? fieldDescriptionId(inputId) : undefined, checked: value, onChange: (e) => onChange(e.currentTarget.checked), size: "md", "data-canopy-field": dataCanopyField, wrapperProps: testId ? { 'data-testid': testId } : undefined }), _jsx(FieldDescription, { baseId: inputId, description: description })] }));
 };

package/dist/editor/hooks/useCommentSystem.js

@@ -113,6 +113,16 @@ export function useCommentSystem(options) {
     }, [activeCommentContext, options.selectedPath, options.branchName]);
     // Listen for field focus messages from preview frame
     useEffect(() => {
+        // Delayed undo steps (highlight restore, focus clear). Cleanup runs them early rather than
+        // dropping them, so an entry switch never leaves a field highlighted or focused.
+        const pending = new Map();
+        const later = (undo, ms) => {
+            const id = window.setTimeout(() => {
+                pending.delete(id);
+                undo();
+            }, ms);
+            pending.set(id, undo);
+        };
         const handleFocus = (event) => {
             // Only accept messages from the preview's origin (same-origin when previewSrc is
             // relative). Origin-only by design: this hook has no handle on the preview iframe
@@ -136,21 +146,26 @@ export function useCommentSystem(options) {
                 target.scrollIntoView({ behavior: 'smooth', block: 'center' });
                 const previous = target.style.boxShadow;
                 target.style.boxShadow = '0 0 0 3px rgba(79, 70, 229, 0.35)';
-                window.setTimeout(() => {
+                later(() => {
                     target.style.boxShadow = previous;
                 }, 1200);
                 // Set focused field path to trigger FieldWrapper auto-focus
                 if (normalizedPath) {
                     setFocusedFieldPath(normalizedPath);
                     // Clear after brief delay to allow FieldWrapper to detect the change
-                    window.setTimeout(() => {
-                        setFocusedFieldPath(undefined);
-                    }, 100);
+                    later(() => setFocusedFieldPath(undefined), 100);
                 }
             }
         };
         window.addEventListener('message', handleFocus);
-        return () => window.removeEventListener('message', handleFocus);
+        return () => {
+            window.removeEventListener('message', handleFocus);
+            for (const [id, undo] of pending) {
+                window.clearTimeout(id);
+                undo();
+            }
+            pending.clear();
+        };
     }, [options.currentEntry]);
     const handleJumpToField = (entryPath, canopyPath, threadId) => {
         if (entryPath !== options.selectedPath) {

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const CANOPYCMS_VERSION = "0.0.68-int.94";
+export declare const CANOPYCMS_VERSION = "0.0.68-int.96";

package/dist/version.js

@@ -1,3 +1,3 @@
 // Generated by scripts/bump-version.mjs, its only writer. The package builds with plain
 // tsc (rootDir: src), so src/ cannot import ../package.json; version.test.ts keeps the two equal.
-export const CANOPYCMS_VERSION = '0.0.68-int.94';
+export const CANOPYCMS_VERSION = '0.0.68-int.96';

package/dist/worker/cms-worker.d.ts

@@ -15,11 +15,11 @@ export type AuthCacheRefresher = () => Promise<void>;
  * interface for the two shapes and why an App is optional.
  */
 export interface CmsWorkerConfig extends GitHubAuthConfig {
-    /** Path to workspace root on EFS (e.g., /mnt/efs/workspace) */
+    /** Path to workspace root on EFS (e.g., /mnt/efs) */
     workspacePath: string;
-    /** GitHub owner (e.g., 'safeinsights') */
+    /** GitHub owner (e.g., 'acme') */
     githubOwner: string;
-    /** GitHub repo name (e.g., 'docs-site') */
+    /** GitHub repo name (e.g., 'site') */
     githubRepo: string;
     /** Called periodically to update the auth metadata cache on EFS. */
     refreshAuthCache?: AuthCacheRefresher;

package/dist/worker/git-sync.d.ts

@@ -15,7 +15,7 @@ import type { WorkerContext } from './worker-context.js';
  *
  * One ordering is load-bearing and nothing enforces it: `runRebaseCycle` MUST
  * follow `reconcileTrackedBranches`. Branch clones fetch the base tip from
- * `remote.git` (`origin`), and `reconcileTrackedBranches` is what advances
+ * `remote.git`, and `reconcileTrackedBranches` is what advances
  * `remote.git`'s `refs/heads/*` toward what the fetch above put in the tracking
  * namespace; reorder them and every branch rebases onto the PREVIOUS cycle's
  * base tip -- not corrupting, but silently a cycle behind.
@@ -51,7 +51,7 @@ export declare function syncGit(ctx: GitSyncContext): Promise<void>;
 export declare function cleanupTrashedBranchDirs(ctx: Pick<GitSyncContext, 'contentBranchesPath'>): Promise<number>;
 /**
  * Fast-forward the base branch's own working-tree clone
- * (content-branches/<baseBranch>) to match origin/<baseBranch>, every sync
+ * (content-branches/<baseBranch>) to match remote.git's <baseBranch>, every sync
  * cycle, so the drift window is bounded by gitSyncInterval.
  *
  * A dedicated, explicit and LOUD step rather than a side effect of the rebase
@@ -60,8 +60,8 @@ export declare function cleanupTrashedBranchDirs(ctx: Pick<GitSyncContext, 'cont
  * new branch "from base" silently gets a stale snapshot. The returned outcome
  * goes to worker-status.json for the same reason.
  *
- * ff-only on purpose: this clone must stay a linear mirror of
- * origin/<baseBranch>, so a merge that isn't a fast-forward (diverged local
+ * ff-only on purpose: this clone must stay a linear mirror of remote.git's
+ * <baseBranch>, so a merge that isn't a fast-forward (diverged local
  * history) is left untouched rather than force-resolved.
  *
  * Holds the provisioning lock and then, like the rebase loop, the [SYNC-C1]

package/dist/worker/git-sync.js

@@ -409,7 +409,7 @@ export async function cleanupTrashedBranchDirs(ctx) {
 const warnedTrackedCanopyState = new Set();
 /**
  * Fast-forward the base branch's own working-tree clone
- * (content-branches/<baseBranch>) to match origin/<baseBranch>, every sync
+ * (content-branches/<baseBranch>) to match remote.git's <baseBranch>, every sync
  * cycle, so the drift window is bounded by gitSyncInterval.
  *
  * A dedicated, explicit and LOUD step rather than a side effect of the rebase
@@ -418,8 +418,8 @@ const warnedTrackedCanopyState = new Set();
  * new branch "from base" silently gets a stale snapshot. The returned outcome
  * goes to worker-status.json for the same reason.
  *
- * ff-only on purpose: this clone must stay a linear mirror of
- * origin/<baseBranch>, so a merge that isn't a fast-forward (diverged local
+ * ff-only on purpose: this clone must stay a linear mirror of remote.git's
+ * <baseBranch>, so a merge that isn't a fast-forward (diverged local
  * history) is left untouched rather than force-resolved.
  *
  * Holds the provisioning lock and then, like the rebase loop, the [SYNC-C1]
@@ -523,15 +523,13 @@ export async function refreshBaseBranchWorkspace(ctx) {
             };
         }
         // Raw (unsanitized) name from here on: these are git ref operations
-        // against origin/<baseBranch>, not filesystem paths, so they must use
+        // against remote.git's <baseBranch>, not filesystem paths, so they must use
         // the same name GitHub knows the branch by.
-        await baseGit.fetch('origin', ctx.baseBranch);
+        await baseGit.fetch(ctx.remoteGitPath, ctx.baseBranch);
         // rev-list, not status.behind, which needs an upstream tracking branch that
-        // is not guaranteed here. Against the just-fetched tip rather than
-        // origin/<base>: workspaces are cloned --single-branch (git-manager.ts), so
-        // for any other base branch origin/<base> never exists and rev-list dies
-        // with "ambiguous argument". Pin FETCH_HEAD to a SHA immediately -- it is
-        // one shared mutable file per repo, silently repointed by any other fetch.
+        // is not guaranteed here. Against the just-fetched tip: a fetch by path
+        // updates no remote-tracking ref. Pin FETCH_HEAD to a SHA immediately -- it
+        // is one shared mutable file per repo, silently repointed by any other fetch.
         const fetchedTip = (await baseGit.revparse(['FETCH_HEAD'])).trim();
         const behindCount = parseInt((await baseGit.raw(['rev-list', '--count', `HEAD..${fetchedTip}`])).trim(), 10);
         if (behindCount > 0) {

package/dist/worker/history-rewrite.d.ts

@@ -72,7 +72,7 @@ export declare function clearHistoryRewrittenMarker(ctx: Pick<HistoryRewriteCont
  * Returns whether the push landed. A refused lease means a concurrent Lambda
  * push moved the ref; logged and retried by the self-heal pass, never thrown.
  */
-export declare function forcePublishToLocalRemote(ctx: Pick<HistoryRewriteContext, 'taskTimeoutMs'>, branchPath: string, branchRef: string, expectedSha: string): Promise<boolean>;
+export declare function forcePublishToLocalRemote(ctx: Pick<HistoryRewriteContext, 'remoteGitPath' | 'taskTimeoutMs'>, branchPath: string, branchRef: string, expectedSha: string): Promise<boolean>;
 /**
  * Queue the GitHub hop for a branch whose rewritten history now sits in
  * `remote.git`, so an open PR's head follows the rebase within a cycle instead

package/dist/worker/history-rewrite.js

@@ -108,7 +108,7 @@ export async function forcePublishToLocalRemote(ctx, branchPath, branchRef, expe
             // Real flags must precede --end-of-options; everything after it is
             // positional (see GitManager.push() for the same guard).
             '--end-of-options',
-            'origin',
+            ctx.remoteGitPath,
             `${branchRef}:${branchRef}`,
         ]);
         workerLog(`  Published rebased ${branchRef} into remote.git`);

package/dist/worker/rebase.js

@@ -162,8 +162,8 @@ async function runRebaseRounds(ctx, branchGit, branchDir, fetchedBaseTip, isLock
             break;
         try {
             if (nextAction === 'start') {
-                // The pinned base tip fetched above (single-branch clones have
-                // no origin/<base> remote-tracking ref for other branches).
+                // The pinned base tip fetched above; a fetch by path updates no
+                // remote-tracking ref.
                 await branchGit.rebase([fetchedBaseTip]);
             }
             else if (nextAction === 'continue') {
@@ -638,7 +638,7 @@ async function rebaseOneBranch(ctx, branchDir, branchPath, isProvisioningLockCom
             // the bytes stay untouched, and the wedge is recorded for an operator.
             const trackedState = trackedCanopyStateChanges(dirtyCheck);
             if (trackedState.length > 0) {
-                await branchGit.fetch('origin', ctx.baseBranch);
+                await branchGit.fetch(ctx.remoteGitPath, ctx.baseBranch);
                 const baseTip = (await branchGit.revparse(['FETCH_HEAD'])).trim();
                 const { stillTracked } = await splitByUpstreamTracking(branchGit, trackedState, baseTip);
                 const reason = stillTracked.length > 0
@@ -672,14 +672,12 @@ async function rebaseOneBranch(ctx, branchDir, branchPath, isProvisioningLockCom
                     marker: metaFile.branch.historyRewrittenFrom,
                 });
             }
-            await branchGit.fetch('origin', ctx.baseBranch);
+            await branchGit.fetch(ctx.remoteGitPath, ctx.baseBranch);
             // rev-list, not status.behind, which needs an upstream tracking branch
             // that checkoutBranch's fallback paths do not always configure. Against
-            // the just-fetched tip, not origin/<base>: branch clones are
-            // --single-branch, so no remote-tracking ref exists for any base branch
-            // other than the one they were cloned from. Pinned to a SHA immediately
-            // — FETCH_HEAD is one shared mutable file per repo, repointed by any
-            // concurrent fetch.
+            // the just-fetched tip: a fetch by path updates no remote-tracking ref.
+            // Pinned to a SHA immediately — FETCH_HEAD is one shared mutable file per
+            // repo, repointed by any concurrent fetch.
             const fetchedBaseTip = (await branchGit.revparse(['FETCH_HEAD'])).trim();
             const behindCount = parseInt((await branchGit.raw(['rev-list', '--count', `HEAD..${fetchedBaseTip}`])).trim(), 10);
             const meta = getBranchMetadataFileManager(branchPath, ctx.contentBranchesPath);

package/dist/worker/worker-context.d.ts

@@ -38,7 +38,12 @@ export interface WorkerContext {
     readonly sanitizedBaseBranch: SanitizedBranchName;
     /** `{workspacePath}/.tasks` — the task queue and worker-status.json. */
     readonly taskDir: string;
-    /** `{workspacePath}/remote.git` — the shared bare repo. */
+    /**
+     * `{workspacePath}/remote.git` — the shared bare repo. The worker fetches
+     * into and pushes from a workspace clone against this path, never the
+     * clone's `origin`: that holds the path the CLONING process saw (usually
+     * the Lambda), and the clone's config is Lambda-writable.
+     */
     readonly remoteGitPath: string;
     /** `{workspacePath}/content-branches` — the branch workspace root. */
     readonly contentBranchesPath: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@codemirror/language, @lezer/highlight: workaround — @mdxeditor/editor uses cm6-theme-basic-light which peer-requires these but mdxeditor doesn't declare them as dependencies",
   "name": "canopycms",
-  "version": "0.0.68-int.94",
+  "version": "0.0.68-int.96",
   "description": "CanopyCMS core package: schema-driven content, branch-aware editing, and editor UI for Next.js.",
   "license": "MIT",
   "repository": {