@netlisian/softconfig 0.1.6 → 0.1.8

package/dist/puck/index.css

@@ -1,4 +1,4 @@
-/* css-module:/media/manual_mount/osamuProjects/netlisian/packages/soft-config/src/puck/components/error-boundary/styles.module.css/#css-module-data */
+/* css-module:/home/osamu/Documents/netlisian-soft/packages/soft-config/src/puck/components/error-boundary/styles.module.css/#css-module-data */
 ._ErrorBoundary_1xl05_5 {
   padding: 20px;
   border: 1px solid #ff5858;
@@ -26,7 +26,7 @@
   background-color: #b71c1c;
 }
 
-/* css-module:/media/manual_mount/osamuProjects/netlisian/packages/soft-config/src/puck/overrides/Header.module.css/#css-module-data */
+/* css-module:/home/osamu/Documents/netlisian-soft/packages/soft-config/src/puck/overrides/Header.module.css/#css-module-data */
 ._Header_19oj9_1 {
   display: flex;
   justify-content: space-between;
@@ -35,7 +35,7 @@
   flex-wrap: wrap;
 }
 
-/* css-module:/media/manual_mount/osamuProjects/netlisian/packages/soft-config/src/puck/overrides/ActionBar.module.css/#css-module-data */
+/* css-module:/home/osamu/Documents/netlisian-soft/packages/soft-config/src/puck/overrides/ActionBar.module.css/#css-module-data */
 ._ActionBar_pvuie_5 {
   align-items: center;
   cursor: default;
@@ -119,7 +119,7 @@
   margin: 0;
 }
 
-/* css-module:/media/manual_mount/osamuProjects/netlisian/packages/soft-config/src/puck/overrides/DrawerItem.module.css/#css-module-data */
+/* css-module:/home/osamu/Documents/netlisian-soft/packages/soft-config/src/puck/overrides/DrawerItem.module.css/#css-module-data */
 ._DrawerItem_182aj_1 {
   background: var(--puck-color-white);
   cursor: grab;
@@ -343,7 +343,7 @@
   gap: 12px;
 }
 
-/* css-module:/media/manual_mount/osamuProjects/netlisian/packages/soft-config/src/puck/components/modal/styles.module.css/#css-module-data */
+/* css-module:/home/osamu/Documents/netlisian-soft/packages/soft-config/src/puck/components/modal/styles.module.css/#css-module-data */
 ._Modal_1t9ot_1 {
   background: color-mix(in srgb, var(--puck-color-black) 75%, transparent);
   display: none;
@@ -372,7 +372,7 @@
   min-height: 0;
 }
 
