@petrarca/sonnet-schema-designer 0.5.0 → 0.7.0

package/README.md

@@ -0,0 +1,97 @@
+# @petrarca/sonnet-schema-designer
+
+A visual editor for JSON Schema, part of the Petrarca Sonnet component library.
+One component, `SchemaDesigner`, edits a schema in place. Presentation hints
+travel beside it in a UI Schema map, or embedded on the schema when you ask for
+that shape.
+
+## What it provides
+
+**Three panes.** A property tree on the left for structure -- select, add,
+delete, reorder, rename, with a collapsible region for `$defs`. A preview in
+the centre with tabs over the live form, the form layout designer, a table and
+the JSON source. An inspector on the right with Data, Enum, UI, Rule and Table
+editors for the selected node. Both side panes resize and collapse.
+
+**Schema authoring.** Types and validation, nesting, `oneOf` variants,
+conditionals, definitions and references. Local `#/$defs/...` and
+`#/definitions/...` references resolve on their own; anything else goes through
+a synchronous `refResolver` and expands read-only in the tree.
+
+**Presentation authoring.** Widgets and their options, table hints, visibility
+rules and form layout, in the same `x-ui-*` vocabulary
+`JsonSchemaFormRenderer` reads. `embedUiSchema` merges the top-level form hints
+onto the schema when a single self-contained artifact is wanted.
+
+**Capability gating.** A profile restricts what a user may author -- a
+data-only profile, a fixed schema with editable areas, or a locked view --
+validated by `resolveCapabilities`, `validateCapabilities` and
+`capabilitiesSchema`.
+
+**The pieces behind the shell.** `useDesignerState` holds the whole model and
+every mutation; `PropertyTree`, `Inspector`, `PreviewPane`,
+`FormLayoutDesigner` and `FormSettingsSheet` each take that state. A real seam,
+though the shell is the supported way to use them.
+
+## Install
+
+```bash
+pnpm add @petrarca/sonnet-schema-designer
+```
+
+`@petrarca/sonnet-core`, `@petrarca/sonnet-ui` and `@petrarca/sonnet-forms` are
+regular dependencies and arrive with it, as do `lucide-react` and Zod.
+
+| Peer | Range | Needed for |
+|---|---|---|
+| `react`, `react-dom` | `>=19` | Everything |
+| `tailwindcss` | `>=3` | The styles the components emit |
+
+It renders through `sonnet-ui`'s stylesheet and Tailwind preset, so set those
+up first -- see
+[sonnet-ui: getting started](../sonnet-ui/docs/usage/getting-started.md).
+
+## Usage
+
+```tsx
+import { SchemaDesigner } from "@petrarca/sonnet-schema-designer";
+import type { JsonSchema, UISchema } from "@petrarca/sonnet-core/schema";
+
+const [schema, setSchema] = useState<JsonSchema>(initial);
+const [uiSchema, setUiSchema] = useState<Record<string, UISchema>>({});
+
+<SchemaDesigner
+  schema={schema}
+  uiSchema={uiSchema}
+  onChange={(nextSchema, nextUiSchema) => {
+    setSchema(nextSchema);
+    setUiSchema(nextUiSchema);
+  }}
+/>;
+```
+
+All nine props are optional -- `schema`, `uiSchema`, `initialSchema`,
+`initialUiSchema`, `onChange`, `readOnly`, `capabilities`, `widgetOptions` and
+`refResolver`. The mode is decided by whether `schema` is `undefined`: omit it
+and seed with `initialSchema` for uncontrolled use, where the designer keeps
+the model internally and still reports every edit through `onChange`. With
+neither, it starts from an empty object schema.
+
+The root element is `w-full h-full`, so the parent must have a resolved height.
+
+## Documentation
+
+- [Usage guides](docs/usage/index.md) -- getting started,
+  [authoring schemas](docs/usage/authoring-schemas.md),
+  [UI hints](docs/usage/ui-hints.md) and
+  [capabilities](docs/usage/capabilities.md).
+- [Design docs](docs/design/index.md) -- the designer's structure, logic
+  authoring, and references and definitions.
+- [The UISchema vocabulary](../sonnet-forms/docs/usage/ui-schema.md) -- what the
+  `x-ui-*` keys mean to the form renderer.
+- [Workspace documentation](../../docs/README.md) -- how the packages layer and
+  the architecture decision records.
+
+## License
+
+Apache 2.0. See [LICENSE.md](../../LICENSE.md).

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { JsonSchemaProperty, JsonSchema, UISchema, UILayoutConfig, UISchemaOptions } from '@petrarca/sonnet-core/schema';
+import { JsonSchemaProperty, JsonSchema, RefResolver, UISchema, UILayoutConfig, UISchemaOptions, UILayoutGroupConfig, UILayoutRowConfig } from '@petrarca/sonnet-core/schema';
 import { z } from 'zod';
 import React from 'react';
 import { WidgetOptionDef } from '@petrarca/sonnet-forms/widget-options';
