@dragcraft/core 0.0.1

package/dist/index.d.mts

@@ -0,0 +1,840 @@
+import { Ref, ShallowRef } from "vue";
+//#region src/types.d.ts
+type DeepReadonly<T> = T extends ((...args: infer Args) => infer Result) ? (...args: Args) => Result : T extends readonly unknown[] ? { readonly [Key in keyof T]: DeepReadonly<T[Key]>; } : T extends object ? { readonly [Key in keyof T]: DeepReadonly<T[Key]>; } : T;
+interface SchemaNode {
+  id: string;
+  type: string;
+  props: Record<string, unknown>;
+  style?: NodeStyle;
+  layout?: NodeLayout;
+  container?: ContainerState;
+  /** Only used on the root node to hold the flat widget list */
+  children?: SchemaNode[];
+}
+type StyleValueMap = Record<string, unknown>;
+interface NodeStyle {
+  /** Styles applied to the node's layout box in its assigned surface. */
+  container?: StyleValueMap;
+  /** Styles applied to the rendered widget component. */
+  content?: StyleValueMap;
+  /** Styles applied to a page or container surface owned by this node. */
+  surface?: StyleValueMap;
+}
+interface DesignerSchema {
+  version: string;
+  globalConfig: Record<string, unknown>;
+  root: SchemaNode;
+}
+type SchemaDiagnosticSeverity = 'warning' | 'error';
+interface SchemaDiagnostic {
+  code: string;
+  severity: SchemaDiagnosticSeverity;
+  nodeId?: string;
+  ownerId?: string;
+  regionId?: string;
+  path?: string;
+  details?: Record<string, unknown>;
+}
+interface IndexedNodeLocation {
+  node: SchemaNode;
+  owner: 'root' | string;
+  regionId?: string;
+  index: number;
+  depth: 1 | 2;
+}
+interface SchemaIndexResult {
+  index: Map<string, IndexedNodeLocation>;
+  diagnostics: SchemaDiagnostic[];
+}
+type NodeOwner = {
+  kind: 'root';
+  sortScope?: string;
+} | {
+  kind: 'container';
+  containerId: string;
+  regionId: string;
+};
+type NodeDestination = ({
+  kind: 'root';
+  sortScope?: string;
+} & {
+  index?: number;
+}) | ({
+  kind: 'container';
+  containerId: string;
+  regionId: string;
+} & {
+  index?: number;
+});
+interface ResolvedNodeSource {
+  location: IndexedNodeLocation;
+  children: SchemaNode[];
+  index: number;
+  destination: NodeDestination;
+}
+interface ResolvedNodeDestination {
+  children: SchemaNode[];
+  destination: NodeDestination;
+  container?: SchemaNode;
+  definition?: ContainerDefinition;
+  variant?: ContainerVariantDefinition;
+  region?: ContainerRegionDefinition;
+}
+type OwnerResolutionResult<T> = {
+  ok: true;
+  value: T;
+} | {
+  ok: false;
+  code: string;
+  message?: string;
+};
+interface SchemaValidationResult {
+  valid: boolean;
+  schema: DesignerSchema;
+  diagnostics: SchemaDiagnostic[];
+}
+interface NodeLayout {
+  placement?: NodePlacement;
+  order?: number;
+  visible?: boolean | ((ctx: {
+    node: SchemaNode;
+    schema: DesignerSchema;
+  }) => boolean);
+}
+interface ResolvedNodeLayout {
+  placement: ResolvedNodePlacement;
+  region?: string;
+  sortScope: string | false;
+  order?: number;
+  visible: boolean;
+}
+interface LayoutNodeEntry {
+  node: SchemaNode;
+  arrayIndex: number;
+  layout: ResolvedNodeLayout;
+}
+interface LayoutPlan {
+  entries: LayoutNodeEntry[];
+  regions: Map<string, LayoutNodeEntry[]>;
+  chrome: LayoutNodeEntry[];
+  layers: Map<string, LayoutNodeEntry[]>;
+  sortScopes: Map<string, LayoutNodeEntry[]>;
+  insets: LayoutInsetPlan;
+}
+type LayoutPlacementKind = 'flow' | 'chrome' | 'layer';
+type LayoutEdge = 'block-start' | 'block-end' | 'inline-start' | 'inline-end';
+type LayoutAnchor = 'start' | 'center' | 'end';
+type LayoutChromePosition = 'fixed' | 'sticky' | 'flow';
+type LayoutLayerMode = 'framework' | 'self';
+type LayoutReserveMode = 'measure' | 'size' | 'none';
+type LayoutAvoidTarget = 'safe-area' | 'chrome' | 'viewport';
+interface LayoutAnchorSpec {
+  anchor: {
+    block?: LayoutAnchor;
+    inline?: LayoutAnchor;
+  };
+}
+interface LayoutOffsets {
+  blockStart?: string | number;
+  blockEnd?: string | number;
+  inlineStart?: string | number;
+  inlineEnd?: string | number;
+}
+interface LayoutReserveSpec {
+  mode?: LayoutReserveMode;
+  size?: string | number;
+}
+interface ResolvedLayoutReserveSpec {
+  mode: LayoutReserveMode;
+  size?: string | number;
+}
+interface FlowPlacement {
+  kind: 'flow';
+  region?: string;
+  sortScope?: string | false;
+}
+interface ChromePlacement {
+  kind: 'chrome';
+  edge: LayoutEdge;
+  position?: LayoutChromePosition;
+  reserve?: LayoutReserveSpec;
+  avoidContent?: boolean;
+}
+interface LayerPlacement {
+  kind: 'layer';
+  layer?: string;
+  mode?: LayoutLayerMode;
+  anchor?: LayoutAnchorSpec['anchor'];
+  offset?: LayoutOffsets;
+  avoid?: LayoutAvoidTarget[];
+}
+type NodePlacement = FlowPlacement | ChromePlacement | LayerPlacement;
+interface ResolvedFlowPlacement extends FlowPlacement {
+  kind: 'flow';
+  region: string;
+  sortScope: string | false;
+}
+interface ResolvedChromePlacement extends ChromePlacement {
+  kind: 'chrome';
+  position: LayoutChromePosition;
+  reserve: ResolvedLayoutReserveSpec;
+  avoidContent: boolean;
+}
+interface ResolvedLayerPlacement extends LayerPlacement {
+  kind: 'layer';
+  layer: string;
+  mode: LayoutLayerMode;
+  anchor: LayoutAnchorSpec['anchor'];
+  avoid: LayoutAvoidTarget[];
+}
+type ResolvedNodePlacement = ResolvedFlowPlacement | ResolvedChromePlacement | ResolvedLayerPlacement;
+interface LayoutInsetContribution {
+  edge: LayoutEdge;
+  sourceNodeId: string;
+  reserve: ResolvedLayoutReserveSpec;
+}
+interface LayoutInsetPlan {
+  contributors: LayoutInsetContribution[];
+}
+interface DragTarget {
+  /** ID of the node being dragged (null if dragging from material panel) */
+  sourceNodeId: string | null;
+  /** Widget type being dragged from material panel (null if moving existing) */
+  widgetType: string | null;
+}
+/**
+ * Context provided when evaluating per-instance behavior fields
+ * (mask, selectable, draggable, sortable, deletable).
+ * Available inside a computed — schema changes trigger re-evaluation.
+ */
+interface InstanceBehaviorContext {
+  /** The specific node being evaluated */
+  node: DeepReadonly<SchemaNode>;
+  /** A deeply readonly snapshot of the current designer schema. */
+  schema: DeepReadonly<DesignerSchema>;
+}
+/**
+ * Context provided when evaluating per-type behavior fields (creatable).
+ * No specific node exists yet — used in the material panel.
+ */
+interface TypeBehaviorContext {
+  /** The widget type identifier */
+  widgetType: string;
+  /** A deeply readonly snapshot of the current designer schema. */
+  schema: DeepReadonly<DesignerSchema>;
+}
+/**
+ * A behavior field that accepts either a static boolean or
+ * a predicate function evaluated at runtime.
+ *
+ * @example
+ * // Static
+ * draggable: false
+ *
+ * // Dynamic
+ * draggable: ({ node }) => node.type !== 'fixed'
+ */
+type BehaviorPredicate<Ctx> = boolean | ((ctx: Ctx) => boolean);
+/**
+ * User-facing reason for a blocked creation attempt.
+ *
+ * `code` is stable for analytics and custom UI mapping.
+ * `messageKey` lets applications provide localized copy.
+ * `message` is the fallback text when no localized message exists.
+ */
+interface CreationBlockReason {
+  code?: string;
+  messageKey?: string;
+  message?: string;
+}
+interface CreatableDecision extends CreationBlockReason {
+  allowed: boolean;
+}
+/**
+ * Type-level creation rule. Return `false` for a generic blocked state, or
+ * return `{ allowed: false, messageKey, message }` to explain the reason.
+ */
+type CreatableBehaviorResult = boolean | CreatableDecision;
+type CreatableBehaviorPredicate = CreatableBehaviorResult | ((ctx: TypeBehaviorContext) => CreatableBehaviorResult);
+type ContainerVariantId = string;
+type ContainerRegionId = string;
+interface ContainerState {
+  variant: ContainerVariantId;
+  regions: Record<ContainerRegionId, SchemaNode[]>;
+}
+interface ContainerRegionConstraints {
+  includeTypes?: string[];
+  excludeTypes?: string[];
+  minItems?: number;
+  maxItems?: number;
+}
+interface ContainerRegionDefinition {
+  id: ContainerRegionId;
+  title: string;
+  titleKey?: string;
+  constraints?: ContainerRegionConstraints;
+}
+interface ContainerVariantDefinition {
+  title: string;
+  titleKey?: string;
+  regions: ContainerRegionDefinition[];
+}
+interface PlacementDecision extends CreationBlockReason {
+  allowed: boolean;
+  details?: Record<string, unknown>;
+}
+interface ContainerDefinition {
+  defaultVariant: ContainerVariantId;
+  variants: Record<ContainerVariantId, ContainerVariantDefinition>;
+  createInitialState?: (ctx: ContainerInitContext) => ContainerState;
+  canPlace?: (ctx: ContainerPlacementContext) => PlacementDecision;
+  migrateVariant?: (ctx: ContainerVariantMigrationContext) => ContainerVariantMigrationResult;
+}
+interface ContainerInitContext {
+  containerNode: Readonly<SchemaNode>;
+  schema: Readonly<DesignerSchema>;
+  createNode: (type: string, overrides?: Partial<Pick<SchemaNode, 'props' | 'style' | 'layout'>>) => SchemaNode;
+}
+interface ContainerPlacementContext {
+  operation: 'add' | 'move';
+  schema: Readonly<DesignerSchema>;
+  container: Readonly<SchemaNode>;
+  variant: Readonly<ContainerVariantDefinition>;
+  region: Readonly<ContainerRegionDefinition>;
+  child: Readonly<SchemaNode>;
+  targetIndex: number;
+}
+interface ContainerVariantMigrationContext {
+  schema: Readonly<DesignerSchema>;
+  container: Readonly<SchemaNode>;
+  fromVariantId: ContainerVariantId;
+  toVariantId: ContainerVariantId;
+  fromVariant: Readonly<ContainerVariantDefinition>;
+  toVariant: Readonly<ContainerVariantDefinition>;
+  state: Readonly<ContainerState>;
+}
+type ContainerVariantMigrationResult = {
+  allowed: true;
+  state: ContainerState;
+} | ({
+  allowed: false;
+} & Omit<PlacementDecision, 'allowed'>);
+type ContainerDefinitionValidationCode = 'CONTAINER_DEFINITION_INVALID' | 'CONTAINER_VARIANTS_INVALID' | 'CONTAINER_VARIANT_INVALID' | 'CONTAINER_REGIONS_INVALID' | 'CONTAINER_REGION_INVALID' | 'CONTAINER_CONSTRAINTS_INVALID' | 'CONTAINER_DEFAULT_VARIANT_MISSING' | 'CONTAINER_VARIANT_ID_RESERVED' | 'CONTAINER_REGION_ID_RESERVED' | 'CONTAINER_REGION_ID_DUPLICATE' | 'CONTAINER_CARDINALITY_INVALID' | 'CONTAINER_TYPE_ID_INVALID';
+interface ContainerDefinitionValidationError {
+  code: ContainerDefinitionValidationCode;
+  path: string;
+}
+interface ContainerDefinitionValidationResult {
+  valid: boolean;
+  errors: ContainerDefinitionValidationError[];
+}
+interface ContainerPlanRegion {
+  definition: ContainerRegionDefinition;
+  nodes: SchemaNode[];
+  isEmpty: boolean;
+}
+interface ContainerPlan {
+  containerId: string;
+  variant: ContainerVariantDefinition;
+  regions: ContainerPlanRegion[];
+}
+type ContainerPlanResult = {
+  ok: true;
+  plan: ContainerPlan;
+} | {
+  ok: false;
+  code: 'CONTAINER_UNRESOLVED' | 'CONTAINER_VARIANT_UNKNOWN';
+  containerId: string;
+};
+type CreateRegisteredNode = ContainerInitContext['createNode'];
+type ContainerStateCreationResult = {
+  ok: true;
+  state: ContainerState;
+} | {
+  ok: false;
+  code: string;
+  message?: string;
+  details?: Record<string, unknown>;
+};
+interface ResolvePlacementContext {
+  definition: ContainerDefinition;
+  region: ContainerRegionDefinition;
+  child: SchemaNode;
+  childHasContainerCapability: boolean;
+  targetCount: number;
+  callbackContext: ContainerPlacementContext;
+}
+/**
+ * Minimal form field schema shape.
+ * Matches the structural contract of `@dragcraft/form-generator` FieldSchema
+ * without creating a package dependency.
+ */
+interface FieldSchemaShape {
+  key: string;
+  label: string;
+  component: string;
+  [key: string]: unknown;
+}
+/**
+ * Minimal form schema shape for widget property panels.
+ * Matches the structural contract of `@dragcraft/form-generator` FormSchema
+ * without creating a package dependency.
+ */
+interface FormSchemaShape {
+  sections: Array<{
+    title: string;
+    fields: FieldSchemaShape[];
+    [key: string]: unknown;
+  }>;
+}
+/**
+ * Per-widget action configuration.
+ * Controls which actions appear in the node toolbar for this widget type.
+ */
+interface CoreWidgetActionConfig {
+  /** If provided, only show actions with these keys */
+  only?: string[];
+  /** Exclude actions with these keys */
+  exclude?: string[];
+}
+/**
+ * Widget meta protocol — the contract every widget registers with the engine.
+ */
+interface CoreWidgetMeta {
+  /** Unique widget type identifier */
+  type: string;
+  /** Human-readable title for material panel */
+  title: string;
+  /** i18n message key for title; overrides `title` when i18n is active */
+  titleKey?: string;
+  /** Group for categorization in material panel */
+  group: string;
+  /** Icon identifier */
+  icon?: string;
+  /** Default prop values when creating a new instance */
+  defaultProps: Record<string, unknown>;
+  /** Default scoped styles when creating a new instance */
+  defaultStyle?: NodeStyle;
+  /** Form schema for the property panel */
+  formSchema: FormSchemaShape;
+  /** Structural container capabilities for this widget type. */
+  container?: ContainerDefinition;
+  /** Whether to render a mask overlay on the widget in the canvas (default: true). Accepts boolean or predicate. */
+  mask?: BehaviorPredicate<InstanceBehaviorContext>;
+  /** Whether this widget can be selected in the canvas (default: true). Accepts boolean or predicate. */
+  selectable?: BehaviorPredicate<InstanceBehaviorContext>;
+  /** Whether this widget can be dragged to reorder (default: true). Accepts boolean or predicate. */
+  draggable?: BehaviorPredicate<InstanceBehaviorContext>;
+  /**
+   * Whether this widget's position can be changed by reordering (default: true).
+   * When false, the widget is locked at its current array index — it cannot
+   * be dragged, and operations on other widgets that would shift this widget's
+   * index are forbidden. Implies draggable=false.
+   */
+  sortable?: BehaviorPredicate<InstanceBehaviorContext>;
+  /** Whether this widget can be deleted via toolbar action (default: true). Accepts boolean or predicate. */
+  deletable?: BehaviorPredicate<InstanceBehaviorContext>;
+  /** Default open layout metadata for new and existing instances of this widget type. */
+  defaultLayout?: NodeLayout;
+  /**
+   * Whether new instances of this widget type can be created (default: true).
+   * Applies to every ADD_NODE entry, including material drops and duplicate
+   * actions. Evaluated per-type, not per-instance.
+   */
+  creatable?: CreatableBehaviorPredicate;
+  /** Per-widget toolbar action configuration */
+  actions?: CoreWidgetActionConfig;
+}
+type WidgetMeta = CoreWidgetMeta;
+type WidgetActionConfig = CoreWidgetActionConfig;
+interface Command<T = unknown> {
+  type: string;
+  payload: T;
+}
+interface CommandInteractionStore {
+  readonly selectedNodeId: Readonly<Ref<string | null>>;
+  readonly hoveredNodeId: Readonly<Ref<string | null>>;
+  selectNode: (id: string | null) => void;
+  hoverNode: (id: string | null) => void;
+}
+interface CommandContext {
+  /** Frozen schema at the start of this command. Safe for user callbacks. */
+  schema: DeepReadonly<DesignerSchema>;
+  /** Command-owned mutable draft. Committed only when the command changes state. */
+  draft: DesignerSchema;
+  store: CommandInteractionStore;
+  registry: RegistryInstance;
+}
+type CommandExecutionResult = {
+  ok: true;
+  changed: boolean;
+  eventPayload?: unknown;
+} | ({
+  ok: false;
+  code: string;
+} & CreationBlockReason & {
+  details?: Record<string, unknown>;
+});
+type CommandResult = false | void | {
+  ok: true;
+  changed?: boolean;
+  eventPayload?: unknown;
+} | Extract<CommandExecutionResult, {
+  ok: false;
+}>;
+declare function commandFailure(code: string, reason?: Omit<Extract<CommandExecutionResult, {
+  ok: false;
+}>, 'ok' | 'code'>): Extract<CommandExecutionResult, {
+  ok: false;
+}>;
+type CommandHandler<T = unknown> = (ctx: CommandContext, payload: T) => CommandResult;
+interface AddNodePayload {
+  node: SchemaNode;
+  destination?: NodeDestination;
+}
+interface MoveNodePayload {
+  nodeId: string;
+  destination: NodeDestination;
+}
+interface RemoveNodePayload {
+  nodeId: string;
+}
+interface DuplicateNodePayload {
+  nodeId: string;
+}
+interface ChangeContainerVariantPayload {
+  containerId: string;
+  variant: ContainerVariantId;
+}
+interface UpdatePropsPayload {
+  nodeId: string;
+  props: Record<string, unknown>;
+  style?: NodeStyle;
+}
+interface SetGlobalConfigPayload {
+  config: Record<string, unknown>;
+}
+interface HistoryEntry {
+  label: string;
+  snapshot: DeepReadonly<DesignerSchema>;
+}
+interface EngineOptions {
+  maxHistorySize?: number;
+}
+interface EngineState {
+  getSchema: () => DeepReadonly<DesignerSchema>;
+  getNodeById: (id: string) => DeepReadonly<SchemaNode> | null;
+  getSelectedNodeId: () => string | null;
+  getHoveredNodeId: () => string | null;
+  getDragTarget: () => DragTarget | null;
+}
+interface EngineStore {
+  readonly schema: Readonly<ShallowRef<DeepReadonly<DesignerSchema>>>;
+  readonly selectedNodeId: Readonly<Ref<string | null>>;
+  readonly hoveredNodeId: Readonly<Ref<string | null>>;
+  readonly dragTarget: Readonly<Ref<DeepReadonly<DragTarget> | null>>;
+  selectNode: (id: string | null) => void;
+  hoverNode: (id: string | null) => void;
+  setDragTarget: (target: DragTarget | null) => void;
+}
+/**
+ * A single migration step that transforms a schema from one version to another.
+ */
+interface SchemaMigration {
+  /** The version this migration upgrades from */
+  fromVersion: string;
+  /** The version this migration upgrades to */
+  toVersion: string;
+  /** Transform function — receives the old schema, returns the migrated schema */
+  migrate: (schema: DesignerSchema) => DesignerSchema;
+}
+interface SchemaStoreInstance {
+  readonly schema: ShallowRef<DeepReadonly<DesignerSchema>>;
+  readonly selectedNodeId: Ref<string | null>;
+  readonly hoveredNodeId: Ref<string | null>;
+  readonly dragTarget: Ref<DragTarget | null>;
+  getSchema: () => DesignerSchema;
+  getSnapshot: () => DeepReadonly<DesignerSchema>;
+  setSchema: (schema: DesignerSchema) => void;
+  commitSchema: (schema: DesignerSchema) => DeepReadonly<DesignerSchema>;
+  restoreSnapshot: (schema: DeepReadonly<DesignerSchema>) => void;
+  selectNode: (id: string | null) => void;
+  hoverNode: (id: string | null) => void;
+  setDragTarget: (target: DragTarget | null) => void;
+  getNodeById: (id: string) => DeepReadonly<SchemaNode> | null;
+}
+interface RegistryInstance {
+  registerWidget: (meta: WidgetMeta) => void;
+  registerGlobalConfigSchema: (schema: Record<string, unknown>) => void;
+  registerGlobalConfigFormSchema: (schema: FormSchemaShape) => void;
+  getWidget: (type: string) => WidgetMeta | undefined;
+  getGlobalConfigSchema: () => Record<string, unknown> | undefined;
+  getAllWidgets: () => WidgetMeta[];
+}
+//#endregion
+//#region src/behavior.d.ts
+/**
+ * Resolves a behavior field that may be a static boolean or a predicate function.
+ *
+ * - `undefined` → returns `defaultValue` (preserves opt-in defaults)
+ * - `boolean`   → returns the boolean directly
+ * - `function`  → invokes the function with the provided context
+ *
+ * @param field - The behavior field from WidgetMeta (may be undefined)
+ * @param ctx   - The context to pass if field is a function
+ * @param defaultValue - Value when field is undefined (default: true)
+ */
+declare function resolveBehavior<Ctx>(field: BehaviorPredicate<Ctx> | undefined, ctx: Ctx, defaultValue?: boolean): boolean;
+declare function resolveCreatable(field: CreatableBehaviorPredicate | undefined, ctx: TypeBehaviorContext, defaultValue?: boolean): CreatableDecision;
+//#endregion
+//#region src/constants.d.ts
+declare const CommandType: {
+  readonly ADD_NODE: "ADD_NODE";
+  readonly MOVE_NODE: "MOVE_NODE";
+  readonly REMOVE_NODE: "REMOVE_NODE";
+  readonly DUPLICATE_NODE: "DUPLICATE_NODE";
+  readonly CHANGE_CONTAINER_VARIANT: "CHANGE_CONTAINER_VARIANT";
+  readonly UPDATE_PROPS: "UPDATE_PROPS";
+  readonly SET_GLOBAL_CONFIG: "SET_GLOBAL_CONFIG";
+};
+type CommandTypeValue = typeof CommandType[keyof typeof CommandType];
+declare const EventName: {
+  readonly SCHEMA_CHANGED: "schema:changed";
+  readonly SELECTION_CHANGED: "selection:changed";
+  readonly DRAG_ENTER: "drag:enter";
+  readonly DRAG_OVER: "drag:over";
+  readonly DRAG_LEAVE: "drag:leave";
+  readonly DRAG_DROP: "drag:drop";
+  readonly HISTORY_CHANGED: "history:changed";
+  readonly NODE_ADDED: "node:added";
+  readonly NODE_REMOVED: "node:removed";
+  readonly NODE_DUPLICATED: "node:duplicated";
+  readonly NODE_MOVED: "node:moved";
+  readonly CONTAINER_VARIANT_CHANGED: "container:variant-changed";
+  readonly NODE_UPDATED: "node:updated";
+  readonly GLOBAL_CONFIG_CHANGED: "global-config:changed";
+};
+type EventNameValue = typeof EventName[keyof typeof EventName];
+declare const DEFAULT_SCHEMA_VERSION = "1.0.0";
+declare const DEFAULT_MAX_HISTORY_SIZE = 50;
+//#endregion
+//#region src/event-hub.d.ts
+type EventListener = (...args: unknown[]) => void;
+declare class EventHub {
+  private emitter;
+  constructor();
+  on(event: EventNameValue | (string & {}), listener: EventListener): void;
+  off(event: EventNameValue | (string & {}), listener: EventListener): void;
+  emit(event: EventNameValue | (string & {}), ...args: unknown[]): void;
+  once(event: EventNameValue | (string & {}), listener: EventListener): void;
+  clear(): void;
+}
+declare function createEventHub(): EventHub;
+//#endregion
+//#region src/history-manager.d.ts
+interface HistoryState {
+  canUndo: boolean;
+  canRedo: boolean;
+  undoCount: number;
+  redoCount: number;
+}
+interface HistoryManagerInstance {
+  readonly state: Readonly<Ref<HistoryState>>;
+  pushSnapshot: (label: string, before: DeepReadonly<DesignerSchema>) => void;
+  undo: () => void;
+  redo: () => void;
+  canUndo: () => boolean;
+  canRedo: () => boolean;
+  beginTransaction: (label?: string) => void;
+  commitTransaction: () => void;
+  discardTransaction: () => void;
+  isInTransaction: () => boolean;
+  clear: () => void;
+}
+declare function createHistoryManager(store: SchemaStoreInstance, eventHub: EventHub, maxSize?: number): HistoryManagerInstance;
+//#endregion
+//#region src/command-bus.d.ts
+interface CommandBusInstance {
+  execute: <T = unknown>(command: Command<T>) => CommandExecutionResult;
+  registerHandler: <T = unknown>(type: string, handler: CommandHandler<T>) => void;
+}
+declare function createCommandBus(store: SchemaStoreInstance, registry: RegistryInstance, eventHub: EventHub, history: HistoryManagerInstance): CommandBusInstance;
+//#endregion
+//#region src/commands/add-node.d.ts
+declare function addNodeHandler(ctx: CommandContext, payload: AddNodePayload): CommandResult;
+//#endregion
+//#region src/commands/change-container-variant.d.ts
+declare function changeContainerVariantHandler(ctx: CommandContext, payload: ChangeContainerVariantPayload): CommandResult;
+//#endregion
+//#region src/commands/duplicate-node.d.ts
+declare function duplicateNodeHandler(ctx: CommandContext, payload: DuplicateNodePayload): CommandResult;
+//#endregion
+//#region src/commands/move-node.d.ts
+declare function moveNodeHandler(ctx: CommandContext, payload: MoveNodePayload): CommandResult;
+//#endregion
+//#region src/commands/remove-node.d.ts
+declare function removeNodeHandler(ctx: CommandContext, payload: RemoveNodePayload): CommandResult;
+//#endregion
+//#region src/commands/set-global-config.d.ts
+declare function setGlobalConfigHandler(ctx: CommandContext, payload: SetGlobalConfigPayload): CommandResult;
+//#endregion
+//#region src/commands/update-props.d.ts
+declare function updatePropsHandler(ctx: CommandContext, payload: UpdatePropsPayload): CommandResult;
+//#endregion
+//#region src/container-definition.d.ts
+declare function validateContainerDefinition(definition: ContainerDefinition): ContainerDefinitionValidationResult;
+//#endregion
+//#region src/container-placement.d.ts
+declare function resolvePlacementDecision(ctx: ResolvePlacementContext): PlacementDecision;
+declare function createContainerState(node: SchemaNode, schema: DesignerSchema, registry: RegistryInstance, createNode: CreateRegisteredNode): ContainerStateCreationResult;
+declare function createRegisteredNode(registry: RegistryInstance, createId?: () => string): CreateRegisteredNode;
+//#endregion
+//#region src/container-plan.d.ts
+declare function createContainerPlan(node: SchemaNode, registry: RegistryInstance): ContainerPlanResult;
+//#endregion
+//#region src/engine.d.ts
+type SchemaImportResult = {
+  ok: true;
+  diagnostics: SchemaDiagnostic[];
+} | {
+  ok: false;
+  diagnostics: SchemaDiagnostic[];
+};
+interface DesignerEngine {
+  store: EngineStore;
+  state: EngineState;
+  commandBus: CommandBusInstance;
+  history: HistoryManagerInstance;
+  registry: RegistryInstance;
+  eventHub: EventHub;
+  execute: <T = unknown>(command: Command<T>) => CommandExecutionResult;
+  registerHandler: <T = unknown>(type: string, handler: CommandHandler<T>) => void;
+  registerWidget: (meta: WidgetMeta) => void;
+  registerMigration: (migration: SchemaMigration) => void;
+  migrateSchema: (schema: DesignerSchema) => DesignerSchema;
+  exportSchema: () => DesignerSchema;
+  importSchema: (schema: DesignerSchema) => SchemaImportResult;
+  dispose: () => void;
+}
+declare function createEngine(options?: EngineOptions): DesignerEngine;
+//#endregion
+//#region src/helpers.d.ts
+declare function cloneNodeSubtree(node: SchemaNode, createId: () => string): SchemaNode;
+declare function collectSubtreeIds(node: SchemaNode): Set<string>;
+/**
+ * Find a node by ID in the shallow ownership structure.
+ */
+declare function findNodeById(root: SchemaNode, id: string): SchemaNode | null;
+/**
+ * Find the parent node of a given node ID.
+ * Returns the owning root or container location, or null if not found.
+ */
+declare function findParentNode(root: SchemaNode, targetId: string): {
+  parent: SchemaNode;
+  regionId?: string;
+  index: number;
+} | null;
+/**
+ * Remove a node from the tree by ID.
+ * Returns the removed node or null if not found.
+ */
+declare function removeNodeFromTree(root: SchemaNode, nodeId: string): SchemaNode | null;
+/**
+ * Insert a node into a parent's children array at a given index.
+ * If index is undefined, appends to the end.
+ */
+declare function insertNodeIntoTree(parent: SchemaNode, node: SchemaNode, index?: number): void;
+/**
+ * Walk root and its direct children (one level), calling visitor for each node.
+ * If visitor returns false, stop traversal.
+ *
+ * Note: This does NOT recurse into grandchildren — the schema is a flat
+ * two-level structure (root → widgets).
+ */
+declare function walkFlatChildren(root: SchemaNode, visitor: (node: SchemaNode) => boolean | void): void;
+//#endregion
+//#region src/layout.d.ts
+declare const DEFAULT_LAYOUT_REGION = "content";
+declare const DEFAULT_SORT_SCOPE = "content";
+declare const DEFAULT_LAYER = "float";
+declare function resolveNodeLayout(node: SchemaNode, registry: RegistryInstance, schema?: DesignerSchema): ResolvedNodeLayout;
+declare function createLayoutPlan(schema: DesignerSchema, registry: RegistryInstance): LayoutPlan;
+declare function getLayoutRegionEntries(plan: LayoutPlan, region?: string): LayoutNodeEntry[];
+declare function getSortScopeEntries(plan: LayoutPlan, sortScope?: string): LayoutNodeEntry[];
+declare function getSortScopeNodes(plan: LayoutPlan, sortScope?: string): SchemaNode[];
+declare function getSortableArrayIndexForInsert(scopeEntries: LayoutNodeEntry[], allChildren: SchemaNode[], visualIndex: number): number;
+declare function resolveNodeSource(schema: DesignerSchema, indexed: SchemaIndexResult, nodeId: string): OwnerResolutionResult<ResolvedNodeSource>;
+declare function resolveDestination(schema: DesignerSchema, registry: RegistryInstance, destination: NodeDestination): OwnerResolutionResult<ResolvedNodeDestination>;
+declare function clampInsertIndex(index: number | undefined, length: number): number;
+declare function stripPageLayout(node: SchemaNode): SchemaNode;
+//#endregion
+//#region src/registry.d.ts
+declare function createRegistry(): RegistryInstance;
+//#endregion
+//#region src/schema-index.d.ts
+declare function buildSchemaIndex(schema: DesignerSchema): SchemaIndexResult;
+declare function findIndexedNode(result: SchemaIndexResult, nodeId: string): IndexedNodeLocation | undefined;
+//#endregion
+//#region src/schema-store.d.ts
+declare function createDefaultSchema(): DesignerSchema;
+//#endregion
+//#region src/schema-validation.d.ts
+declare function validateSchema(input: DesignerSchema, registry: RegistryInstance): SchemaValidationResult;
+//#endregion
+//#region src/sortable.d.ts
+/**
+ * Collect the indices of all widgets whose `sortable` behavior resolves to false.
+ * These widgets must stay at their current array index (absolute index locking).
+ *
+ * @param _children - The flat widget list (`root.children`)
+ * @param registry - Widget meta registry for resolving behavior predicates
+ * @param schema   - Current designer schema (for predicate evaluation context)
+ * @param sortScope - Sort scope to evaluate
+ */
+declare function getLockedIndices(_children: SchemaNode[], registry: RegistryInstance, schema: DesignerSchema, sortScope?: string): Set<number>;
+declare function getLockedIndicesFromNodes(nodes: readonly SchemaNode[], registry: RegistryInstance, schema: DesignerSchema): Set<number>;
+/**
+ * Can a new node be inserted at `insertIndex` without shifting any locked widget?
+ *
+ * Inserting at index `i` shifts all widgets at index >= `i` rightward by 1.
+ * If any locked widget has index >= `insertIndex`, it would be displaced.
+ */
+declare function isInsertAllowed(insertIndex: number, lockedIndices: Set<number>): boolean;
+/**
+ * Can a node be moved from `srcIdx` to `targetIdx` (post-removal insertion index)
+ * without altering any locked widget's absolute position?
+ *
+ * Mathematical analysis for each locked widget at index L (L !== srcIdx):
+ * - srcIdx < L: Removal shifts L to L-1. Insertion must be at targetIdx <= L-1 to restore it.
+ * - srcIdx > L: L is unaffected by removal. Insertion must satisfy targetIdx > L to keep it at L.
+ */
+declare function isMoveAllowed(srcIdx: number, targetIdx: number, lockedIndices: Set<number>): boolean;
+/**
+ * Can a node at `removeIndex` be removed without shifting any locked widget?
+ *
+ * Removing at index `i` shifts all widgets at index > `i` leftward by 1.
+ * If any locked widget has index > `removeIndex`, it would be displaced.
+ */
+declare function isRemoveAllowed(removeIndex: number, lockedIndices: Set<number>): boolean;
+/**
+ * Compute the set of valid visual drop indices (0..children.length) for a drag operation.
+ *
+ * For new-widget drops (sourceNodeId === null): checks isInsertAllowed for each position.
+ * For existing-widget moves: converts visual gap index to post-removal target index
+ * and checks isMoveAllowed.
+ *
+ * @param children     - The flat widget list
+ * @param lockedIndices - Pre-computed locked indices from getLockedIndices()
+ * @param sourceNodeId  - ID of the dragged widget (null if dragging from material panel)
+ */
+declare function getValidDropIndices(children: SchemaNode[] | LayoutNodeEntry[], lockedIndices: Set<number>, sourceNodeId: string | null): Set<number>;
+/**
+ * Given a raw visual index and a set of valid indices, find the nearest valid one.
+ * Returns null if no valid index exists.
+ */
+declare function findNearestValidIndex(rawIndex: number, validIndices: Set<number>): number | null;
+//#endregion
+//#region src/style.d.ts
+declare function normalizeStyleValueMap(style: DeepReadonly<StyleValueMap> | undefined): StyleValueMap | undefined;
+//#endregion
+export { type AddNodePayload, type BehaviorPredicate, type ChangeContainerVariantPayload, type Command, type CommandBusInstance, type CommandContext, type CommandExecutionResult, type CommandHandler, type CommandResult, CommandType, type CommandTypeValue, type ContainerDefinition, type ContainerDefinitionValidationCode, type ContainerDefinitionValidationError, type ContainerDefinitionValidationResult, type ContainerInitContext, type ContainerPlacementContext, type ContainerPlan, type ContainerPlanRegion, type ContainerPlanResult, type ContainerRegionConstraints, type ContainerRegionDefinition, type ContainerRegionId, type ContainerState, type ContainerStateCreationResult, type ContainerVariantDefinition, type ContainerVariantId, type ContainerVariantMigrationContext, type ContainerVariantMigrationResult, type CoreWidgetActionConfig, type CoreWidgetMeta, type CreatableBehaviorPredicate, type CreatableBehaviorResult, type CreatableDecision, type CreateRegisteredNode, type CreationBlockReason, DEFAULT_LAYER, DEFAULT_LAYOUT_REGION, DEFAULT_MAX_HISTORY_SIZE, DEFAULT_SCHEMA_VERSION, DEFAULT_SORT_SCOPE, type DeepReadonly, type DesignerEngine, type DesignerSchema, type DragTarget, type DuplicateNodePayload, type EngineOptions, type EngineState, type EngineStore, EventHub, type EventListener, EventName, type EventNameValue, type FieldSchemaShape, type FormSchemaShape, type HistoryEntry, type HistoryManagerInstance, type HistoryState, type IndexedNodeLocation, type InstanceBehaviorContext, type LayoutAnchor, type LayoutAnchorSpec, type LayoutAvoidTarget, type LayoutChromePosition, type LayoutEdge, type LayoutInsetContribution, type LayoutInsetPlan, type LayoutLayerMode, type LayoutNodeEntry, type LayoutOffsets, type LayoutPlacementKind, type LayoutPlan, type LayoutReserveMode, type LayoutReserveSpec, type MoveNodePayload, type NodeDestination, type NodeLayout, type NodeOwner, type NodePlacement, type NodeStyle, type OwnerResolutionResult, type PlacementDecision, type RegistryInstance, type RemoveNodePayload, type ResolvePlacementContext, type ResolvedChromePlacement, type ResolvedFlowPlacement, type ResolvedLayerPlacement, type ResolvedLayoutReserveSpec, type ResolvedNodeDestination, type ResolvedNodeLayout, type ResolvedNodePlacement, type ResolvedNodeSource, type SchemaDiagnostic, type SchemaDiagnosticSeverity, type SchemaImportResult, type SchemaIndexResult, type SchemaMigration, type SchemaNode, type SchemaValidationResult, type SetGlobalConfigPayload, type StyleValueMap, type TypeBehaviorContext, type UpdatePropsPayload, type WidgetActionConfig, type WidgetMeta, addNodeHandler, buildSchemaIndex, changeContainerVariantHandler, clampInsertIndex, cloneNodeSubtree, collectSubtreeIds, commandFailure, createCommandBus, createContainerPlan, createContainerState, createDefaultSchema, createEngine, createEventHub, createHistoryManager, createLayoutPlan, createRegisteredNode, createRegistry, duplicateNodeHandler, findIndexedNode, findNearestValidIndex, findNodeById, findParentNode, getLayoutRegionEntries, getLockedIndices, getLockedIndicesFromNodes, getSortScopeEntries, getSortScopeNodes, getSortableArrayIndexForInsert, getValidDropIndices, insertNodeIntoTree, isInsertAllowed, isMoveAllowed, isRemoveAllowed, moveNodeHandler, normalizeStyleValueMap, removeNodeFromTree, removeNodeHandler, resolveBehavior, resolveCreatable, resolveDestination, resolveNodeLayout, resolveNodeSource, resolvePlacementDecision, setGlobalConfigHandler, stripPageLayout, updatePropsHandler, validateContainerDefinition, validateSchema, walkFlatChildren };