-/* css-module:/media/manual_mount/osamuProjects/netlisian/packages/soft-config/src/puck/overrides/Drawer.module.css/#css-module-data */
+/* css-module:/home/osamu/Documents/netlisian-soft/packages/soft-config/src/puck/overrides/Drawer.module.css/#css-module-data */
 ._Drawer_12zq5_1 {
   display: flex;
   flex-direction: column;

package/dist/puck/index.d.mts

@@ -1,7 +1,7 @@
 import * as zustand from 'zustand';
 import { StoreApi } from 'zustand';
 import * as _measured_puck from '@measured/puck';
-import { Field, Fields, Config, DefaultComponentProps, History, AppState, PuckApi, ComponentData, ComponentConfig, RootData, AsFieldProps, WithChildren, Metadata, ResolveDataTrigger, PuckAction, Data } from '@measured/puck';
+import { Field, Fields, Config, DefaultComponentProps, History, AppState, PuckApi, ComponentData, ComponentConfig, RootData, AsFieldProps, WithChildren, Metadata, ResolveDataTrigger, PuckAction, Data, Overrides as Overrides$1 } from '@measured/puck';
 import * as React$1 from 'react';
 import React__default, { ReactNode, ReactElement } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
@@ -304,12 +304,12 @@ type RenderFunc<Props extends Record<string, unknown> = {
     children: ReactNode;
 }> = (props: Props) => ReactElement;
 type Overrides = {
-    componentNameToKey?: (displayName: string, context: Partial<BuilderRootConfig> & {
+    componentLabelToName?: (label: string, context: Partial<BuilderRootConfig> & {
         existingKeys: string[];
         state: "building" | "remodeling" | "ready" | "inspecting";
     }) => string;
-    componentKeyToName?: (key: string) => string;
-    onRemodel?: (key: string) => Record<string, unknown>;
+    componentNameToLabel?: (name: string) => string;
+    onRemodel?: (name: string) => Record<string, unknown>;
     additionalRootFields?: Record<string, Field>;
     map?: RenderFunc<{
         rootProps: BuilderRootConfig;
@@ -342,90 +342,164 @@ type Overrides = {
         props: RootData<AsFieldProps<WithChildren<BuilderRootConfig>>> | Promise<RootData<AsFieldProps<WithChildren<BuilderRootConfig>>>>;
         readOnly: Readonly<Record<string, boolean>> | undefined;
     };
-    mapComponentConfig?: (componentName: string, defaultConfig: ComponentConfig) => Partial<ComponentConfig>;
+    mapComponentConfig?: (componentName: string, defaultConfig: ComponentConfig, rootProps: BuilderRootConfig & RootData) => ComponentConfig;
 };
 
+/** Represents the current editing mode of the Puck editor. */
 type Status = "building" | "remodeling" | "ready" | "inspecting";
 type AppStore = {
+    /** The current merged Puck config (hard + soft components). Rebuilt on soft component changes. */
     softConfig: Config;
+    /** Flat map of all registered soft components, keyed by component name. */
     softComponents: SoftComponents;
+    /**
+     * Soft components after `hydrateMapTransform` has been applied.
+     * Only populated when `overrides.hydrateMapTransform` is provided.
+     */
     hydratedSoftComponents?: SoftComponents;
+    /** The current editing mode. Controls which components can be mutated. */
     state: Status;
+    /** Snapshot of Puck history entries saved before an editing session starts. */
     originalHistory: History[];
+    /** A stored copy of the Puck config, used for rollback scenarios. */
     storedConfig?: Config;
+    /** Lifecycle and rendering overrides forwarded from the SoftConfigProvider. */
     overrides: Overrides;
+    /** Custom field definitions to extend the built-in Puck field types. */
     customFields: CustomFields;
+    /**
+     * Callback fired on every Puck action dispatch.
+     * Gives consumers a hook to react to drag-and-drop, insert, remove, etc.
+     */
     onActions?: OnActionsCallback;
+    /** The currently selected component in the Puck canvas, or null if none. */
     itemSelector: {
         index: number;
         zone: string;
     } | null;
+    /** Update or clear the active item selection. */
     setItemSelector: (selector: {
         index: number;
         zone: string;
     } | null) => void;
+    /** Snapshot of the selected component's props before any edits began. Used for cancel/rollback. */
     originalItem: DefaultComponentProps | null;
+    /** Persist the pre-edit props snapshot for the active item. */
     setOriginalItem: (item: DefaultComponentProps | null) => void;
+    /** Persist the full Puck history stack (called when entering an editing session). */
     storeHistory: (history: History[]) => void;
+    /** Clear the stored history (called when an editing session completes or cancels). */
     removeHistory: () => void;
+    /**
+     * Register or update a single soft component's Puck config.
+     * Optionally assigns the component to a Puck category.
+     */
     setSoftComponentConfig: (key: string, config: ComponentConfig, category?: string) => void;
+    /** Remove a soft component's Puck config entry by key. */
     removeSoftComponentConfig: (key: string) => void;
+    /**
+     * Delete a specific version of a soft component.
+     * If the deleted version was the default, promotes the most recent remaining version.
+     */
     removeSoftComponentVersion: (key: string, version: string) => void;
+    /** Register or update a Puck category (visibility, expansion, membership). */
     setSoftCategoryConfig: (key: string, category: {
         components?: string[];
         visible?: boolean;
         defaultExpanded?: boolean;
         title?: string;
     }) => void;
+    /** Remove a Puck category entry by key. */
     removeSoftCategoryConfig: (key: string) => void;
+    /** Builder sub-slice — handles multi-step build/remodel workflows. */
     builder: BuildersSlice;
+    /**
+     * Upsert a single version of a soft component.
+     * Creates the component entry if it doesn't already exist.
+     */
     setSoftComponent: (key: string, version: string, component: SoftComponent) => void;
+    /**
+     * Batch-upsert multiple soft components at once.
+     * Merges incoming versions with any existing versions for each component.
+     */
     setSoftComponents: (components: SoftComponents) => void;
+    /**
+     * Re-apply `overrides.hydrateMapTransform` to the current soft components.
+     * Call this when the transform function or its dependencies change at runtime.
+     */
     hydrateTransforms: () => void;
+    /**
+     * Promote a specific version of a soft component to be the active/default version.
+     * Rebuilds the Puck config entry for that component.
+     */
     setSoftComponentDefaultVersion: (key: string, version: string) => void;
+    /** Completely remove a soft component and all its versions from the store. */
     removeSoftComponent: (key: string) => void;
+    /** Name of the component type currently being edited (e.g. "Hero"), or null. */
     editingComponent: string | null;
+    /** Instance ID of the component currently being edited in the Puck canvas, or null. */
     editingComponentId: string | null;
+    /**
+     * Set of component instance IDs the user is allowed to mutate in the current session.
+     * Populated when entering "building" or "remodeling" state.
+     */
     editableComponentIds: Set<string>;
+    /** Overwrite the entire set of editable component IDs. */
     setEditableComponentIds: (ids: Set<string>) => void;
+    /** Append a single component instance ID to the editable set. */
     addEditableComponentId: (id: string) => void;
+    /** Reset editing state: clears editingComponentId and editableComponentIds. */
     clearEditingState: () => void;
     /**
-     * Reverse dependency graph: componentName -> Set of components that depend on it
-     * Used to efficiently rebuild dependent components when a soft component is updated
+     * Reverse dependency graph: componentName → Set of component names that depend on it.
+     * Built once on store creation and updated when components change.
+     * Used to efficiently cascade Puck config rebuilds to affected dependents.
      */
     dependencyGraph: Map<string, Set<string>>;
     /**
-     * Rebuild all dependent components after a soft component is updated
-     * Only rebuilds components that depend on the changed component
+     * Rebuild the Puck config entries for every component that depends on the given one.
+     * Should be called after a soft component's render or schema changes.
      *
-     * @param componentName - The component that was updated
-     * @param version - The version that was updated
+     * @param componentName - The component that was updated.
+     * @param version - The version that changed (for future granular diffing).
      */
     rebuildDependents: (componentName: string, version: string) => void;
     /**
-     * Iframe document reference for applying styling and edit visibility
-     * Stored as a mutable ref to avoid triggering store updates.
+     * Mutable ref holding the Puck iframe's Document.
+     * Stored as a ref object to mutate without triggering Zustand subscribers.
      */
-    iframeDocRef: {
-        current: Document | null;
-    };
-    /**
-     * Get the current iframe document reference
-     */
-    getIframeDoc: () => Document | null;
+    iframeDoc: Document | null;
     /**
-     * Set the iframe document reference without causing re-renders
+     * Point the store at a new iframe Document.
+     * Immediately applies or clears edit-visibility CSS based on the current state.
      */
     setIframeDoc: (doc: Document | null) => void;
     /**
-     * Flag to control visibility of version config fields
+     * When true, version-selection fields are shown in the Puck sidebar.
+     * Defaults to true; set to false to hide version controls from end users.
      */
     showVersionFields: boolean;
+    /** Toggle the visibility of version-selection fields in the Puck sidebar. */
+    setShowVersionFields: (show: boolean) => void;
     /**
-     * Toggle the visibility of version config fields
+     * Reference to Puck's `history.back` function, injected by the UndoSync
+     * component that lives inside the ActionBar override.
+     * Null until the Puck editor mounts and ActionBar renders.
      */
-    setShowVersionFields: (show: boolean) => void;
+    undoFn: (() => void) | null;
+    /**
+     * Called by UndoSync (inside the Puck tree) to register the live undo function.
+     * Must be called once per editor mount so `validateAction` can trigger rollbacks.
+     */
+    setUndoFn: (fn: () => void) => void;
+    /**
+     * Guard function passed to Puck's `onAction` via `createActionCallback`.
+     * Returns false for any action that targets a component outside the current
+     * editable set, which causes `createActionCallback` to immediately undo it.
+     *
+     * Always returns true when `state === "ready"` (no restrictions apply).
+     */
+    validateAction: (action: PuckAction, previousAction?: PuckAction) => boolean;
 };
 type AppStoreApi = StoreApi<AppStore>;
 declare const createSoftConfigStore: (hardConfig?: Config, softComponents?: SoftComponents, overrides?: Overrides, onActions?: OnActionsCallback, showVersionFields?: boolean, customFields?: CustomFields) => zustand.UseBoundStore<Omit<StoreApi<AppStore>, "subscribe"> & {
@@ -438,10 +512,27 @@ declare const createSoftConfigStore: (hardConfig?: Config, softComponents?: Soft
     };
 }>;
 
+/**
+ * SoftConfigProvider is responsible for providing the soft config context to the Puck editor.
+ *
+ * @param props - The component props.
+ * @param props.children - A render prop that receives the following arguments:
+ * - `softConfig`: The current soft configuration object.
+ * - `softComponents`: The current mapping of soft components.
+ * - `setIframeDoc`: Function to set the iframe document reference in the store. Used to apply edit visibility styles on the iframe.
+ * - `validateAction`: Function to validate actions based on current state and editable component IDs. Used to disallow editing components that are not in the editable list during "building" or "remodeling" states.
+ * @param props.hardConfig - Initial Puck Config.
+ * @param props.softComponents - Initial soft components.
+ * @param props.customFields - Custom field to allow additional field types.
+ * @param props.overrides - Soft Config overrides.
+ * @param props.value - Optional external store API.
+ * @param props.onActions - Callback triggered on Puck actions.
+ * @param props.useVersioning - Flag to enable or disable versioning (defaults to false).
+ */
 declare const SoftConfigProvider: ({ children, hardConfig, softComponents, customFields, overrides, value, onActions, useVersioning, }: {
-    children: (softConfig: Config, softComponents: SoftComponents, iframeDoc: AppStore["setIframeDoc"], validateAction: (action: PuckAction) => boolean) => ReactNode;
+    children: (softConfig: Config) => ReactNode;
     hardConfig: Config;
-    softComponents: SoftComponents;
+    softComponents?: SoftComponents;
     customFields?: CustomFields;
     overrides?: Overrides;
     value?: StoreApi<AppStore>;
@@ -451,6 +542,10 @@ declare const SoftConfigProvider: ({ children, hardConfig, softComponents, custo
 
 declare const createUseSoftConfig: () => <T>(selector: (state: AppStore) => T, equalityFn?: (a: T, b: T) => boolean) => T;
 declare const useSoftConfig: <T>(selector: (state: AppStore) => T, equalityFn?: (a: T, b: T) => boolean) => T;
+/**
+ * Access the soft config store instance without subscribing to state changes.
+ */
+declare const useSoftConfigStore: () => StoreApi<AppStore>;
 
 declare const useBuild: (name?: string) => {
     handleBuild: () => void;
@@ -491,6 +586,10 @@ declare const useCancel: () => {
     canCancel: boolean;
 };
 
+/** * Custom hook to handle inspecting a completed component in the Puck editor.
+ * @deprecated This hook is deprecated
+ * @param component - The completed component result to inspect. Should be set after completing a component.
+ */
 declare const useInspect: (component: CompletedComponentResult | null) => void;
 
 declare const useDecompose: () => {
@@ -550,6 +649,8 @@ declare const Drawer: (_props: {
     children?: React__default.ReactNode;
 }) => react_jsx_runtime.JSX.Element;
 
+declare const HeaderActions: Overrides$1["headerActions"];
+
 type NotificationHandler = (message: string, type: "error" | "success") => void;
 declare const setNotificationHandler: (handler: NotificationHandler) => void;
 declare const notify: {
@@ -577,7 +678,7 @@ declare const confirm: (message: string) => Promise<boolean>;
  * @param undo Function to undo the last action (from Puck's history)
  * @returns Action handler function
  */
-declare const createActionCallback: (validateAction: (action: PuckAction) => boolean, undo: PuckApi["history"]["back"]) => (action: PuckAction) => void;
+declare const createActionCallback: (validateAction: (action: PuckAction) => boolean, undo: PuckApi["history"]["back"] | null) => (action: PuckAction) => void;
 
 /**
  * Resolves soft components in data by dissolving them to hard components only.
@@ -645,4 +746,4 @@ declare const isArrayMappingPath: (path: string) => boolean;
 declare const getArrayBasePath: (arrayPath: string) => string | null;
 declare const getArrayItemSubPath: (arrayPath: string) => string | null;
 
-export { ActionBarOverride as ActionBar, type ActionEventPayload, type AppStore, type AppStoreApi, type ApplyMappingOptions, type ApplyMappingResult, type BuilderComponentConfig, type BuilderConfig, type BuilderRootConfig, ComponentItem, Drawer as ComponentList, type CustomFieldDefinition, type CustomFieldReturnType, type CustomFields, Drawer, DrawerItem, type FieldSettings, Header, type MapEntry, Modal, type OnActionsCallback, type Overrides, type SoftComponent, type SoftComponents, SoftConfigProvider, type SoftFieldDefinition, type SoftFieldSettings, type VersionedSoftComponent, applyMapping, confirm, createActionCallback, createSoftConfigStore, createUseSoftConfig, filterToOptionsForFrom, getArrayBasePath, getArrayItemSubPath, isArrayMappingPath, notify, resolveSoftConfig, resolveValueByPath, setConfirmHandler, setNotificationHandler, useBuild, useCancel, useComplete, useDecompose, useDemolish, useInspect, useRemodel, useSetDefaultVersion, useSoftConfig };
+export { ActionBarOverride as ActionBar, type ActionEventPayload, type AppStore, type AppStoreApi, type ApplyMappingOptions, type ApplyMappingResult, type BuilderComponentConfig, type BuilderConfig, type BuilderRootConfig, ComponentItem, Drawer as ComponentList, type CustomFieldDefinition, type CustomFieldReturnType, type CustomFields, Drawer, DrawerItem, type FieldSettings, Header, HeaderActions, type MapEntry, Modal, type OnActionsCallback, type Overrides, type SoftComponent, type SoftComponents, SoftConfigProvider, type SoftFieldDefinition, type SoftFieldSettings, type VersionedSoftComponent, applyMapping, confirm, createActionCallback, createSoftConfigStore, createUseSoftConfig, filterToOptionsForFrom, getArrayBasePath, getArrayItemSubPath, isArrayMappingPath, notify, resolveSoftConfig, resolveValueByPath, setConfirmHandler, setNotificationHandler, useBuild, useCancel, useComplete, useDecompose, useDemolish, useInspect, useRemodel, useSetDefaultVersion, useSoftConfig, useSoftConfigStore };

package/dist/puck/index.d.ts

@@ -1,7 +1,7 @@
 import * as zustand from 'zustand';
 import { StoreApi } from 'zustand';
 import * as _measured_puck from '@measured/puck';
-import { Field, Fields, Config, DefaultComponentProps, History, AppState, PuckApi, ComponentData, ComponentConfig, RootData, AsFieldProps, WithChildren, Metadata, ResolveDataTrigger, PuckAction, Data } from '@measured/puck';
+import { Field, Fields, Config, DefaultComponentProps, History, AppState, PuckApi, ComponentData, ComponentConfig, RootData, AsFieldProps, WithChildren, Metadata, ResolveDataTrigger, PuckAction, Data, Overrides as Overrides$1 } from '@measured/puck';
 import * as React$1 from 'react';
 import React__default, { ReactNode, ReactElement } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
@@ -304,12 +304,12 @@ type RenderFunc<Props extends Record<string, unknown> = {
     children: ReactNode;
 }> = (props: Props) => ReactElement;
 type Overrides = {
-    componentNameToKey?: (displayName: string, context: Partial<BuilderRootConfig> & {
+    componentLabelToName?: (label: string, context: Partial<BuilderRootConfig> & {
         existingKeys: string[];
         state: "building" | "remodeling" | "ready" | "inspecting";
     }) => string;
-    componentKeyToName?: (key: string) => string;
-    onRemodel?: (key: string) => Record<string, unknown>;
+    componentNameToLabel?: (name: string) => string;
+    onRemodel?: (name: string) => Record<string, unknown>;
     additionalRootFields?: Record<string, Field>;
     map?: RenderFunc<{
         rootProps: BuilderRootConfig;
@@ -342,90 +342,164 @@ type Overrides = {
         props: RootData<AsFieldProps<WithChildren<BuilderRootConfig>>> | Promise<RootData<AsFieldProps<WithChildren<BuilderRootConfig>>>>;
         readOnly: Readonly<Record<string, boolean>> | undefined;
     };
-    mapComponentConfig?: (componentName: string, defaultConfig: ComponentConfig) => Partial<ComponentConfig>;
+    mapComponentConfig?: (componentName: string, defaultConfig: ComponentConfig, rootProps: BuilderRootConfig & RootData) => ComponentConfig;
 };
 
+/** Represents the current editing mode of the Puck editor. */
 type Status = "building" | "remodeling" | "ready" | "inspecting";
 type AppStore = {
+    /** The current merged Puck config (hard + soft components). Rebuilt on soft component changes. */
     softConfig: Config;
+    /** Flat map of all registered soft components, keyed by component name. */
     softComponents: SoftComponents;
+    /**
+     * Soft components after `hydrateMapTransform` has been applied.
+     * Only populated when `overrides.hydrateMapTransform` is provided.
+     */
     hydratedSoftComponents?: SoftComponents;
+    /** The current editing mode. Controls which components can be mutated. */
     state: Status;
+    /** Snapshot of Puck history entries saved before an editing session starts. */
     originalHistory: History[];
+    /** A stored copy of the Puck config, used for rollback scenarios. */
     storedConfig?: Config;
+    /** Lifecycle and rendering overrides forwarded from the SoftConfigProvider. */
     overrides: Overrides;
+    /** Custom field definitions to extend the built-in Puck field types. */
     customFields: CustomFields;
+    /**
+     * Callback fired on every Puck action dispatch.
+     * Gives consumers a hook to react to drag-and-drop, insert, remove, etc.
+     */
     onActions?: OnActionsCallback;
+    /** The currently selected component in the Puck canvas, or null if none. */
     itemSelector: {
         index: number;
         zone: string;
     } | null;
+    /** Update or clear the active item selection. */
     setItemSelector: (selector: {
         index: number;
         zone: string;
     } | null) => void;
+    /** Snapshot of the selected component's props before any edits began. Used for cancel/rollback. */
     originalItem: DefaultComponentProps | null;
+    /** Persist the pre-edit props snapshot for the active item. */
     setOriginalItem: (item: DefaultComponentProps | null) => void;
+    /** Persist the full Puck history stack (called when entering an editing session). */
     storeHistory: (history: History[]) => void;
+    /** Clear the stored history (called when an editing session completes or cancels). */
     removeHistory: () => void;
+    /**
+     * Register or update a single soft component's Puck config.
+     * Optionally assigns the component to a Puck category.
+     */
     setSoftComponentConfig: (key: string, config: ComponentConfig, category?: string) => void;
+    /** Remove a soft component's Puck config entry by key. */
     removeSoftComponentConfig: (key: string) => void;
+    /**
+     * Delete a specific version of a soft component.
+     * If the deleted version was the default, promotes the most recent remaining version.
+     */
     removeSoftComponentVersion: (key: string, version: string) => void;
+    /** Register or update a Puck category (visibility, expansion, membership). */
     setSoftCategoryConfig: (key: string, category: {
         components?: string[];
         visible?: boolean;
         defaultExpanded?: boolean;
         title?: string;
     }) => void;
+    /** Remove a Puck category entry by key. */
     removeSoftCategoryConfig: (key: string) => void;
+    /** Builder sub-slice — handles multi-step build/remodel workflows. */
     builder: BuildersSlice;
+    /**
+     * Upsert a single version of a soft component.
+     * Creates the component entry if it doesn't already exist.
+     */
     setSoftComponent: (key: string, version: string, component: SoftComponent) => void;
+    /**
+     * Batch-upsert multiple soft components at once.
+     * Merges incoming versions with any existing versions for each component.
+     */
     setSoftComponents: (components: SoftComponents) => void;
+    /**
+     * Re-apply `overrides.hydrateMapTransform` to the current soft components.
+     * Call this when the transform function or its dependencies change at runtime.
+     */
     hydrateTransforms: () => void;
+    /**
+     * Promote a specific version of a soft component to be the active/default version.
+     * Rebuilds the Puck config entry for that component.
+     */
     setSoftComponentDefaultVersion: (key: string, version: string) => void;
+    /** Completely remove a soft component and all its versions from the store. */
     removeSoftComponent: (key: string) => void;
+    /** Name of the component type currently being edited (e.g. "Hero"), or null. */
     editingComponent: string | null;
+    /** Instance ID of the component currently being edited in the Puck canvas, or null. */
     editingComponentId: string | null;
+    /**
+     * Set of component instance IDs the user is allowed to mutate in the current session.
+     * Populated when entering "building" or "remodeling" state.
+     */
     editableComponentIds: Set<string>;
+    /** Overwrite the entire set of editable component IDs. */
     setEditableComponentIds: (ids: Set<string>) => void;
+    /** Append a single component instance ID to the editable set. */
     addEditableComponentId: (id: string) => void;
+    /** Reset editing state: clears editingComponentId and editableComponentIds. */
     clearEditingState: () => void;
     /**
-     * Reverse dependency graph: componentName -> Set of components that depend on it
-     * Used to efficiently rebuild dependent components when a soft component is updated
+     * Reverse dependency graph: componentName → Set of component names that depend on it.
+     * Built once on store creation and updated when components change.
+     * Used to efficiently cascade Puck config rebuilds to affected dependents.
      */
     dependencyGraph: Map<string, Set<string>>;
     /**
-     * Rebuild all dependent components after a soft component is updated
-     * Only rebuilds components that depend on the changed component
+     * Rebuild the Puck config entries for every component that depends on the given one.
+     * Should be called after a soft component's render or schema changes.
      *
-     * @param componentName - The component that was updated
-     * @param version - The version that was updated
+     * @param componentName - The component that was updated.
+     * @param version - The version that changed (for future granular diffing).
      */
     rebuildDependents: (componentName: string, version: string) => void;
     /**
-     * Iframe document reference for applying styling and edit visibility
-     * Stored as a mutable ref to avoid triggering store updates.
+     * Mutable ref holding the Puck iframe's Document.
+     * Stored as a ref object to mutate without triggering Zustand subscribers.
      */
-    iframeDocRef: {
-        current: Document | null;
-    };
-    /**
-     * Get the current iframe document reference
-     */
-    getIframeDoc: () => Document | null;
+    iframeDoc: Document | null;
     /**
-     * Set the iframe document reference without causing re-renders
+     * Point the store at a new iframe Document.
+     * Immediately applies or clears edit-visibility CSS based on the current state.
      */
     setIframeDoc: (doc: Document | null) => void;
     /**
-     * Flag to control visibility of version config fields
+     * When true, version-selection fields are shown in the Puck sidebar.
+     * Defaults to true; set to false to hide version controls from end users.
      */
     showVersionFields: boolean;
+    /** Toggle the visibility of version-selection fields in the Puck sidebar. */
+    setShowVersionFields: (show: boolean) => void;
     /**
-     * Toggle the visibility of version config fields
+     * Reference to Puck's `history.back` function, injected by the UndoSync
+     * component that lives inside the ActionBar override.
+     * Null until the Puck editor mounts and ActionBar renders.
      */
-    setShowVersionFields: (show: boolean) => void;
+    undoFn: (() => void) | null;
+    /**
+     * Called by UndoSync (inside the Puck tree) to register the live undo function.
+     * Must be called once per editor mount so `validateAction` can trigger rollbacks.
+     */
+    setUndoFn: (fn: () => void) => void;
+    /**
+     * Guard function passed to Puck's `onAction` via `createActionCallback`.
+     * Returns false for any action that targets a component outside the current
+     * editable set, which causes `createActionCallback` to immediately undo it.
+     *
+     * Always returns true when `state === "ready"` (no restrictions apply).
+     */
+    validateAction: (action: PuckAction, previousAction?: PuckAction) => boolean;
 };
 type AppStoreApi = StoreApi<AppStore>;
 declare const createSoftConfigStore: (hardConfig?: Config, softComponents?: SoftComponents, overrides?: Overrides, onActions?: OnActionsCallback, showVersionFields?: boolean, customFields?: CustomFields) => zustand.UseBoundStore<Omit<StoreApi<AppStore>, "subscribe"> & {
@@ -438,10 +512,27 @@ declare const createSoftConfigStore: (hardConfig?: Config, softComponents?: Soft
     };
 }>;
 
+/**
+ * SoftConfigProvider is responsible for providing the soft config context to the Puck editor.
+ *
+ * @param props - The component props.
+ * @param props.children - A render prop that receives the following arguments:
+ * - `softConfig`: The current soft configuration object.
+ * - `softComponents`: The current mapping of soft components.
+ * - `setIframeDoc`: Function to set the iframe document reference in the store. Used to apply edit visibility styles on the iframe.
+ * - `validateAction`: Function to validate actions based on current state and editable component IDs. Used to disallow editing components that are not in the editable list during "building" or "remodeling" states.
+ * @param props.hardConfig - Initial Puck Config.
+ * @param props.softComponents - Initial soft components.
+ * @param props.customFields - Custom field to allow additional field types.
+ * @param props.overrides - Soft Config overrides.
+ * @param props.value - Optional external store API.
+ * @param props.onActions - Callback triggered on Puck actions.
+ * @param props.useVersioning - Flag to enable or disable versioning (defaults to false).
+ */
 declare const SoftConfigProvider: ({ children, hardConfig, softComponents, customFields, overrides, value, onActions, useVersioning, }: {
-    children: (softConfig: Config, softComponents: SoftComponents, iframeDoc: AppStore["setIframeDoc"], validateAction: (action: PuckAction) => boolean) => ReactNode;
+    children: (softConfig: Config) => ReactNode;
     hardConfig: Config;
-    softComponents: SoftComponents;
+    softComponents?: SoftComponents;
     customFields?: CustomFields;
     overrides?: Overrides;
     value?: StoreApi<AppStore>;
@@ -451,6 +542,10 @@ declare const SoftConfigProvider: ({ children, hardConfig, softComponents, custo
 
 declare const createUseSoftConfig: () => <T>(selector: (state: AppStore) => T, equalityFn?: (a: T, b: T) => boolean) => T;
 declare const useSoftConfig: <T>(selector: (state: AppStore) => T, equalityFn?: (a: T, b: T) => boolean) => T;
+/**
+ * Access the soft config store instance without subscribing to state changes.
+ */
+declare const useSoftConfigStore: () => StoreApi<AppStore>;
 
 declare const useBuild: (name?: string) => {
     handleBuild: () => void;
@@ -491,6 +586,10 @@ declare const useCancel: () => {
     canCancel: boolean;
 };
 
+/** * Custom hook to handle inspecting a completed component in the Puck editor.
+ * @deprecated This hook is deprecated
+ * @param component - The completed component result to inspect. Should be set after completing a component.
+ */
 declare const useInspect: (component: CompletedComponentResult | null) => void;
 
 declare const useDecompose: () => {
@@ -550,6 +649,8 @@ declare const Drawer: (_props: {
     children?: React__default.ReactNode;
 }) => react_jsx_runtime.JSX.Element;
 
+declare const HeaderActions: Overrides$1["headerActions"];
+
 type NotificationHandler = (message: string, type: "error" | "success") => void;
 declare const setNotificationHandler: (handler: NotificationHandler) => void;
 declare const notify: {
@@ -577,7 +678,7 @@ declare const confirm: (message: string) => Promise<boolean>;
  * @param undo Function to undo the last action (from Puck's history)
  * @returns Action handler function
  */
-declare const createActionCallback: (validateAction: (action: PuckAction) => boolean, undo: PuckApi["history"]["back"]) => (action: PuckAction) => void;
+declare const createActionCallback: (validateAction: (action: PuckAction) => boolean, undo: PuckApi["history"]["back"] | null) => (action: PuckAction) => void;
 
 /**
  * Resolves soft components in data by dissolving them to hard components only.
@@ -645,4 +746,4 @@ declare const isArrayMappingPath: (path: string) => boolean;
 declare const getArrayBasePath: (arrayPath: string) => string | null;
 declare const getArrayItemSubPath: (arrayPath: string) => string | null;
 
-export { ActionBarOverride as ActionBar, type ActionEventPayload, type AppStore, type AppStoreApi, type ApplyMappingOptions, type ApplyMappingResult, type BuilderComponentConfig, type BuilderConfig, type BuilderRootConfig, ComponentItem, Drawer as ComponentList, type CustomFieldDefinition, type CustomFieldReturnType, type CustomFields, Drawer, DrawerItem, type FieldSettings, Header, type MapEntry, Modal, type OnActionsCallback, type Overrides, type SoftComponent, type SoftComponents, SoftConfigProvider, type SoftFieldDefinition, type SoftFieldSettings, type VersionedSoftComponent, applyMapping, confirm, createActionCallback, createSoftConfigStore, createUseSoftConfig, filterToOptionsForFrom, getArrayBasePath, getArrayItemSubPath, isArrayMappingPath, notify, resolveSoftConfig, resolveValueByPath, setConfirmHandler, setNotificationHandler, useBuild, useCancel, useComplete, useDecompose, useDemolish, useInspect, useRemodel, useSetDefaultVersion, useSoftConfig };
+export { ActionBarOverride as ActionBar, type ActionEventPayload, type AppStore, type AppStoreApi, type ApplyMappingOptions, type ApplyMappingResult, type BuilderComponentConfig, type BuilderConfig, type BuilderRootConfig, ComponentItem, Drawer as ComponentList, type CustomFieldDefinition, type CustomFieldReturnType, type CustomFields, Drawer, DrawerItem, type FieldSettings, Header, HeaderActions, type MapEntry, Modal, type OnActionsCallback, type Overrides, type SoftComponent, type SoftComponents, SoftConfigProvider, type SoftFieldDefinition, type SoftFieldSettings, type VersionedSoftComponent, applyMapping, confirm, createActionCallback, createSoftConfigStore, createUseSoftConfig, filterToOptionsForFrom, getArrayBasePath, getArrayItemSubPath, isArrayMappingPath, notify, resolveSoftConfig, resolveValueByPath, setConfirmHandler, setNotificationHandler, useBuild, useCancel, useComplete, useDecompose, useDemolish, useInspect, useRemodel, useSetDefaultVersion, useSoftConfig, useSoftConfigStore };