@@ -7,26 +7,115 @@ import { TableUiSchema } from '@petrarca/sonnet-ui';
 /**
  * Path navigation over a JsonSchema tree.
  *
- * A property path is an array of property keys from the root down to a
- * property, e.g. ["address", "city"]. Object children nest through
- * `properties`; array children nest through `items.properties`. The path names
- * the property and the navigator descends through `items` transparently, so an
- * array-of-objects and its item object share one editing surface.
+ * A path is a list of typed segments from the root down to a property. Most
+ * segments are property keys (`{kind:"prop"}`) -- object children nest through
+ * `properties`, array-of-object children through `items.properties`, and the
+ * navigator descends through `items` transparently so an array and its item
+ * object share one editing surface.
+ *
+ * Logic constructs introduce non-property segments: `{kind:"branch"}` for a
+ * `oneOf`/`allOf` element, and `{kind:"slot"}` for a fixed schema slot
+ * (`then`/`else`/`items`). The discriminated union keeps the distinction
+ * explicit and type-checked; a single codec (pathKey/parsePathKey) owns all
+ * conversion to/from strings.
  */
 
-type PropertyPath = string[];
-/** Serialize a path for use as a stable React key or selection id. */
+/** A fixed schema slot that holds a single sub-schema. */
+type PathSlot = "then" | "else" | "items";
+/**
+ * The array a conditional (if/then/else) member lives in. `allOf` = every
+ * condition must hold (AND); `anyOf` = any condition suffices (OR). Maps to
+ * FHIR `enableBehavior` "all" / "any".
+ */
+type ConditionCombinator = "allOf" | "anyOf";
+/** One step in a property path. */
+type PathSegment = {
+    kind: "prop";
+    key: string;
+} | {
+    kind: "branch";
+    index: number;
+} | {
+    kind: "condition";
+    combinator: ConditionCombinator;
+    index: number;
+} | {
+    kind: "slot";
+    slot: PathSlot;
+} | {
+    kind: "def";
+    name: string;
+};
+type PropertyPath = PathSegment[];
+/**
+ * Whether a property key is reserved by the path codec. Keys matching
+ * `/^#(branch|condition|def|slot):/` would corrupt the pathKey/parsePathKey
+ * round-trip. The designer guards against these at rename/add time.
+ */
+declare function isReservedKey(key: string): boolean;
+/** Construct a property-key segment. */
+declare function prop(key: string): PathSegment;
+/** Construct a branch (oneOf element) segment. */
+declare function branch(index: number): PathSegment;
+/** Construct a condition (if/then/else member) segment for a combinator array. */
+declare function condition(index: number, combinator?: ConditionCombinator): PathSegment;
+/** Construct a fixed-slot segment. */
+declare function slot(name: PathSlot): PathSegment;
+/** Construct a definition ($defs entry) segment. Root-only in practice. */
+declare function def(name: string): PathSegment;
+/** Serialize a path to a stable string (React key, selection id, scope value). */
 declare function pathKey(path: PropertyPath): string;
-/** Whether two paths refer to the same property. */
+/** Parse a string produced by {@link pathKey} back into a path. */
+declare function parsePathKey(key: string): PropertyPath;
+/** Whether two path segments refer to the same position. */
+declare function sameSegment(a: PathSegment, b: PathSegment): boolean;
+/** Whether two paths refer to the same node (structural comparison). */
 declare function samePath(a: PropertyPath | null, b: PropertyPath | null): boolean;
-/** The container that holds a property's children, or undefined for scalars. */
+/** How a child slot is presented and mutated. */
+type SlotKind = "property" | "branch" | "conditional" | "definition";
+/** A single editable child of a property (or the root). */
+interface ChildSlot {
+    /** Segment appended to the parent path to reach this child. */
+    segment: PathSegment;
+    /** Display label for the tree row. */
+    label: string;
+    /** The child schema. */
+    property: JsonSchemaProperty;
+    kind: SlotKind;
+    removable: boolean;
+    reorderable: boolean;
+}
+/**
+ * The properties map that holds a property's named children, or undefined when
+ * it has none. Object children live in `properties`; array-of-object children
+ * live in `items.properties`. (Logic constructs use branch/slot children and
+ * are surfaced via {@link childSlots}, not here.)
+ */
 declare function childContainer(prop: JsonSchemaProperty): Record<string, JsonSchemaProperty> | undefined;
