lineadraw 0.9.0 → 0.10.0

package/lineadraw.d.ts

@@ -1,6 +1,7 @@
 // GENERATED — do not edit. Typings for the virtual "lineadraw" and
 // "lineadraw/helpers" modules block scripts import from, emitted from
-// packages/core/src/extensions/{scriptTypes,scriptHelpers}.ts. Regenerate with:
+// packages/core/src/extensions/{scriptTypes,scriptHelpers,scriptBooleans}.ts.
+// Regenerate with:
 //   npm run gen:lineadraw-dts -w @lineadraw/core
 
 declare module "lineadraw" {
@@ -204,9 +205,12 @@ declare module "lineadraw" {
       /** Applied last, about the pivot (the first input point). */
       rotation?: number;
       scale?: number;
-      params?: Record<string, number | string | boolean | readonly number[] | readonly string[]>;
-      /** Input points in the PARENT's local coords; the first is the pivot. */
-      inputs?: readonly Vec2Like[];
+      params?: Record<string, number | string | boolean | readonly number[] | readonly string[] | JsonValue>;
+      /** Input points in the PARENT's local coords (the first is the pivot):
+       * in pick order, or by input name for a block declaring an `inputs`
+       * table. Object ids (a `host`, picked objects) only on instances a
+       * script ADDS to the document — a block's own children can't reference. */
+      inputs?: readonly Vec2Like[] | Readonly<Record<string, Vec2Like | readonly Vec2Like[] | string | readonly string[]>>;
   }>;
   /** A table cell: plain text, or text with merge / alignment / style. */
   export type TableCellInput = string | {
@@ -302,7 +306,7 @@ declare module "lineadraw" {
       modelCenter?: Vec2Like;
       /** Drawing-scale denominator (model mm per paper mm); 1:50 => 50. */
       scale?: number;
-      /** Pinned: no pan/zoom-through, no move/resize grips. */
+      /** Pinned: no pan/zoom-through, no move/resize handles. */
       locked?: boolean;
       /** Layer ids hidden in this viewport only. */
       hiddenLayerIds?: readonly string[];
@@ -448,9 +452,10 @@ declare module "lineadraw" {
       definitionId: string;
       rotation: number;
       scale: number;
-      params: Readonly<Record<string, number | string | boolean | readonly number[] | readonly string[]>>;
-      /** World points and/or referenced object ids, in pick order. */
-      inputs: readonly (Vec2 | string)[];
+      params: Readonly<Record<string, number | string | boolean | readonly number[] | readonly string[] | JsonValue>>;
+      /** World points and/or referenced object ids: in pick order, or by
+       * input name for a block declaring an `inputs` table. */
+      inputs: readonly (Vec2 | string)[] | Readonly<Record<string, Vec2 | string | readonly Vec2[] | readonly string[]>>;
   }>;
   /** Paper-space window into model space; exists only in layout spaces. */
   export type Viewport = ObjectShape<{
@@ -641,6 +646,12 @@ declare module "lineadraw" {
    * value: it never appears in the `params` record `draw` receives.
    * `name` stays the unique key (paramVisibility can hide it by name). */
    | (ParamBase & {
+      /** Structured data the block owns (any JSON value) — no panel row;
+       * edited through handles, handle menus and actions. Typed by its
+       * default: `default: {} as Record<string, Wall>`. */
+      type: "data";
+      default: JsonValue;
+  }) | (ParamBase & {
       type: "label";
   })
   /** Layout only: 2–3 compact params on one panel row, each item's label a
@@ -711,12 +722,147 @@ declare module "lineadraw" {
    * declares (or a block's function form returns).
    */
   export type ParamDefs = readonly ParamDef[];
+  /**
+   * One declared input — a row of the `inputs` table a block or command
+   * spec declares. Inputs are read by `name` (`inputs.<name>`); `label` is
+   * the pick prompt. `types` limits object picks to those object types
+   * (empty / absent = any). Optional inputs are skipped with Enter.
+   */
+  export type InputDef = {
+      name: string;
+      label?: string;
+      description?: string;
+      type: "point";
+      optional?: boolean;
+  } | {
+      name: string;
+      label?: string;
+      description?: string;
+      type: "points";
+      /** Default 1. */
+      min?: number;
+      max?: number;
+      /** A polygon (closing segment previewed) rather than an open chain. */
+      closed?: boolean;
+  } | {
+      name: string;
+      label?: string;
+      description?: string;
+      type: "object";
+      types?: readonly ModelObject["type"][];
+      optional?: boolean;
+  } | {
+      name: string;
+      label?: string;
+      description?: string;
+      type: "objects";
+      types?: readonly ModelObject["type"][];
+      /** Default 1. */
+      min?: number;
+      max?: number;
+  } | {
+      name: string;
+      label?: string;
+      description?: string;
+      /** The block instance this one LIVES ON (a door on a floor plan): it
+       * draws in the host's frame and reads the host's `expose` as `host`;
+       * the host's `draw` sees it in `hosted`. Picked by clicking the host;
+       * `attach` turns the click into params. */
+      type: "host";
+      /** Accepted host DEFINITION ids (empty = any block). */
+      types?: readonly string[];
+  };
+  /** A custom handle's marker shape (cosmetic: triangle / arrow = "pull this
+   * way", diamond = "options here", plus / minus = "add / remove"). */
+  export type HandleShape = "square" | "circle" | "diamond" | "triangle" | "arrow" | "double-arrow" | "plus" | "minus";
+  /** Icons a button handle may show (lucide glyphs). */
+  export type HandleIcon = "plus" | "minus" | "x" | "check" | "flip-horizontal" | "flip-vertical" | "rotate-cw" | "rotate-ccw" | "refresh-cw" | "arrow-left-right" | "arrow-up-down" | "settings-2" | "ellipsis";
+  /** An inputs table. */
+  export type InputDefs = readonly InputDef[];
+  /** A command's inputs table: a `host` is a block-only input. */
+  export type CommandInputDefs = readonly Exclude<InputDef, {
+      type: "host";
+  }>[];
+  /** The object type an object input's `types` filter admits. */
+  type PickedObject<D> = D extends {
+      types: readonly (infer T)[];
+  } ? [T] extends [never] ? ModelObject : Extract<ModelObject, {
+      type: T;
+  }> : ModelObject;
+  type DrawInputValue<D> = D extends {
+      type: "point";
+  } ? D extends {
+      optional: true;
+  } ? Vec2 | undefined : Vec2 : D extends {
+      type: "points";
+  } ? readonly Vec2[] : D extends {
+      type: "object";
+  } ? PickedObject<D> | null : readonly PickedObject<D>[];
+  /**
+   * What a block's `draw` receives as `inputs` for a table: points
+   * pivot-localized, object inputs as the referenced object (pivot-local) or
+   * null once deleted, lists as arrays (deleted objects dropped).
+   */
+  export type DrawInputs<I extends InputDefs> = {
+      readonly [D in I[number] as D extends {
+          type: "host";
+      } ? never : D["name"]]: DrawInputValue<D>;
+  };
+  type StoredInputValue<D> = D extends {
+      type: "host";
+  } ? string : D extends {
+      type: "point";
+  } ? Vec2Like : D extends {
+      type: "points";
+  } ? readonly Vec2Like[] : D extends {
+      type: "object";
+  } ? string : readonly string[];
+  /**
+   * Inputs as STORED for a table (what `place` returns and `previewInputs`
+   * holds): points in world coords ([x, y] accepted), objects as ids.
+   * Optional inputs may be left out.
+   */
+  export type StoredInputs<I extends InputDefs> = {
+      readonly [D in I[number] as D extends {
+          optional: true;
+      } ? never : D["name"]]: StoredInputValue<D>;
+  } & {
+      readonly [D in I[number] as D extends {
+          optional: true;
+      } ? D["name"] : never]?: StoredInputValue<D>;
+  };
+  type CommandInputValue<D> = D extends {
+      type: "point";
+  } ? D extends {
+      optional: true;
+  } ? Vec2 | undefined : Vec2 : D extends {
+      type: "points";
+  } ? readonly Vec2[] : D extends {
+      type: "object";
+  } ? D extends {
+      optional: true;
+  } ? string | undefined : string : readonly string[];
+  /**
+   * What a command's `ctx.inputs` is: the points in label order for a
+   * labels array, a record by name for a table (objects as ids — read them
+   * with `document.getObject`).
+   */
+  export type CommandInputs<I> = I extends readonly string[] ? readonly Vec2[] : I extends CommandInputDefs ? {
+      readonly [D in I[number] as D["name"]]: CommandInputValue<D>;
+  } : readonly Vec2[];
   /** The value an enum option denotes (its string, or `value` of the record form). */
   type OptionValue<O extends ParamOption> = O extends string ? O : O extends {
       value: infer V extends string;
   } ? V : never;
+  /** Any JSON value — what a `data` param holds. */
+  export type JsonValue = string | number | boolean | null | readonly JsonValue[] | {
+      readonly [key: string]: JsonValue;
+  };
   /** The runtime value type of one `params` table entry. */
   type ParamValue<Q extends ParamDef> = Q extends {
+      type: "data";
+      default: infer D;
+  } ? D : Q extends {
       type: "enum";
   } ? OptionValue<Q["options"][number]> : Q extends {
       type: "number";
@@ -889,6 +1035,9 @@ declare module "lineadraw" {
       authors?: readonly string[];
       tags?: readonly string[];
       dependencies?: readonly string[];
+      /** The declared inputs table, when the block has one (instances then
+       * store their inputs by name). */
+      inputs?: InputDefs;
   };
   /** A command module's identity/metadata (from its exports). */
   export type CommandInfo = {
@@ -898,8 +1047,11 @@ declare module "lineadraw" {
       version?: string;
       authors?: readonly string[];
       tags?: readonly string[];
-      /** Declared point inputs (labels), picked or supplied before `run`. */
-      inputs?: readonly string[];
+      /** Declared inputs, picked or supplied before `run`: point labels
+       * (positional) or an inputs table (by name). */
+      inputs?: readonly string[] | CommandInputDefs;
+      /** Asks during the run, so headless runners refuse it. */
+      requiresEditor?: boolean;
       /** Declared parameters (same table as a block's), prompted or supplied
        * before `run`. */
       params?: readonly ParamDef[];
@@ -1271,10 +1423,43 @@ declare module "lineadraw" {
           label?: string;
           referencePoint?: Vec2Like;
       }): Promise<Vec2>;
-      /** Await one object click; resolves the object's id. */
+      /** Await one object click; resolves the object's id. `types` limits
+       * what can be picked (empty / absent = any). */
       pickObject(opts?: {
           label?: string;
+          types?: readonly ModelObject["type"][];
       }): Promise<string>;
+      /** Await a chain of snapped points (rubber band from the previous);
+       * Enter / Esc finishes once `min` (default 1) is met, `max` ends it,
+       * `closed` previews the closing segment. Rejects on cancel below `min`. */
+      pickPoints(opts?: {
+          label?: string;
+          min?: number;
+          max?: number;
+          closed?: boolean;
+          referencePoint?: Vec2Like;
+      }): Promise<Vec2[]>;
+      /** Await several object picks (each once); Enter / Esc finishes once
+       * `min` (default 1) is met. Rejects on cancel below `min`. */
+      pickObjects(opts?: {
+          label?: string;
+          types?: readonly ModelObject["type"][];
+          min?: number;
+          max?: number;
+      }): Promise<string[]>;
+      /**
+       * Ask several values in ONE dialog — the same form a command's `params`
+       * table shows, from a params table (number / string / boolean / enum …):
+       *   const { count, label } = await editor.ask(
+       *     [{ name: "count", type: "number", default: 3 },
+       *      { name: "label", type: "string", default: "A" }],
+       *     { title: "Array" });
+       * Resolves the values typed by the table; rejects on cancel.
+       */
+      ask<const P extends ParamDefs>(params: P, opts?: {
+          title?: string;
+          description?: string;
+      }): Promise<ParamValues<P>>;
       /** Await a typed value from a small input dialog. */
       prompt(message: string, opts?: {
           initial?: string;
@@ -1286,20 +1471,21 @@ declare module "lineadraw" {
       /** Trigger a command by id — like the user pressing its hotkey. A macro
        * takes its declared `inputs` / `params` up front (params passed skip its
        * params dialog). */
-      runCommand(id: string, inputs?: readonly Vec2Like[], params?: Readonly<Record<string, unknown>>): Promise<void>;
+      runCommand(id: string, inputs?: readonly Vec2Like[] | Readonly<Record<string, Vec2Like | readonly Vec2Like[] | string | readonly string[]>>, params?: Readonly<Record<string, unknown>>): Promise<void>;
   }
   /**
    * What `run` receives. `document` is the Drawing; `editor` the interactive
-   * surface when there is one; `inputs` the points the command's declared
-   * `inputs` labels produced (picked in the editor, or supplied by the
-   * caller), in label order; `params` the values of the declared `params`
-   * table (asked for in a dialog in the editor, or passed by the caller;
-   * omitted ones take their defaults).
+   * surface when there is one; `inputs` what the command's declared `inputs`
+   * produced (picked in the editor — object inputs take the selection first
+   * — or supplied by the caller): the points in label order for labels, a
+   * record by name for a table (see CommandInputs); `params` the values of
+   * the declared `params` table (asked for in a dialog in the editor, or
+   * passed by the caller; omitted ones take their defaults).
    */
-  export interface CommandContext<P = Readonly<Record<string, unknown>>> {
+  export interface CommandContext<P = Readonly<Record<string, unknown>>, I = readonly Vec2[]> {
       document: Drawing;
       editor?: EditorSurface;
-      inputs: readonly Vec2[];
+      inputs: I;
       params: P;
   }
 
@@ -1371,9 +1557,164 @@ declare module "lineadraw" {
   export interface PlaceProps<P = BlockParams> {
     params: ParamValues<P>;
     pickPoint: (label?: string) => Promise<Vec2>;
-    pickObject: (label?: string) => Promise<string>;
+    pickObject: (
+      label?: string,
+      opts?: { types?: readonly ModelObject["type"][] },
+    ) => Promise<string>;
+    /** A chain of points; Enter / Esc finishes once `min` (default 1) is met. */
+    pickPoints: (
+      label?: string,
+      opts?: { min?: number; max?: number; closed?: boolean },
+    ) => Promise<Vec2[]>;
+    /** Several objects; Enter / Esc finishes once `min` (default 1) is met. */
+    pickObjects: (
+      label?: string,
+      opts?: {
+        types?: readonly ModelObject["type"][];
+        min?: number;
+        max?: number;
+      },
+    ) => Promise<string[]>;
+  }
+
+  // ——— Custom handles ———
+
+  /** The names of a params table's NUMBER parameters. */
+  export type NumberParamName<P> = {
+    [K in keyof ParamValues<P>]: ParamValues<P>[K] extends number ? K : never;
+  }[keyof ParamValues<P>] &
+    string;
+
+  /**
+   * What a handle's drag / click / action changes: params by name (numbers
+   * are clamped to the param's min / max), and — for a block with an
+   * `inputs` table — inputs by name in block-LOCAL coordinates.
+   */
+  export interface HandlePatch<P = BlockParams, S = never> {
+    params?: Partial<ParamValues<P>>;
+    inputs?: S;
+  }
+
+  /** What a `drag` function receives — the values at drag START (not
+   * compounding) plus where the cursor is, already constrained. */
+  export interface HandleDragEvent<P = BlockParams, D = unknown> {
+    params: ParamValues<P>;
+    inputs: D;
+    /** The cursor, block-local, after the handle's constraint. */
+    point: Vec2;
+    /** The handle's position when the drag started. */
+    start: Vec2;
+    /** `along`: signed distance from its origin; `around`: the angle
+     * (radians); free: undefined. */
+    value: number | undefined;
   }
 
+  /**
+   * One custom handle on a selected instance, in block-LOCAL coordinates
+   * (pivot at the origin, before the instance's rotation / scale). Give it
+   * ONE drag behaviour — `param` (the constrained value → a number param),
+   * `input` (moves a point input), or `drag` (anything else) — or mark it
+   * `fixed`; `click` makes it a button (a press without a move).
+   */
+  /**
+   * A button in a handle's hover menu, or in the instance's context menu
+   * (the block's top-level `actions`). One undo step.
+   */
+  export interface BlockAction<P = BlockParams, D = unknown, S = never> {
+    label: string;
+    icon?: HandleIcon;
+    /** Pick a point first (snapping as usual); `run` receives it,
+     * block-local, as `point`. Esc cancels. */
+    pick?: "point";
+    run: (s: {
+      params: ParamValues<P>;
+      inputs: D;
+      point?: Vec2;
+    }) => HandlePatch<P, S> | undefined;
+  }
+
+  /** A field in a handle's hover menu: a parameter by name, or a field
+   * bound to any value (one wall's thickness inside a `data` param), with
+   * `set` returning what an edit changes. Each edit is one undo step. */
+  export type MenuField<P = BlockParams, S = never> =
+    | (keyof ParamValues<P> & string)
+    | {
+        /** The field: any value parameter row without name / default
+         * (`{ type: "number", label: "Thickness", min: 50 }`). */
+        field: Record<string, unknown> & { type: string; label?: string };
+        value: unknown;
+        set: (value: never) => HandlePatch<P, S> | undefined;
+      };
+
+  interface HandleBase<P, D, S> {
+    /** Stable within the instance (hover / drag continuity, tests). */
+    id: string;
+    /** Tooltip, and the hover menu's title. */
+    label?: string;
+    /** Not draggable (a button, or menu-only). */
+    fixed?: boolean;
+    /** The constrained value → this NUMBER param. */
+    param?: NumberParamName<P>;
+    drag?: (e: HandleDragEvent<P, D>) => HandlePatch<P, S> | undefined;
+    /** Button behaviour: one undo step; the selection doesn't change. */
+    click?: (s: {
+      params: ParamValues<P>;
+      inputs: D;
+    }) => HandlePatch<P, S> | undefined;
+    /** Fields shown in the hover menu (see MenuField). */
+    menu?: readonly MenuField<P, S>[];
+    /** Buttons in the hover menu. */
+    actions?: readonly BlockAction<P, D, S>[];
+  }
+
+  /**
+   * One custom point handle on a selected instance, in block-LOCAL
+   * coordinates (pivot at the origin, before the instance's rotation /
+   * scale). Give it ONE drag behaviour — `param` (the constrained value →
+   * a number param), `input` (moves a point input), or `drag` (anything
+   * else) — or mark it `fixed`; `click` makes it a button.
+   */
+  export interface PointHandleDef<P = BlockParams, D = unknown, S = never>
+    extends HandleBase<P, D, S> {
+    kind?: "point";
+    at: Vec2Like;
+    shape?: HandleShape;
+    /** Radians — points a triangle / arrow (default: the constraint axis). */
+    direction?: number;
+    /** Constrain to a line through `origin`; value = signed distance. */
+    along?: {
+      origin: Vec2Like;
+      direction: Vec2Like;
+      min?: number;
+      max?: number;
+    };
+    /** Constrain to the circle through `at` around `center`; value =
+     * the angle (radians). */
+    around?: { center: Vec2Like };
+    /** Move a point input: `"hinge"`, or one point of a list
+     * (`{ name: "path", index: 2 }`). Replaces that point's default handle. */
+    input?: string | { name: string; index: number };
+    /** A lucide glyph drawn in the handle — the button look. */
+    icon?: HandleIcon;
+  }
+
+  /**
+   * A line handle (a wall face, an offset): drawn while hovered, dragged
+   * along its NORMAL by default (value = the signed offset, left of
+   * from → to positive); `along` gives another direction.
+   */
+  export interface LineHandleDef<P = BlockParams, D = unknown, S = never>
+    extends HandleBase<P, D, S> {
+    kind: "line";
+    from: Vec2Like;
+    to: Vec2Like;
+    along?: { direction: Vec2Like; min?: number; max?: number };
+  }
+
+  export type HandleDef<P = BlockParams, D = unknown, S = never> =
+    | PointHandleDef<P, D, S>
+    | LineHandleDef<P, D, S>;
+
   // ——— defineBlock ———
 
   /**
@@ -1423,6 +1764,7 @@ declare module "lineadraw" {
   export interface BlockSpec<
     P extends ParamDefs = readonly [],
     Pl extends PlaceSpec<P> | undefined = undefined,
+    I extends InputDefs | undefined = undefined,
   > {
     id: string;
     name: string;
@@ -1447,16 +1789,58 @@ declare module "lineadraw" {
     paramVisibility?: (props: {
       params: ParamValues<P>;
     }) => Partial<Record<keyof ParamValues<P> & string, boolean>>;
-    /** Point labels (fixed picks) or an interactive function (see PlaceSpec). */
-    place?: Pl;
+    /**
+     * The block's declared inputs, by name — picked in table order at
+     * insertion (`points` until Enter, `objects` from the selection when
+     * it fits), and read in `draw` as `inputs.<name>`. Instances store
+     * them by name, so reordering or adding inputs never breaks existing
+     * instances. Replaces `place` labels.
+     */
+    inputs?: I;
+    /**
+     * Point labels (fixed picks) or an interactive function (see
+     * PlaceSpec). With an `inputs` table, only the function form: it
+     * returns the inputs by name (for conditional or chained picks).
+     */
+    place?: [I] extends [InputDefs]
+      ? (props: PlaceProps<P>) => StoredInputs<I> | Promise<StoredInputs<I>>
+      : Pl;
     /**
      * Optional inputs used for the block's PREVIEW (panel/Library
      * thumbnails, marketplace cards, save-time dry run) instead of the
      * generic stand-in picks — curate them so the preview shows the block
-     * at its best. Same shape `place` produces; points accept [x, y];
-     * object-id strings resolve to a stand-in line in previews.
+     * at its best. Same shape `place` produces (by name with an
+     * `inputs` table); points accept [x, y]; object-id strings resolve to
+     * a stand-in line in previews.
      */
-    previewInputs?: PreviewInputs<Pl>;
+    previewInputs?: [I] extends [InputDefs] ? StoredInputs<I> : PreviewInputs<Pl>;
+    /**
+     * Custom handles on a selected instance — pure, block-local, re-run
+     * whenever params / inputs change, so positions follow the values (a
+     * width handle sits at the width). See HandleDef.
+     */
+    handles?: (props: {
+      params: ParamValues<P>;
+      inputs: [I] extends [InputDefs] ? DrawInputs<I> : PlaceInputs<Pl>;
+      /** Hosted blocks: the host's `expose` result (null when this block
+       * has no host). Shape it as the host documents it. */
+      host: any;
+      /** Hosting: what lives on this instance — each one's `expose`. */
+      hosted: readonly HostedBlock[];
+    }) => readonly HandleDef<
+      P,
+      [I] extends [InputDefs] ? DrawInputs<I> : PlaceInputs<Pl>,
+      [I] extends [InputDefs] ? Partial<StoredInputs<I>> : never
+    >[];
+    /**
+     * Actions in the instance's context menu (right-click) — e.g. "Add
+     * window" with `pick: "point"`. Static records; one undo step each.
+     */
+    actions?: readonly BlockAction<
+      P,
+      [I] extends [InputDefs] ? DrawInputs<I> : PlaceInputs<Pl>,
+      [I] extends [InputDefs] ? Partial<StoredInputs<I>> : never
+    >[];
     /**
      * Children in block-LOCAL coordinates (pure, runs per evaluation).
      * The first point input is the pivot; `inputs` arrive localized
@@ -1466,12 +1850,51 @@ declare module "lineadraw" {
      */
     draw: (props: {
       params: ParamValues<P>;
-      inputs: PlaceInputs<Pl>;
+      inputs: [I] extends [InputDefs] ? DrawInputs<I> : PlaceInputs<Pl>;
       /** The document's text / dimension styles by id — for blocks that
        * lay out with real text sizes. Pass a picked id on to children as
        * `styleId` to let them follow the style. */
       styles: BlockStyles;
+      /** Hosted blocks: the host's `expose` result (null when this block
+       * has no host). Shape it as the host documents it. */
+      host: any;
+      /** Hosting: what lives on this instance — each one's `expose`. */
+      hosted: readonly HostedBlock[];
     }) => BlockChildInput[];
+    /**
+     * Hosting (blocks living on blocks — a door on a floor plan): JSON
+     * this block PUBLISHES for others to read — a host its `walls`, a
+     * door its `cut`. It sees only its own params, which is what keeps
+     * a host and what lives on it from looping.
+     */
+    expose?: (props: { params: ParamValues<P> }) => JsonValue;
+    /**
+     * A hosted block (one with a `host` input): turns the click on the
+     * host — host-local, with the host's exposed data — into this
+     * instance's params (`{ wall: "B/1-2", at: 1200 }`).
+     */
+    attach?: (props: {
+      host: any;
+      point: Vec2;
+      params: ParamValues<P>;
+    }) => Partial<ParamValues<P>>;
+    /**
+     * A hosted block's stand-in host for previews, Library / marketplace
+     * thumbnails and the save-time dry run: the JSON a real host's
+     * `expose` would return. The preview places the block as if its host
+     * were clicked at the origin (`attach`), and `draw` gets this as
+     * `host`. Add a flag (`preview: true`) to draw extra context there,
+     * e.g. a stretch of wall around a door.
+     */
+    previewHost?: JsonValue;
+  }
+
+  /** One block living on a host, as the host's `draw` sees it. */
+  export interface HostedBlock {
+    id: string;
+    definitionId: string;
+    /** Its `expose` result (null without one). */
+    exposed: any;
   }
 
   /**
@@ -1510,13 +1933,21 @@ declare module "lineadraw" {
   >(
     spec: BlockSpec<P, (props: PlaceProps<P>) => R>,
   ): BlockSpec<P, (props: PlaceProps<P>) => R>;
+  // An `inputs` table: `draw`'s inputs are typed by name from it.
+  export function defineBlock<
+    const P extends ParamDefs = readonly [],
+    const I extends InputDefs = readonly [],
+  >(spec: BlockSpec<P, undefined, I>): BlockSpec<P, undefined, I>;
 
   // ——— Commands (macro scripts) ———
   // Drawing / EditorSurface / CommandContext are emitted from scriptTypes.ts
   // above (the script-facing mirror of core's real interfaces).
 
   /** One user command (macro): identity, metadata, and the `run` body. */
-  export interface CommandSpec<P extends ParamDefs = readonly []> {
+  export interface CommandSpec<
+    P extends ParamDefs = readonly [],
+    I extends readonly string[] | CommandInputDefs = readonly [],
+  > {
     id: string;
     name: string;
     description?: string;
@@ -1524,13 +1955,24 @@ declare module "lineadraw" {
     authors?: readonly string[];
     tags?: readonly string[];
     /**
-     * Point inputs the command needs, as labels (`["Start", "End"]`). In
-     * the editor each is picked in turn before `run` (rubber-band from the
-     * previous pick); a headless or remote caller supplies them up front.
-     * They arrive as `ctx.inputs`, in this order. This is what lets one
-     * script run in the editor, from a shell, and from an agent alike.
+     * The inputs the command needs: an inputs TABLE
+     * (`[{ name: "doors", type: "objects", types: ["block"] }]`, arriving
+     * as `ctx.inputs.doors`), or point labels (`["Start", "End"]`,
+     * arriving as `ctx.inputs` in order). In the editor they are acquired
+     * before `run` — object inputs take the current selection when it
+     * fits, the rest are picked; a headless or remote caller supplies them
+     * up front (by name for a table). This is what lets one script run in
+     * the editor, from a shell, and from an agent alike.
+     */
+    inputs?: I;
+    /**
+     * The command ASKS during the run (`editor.pickPoint`, `prompt`,
+     * `ask` — the next question depends on the last answer), so it can't
+     * run headless: CLI / agent / SDK runners refuse it up front instead of
+     * failing halfway. Leave it off for commands whose `inputs` /
+     * `params` cover everything.
      */
-    inputs?: readonly string[];
+    requiresEditor?: boolean;
     /**
      * Parameters the command needs — the same table a block's `params`
      * declares (number / string / boolean / enum / label rows), or a
@@ -1546,7 +1988,7 @@ declare module "lineadraw" {
      * uncaught error rolls everything back. A return value is handed to
      * the caller (the agent tool / CLI) — the editor ignores it.
      */
-    run(ctx: CommandContext<ParamValues<P>>): unknown;
+    run(ctx: CommandContext<ParamValues<P>, CommandInputs<I>>): unknown;
   }
 
   /**
@@ -1572,9 +2014,10 @@ declare module "lineadraw" {
    *     },
    *   });
    */
-  export function defineCommand<const P extends ParamDefs = readonly []>(
-    spec: CommandSpec<P>,
-  ): CommandSpec<P>;
+  export function defineCommand<
+    const P extends ParamDefs = readonly [],
+    const I extends readonly string[] | CommandInputDefs = readonly [],
+  >(spec: CommandSpec<P, I>): CommandSpec<P, I>;
 }
 
 declare module "lineadraw/helpers" {
@@ -1607,4 +2050,29 @@ declare module "lineadraw/helpers" {
   export const dot: (a: Vec2, b: Vec2) => number;
   /** Rotate vector by `angle` (radians, CCW). */
   export const rotate: (p: Vec2, angle: number) => Vec2;
+  /** A point as scripts write it: [x, y] or { x, y }. */
+  export type PointLike = readonly [number, number] | {
+      readonly x: number;
+      readonly y: number;
+  };
+  /** A polygon: one ring of points (implicitly closed), or several rings —
+   * the first the outer boundary, the rest holes. */
+  export type PolygonLike = readonly PointLike[] | readonly (readonly PointLike[])[];
+  /** A result ring: closed implicitly (the first point is not repeated). */
+  export type Ring = {
+      x: number;
+      y: number;
+  }[];
+  /**
+   * The union of polygons: overlapping walls become one outline. Returns
+   * every ring of the result — outer boundaries and holes alike. Draw them as
+   * closed polylines, or hand them all to ONE hatch (`loops: rings.map((r) =>
+   * ({ points: r }))`): hatches fill even-odd, so holes stay holes.
+   */
+  export const union: (...polygons: PolygonLike[]) => Ring[];
+  /** `subject` minus every clip polygon (openings cut from a wall). Same
+   * result rings as `union`. */
+  export const difference: (subject: PolygonLike, ...clips: PolygonLike[]) => Ring[];
+  /** Where ALL the polygons overlap. Same result rings as `union`. */
+  export const intersection: (...polygons: PolygonLike[]) => Ring[];
 }