+/**
+ * The reusable definitions map of a schema. Canonically 2020-12 `$defs`; also
+ * reads Draft-7 `definitions` so both dialects surface as editable nodes. New
+ * definitions are always authored into `$defs` (see mutate.addDefinition).
+ */
+declare function definitionsOf(property: JsonSchemaProperty): Record<string, JsonSchemaProperty> | undefined;
+/**
+ * The ordered child slots of a property (the single extension point for the
+ * tree/inspector/mutations). Surfaces object/array property children, oneOf
+ * branches, if/then/else conditionals (allOf/anyOf members), and $defs
+ * definitions (root-only in practice).
+ */
+declare function childSlots(property: JsonSchemaProperty): ChildSlot[];
+/**
+ * Wrap a JsonSchema root as an object-shaped JsonSchemaProperty so the path
+ * navigation machinery can traverse it with the same stepInto logic as any
+ * nested property. Pass the keys needed by the caller; unused fields default
+ * to undefined.
+ */
+declare function schemaAsRootProp(schema: JsonSchema): JsonSchemaProperty;
 /** Resolve a path to its property definition, or undefined if not found. */
 declare function getProperty(schema: JsonSchema, path: PropertyPath): JsonSchemaProperty | undefined;
-/** Whether a property has (or can have) child properties. */
+/** Whether a property has (or can have) child slots (properties, branches, conditionals). */
 declare function isContainer(prop: JsonSchemaProperty): boolean;
-/** The child properties of a property, or an empty map for scalars. */
-declare function childrenOf(prop: JsonSchemaProperty): Record<string, JsonSchemaProperty>;
 
 /**
  * Read-shaping: turn a JsonSchema into a property tree for the designer UI.
@@ -35,32 +124,51 @@ declare function childrenOf(prop: JsonSchemaProperty): Record<string, JsonSchema
  * first, then remaining keys in declaration order.
  */
 
-type PropertyKind = "scalar" | "enum" | "object" | "array";
+type PropertyKind = "scalar" | "enum" | "object" | "array" | "oneOf" | "conditional" | "reference" | "definition";
 interface PropertyNode {
     path: PropertyPath;
     key: string;
     property: JsonSchemaProperty;
     kind: PropertyKind;
+    /** How this node sits in its parent: a named property or a oneOf branch. */
+    slotKind: SlotKind;
     required: boolean;
     /** Short type descriptor for the tree row, e.g. "string", "object[]". */
     typeLabel: string;
     /** Resolved widget override (x-ui-widget) if any. */
     widget?: string;
+    /**
+     * When this node is a `$ref`, the ref string it points at. Undefined for
+     * non-ref nodes.
+     */
+    reference?: string;
+    /**
+     * True for nodes that live inside a resolved `$ref` (the ref's descendants).
+     * These come from a shared definition and are not editable here -- the tree
+     * and inspector use this to show read-only affordances. Computed once at
+     * build time (no per-render schema walks). The ref node itself is NOT marked
+     * (the usage can be renamed/deleted).
+     */
+    readOnly?: boolean;
     children: PropertyNode[];
 }
 /** Classify a property into a tree kind. */
 declare function propertyKind(prop: JsonSchemaProperty): PropertyKind;
 /** Order keys by explicit x-ui-order, then remaining declaration order. */
 declare function orderedKeys(properties: Record<string, JsonSchemaProperty>, order: string[] | undefined): string[];
-/** Build the full property tree for a schema. */
-declare function buildPropertyTree(schema: JsonSchema): PropertyNode[];
+/**
+ * Build the full property tree for a schema. Pass `resolve` to expand `$ref`
+ * nodes (read-only) so referenced structure is legible; without it, ref nodes
+ * show as leaves. `resolve` mirrors the renderer's RefResolver.
+ */
+declare function buildPropertyTree(schema: JsonSchema, resolve?: RefResolver): PropertyNode[];
 /**
  * A layout scope: a container whose fields can be arranged into rows. Root is
  * the form itself (path []); nested scopes are object/array containers.
  */
 interface LayoutScope {
     /** Empty for root, otherwise the property path to the container. */
-    path: string[];
+    path: PropertyPath;
     /** Human label, e.g. "Form (root)" or "contact" or "addresses (items)". */
     label: string;
 }
@@ -81,13 +189,56 @@ interface DesignerModel {
     schema: JsonSchema;
     uiSchema: UiSchemaMap;
 }
+/** Kinds that can be created as a new property. */
+type NewPropertyKind = "scalar" | "object" | "array" | "oneOf";
 /** A default property for a newly created property of a given kind. */
-declare function newProperty(kind: "scalar" | "object" | "array"): JsonSchemaProperty;
+declare function newProperty(kind: NewPropertyKind): JsonSchemaProperty;
+/** A default oneOf branch: an object with a const-valued `kind` discriminator. */
+declare function newBranch(value: string): JsonSchemaProperty;
 /** Add a property under a parent path (root when empty). Returns the new model. */
-declare function addProperty(model: DesignerModel, parentPath: PropertyPath, kind: "scalar" | "object" | "array"): {
+declare function addProperty(model: DesignerModel, parentPath: PropertyPath, kind: NewPropertyKind): {
+    model: DesignerModel;
+    path: PropertyPath;
+};
+/** Add a branch to the oneOf property at `path`. Returns the new model + branch path. */
+declare function addBranch(model: DesignerModel, path: PropertyPath): {
+    model: DesignerModel;
+    path: PropertyPath;
+};
+/** Remove the branch at `path` (a branch segment). Returns the new model. */
+declare function removeBranch(model: DesignerModel, path: PropertyPath): DesignerModel;
+/** Move the branch at `path` up (-1) or down (+1) among its siblings. */
+declare function moveBranch(model: DesignerModel, path: PropertyPath, direction: -1 | 1): DesignerModel;
+/**
+ * A seed conditional member: an empty `if` (no field yet) plus an empty `then`.
+ * The condition is filled in by setCondition; `then` fields are added like any
+ * object's properties.
+ */
+declare function newCondition(): JsonSchemaProperty;
+/**
+ * Add a conditional (if/then/else) to the object at `objectPath` (root when
+ * empty), appended to the given combinator array (`allOf` = AND, default;
+ * `anyOf` = OR). Returns the new model + the condition path.
+ */
+declare function addConditional(model: DesignerModel, objectPath: PropertyPath, combinator?: ConditionCombinator): {
     model: DesignerModel;
     path: PropertyPath;
 };
+/** Remove the conditional at `path` (a condition segment). Returns the new model. */
+declare function removeConditional(model: DesignerModel, path: PropertyPath): DesignerModel;
+/** Write the `if` of the conditional at `path` from a condition triple. */
+declare function setCondition(model: DesignerModel, path: PropertyPath, ifSchema: JsonSchemaProperty): DesignerModel;
+/** Add an empty `else` branch to the conditional at `path`. */
+declare function addElse(model: DesignerModel, path: PropertyPath): DesignerModel;
+/** Remove the `else` branch from the conditional at `path`. */
+declare function removeElse(model: DesignerModel, path: PropertyPath): DesignerModel;
+/**
+ * Switch the combinator (AND/OR) for the conditionals of the object at
+ * `objectPath`. Migrates every conditional member from the current combinator
+ * array to `next`. Non-conditional members (structural allOf/anyOf entries)
+ * stay put. No-op when already using `next` or when there are no conditionals.
+ */
+declare function setConditionalBehavior(model: DesignerModel, objectPath: PropertyPath, next: ConditionCombinator): DesignerModel;
 /** Delete the property at path. Returns the new model. */
 declare function deleteProperty(model: DesignerModel, path: PropertyPath): DesignerModel;
 /** Rename the property at path. Rewrites key, order, required, and uiSchema. */
@@ -101,12 +252,45 @@ declare function moveProperty(model: DesignerModel, path: PropertyPath, directio
 declare function setRequired(model: DesignerModel, path: PropertyPath, required: boolean): DesignerModel;
 /** Replace the property definition at path (merges the given partial). */
 declare function updateProperty(model: DesignerModel, path: PropertyPath, patch: Partial<JsonSchemaProperty>): DesignerModel;
+/** The kind a property can be changed to: a JSON Schema type, or a "oneOf" union. */
+type PropertyTypeChoice = NonNullable<JsonSchemaProperty["type"]> | "oneOf";
+/**
+ * Change the kind of the property at path, reshaping structural keys: object
+ * adds an empty `properties`; array adds `items`; oneOf adds branches + a
+ * discriminator; leaving a kind strips its keys. Type-specific validation keys
+ * that no longer apply are dropped.
+ */
+declare function changePropertyType(model: DesignerModel, path: PropertyPath, next: PropertyTypeChoice): DesignerModel;
+/**
+ * Point the property at path to a definition by name, writing a local `$ref`
+ * (`#/$defs/<name>`) and stripping type-specific keys. Turns a plain property
+ * into a reference usage. No-op for the root or an unknown target.
+ */
+declare function setReference(model: DesignerModel, path: PropertyPath, name: string): DesignerModel;
+/**
+ * Add a new empty object definition under `$defs`. Returns the new model and the
+ * path to the created definition for selection.
+ */
+declare function addDefinition(model: DesignerModel, name?: string): {
+    model: DesignerModel;
+    path: PropertyPath;
+};
+/**
+ * Rename a `$defs` entry, preserving order, and rewrite every local `$ref` that
+ * targets it (both `#/$defs/` and `#/definitions/` forms) to the new pointer.
+ * No-op on collision, reserved, or empty names.
+ */
+declare function renameDefinition(model: DesignerModel, oldName: string, newName: string): {
+    model: DesignerModel;
+    path: PropertyPath;
+};
 /**
- * Change the type of the property at path, reshaping structural keys: switching to
- * object adds an empty `properties`; to array adds `items`; leaving them strips
- * those keys. Type-specific validation keys that no longer apply are dropped.
+ * Remove a `$defs` entry. Blocked (no-op) while any local `$ref` still targets
+ * it; the UI surfaces the usage count. Drops the `$defs` map when it empties.
  */
-declare function changePropertyType(model: DesignerModel, path: PropertyPath, nextType: JsonSchemaProperty["type"]): DesignerModel;
+declare function removeDefinition(model: DesignerModel, name: string): DesignerModel;
+/** Whether a definition is referenced anywhere (for UI delete-guard messaging). */
+declare function definitionUsageCount(schema: JsonSchema, name: string): number;
 /** One enum choice: a value and an optional display label. */
 interface EnumChoice {
     value: string;
@@ -160,6 +344,58 @@ declare function getScopedLayout(schema: JsonSchema, uiSchema: UiSchemaMap, scop
  * x-ui-layout, preserving rows and other keys. Undefined values clear the key.
  */
 declare function setScopedLayoutOptions(model: DesignerModel, scopePath: PropertyPath, options: Pick<UILayoutConfig, "direction" | "gap" | "labels" | "compact">): DesignerModel;
+/**
+ * Set the group definitions for a scope, preserving other x-ui-layout keys.
+ * Passing an empty list (or undefined) clears groups, returning the scope to the
+ * flat row layout. Root groups live in uiSchema["x-ui-layout"]; a container's
+ * live on the property's x-ui-layout (array -> items).
+ *
+ * Groups and flat rows are mutually exclusive (the renderer gives groups
+ * precedence), so setting groups drops `rows` -- otherwise the orphaned list
+ * would be invisible in both the form and the designer.
+ */
+declare function setScopedLayoutGroups(model: DesignerModel, scopePath: PropertyPath, groups: UILayoutConfig["groups"]): DesignerModel;
+/** Append an empty group. The label defaults to the next ordinal ("Group 3"). */
+declare function addLayoutGroup(model: DesignerModel, scopePath: PropertyPath, label?: string): DesignerModel;
+/** Rename one group. No-op for an unknown index or a blank label. */
+declare function renameLayoutGroup(model: DesignerModel, scopePath: PropertyPath, groupIndex: number, label: string): DesignerModel;
+/**
+ * Place a property into one group's row, removing it from wherever it currently
+ * sits across *all* groups. Passing a null target returns it to the pool.
+ *
+ * Needed because each group owns its own rows: without a cross-group operation a
+ * field could only be moved between groups by visiting its old group first.
+ */
+declare function placeFieldInGroup(model: DesignerModel, scopePath: PropertyPath, key: string, target: {
+    groupIndex: number;
+    rowIndex: number;
+} | null): DesignerModel;
+/** Move one group left (-1) or right (+1). No-op at the ends. */
+declare function moveLayoutGroup(model: DesignerModel, scopePath: PropertyPath, groupIndex: number, direction: -1 | 1): DesignerModel;
+/**
+ * Set (or clear) a group's show/hide rule. Passing undefined makes the group
+ * unconditional.
+ */
+declare function setLayoutGroupRule(model: DesignerModel, scopePath: PropertyPath, groupIndex: number, rule: UILayoutGroupConfig["rule"]): DesignerModel;
+/**
+ * Set the group presentation for a scope ("groups", "stepper", or a custom
+ * template name). Passing undefined restores the default group presentation.
+ */
+declare function setScopedLayoutVariant(model: DesignerModel, scopePath: PropertyPath, variant: UILayoutConfig["variant"]): DesignerModel;
+/**
+ * Remove one group. Its rows are not discarded: removing the last remaining group
+ * flattens them back into the scope's flat row layout, so a single click can
+ * never destroy every field placement.
+ */
+declare function removeLayoutGroup(model: DesignerModel, scopePath: PropertyPath, groupIndex: number): DesignerModel;
+/** Replace the rows of one group in a scope. No-op for an unknown group index. */
+declare function setScopedGroupRows(model: DesignerModel, scopePath: PropertyPath, groupIndex: number, rows: UILayoutRowConfig[]): DesignerModel;
+/**
+ * Switch a scope between flat rows and groups, carrying the existing layout over
+ * so no field placement is lost: rows become the first group's rows, and leaving
+ * group mode flattens every group's rows back into one list.
+ */
+declare function setScopedLayoutMode(model: DesignerModel, scopePath: PropertyPath, mode: "rows" | "groups"): DesignerModel;
 /** Set (or clear) the root global options (uiSchema["x-ui-globalOptions"]). */
 declare function setGlobalOptions(model: DesignerModel, options: UISchemaOptions | undefined): DesignerModel;
 
@@ -207,7 +443,8 @@ declare function embedUiSchema(schema: JsonSchema, uiSchema: Record<string, UISc
  * fully-locked shorthand). Every field is optional and defaults to the most
  * permissive value, so adding a capability never tightens an existing profile.
  *
- * Design: docs/design/schema-designer.md, section "Capability gating".
+ * Design: docs/design/schema-designer.md in this package; usage in
+ * docs/usage/capabilities.md.
  */
 
 /**
@@ -215,11 +452,17 @@ declare function embedUiSchema(schema: JsonSchema, uiSchema: Record<string, UISc
  * schema; "capabilities" is a meta-editor for the profile itself (a dev /
  * power-user affordance), not a preview -- it is opt-in and never in a default.
  */
-type PreviewKind = "form" | "table" | "json" | "capabilities";
+declare const previewKindSchema: z.ZodEnum<{
+    form: "form";
+    table: "table";
+    json: "json";
+    capabilities: "capabilities";
+}>;
+type PreviewKind = z.infer<typeof previewKindSchema>;
 /**
  * The capabilities schema. Small by design -- it covers the real consumer needs
- * (sestina's audit-event and terminology schema editors) without a per-area
- * matrix we do not use yet.
+ * (locked-down, single-schema editors embedded in an application) without a
+ * per-area matrix we do not use yet.
  */
 declare const capabilitiesSchema: z.ZodObject<{
     mode: z.ZodDefault<z.ZodEnum<{
@@ -239,13 +482,15 @@ declare const capabilitiesSchema: z.ZodObject<{
  * fields optional on input (defaults are applied by resolveCapabilities).
  */
 type SchemaDesignerCapabilities = z.input<typeof capabilitiesSchema>;
+/**
+ * The schema's own fields once resolved. Derived from the schema rather than
+ * restated, so adding or retyping a capability cannot silently drift from it.
+ * `Required` because resolveCapabilities defaults every optional field --
+ * `previews` by mode, `editablePaths` to empty -- so none is absent downstream.
+ */
+type ResolvedSchemaFields = Required<z.output<typeof capabilitiesSchema>>;
 /** The fully-resolved capabilities, plus the derived flags used for gating. */
-interface ResolvedCapabilities {
-    mode: "data" | "full";
-    /** Effective preview list (defaulted by mode when not provided). */
-    previews: PreviewKind[];
-    /** JSON Pointer paths whose children are editable; empty = no scoping. */
-    editablePaths: string[];
+interface ResolvedCapabilities extends ResolvedSchemaFields {
     /** No structural edits at all (readOnly shorthand). */
     locked: boolean;
     /** editablePaths is non-empty -- only designated subtrees are editable. */
@@ -293,12 +538,17 @@ interface UseDesignerStateArgs {
     onChange?: (schema: JsonSchema, uiSchema: UiSchemaMap) => void;
     readOnly?: boolean;
     capabilities?: SchemaDesignerCapabilities;
+    /** Optional resolver for non-local `$ref`s (registry id / URI); local $defs
+     * resolve automatically. Used to expand ref nodes (read-only) in the tree. */
+    refResolver?: RefResolver;
 }
 interface DesignerState {
     schema: JsonSchema;
     uiSchema: UiSchemaMap;
     selection: PropertyPath | null;
     readOnly: boolean;
+    /** Resolver for $ref expansion in the tree (undefined = local $defs only). */
+    refResolver?: RefResolver;
     /** Resolved capability profile (readOnly + editablePaths applied). */
     capabilities: ResolvedCapabilities;
     /** Whether the property at path may be renamed / deleted / retyped / reordered. */
@@ -306,13 +556,43 @@ interface DesignerState {
     /** Whether a child property may be added to the container at path (root = []). */
     canAddChild: (path: PropertyPath) => boolean;
     select: (path: PropertyPath | null) => void;
-    addProperty: (parentPath: PropertyPath, kind: "scalar" | "object" | "array") => void;
+    addProperty: (parentPath: PropertyPath, kind: NewPropertyKind) => void;
+    /** Add a branch to the oneOf property at path. */
+    addBranch: (path: PropertyPath) => void;
+    /** Remove the branch at path (a branch segment). */
+    removeBranch: (path: PropertyPath) => void;
+    /** Move the branch at path up (-1) or down (+1). */
+    moveBranch: (path: PropertyPath, direction: -1 | 1) => void;
+    /** Add an if/then/else conditional to the object at path (root when empty). */
+    addConditional: (objectPath: PropertyPath, combinator?: ConditionCombinator) => void;
+    /** Switch the AND/OR combinator for the conditionals of the object at path. */
+    setConditionalBehavior: (objectPath: PropertyPath, combinator: ConditionCombinator) => void;
+    /** Remove the conditional at path (a condition segment). */
+    removeConditional: (path: PropertyPath) => void;
+    /** Write the `if` schema of the conditional at path. */
+    setCondition: (path: PropertyPath, ifSchema: JsonSchemaProperty) => void;
+    /** Add an empty `else` branch to the conditional at path. */
+    addElse: (path: PropertyPath) => void;
+    /** Remove the `else` branch from the conditional at path. */
+    removeElse: (path: PropertyPath) => void;
     deleteProperty: (path: PropertyPath) => void;
     renameProperty: (path: PropertyPath, nextKey: string) => void;
     moveProperty: (path: PropertyPath, direction: -1 | 1) => void;
     setRequired: (path: PropertyPath, required: boolean) => void;
     updateProperty: (path: PropertyPath, patch: Partial<JsonSchemaProperty>) => void;
-    changePropertyType: (path: PropertyPath, nextType: JsonSchemaProperty["type"]) => void;
+    changePropertyType: (path: PropertyPath, next: PropertyTypeChoice) => void;
+    /** Point the property at path at a definition (writes a local `$ref`). */
+    setReference: (path: PropertyPath, name: string) => void;
+    /** Add a new empty object definition to `$defs`. Selects the new node. */
+    addDefinition: (name?: string) => void;
+    /** Rename a `$defs` entry; rewrites every local `$ref` that targets it. */
+    renameDefinition: (oldName: string, newName: string) => void;
+    /** Remove an unused `$defs` entry (blocked while any `$ref` targets it). */
+    removeDefinition: (name: string) => void;
+    /** Replace the whole JSON Schema (from the editable JSON Schema source tab). */
+    replaceSchema: (schema: JsonSchema) => void;
+    /** Replace the whole UI Schema map (from the editable UI Schema source tab). */
+    replaceUiSchema: (uiSchema: UiSchemaMap) => void;
     setEnum: (path: PropertyPath, choices: EnumChoice[]) => void;
     setUiEntry: (path: PropertyPath, entry: UISchema | undefined) => void;
     setTableHints: (path: PropertyPath, hints: TableHints) => void;
@@ -321,6 +601,29 @@ interface DesignerState {
     setRootLayoutRows: (rows: UILayoutConfig["rows"]) => void;
     setScopedLayoutRows: (scopePath: PropertyPath, rows: UILayoutConfig["rows"]) => void;
     setScopedLayoutOptions: (scopePath: PropertyPath, options: Pick<UILayoutConfig, "direction" | "gap" | "labels" | "compact">) => void;
+    /** Replace a scope's group definitions (empty clears groups -> flat rows). */
+    setScopedLayoutGroups: (scopePath: PropertyPath, groups: UILayoutConfig["groups"]) => void;
+    /** Replace the rows of one group within a scope. */
+    setScopedGroupRows: (scopePath: PropertyPath, groupIndex: number, rows: UILayoutRowConfig[]) => void;
+    /** Switch a scope between flat rows and groups, carrying placements over. */
+    setScopedLayoutMode: (scopePath: PropertyPath, mode: "rows" | "groups") => void;
+    /** Append an empty group to a scope. */
+    addLayoutGroup: (scopePath: PropertyPath, label?: string) => void;
+    /** Rename one group of a scope. */
+    renameLayoutGroup: (scopePath: PropertyPath, groupIndex: number, label: string) => void;
+    /** Remove one group; removing the last flattens its rows back to flat rows. */
+    removeLayoutGroup: (scopePath: PropertyPath, groupIndex: number) => void;
+    /** Move one group left (-1) or right (+1). */
+    moveLayoutGroup: (scopePath: PropertyPath, groupIndex: number, direction: -1 | 1) => void;
+    /** Set (or clear) a group's show/hide rule. */
+    setLayoutGroupRule: (scopePath: PropertyPath, groupIndex: number, rule: UILayoutGroupConfig["rule"]) => void;
+    /** Choose the group presentation ("tabs", "stepper", "sections", ...). */
+    setScopedLayoutVariant: (scopePath: PropertyPath, variant: UILayoutConfig["variant"]) => void;
+    /** Place a property into a group's row, or back in the pool (null target). */
+    placeFieldInGroup: (scopePath: PropertyPath, key: string, target: {
+        groupIndex: number;
+        rowIndex: number;
+    } | null) => void;
     setGlobalOptions: (options: UISchemaOptions | undefined) => void;
 }
 declare function useDesignerState(args: UseDesignerStateArgs): DesignerState;
@@ -359,6 +662,13 @@ interface SchemaDesignerProps {
     capabilities?: SchemaDesignerCapabilities;
     /** Option descriptors for custom widgets, keyed by widget name (merged over built-ins). */
     widgetOptions?: Record<string, WidgetOptionDef[]>;
+    /**
+     * Optional resolver for non-local `$ref`s (schema-registry id / canonical
+     * URI). Local `#/$defs` refs resolve automatically. When provided, ref nodes
+     * are expanded read-only in the tree. Synchronous -- pre-load referenced
+     * schemas and pass a lookup.
+     */
+    refResolver?: RefResolver;
 }
 declare function SchemaDesigner(props: SchemaDesignerProps): React.ReactElement;
 
@@ -528,4 +838,4 @@ interface FormSettingsSheetProps {
 }
 declare function FormSettingsSheet({ open, onOpenChange, state, }: FormSettingsSheetProps): React.ReactElement;
 
-export { type CapabilitiesValidation, DataTab, type DesignerModel, type DesignerState, type EnumChoice, EnumEditor, FormLayoutDesigner, FormSettingsSheet, Inspector, type LayoutScope, PreviewPane, type PropertyKind, type PropertyNode, type PropertyPath, PropertyTree, type ResolvedCapabilities, SchemaDesigner, type SchemaDesignerCapabilities, type SchemaDesignerProps, type TableHints, TableHintsTab, TablePreview, UITab, type UiSchemaMap, type UseDesignerStateArgs, type WidgetChoice, addProperty, buildPropertyTree, capabilitiesSchema, changePropertyType, childContainer, childrenOf, compatibleWidgets, deleteProperty, embedUiSchema, getProperty, getScopedLayout, getUiEntryAtPath, isContainer, layoutScopes, moveProperty, newProperty, orderedKeys, pathKey, propertyKind, readEnumChoices, readTableHints, renameProperty, resolveCapabilities, samePath, sampleRows, setEnum, setGlobalOptions, setPropertyLayout, setRequired, setRootLayout, setRootLayoutRows, setScopedLayoutOptions, setScopedLayoutRows, setTableHints, setUiEntry, updateProperty, useDesignerState, validateCapabilities };
+export { type CapabilitiesValidation, type ChildSlot, type ConditionCombinator, DataTab, type DesignerModel, type DesignerState, type EnumChoice, EnumEditor, FormLayoutDesigner, FormSettingsSheet, Inspector, type LayoutScope, type NewPropertyKind, type PathSegment, type PathSlot, type PreviewKind, PreviewPane, type PropertyKind, type PropertyNode, type PropertyPath, PropertyTree, type PropertyTypeChoice, type ResolvedCapabilities, SchemaDesigner, type SchemaDesignerCapabilities, type SchemaDesignerProps, type SlotKind, type TableHints, TableHintsTab, TablePreview, UITab, type UiSchemaMap, type UseDesignerStateArgs, type WidgetChoice, addBranch, addConditional, addDefinition, addElse, addLayoutGroup, addProperty, branch, buildPropertyTree, capabilitiesSchema, changePropertyType, childContainer, childSlots, compatibleWidgets, condition, def, definitionUsageCount, definitionsOf, deleteProperty, embedUiSchema, getProperty, getScopedLayout, getUiEntryAtPath, isContainer, isReservedKey, layoutScopes, moveBranch, moveLayoutGroup, moveProperty, newBranch, newCondition, newProperty, orderedKeys, parsePathKey, pathKey, placeFieldInGroup, prop, propertyKind, readEnumChoices, readTableHints, removeBranch, removeConditional, removeDefinition, removeElse, removeLayoutGroup, renameDefinition, renameLayoutGroup, renameProperty, resolveCapabilities, samePath, sameSegment, sampleRows, schemaAsRootProp, setCondition, setConditionalBehavior, setEnum, setGlobalOptions, setLayoutGroupRule, setPropertyLayout, setReference, setRequired, setRootLayout, setRootLayoutRows, setScopedGroupRows, setScopedLayoutGroups, setScopedLayoutMode, setScopedLayoutOptions, setScopedLayoutRows, setScopedLayoutVariant, setTableHints, setUiEntry, slot, updateProperty, useDesignerState, validateCapabilities };