lineadraw 0.8.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" {
@@ -10,20 +11,33 @@ declare module "lineadraw" {
       y: number;
   };
   export type Vec2Like = Vec2 | readonly [number, number];
+  /** An axis-aligned box (mm). */
+  export type Box = {
+      minX: number;
+      minY: number;
+      maxX: number;
+      maxY: number;
+  };
+  /** Arrowhead styles (leaders, dimensions). */
+  export type ArrowType = "filled" | "open" | "tick" | "dot" | "none";
+  /** Print color remap: as authored, gray levels, or everything black. */
+  export type PrintPalette = "color" | "grayscale" | "monochrome";
   /** Polyline vertex; bulge = tan(sweep/4), 0 = straight. Accepts [x, y, bulge?]. */
-  export type PolylineVertexLike = {
+  export type PolylineVertexInput = {
       x: number;
       y: number;
       bulge?: number;
   } | readonly [number, number, number?];
-  /** Style overrides children may carry (otherwise inherited from the instance). */
-  export type BaseStyle = {
-      /** Id of a document layer this object sits on. For a block child: absent
-       * = the instance's layer (the portable default; an id unknown to the
-       * document falls back to it); a child that names another layer hides
-       * with that layer, while its color / line type / width still follow the
-       * instance unless it sets its own (ByBlock, as in CAD). For
-       * `document.add`: absent = the current layer. */
+  /** The fields every object input may carry: its layer and the style
+   * overrides (otherwise by layer — or, for a block child, by the instance). */
+  export type ObjectInputBase = {
+      /** The layer, by NAME or id. Absent: `document.add` uses the current
+       * layer, a block child the instance's (the portable default; an unknown
+       * name falls back to it too). A child on another layer hides with that
+       * layer, while its color / line type / width still follow the instance
+       * unless it sets its own (ByBlock, as in CAD). */
+      layer?: string;
+      /** The layer by id only — prefer `layer`. */
       layerId?: string;
       /** #rrggbb; absent = by layer. */
       color?: string;
@@ -37,37 +51,37 @@ declare module "lineadraw" {
       opacity?: number;
   };
   /**
-   * T plus the shared style fields, FLATTENED (the homomorphic map forces the
+   * T plus the shared input fields, FLATTENED (the homomorphic map forces the
    * intersection to resolve): hovers then list every member inline instead of
-   * the opaque `BaseStyle & { … }` — the block editor has no expand-type
-   * affordance, so the alias display is all a script author gets.
+   * the opaque `ObjectInputBase & { … }` — the block editor has no
+   * expand-type affordance, so the alias display is all a script author gets.
    */
-  type Styled<T> = {
-      [K in keyof (T & BaseStyle)]: (T & BaseStyle)[K];
+  type ObjectInputShape<T> = {
+      [K in keyof (T & ObjectInputBase)]: (T & ObjectInputBase)[K];
   } & {};
-  export type Line = Styled<{
+  export type LineInput = ObjectInputShape<{
       type: "line";
       a: Vec2Like;
       b: Vec2Like;
   }>;
   /** A point: paints as a round dot whose diameter is the lineWidth. */
-  export type Point = Styled<{
+  export type PointInput = ObjectInputShape<{
       type: "point";
       p: Vec2Like;
   }>;
-  export type Polyline = Styled<{
+  export type PolylineInput = ObjectInputShape<{
       type: "polyline";
       /** At least 2 vertices. */
-      points: readonly PolylineVertexLike[];
+      points: readonly PolylineVertexInput[];
       closed?: boolean;
   }>;
-  export type Circle = Styled<{
+  export type CircleInput = ObjectInputShape<{
       type: "circle";
       center: Vec2Like;
       radius: number;
   }>;
   /** Runs CCW from startAngle to endAngle (radians; DXF ARC convention). */
-  export type Arc = Styled<{
+  export type ArcInput = ObjectInputShape<{
       type: "arc";
       center: Vec2Like;
       radius: number;
@@ -75,7 +89,7 @@ declare module "lineadraw" {
       endAngle: number;
   }>;
   /** majorAxis = endpoint vector from center; ratio = minor/major in (0, 1]. */
-  export type Ellipse = Styled<{
+  export type EllipseInput = ObjectInputShape<{
       type: "ellipse";
       center: Vec2Like;
       majorAxis: Vec2Like;
@@ -83,11 +97,11 @@ declare module "lineadraw" {
       startAngle?: number;
       endAngle?: number;
   }>;
-  export type Hatch = Styled<{
+  export type HatchInput = ObjectInputShape<{
       type: "hatch";
       /** loops[0] = outer boundary, the rest are holes (even-odd). */
       loops: readonly {
-          points: readonly PolylineVertexLike[];
+          points: readonly PolylineVertexInput[];
       }[];
       fill?: {
           kind: "solid";
@@ -131,7 +145,7 @@ declare module "lineadraw" {
       height?: number;
       script?: "sub" | "super";
   };
-  export type Text = Styled<{
+  export type TextInput = ObjectInputShape<{
       type: "text";
       position: Vec2Like;
       content: string;
@@ -150,20 +164,11 @@ declare module "lineadraw" {
       /** The document text style to follow (name or id); absent = the first. */
       styleId?: string;
       /** Style overrides; absent keys inherit the document text style. */
-      styleOverride?: {
-          font?: string;
-          widthFactor?: number;
-          bold?: boolean;
-          italic?: boolean;
-          /** Cap height in mm (before `scale`). */
-          textHeight?: number;
-          arrowSize?: number;
-          arrowType?: "filled" | "open" | "tick" | "dot" | "none";
-      };
+      styleOverride?: TextStyleOverride;
       /** Size multiplier for height + arrow size. */
       scale?: number;
   }>;
-  export type Dimension = Styled<{
+  export type DimensionInput = ObjectInputShape<{
       type: "dimension";
       kind?: "linear" | "angular" | "radial" | "diameter";
       /** linear: 2+ chained points (measured point to point); angular: [vertex, a, b]; radial: [center, p]; diameter: [p1, p2]. */
@@ -188,33 +193,27 @@ declare module "lineadraw" {
       }[];
       /** The document dimension style to follow (name or id); absent = the first. */
       styleId?: string;
-      styleOverride?: {
-          textHeight?: number;
-          arrowSize?: number;
-          arrowType?: "filled" | "open" | "tick" | "dot" | "none";
-          /** "short" = a 2×overshoot tick across the dimension line. */
-          extensionType?: "long" | "short";
-          extensionOffset?: number;
-          extensionOvershoot?: number;
-          textOffset?: number;
-          precision?: number;
-      };
+      /** Style overrides; absent keys inherit the document dimension style. */
+      styleOverride?: DimStyleOverride;
       /** Annotation size multiplier (text/arrows/offsets). */
       scale?: number;
   }>;
   /** Nested block instance (inputs may hold points, never object references). */
-  export type Block = Styled<{
+  export type BlockInput = ObjectInputShape<{
       type: "block";
       definitionId: string;
       /** 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 TableCell = string | {
+  export type TableCellInput = string | {
       content?: string;
       /** Character formatting over `content`. */
       spans?: readonly TextSpan[];
@@ -231,7 +230,7 @@ declare module "lineadraw" {
   };
   /** Grid of text cells hanging right/down from `position` (top-left);
    * rows grow to fit their wrapped text. */
-  export type Table = Styled<{
+  export type TableInput = ObjectInputShape<{
       type: "table";
       position: Vec2Like;
       /** Column widths (mm, before `scale`). */
@@ -241,7 +240,7 @@ declare module "lineadraw" {
           minHeight?: number;
       }[];
       /** Row-major `cells[row][column]`, exactly rows × columns. */
-      cells: readonly (readonly TableCell[])[];
+      cells: readonly (readonly TableCellInput[])[];
       rotation?: number;
       scale?: number;
       /** Rows above the heavier header rule. */
@@ -252,16 +251,84 @@ declare module "lineadraw" {
       styleId?: string;
       styleOverride?: TextStyleOverride;
   }>;
+  /** Where a reference's file lives: a path (relative to the drawing's
+   * folder), a url, or EMBEDDED — an asset of the document holding it (add the
+   * file's bytes first with `document.addAsset`). */
+  export type ReferenceSource = {
+      kind: "path";
+      path: string;
+      cacheKey?: string;
+  } | {
+      kind: "url";
+      url: string;
+  } | {
+      kind: "asset";
+      assetId: string;
+  };
+  /** A file drawn in place — a .linea, DXF, DWG, PDF page or picture (PNG /
+   * JPEG). The file's origin lands at `position`; a picture draws at its
+   * natural size (96 dpi) times `scale`. */
+  export type ReferenceInput = ObjectInputShape<{
+      type: "reference";
+      format: "linea" | "dxf" | "dwg" | "pdf" | "png" | "jpg";
+      name: string;
+      source: ReferenceSource;
+      position: Vec2Like;
+      /** Radians CCW about `position`. */
+      rotation?: number;
+      scale?: number;
+      /** Flipped left-right (x → −x) before the rotation. */
+      mirrored?: boolean;
+      /** PDF: the 1-based page, drawn as vectors or rasterized. */
+      pdfPage?: number;
+      pdfMode?: "vector" | "raster";
+      /** The file's layers not drawn, by name. */
+      hiddenLayers?: readonly string[];
+      hidden?: boolean;
+      locked?: boolean;
+      /** Crop rectangle in file coordinates. */
+      clip?: Box;
+      /** Content bounds in file coordinates (the frame drawn before it loads). */
+      extent?: Box;
+  }>;
+  /** Paper-space window into model space; only in a layout (`document.add`
+   * with `layout`). */
+  export type ViewportInput = ObjectInputShape<{
+      type: "viewport";
+      /** The frame on the sheet (mm): bottom-left corner + size. */
+      rect: {
+          x: number;
+          y: number;
+          w: number;
+          h: number;
+      };
+      /** The model point shown at the frame's centre. */
+      modelCenter?: Vec2Like;
+      /** Drawing-scale denominator (model mm per paper mm); 1:50 => 50. */
+      scale?: number;
+      /** Pinned: no pan/zoom-through, no move/resize handles. */
+      locked?: boolean;
+      /** Layer ids hidden in this viewport only. */
+      hiddenLayerIds?: readonly string[];
+  }>;
+  /** Review note pinned to a point; the editor shows a screen-fixed marker. */
+  export type CommentInput = ObjectInputShape<{
+      type: "comment";
+      /** Tail tip of the bubble (world/sheet mm). */
+      position: Vec2Like;
+      text?: string;
+      tags?: readonly string[];
+  }>;
   /** What a script WRITES — the union of the authoring DTOs above (what
-   * `draw` returns, what `document.add` takes). Read results are
-   * `StoredObject`. */
-  export type ObjectInput = Line | Point | Polyline | Circle | Arc | Ellipse | Hatch | Text | Dimension | Block | Table;
-  /** @deprecated The input union is `ObjectInput`; in the SDK and core
-   * `ModelObject` is the STORED shape, so this name misled. Kept so existing
-   * scripts compile. */
-  export type ModelObject = ObjectInput;
+   * `document.add` takes). Reads return `ModelObject`. */
+  export type ModelObjectInput = LineInput | PointInput | PolylineInput | CircleInput | ArcInput | EllipseInput | HatchInput | TextInput | DimensionInput | BlockInput | TableInput | ViewportInput | CommentInput | ReferenceInput;
+  /** One child a block's `draw` may return: every input except viewports and
+   * comments (both are drawn only as a space's own objects — a block's would
+   * never show). An `asset` reference resolves in the document the instance
+   * lives in. */
+  export type BlockChildInput = Exclude<ModelObjectInput, ViewportInput | CommentInput>;
   /** Identity + shared style fields every stored object carries. */
-  export type StoredObjectBase = {
+  export type ObjectBase = {
       id: string;
       layerId: string;
       /** #rrggbb override; absent = by layer. */
@@ -273,43 +340,43 @@ declare module "lineadraw" {
       opacity?: number;
   };
   /** Flattens base + per-type fields so hovers list every member inline
-   * (same trick as Styled<T> for the authoring DTOs). */
-  type StoredShape<T> = {
-      [K in keyof (T & StoredObjectBase)]: (T & StoredObjectBase)[K];
+   * (same trick as ObjectInputShape<T> for the authoring DTOs). */
+  type ObjectShape<T> = {
+      [K in keyof (T & ObjectBase)]: (T & ObjectBase)[K];
   } & {};
   /** Stored polyline vertex — bulge always present (default 0 applied). */
-  export type StoredPolylineVertex = {
+  export type PolylineVertex = {
       x: number;
       y: number;
       bulge: number;
   };
-  export type StoredLine = StoredShape<{
+  export type Line = ObjectShape<{
       type: "line";
       a: Vec2;
       b: Vec2;
   }>;
-  export type StoredPoint = StoredShape<{
+  export type Point = ObjectShape<{
       type: "point";
       p: Vec2;
   }>;
-  export type StoredPolyline = StoredShape<{
+  export type Polyline = ObjectShape<{
       type: "polyline";
-      points: readonly StoredPolylineVertex[];
+      points: readonly PolylineVertex[];
       closed: boolean;
   }>;
-  export type StoredCircle = StoredShape<{
+  export type Circle = ObjectShape<{
       type: "circle";
       center: Vec2;
       radius: number;
   }>;
-  export type StoredArc = StoredShape<{
+  export type Arc = ObjectShape<{
       type: "arc";
       center: Vec2;
       radius: number;
       startAngle: number;
       endAngle: number;
   }>;
-  export type StoredEllipse = StoredShape<{
+  export type Ellipse = ObjectShape<{
       type: "ellipse";
       center: Vec2;
       majorAxis: Vec2;
@@ -317,7 +384,7 @@ declare module "lineadraw" {
       startAngle: number;
       endAngle: number;
   }>;
-  export type StoredHatchFill = {
+  export type HatchFill = {
       kind: "solid";
   } | {
       kind: "pattern";
@@ -337,16 +404,16 @@ declare module "lineadraw" {
       color2: string;
       angle: number;
   };
-  export type StoredHatch = StoredShape<{
+  export type Hatch = ObjectShape<{
       type: "hatch";
       /** loops[0] = outer boundary, the rest are holes (even-odd). */
       loops: readonly {
-          points: readonly StoredPolylineVertex[];
+          points: readonly PolylineVertex[];
       }[];
-      fill: StoredHatchFill;
+      fill: HatchFill;
       scale: number;
   }>;
-  export type StoredText = StoredShape<{
+  export type Text = ObjectShape<{
       type: "text";
       position: Vec2;
       content: string;
@@ -359,19 +426,11 @@ declare module "lineadraw" {
       frame?: "none" | "rectangle" | "circle" | "slot" | "bottom" | "firstLine";
       styleId?: string;
       /** Only the keys the user actually overrode on this text. */
-      styleOverride?: {
-          font?: string;
-          widthFactor?: number;
-          bold?: boolean;
-          italic?: boolean;
-          textHeight?: number;
-          arrowType?: "filled" | "open" | "tick" | "dot" | "none";
-          arrowSize?: number;
-      };
+      styleOverride?: TextStyleOverride;
       rotation: number;
       scale: number;
   }>;
-  export type StoredDimension = StoredShape<{
+  export type Dimension = ObjectShape<{
       type: "dimension";
       kind: "linear" | "angular" | "radial" | "diameter";
       points: readonly Vec2[];
@@ -385,33 +444,21 @@ declare module "lineadraw" {
       }[];
       styleId?: string;
       /** Only the keys the user actually overrode on this dimension. */
-      styleOverride?: {
-          font?: string;
-          widthFactor?: number;
-          bold?: boolean;
-          italic?: boolean;
-          textHeight?: number;
-          textOffset?: number;
-          arrowType?: "filled" | "open" | "tick" | "dot" | "none";
-          arrowSize?: number;
-          extensionType?: "long" | "short";
-          extensionOffset?: number;
-          extensionOvershoot?: number;
-          precision?: number;
-      };
+      styleOverride?: DimStyleOverride;
       scale: number;
   }>;
-  export type StoredBlock = StoredShape<{
+  export type Block = ObjectShape<{
       type: "block";
       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 StoredViewport = StoredShape<{
+  export type Viewport = ObjectShape<{
       type: "viewport";
       rect: {
           x: number;
@@ -425,29 +472,13 @@ declare module "lineadraw" {
       locked: boolean;
       hiddenLayerIds: readonly string[];
   }>;
-  /** Raster reference; pixels live in the document's assets map. */
-  export type StoredImage = StoredShape<{
-      type: "image";
-      assetId: string;
-      origin: Vec2;
-      width: number;
-      height: number;
-      rotation: number;
-  }>;
-  /** A LINKED file drawn in place (an xref); the document holds only this
-   * record — the file's content is not readable from scripts. */
-  export type StoredReference = StoredShape<{
+  /** A file drawn in place — linked (an xref) or embedded in the document's
+   * assets; the file's content is not readable from scripts. */
+  export type Reference = ObjectShape<{
       type: "reference";
       format: "linea" | "dxf" | "dwg" | "pdf" | "png" | "jpg";
       name: string;
-      source: {
-          kind: "path";
-          path: string;
-          cacheKey?: string;
-      } | {
-          kind: "url";
-          url: string;
-      };
+      source: ReferenceSource;
       /** Where the file's origin lands. */
       position: Vec2;
       rotation: number;
@@ -462,22 +493,12 @@ declare module "lineadraw" {
       /** Locked in the References panel: drawn and snapped, never picked. */
       locked?: boolean;
       /** Crop rectangle in file coordinates. */
-      clip?: {
-          minX: number;
-          minY: number;
-          maxX: number;
-          maxY: number;
-      };
+      clip?: Box;
       /** Content bounds in file coordinates at the last load. */
-      extent?: {
-          minX: number;
-          minY: number;
-          maxX: number;
-          maxY: number;
-      };
+      extent?: Box;
   }>;
   /** Review note pinned to a point; the editor shows a screen-fixed marker. */
-  export type StoredComment = StoredShape<{
+  export type Comment = ObjectShape<{
       type: "comment";
       /** Tail tip of the bubble (world/sheet mm). */
       position: Vec2;
@@ -485,17 +506,11 @@ declare module "lineadraw" {
       tags: readonly string[];
   }>;
   /** Text style keys a text, table or table cell may override. */
-  export type TextStyleOverride = {
-      font?: string;
-      widthFactor?: number;
-      bold?: boolean;
-      italic?: boolean;
-      textHeight?: number;
-      arrowType?: "filled" | "open" | "tick" | "dot" | "none";
-      arrowSize?: number;
-  };
+  export type TextStyleOverride = Partial<Omit<TextStyle, "id" | "name">>;
+  /** Dimension style keys a dimension may override. */
+  export type DimStyleOverride = Partial<Omit<DimStyle, "id" | "name">>;
   /** One table cell as stored. */
-  export type StoredTableCell = {
+  export type TableCell = {
       /** Plain text; "\n" = line break. */
       content: string;
       spans?: readonly TextSpan[];
@@ -511,7 +526,7 @@ declare module "lineadraw" {
       color?: string;
   };
   /** Grid of text cells hanging right/down from `position` (top-left). */
-  export type StoredTable = StoredShape<{
+  export type Table = ObjectShape<{
       type: "table";
       position: Vec2;
       rotation: number;
@@ -522,7 +537,7 @@ declare module "lineadraw" {
           minHeight?: number;
       }[];
       /** Row-major `cells[row][column]`. */
-      cells: readonly (readonly StoredTableCell[])[];
+      cells: readonly (readonly TableCell[])[];
       headerRows: number;
       cellMargin: number;
       borders: "all" | "outer" | "rows" | "none";
@@ -530,13 +545,13 @@ declare module "lineadraw" {
       styleOverride?: TextStyleOverride;
   }>;
   /** Any object as stored in the document — what reads hand to scripts. */
-  export type StoredObject = StoredLine | StoredPoint | StoredPolyline | StoredCircle | StoredArc | StoredEllipse | StoredHatch | StoredText | StoredDimension | StoredBlock | StoredViewport | StoredImage | StoredComment | StoredTable | StoredReference;
+  export type ModelObject = Line | Point | Polyline | Circle | Arc | Ellipse | Hatch | Text | Dimension | Block | Viewport | Comment | Table | Reference;
   /**
    * One choice of a "Select" parameter: the value (what scripts receive) with
    * an optional properties-panel label. A plain string is shorthand for
    * `{ value }`.
    */
-  export type ParameterOption = string | {
+  export type ParamOption = string | {
       value: string;
       label?: string;
       /** A `#rrggbb` color square before the option's label. */
@@ -613,7 +628,7 @@ declare module "lineadraw" {
   }) | (ParamBase & {
       type: "enum";
       default: string;
-      options: readonly ParameterOption[];
+      options: readonly ParamOption[];
       /** "buttons": a segmented toggle group of the options (short
        * choices); falls back to the dropdown when they don't fit. */
       display?: "dropdown" | "buttons";
@@ -631,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
@@ -639,9 +660,10 @@ declare module "lineadraw" {
       type: "row";
       items: readonly RowItemDef[];
   });
-  /** A document text style as `draw` reads it (`styles.text(id)`). Heights
-   * and arrow sizes are mm before an object's `scale`. */
-  export type TextStyleInfo = {
+  /** A document text style (`styles.text(id)` in `draw`,
+   * `document.listTextStyles()`). Heights and arrow sizes are mm before an
+   * object's `scale`. */
+  export type TextStyle = {
       readonly id: string;
       readonly name: string;
       readonly font: string;
@@ -649,11 +671,12 @@ declare module "lineadraw" {
       readonly bold?: boolean;
       readonly italic?: boolean;
       readonly textHeight: number;
-      readonly arrowType: "filled" | "open" | "tick" | "dot" | "none";
+      readonly arrowType: ArrowType;
       readonly arrowSize: number;
   };
-  /** A document dimension style as `draw` reads it (`styles.dim(id)`). */
-  export type DimStyleInfo = {
+  /** A document dimension style (`styles.dim(id)`,
+   * `document.listDimStyles()`). */
+  export type DimStyle = {
       readonly id: string;
       readonly name: string;
       readonly font: string;
@@ -662,8 +685,9 @@ declare module "lineadraw" {
       readonly italic?: boolean;
       readonly textHeight: number;
       readonly textOffset: number;
-      readonly arrowType: "filled" | "open" | "tick" | "dot" | "none";
+      readonly arrowType: ArrowType;
       readonly arrowSize: number;
+      /** "short" = a 2×overshoot tick across the dimension line. */
       readonly extensionType: "long" | "short";
       readonly extensionOffset: number;
       readonly extensionOvershoot: number;
@@ -673,9 +697,17 @@ declare module "lineadraw" {
    * (a deleted style, a block from another drawing) gives the document's
    * first style — the same rule a child's `styleId` follows. */
   export interface BlockStyles {
-      text(id?: string): TextStyleInfo;
-      dim(id?: string): DimStyleInfo;
+      text(id?: string): TextStyle;
+      dim(id?: string): DimStyle;
   }
+  /** A new text style: a unique name, every other field optional. */
+  export type TextStyleInput = {
+      name: string;
+  } & Partial<Omit<TextStyle, "id">>;
+  /** A new dimension style: a unique name, every other field optional. */
+  export type DimStyleInput = {
+      name: string;
+  } & Partial<Omit<DimStyle, "id">>;
   /** What a `row` may hold: the compact, single-line param kinds. */
   export type RowItemDef = Extract<ParamDef, {
       type: "number" | "string" | "boolean" | "enum" | "color" | "textStyle" | "dimStyle" | "font" | "lineType" | "hatchPattern";
@@ -686,18 +718,151 @@ declare module "lineadraw" {
       items: readonly (infer I)[];
   } ? I : Q;
   /**
-   * The block's parameters table — what the `params` member of a BlockSpec
-   * declares (or its function form returns).
+   * A parameters table — what the `params` member of a block or command spec
+   * 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 BlockParamDefs = readonly ParamDef[];
-  /** What the script's `draw` export must return. */
-  export type BlockScriptResult = ObjectInput[];
+  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 ParameterOption> = O extends string ? O : O extends {
+  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";
@@ -755,17 +920,10 @@ declare module "lineadraw" {
       description?: string;
       lines: HatchPatternLine[];
   };
-  /** An axis-aligned box in world mm. */
-  export type Box = {
-      minX: number;
-      minY: number;
-      maxX: number;
-      maxY: number;
-  };
   /** Filters for Drawing.query — all present filters AND together. */
   export type ObjectQuery = {
       ids?: readonly string[];
-      type?: ObjectInput["type"];
+      type?: ModelObject["type"];
       /** Layer name or id. */
       layer?: string;
       /** #rrggbb override (objects without one inherit from their layer). */
@@ -773,9 +931,9 @@ declare module "lineadraw" {
       lineType?: string;
       /** Substring match on text content. */
       content?: string;
-      /** Bounds intersect this box. */
+      /** Box intersect this box. */
       bbox?: Box;
-      /** Bounds entirely inside this box. */
+      /** Box entirely inside this box. */
       inside?: Box;
       /** Geometry within `tol` mm of `point`. */
       near?: {
@@ -786,38 +944,87 @@ declare module "lineadraw" {
        * model space. */
       layout?: string;
   };
-  /** A STORED object as query() returns it (see StoredObject — schema
-   * output: defaults applied, points always {x, y}, identity present). */
-  export type ExistingObject = StoredObject;
+  /** `Drawing.summary()`: counts by type / layer, extents, names. */
+  export type DocumentSummary = {
+      name: string;
+      objectCount: number;
+      byType: Record<string, number>;
+      byLayer: Record<string, number>;
+      bbox: Box | null;
+      layers: string[];
+      layouts: {
+          name: string;
+          objectCount: number;
+      }[];
+      settings: {
+          units: "mm" | "in";
+      };
+  };
+  /** What `renderSvg` draws: model space or one layout. */
+  export type RenderSvgOptions = {
+      /** Render this paper layout (name or id) instead of model space. */
+      layout?: string;
+      /** Crop to this box (world mm; sheet mm in a layout). */
+      bbox?: Box;
+      /** Padding around the content, mm (default 5). */
+      padding?: number;
+      /** Default: "color" for model space, the layout's own for a layout. */
+      palette?: PrintPalette;
+  };
+  export type RenderPngOptions = RenderSvgOptions & {
+      /** Output width in px (height follows). Default 1024. */
+      width?: number;
+      /** Background fill, e.g. "#ffffff". Default: the dark canvas. */
+      background?: string;
+  };
+  export type RenderPdfOptions = {
+      /** Layouts (names or ids) in page order; default: all of them. */
+      layouts?: readonly string[];
+      /** Override every page's print palette. */
+      palette?: PrintPalette;
+  };
   /** Per-object measurements; null where the type has no natural value. */
   export type Measurement = {
       bbox: Box | null;
       length: number | null;
       area: number | null;
   };
-  /** A layer as stored (defaults applied) plus the current-layer flag. */
-  export type LayerInfo = {
+  /** A document layer (defaults applied). */
+  export type Layer = {
       id: string;
       name: string;
+      /** #rrggbb — objects without their own color take it. */
       color: string;
+      /** Default line type of the layer's objects. */
       lineType: string;
+      /** Default lineweight, mm. */
       lineWidth: number;
+      /** Default paint opacity 0..1. */
       opacity: number;
       visible: boolean;
       locked: boolean;
+      /** false = shown on screen but left out of PDF / print output. */
+      print: boolean;
+  };
+  /** A layer as `listLayers()` returns it: plus the current-layer flag. */
+  export type LayerInfo = Layer & {
       current: boolean;
-      [key: string]: unknown;
   };
-  /** A paper layout as stored: sheet metadata + its sheet-space objects. */
-  export type LayoutInfo = {
+  /** A new layer: a unique name, every other field optional. */
+  export type LayerInput = {
+      name: string;
+  } & Partial<Omit<Layer, "id">>;
+  /** A paper layout: sheet metadata + its sheet-space objects. */
+  export type PaperLayout = {
       id: string;
       name: string;
+      /** Sheet size, mm. */
       sheet: {
           width: number;
           height: number;
       };
-      printPalette: "color" | "grayscale" | "monochrome";
-      objects: readonly StoredObject[];
+      printPalette: PrintPalette;
+      objects: readonly ModelObject[];
   };
   /** A block module's identity/metadata (from its exports). */
   export type BlockInfo = {
@@ -828,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 = {
@@ -837,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[];
@@ -945,18 +1158,29 @@ declare module "lineadraw" {
       index?: number;
   };
   /** The whole document as stored (defaults applied). */
-  export type StoredDocument = {
+  export type LineaDocument = {
       id: string;
+      type: "lineadraw";
       version: number;
-      layers: readonly Omit<LayerInfo, "current">[];
+      settings: {
+          units: "mm" | "in";
+      };
+      layers: readonly Layer[];
       currentLayerId: string;
-      objects: readonly StoredObject[];
-      layouts: readonly LayoutInfo[];
-      /** Raw block module sources. */
+      /** Model space. */
+      objects: readonly ModelObject[];
+      layouts: readonly PaperLayout[];
+      textStyles: readonly TextStyle[];
+      dimStyles: readonly DimStyle[];
+      /** The document's own line type / hatch pattern definitions. */
+      lineTypes: readonly LineType[];
+      hatchPatterns: readonly HatchPattern[];
+      /** Embedded files: content hash → data URL. */
+      assets: Readonly<Record<string, string>>;
+      /** Block module sources. */
       blockDefinitions: readonly string[];
-      /** Raw command module sources. */
+      /** Command module sources. */
       commands: readonly string[];
-      [key: string]: unknown;
   };
   /** Where a draw-order move puts the objects. */
   export type ReorderPlacement = "front" | "back" | {
@@ -978,60 +1202,29 @@ declare module "lineadraw" {
       /** Monotonic change counter. */
       readonly revision: number;
       /** The full document — a detached snapshot. */
-      readonly document: StoredDocument;
+      readonly document: LineaDocument;
       /** Counts by type/layer, bbox, layer + layout names. */
-      summary(): {
-          name: string;
-          objectCount: number;
-          byType: Record<string, number>;
-          byLayer: Record<string, number>;
-          bbox: Box | null;
-          layers: string[];
-          layouts: {
-              name: string;
-              objectCount: number;
-          }[];
-          settings: {
-              units: "mm" | "in";
-          };
-      };
+      summary(): DocumentSummary;
       /** Filtered objects — model space, or one layout via `filter.layout`. */
-      listObjects(filter?: ObjectQuery): ExistingObject[];
+      listObjects(filter?: ObjectQuery): ModelObject[];
       /** One object from ANY space, or undefined. */
-      getObject(id: string): ExistingObject | undefined;
+      getObject(id: string): ModelObject | undefined;
       /** bbox / curve length / enclosed area of one object. */
       measure(id: string): Measurement;
       listLayers(): LayerInfo[];
-      listLayouts(): LayoutInfo[];
+      listLayouts(): PaperLayout[];
       /** Compilable block definitions in this document. */
       listBlockDefinitions(): BlockInfo[];
       /** Compilable command modules travelling with this document. */
       listUserCommands(): CommandInfo[];
       /** Model space (or a layout via `layout`) as an SVG string. */
-      renderSvg(opts?: {
-          layout?: string;
-          bbox?: Box;
-          padding?: number;
-          palette?: "color" | "grayscale" | "monochrome";
-      }): string;
+      renderSvg(opts?: RenderSvgOptions): string;
       /** Model space (or a layout) as PNG bytes — absent on hosts that can't
        * rasterize, so check before calling. */
-      renderPng?(opts?: {
-          layout?: string;
-          bbox?: Box;
-          padding?: number;
-          palette?: "color" | "grayscale" | "monochrome";
-          /** Output width in px (height follows). Default 1024. */
-          width?: number;
-          /** Background fill, e.g. "#ffffff". Default: the dark canvas. */
-          background?: string;
-      }): Promise<Uint8Array>;
+      renderPng?(opts?: RenderPngOptions): Promise<Uint8Array>;
       /** Multi-page PDF of the layouts (default: all) — absent on hosts
        * without fonts, so check before calling. */
-      renderPdf?(opts?: {
-          layouts?: readonly string[];
-          palette?: "color" | "grayscale" | "monochrome";
-      }): Promise<Uint8Array>;
+      renderPdf?(opts?: RenderPdfOptions): Promise<Uint8Array>;
       /** The whole document as DXF text. */
       toDxf(): Promise<string>;
       /** DWG bytes (default AC1027 — AutoCAD 2013). */
@@ -1040,10 +1233,9 @@ declare module "lineadraw" {
       }): Promise<Uint8Array>;
       /** The `.linea` file text. */
       toLinea(): string;
-      /** Add objects (each may carry `layer` — a name — instead of an id);
-       * returns the created ids. */
-      add(objects: readonly (ObjectInput & {
-          layer?: string;
+      /** Add objects (each may carry its own `id`); returns the created ids. */
+      add(objects: readonly (ModelObjectInput & {
+          id?: string;
       })[], opts?: {
           layout?: string;
       }): string[];
@@ -1070,17 +1262,14 @@ declare module "lineadraw" {
       updateLayout(nameOrId: string, patch: {
           name?: string;
           sheet?: SheetSpec;
-          printPalette?: "color" | "grayscale" | "monochrome";
+          printPalette?: PrintPalette;
       }): void;
       removeLayout(nameOrId: string): void;
       /** Explicit total order (names or ids) — the PDF page order. */
       reorderLayouts(order: readonly string[]): void;
       /** Create a layer (unique name); returns its id. */
-      addLayer(props: {
-          name: string;
-          color?: string;
-      } & Record<string, unknown>): string;
-      updateLayer(nameOrId: string, patch: Record<string, unknown>): void;
+      addLayer(props: LayerInput): string;
+      updateLayer(nameOrId: string, patch: Partial<LayerInput>): void;
       /** Remove an EMPTY, non-current layer. */
       removeLayer(nameOrId: string): void;
       /** Explicit total order (names or ids, every layer exactly once). */
@@ -1106,31 +1295,17 @@ declare module "lineadraw" {
       }): Promise<MarketplaceHit[]>;
       /** Install (or update) entries by id, dependencies first — one undo step. */
       installMarketplaceEntries(ids: readonly string[], marketplace?: string): Promise<MergeReport>;
-      listTextStyles(): ({
-          id: string;
-          name: string;
-      } & Record<string, unknown>)[];
-      listDimStyles(): ({
-          id: string;
-          name: string;
-      } & Record<string, unknown>)[];
+      listTextStyles(): TextStyle[];
+      listDimStyles(): DimStyle[];
       /** Create a style (unique name; unset fields take the defaults); returns
        * its id. Styles are addressed by name or id. */
-      addTextStyle(props: {
-          name: string;
-      } & Record<string, unknown>): string;
-      updateTextStyle(nameOrId: string, patch: Record<string, unknown>): void;
+      addTextStyle(props: TextStyleInput): string;
+      updateTextStyle(nameOrId: string, patch: Partial<TextStyleInput>): void;
       /** Remove a style no object uses (refused otherwise). */
       removeTextStyle(nameOrId: string): void;
-      addDimStyle(props: {
-          name: string;
-      } & Record<string, unknown>): string;
-      updateDimStyle(nameOrId: string, patch: Record<string, unknown>): void;
+      addDimStyle(props: DimStyleInput): string;
+      updateDimStyle(nameOrId: string, patch: Partial<DimStyleInput>): void;
       removeDimStyle(nameOrId: string): void;
-      /** @deprecated Use updateDimStyle (default here: the first style). */
-      setDimStyle(patch: Record<string, unknown>, styleId?: string): void;
-      /** @deprecated Use updateTextStyle (default here: the first style). */
-      setTextStyle(patch: Record<string, unknown>, styleId?: string): void;
       /** The document's own line type definitions (objects and layers name
        * them, ahead of the built-in catalogue). */
       listLineTypes(): LineType[];
@@ -1146,12 +1321,13 @@ declare module "lineadraw" {
       addHatchPatterns(patterns: readonly HatchPattern[]): void;
       updateHatchPattern(name: string, patch: Partial<HatchPattern>): void;
       removeHatchPattern(name: string): void;
-      /** Embed image pixels (a data URL); returns the content-keyed assetId
-       * that `image` objects reference. */
+      /** Embed a file (a data URL — PNG, JPEG, PDF…); returns the content-keyed
+       * assetId an embedded reference's `source: { kind: "asset", assetId }`
+       * names. */
       addAsset(dataUrl: string): string;
-      /** Remove an asset (refused while an image references it). */
+      /** Remove an asset (refused while a reference embeds it). */
       removeAsset(id: string): void;
-      /** Embedded image assets and how many images use each. */
+      /** Embedded files and how many references use each. */
       listAssets(): {
           id: string;
           mimeType: string;
@@ -1176,7 +1352,8 @@ declare module "lineadraw" {
           layoutIds: string[];
       }>;
       /** Merge a PDF: vectors/text onto the current layer, or (`as: "image"`,
-       * not available on every host) each page as an image at true scale. */
+       * not available on every host) embedded, each page a raster reference
+       * at true scale. */
       importPdfData(data: ArrayBuffer | Uint8Array, opts?: {
           as?: "vectors" | "image";
           origin?: Vec2Like;
@@ -1246,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;
@@ -1261,40 +1471,33 @@ 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;
-      /** @deprecated Use `editor.pickPoint({ label })` (throws without an editor). */
-      pickPoint(label?: string): Promise<Vec2>;
-      /** @deprecated Use `editor.pickObject({ label })`. */
-      pickObject(label?: string): Promise<string>;
-      /** @deprecated Use `editor.state().selectedIds`. */
-      selection(): string[];
-      /** @deprecated Use `editor.setSelection(ids)`. */
-      setSelection(ids: readonly string[]): void;
-      /** @deprecated Use `editor.prompt(message, options)`. */
-      prompt(message: string, options?: {
-          initial?: string;
-          placeholder?: string;
-      }): Promise<string>;
-      /** @deprecated Use `editor.toast(message, kind)`. */
-      showToast(message: string, kind?: "info" | "success" | "error"): void;
   }
 
   // ——— Script contract ———
 
+  /**
+   * @deprecated All "lineadraw/helpers" functions as one object — what
+   * migration-wrapped legacy scripts import. Import the named functions from
+   * "lineadraw/helpers" instead.
+   */
+  export const helpers: Readonly<typeof import("lineadraw/helpers")>;
+
   // #region BlockParams
   /**
    * The open fallback for a block's parameter values, by name. Inside
@@ -1317,12 +1520,12 @@ declare module "lineadraw" {
   /**
    * A referenced document object as `draw` receives it: the STORED record
    * (schema output — defaults applied, points always {x, y}, id/layerId
-   * present; see StoredObject), localized against the instance pivot like
+   * present; see ModelObject), localized against the instance pivot like
    * every point input. Null when the reference no longer resolves (the
    * object was deleted) — handle it or throw (a throw shows as the
    * instance's evaluation error).
    */
-  export type ResolvedObject = StoredObject | null;
+  export type ResolvedObject = ModelObject | null;
 
   /**
    * How one stored input arrives at `draw`: points pass through
@@ -1354,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 ———
 
   /**
@@ -1404,8 +1762,9 @@ declare module "lineadraw" {
    * typeof / satisfies / as-const annotations. See defineBlock.
    */
   export interface BlockSpec<
-    P extends BlockParamDefs = readonly [],
+    P extends ParamDefs = readonly [],
     Pl extends PlaceSpec<P> | undefined = undefined,
+    I extends InputDefs | undefined = undefined,
   > {
     id: string;
     name: string;
@@ -1430,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
@@ -1449,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;
-    }) => BlockScriptResult;
+      /** 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;
   }
 
   /**
@@ -1481,25 +1921,33 @@ declare module "lineadraw" {
    * plain named exports describe the same block.
    */
   export function defineBlock<
-    const P extends BlockParamDefs = readonly [],
+    const P extends ParamDefs = readonly [],
     const L extends readonly string[] | undefined = undefined,
   >(spec: BlockSpec<P, L>): BlockSpec<P, L>;
   // Function-form place: the props type is concrete (from P) and only the
   // RETURN is inferred — inferring a whole context-sensitive function into
   // a type parameter would fall back to its default.
   export function defineBlock<
-    const P extends BlockParamDefs = readonly [],
+    const P extends ParamDefs = readonly [],
     const R extends BlockInputs | Promise<BlockInputs> = BlockInputs,
   >(
     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 BlockParamDefs = readonly []> {
+  export interface CommandSpec<
+    P extends ParamDefs = readonly [],
+    I extends readonly string[] | CommandInputDefs = readonly [],
+  > {
     id: string;
     name: string;
     description?: string;
@@ -1507,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?: readonly string[];
+    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.
+     */
+    requiresEditor?: boolean;
     /**
      * Parameters the command needs — the same table a block's `params`
      * declares (number / string / boolean / enum / label rows), or a
@@ -1529,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;
   }
 
   /**
@@ -1555,9 +2014,10 @@ declare module "lineadraw" {
    *     },
    *   });
    */
-  export function defineCommand<const P extends BlockParamDefs = 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" {
@@ -1590,1334 +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;
+  }[];
   /**
-   * All helpers as one object — what migration-wrapped legacy scripts receive
-   * via `import { helpers } from "lineadraw"`. New scripts import the named
-   * functions from "lineadraw/helpers" instead.
+   * 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 helpers: Readonly<{
-      range: (n: number) => number[];
-      polar: (angle: number, distance: number, p?: Vec2) => Vec2;
-      toDeg: (r: number) => number;
-      toRad: (d: number) => number;
-      len: (p: Vec2) => number;
-      dist: (a: Vec2, b: Vec2) => number;
-      add: (a: Vec2, b: Vec2) => Vec2;
-      sub: (a: Vec2, b: Vec2) => Vec2;
-      scale: (p: Vec2, s: number) => Vec2;
-      norm: (p: Vec2) => Vec2;
-      dot: (a: Vec2, b: Vec2) => number;
-      rotate: (p: Vec2, angle: number) => Vec2;
-  }>;
-}
-
-// The same declarations again at GLOBAL scope, so scripts can annotate
-// without importing. Structurally identical to the "lineadraw" exports, so the
-// two mix freely. Requires a DOM-less lib (blocks/tsconfig and the in-app
-// editor both use lib es2022) — with lib.dom, `Text` would collide.
-/** A 2D point (mm, y-up). Point-valued fields also accept [x, y]. */
-type Vec2 = {
-    x: number;
-    y: number;
-};
-type Vec2Like = Vec2 | readonly [number, number];
-/** Polyline vertex; bulge = tan(sweep/4), 0 = straight. Accepts [x, y, bulge?]. */
-type PolylineVertexLike = {
-    x: number;
-    y: number;
-    bulge?: number;
-} | readonly [number, number, number?];
-/** Style overrides children may carry (otherwise inherited from the instance). */
-type BaseStyle = {
-    /** Id of a document layer this object sits on. For a block child: absent
-     * = the instance's layer (the portable default; an id unknown to the
-     * document falls back to it); a child that names another layer hides
-     * with that layer, while its color / line type / width still follow the
-     * instance unless it sets its own (ByBlock, as in CAD). For
-     * `document.add`: absent = the current layer. */
-    layerId?: string;
-    /** #rrggbb; absent = by layer. */
-    color?: string;
-    /** Line type; absent = by layer. */
-    lineType?: string;
-    /** Dash-pattern length multiplier; absent = 1. */
-    lineTypeScale?: number;
-    /** Line weight in mm; absent = by layer. */
-    lineWidth?: number;
-    /** Paint opacity 0..1; absent = by layer (opaque unless the layer says). */
-    opacity?: number;
-};
-/**
- * T plus the shared style fields, FLATTENED (the homomorphic map forces the
- * intersection to resolve): hovers then list every member inline instead of
- * the opaque `BaseStyle & { … }` — the block editor has no expand-type
- * affordance, so the alias display is all a script author gets.
- */
-type Styled<T> = {
-    [K in keyof (T & BaseStyle)]: (T & BaseStyle)[K];
-} & {};
-type Line = Styled<{
-    type: "line";
-    a: Vec2Like;
-    b: Vec2Like;
-}>;
-/** A point: paints as a round dot whose diameter is the lineWidth. */
-type Point = Styled<{
-    type: "point";
-    p: Vec2Like;
-}>;
-type Polyline = Styled<{
-    type: "polyline";
-    /** At least 2 vertices. */
-    points: readonly PolylineVertexLike[];
-    closed?: boolean;
-}>;
-type Circle = Styled<{
-    type: "circle";
-    center: Vec2Like;
-    radius: number;
-}>;
-/** Runs CCW from startAngle to endAngle (radians; DXF ARC convention). */
-type Arc = Styled<{
-    type: "arc";
-    center: Vec2Like;
-    radius: number;
-    startAngle: number;
-    endAngle: number;
-}>;
-/** majorAxis = endpoint vector from center; ratio = minor/major in (0, 1]. */
-type Ellipse = Styled<{
-    type: "ellipse";
-    center: Vec2Like;
-    majorAxis: Vec2Like;
-    ratio: number;
-    startAngle?: number;
-    endAngle?: number;
-}>;
-type Hatch = Styled<{
-    type: "hatch";
-    /** loops[0] = outer boundary, the rest are holes (even-odd). */
-    loops: readonly {
-        points: readonly PolylineVertexLike[];
-    }[];
-    fill?: {
-        kind: "solid";
-    }
-    /** A named pattern: the built-in catalogue (ANSI31, AR-CONC, …) or one of
-     * the document's own hatch patterns, by name. `angle` radians, `scale`
-     * multiplies the definition's mm; `origin` anchors the pattern frame
-     * (block-local mm; absent = the block origin). */
-     | {
-        kind: "pattern";
-        name: string;
-        angle: number;
-        scale: number;
-        origin?: Vec2Like;
-    } | {
-        kind: "lines";
-        angle: number;
-        spacing: number;
-    } | {
-        kind: "gradient";
-        shape?: "linear" | "radial";
-        color1?: string;
-        color2?: string;
-        angle?: number;
-    };
-    /** Pattern spacing multiplier. */
-    scale?: number;
-}>;
-/** Character formatting over [start, end) of a text's `content` (JS string
- * indices). Absent attributes inherit the text's style; `height` is a ratio
- * of its cap height. Setting `content` without `spans` drops old spans. */
-type TextSpan = {
-    start: number;
-    end: number;
-    font?: string;
-    bold?: boolean;
-    italic?: boolean;
-    underline?: boolean;
-    /** "#rrggbb". */
-    color?: string;
-    height?: number;
-    script?: "sub" | "super";
-};
-type Text = Styled<{
-    type: "text";
-    position: Vec2Like;
-    content: string;
-    spans?: readonly TextSpan[];
-    rotation?: number;
-    /** Justification, as in AutoCAD / DXF: which edge sits on the point —
-     * "left" = the text runs right of it, "right" = left of it; vAlign
-     * "bottom" = the text sits above the point, "top" = below it. */
-    hAlign?: "left" | "center" | "right";
-    vAlign?: "bottom" | "center" | "top";
-    /** Word-wrap / frame width in mm (before `scale`); absent = no wrapping. */
-    width?: number;
-    frame?: "none" | "rectangle" | "circle" | "slot" | "bottom" | "firstLine";
-    /** MLEADER-style arrow polylines pointing at the text (arrowhead at [0]). */
-    leaderLines?: readonly (readonly Vec2Like[])[];
-    /** The document text style to follow (name or id); absent = the first. */
-    styleId?: string;
-    /** Style overrides; absent keys inherit the document text style. */
-    styleOverride?: {
-        font?: string;
-        widthFactor?: number;
-        bold?: boolean;
-        italic?: boolean;
-        /** Cap height in mm (before `scale`). */
-        textHeight?: number;
-        arrowSize?: number;
-        arrowType?: "filled" | "open" | "tick" | "dot" | "none";
-    };
-    /** Size multiplier for height + arrow size. */
-    scale?: number;
-}>;
-type Dimension = Styled<{
-    type: "dimension";
-    kind?: "linear" | "angular" | "radial" | "diameter";
-    /** linear: 2+ chained points (measured point to point); angular: [vertex, a, b]; radial: [center, p]; diameter: [p1, p2]. */
-    points: readonly Vec2Like[];
-    /** linear only: the measuring direction, radians CCW from +X. Unset =
-     * aligned to the points. */
-    rotation?: number;
-    /** linear: signed distance of the dimension line from points[0], positive
-     * to the LEFT of the measuring direction; angular: signed arc radius
-     * (negative = the complementary arc). Not for radial/diameter. */
-    offset?: number;
-    /** One per measured segment (linear chain: points.length − 1, others: 1).
-     * `along` (mm along the line from the segment origin — radial/diameter:
-     * from the center) and `across` (mm off the line) place the text, unset =
-     * automatic; `content` is the text, `{value}` = the measurement. */
-    labels?: readonly {
-        along?: number;
-        across?: number;
-        content?: string;
-        /** Formatting over `content` (spans covering `{value}` format it). */
-        spans?: readonly TextSpan[];
-    }[];
-    /** The document dimension style to follow (name or id); absent = the first. */
-    styleId?: string;
-    styleOverride?: {
-        textHeight?: number;
-        arrowSize?: number;
-        arrowType?: "filled" | "open" | "tick" | "dot" | "none";
-        /** "short" = a 2×overshoot tick across the dimension line. */
-        extensionType?: "long" | "short";
-        extensionOffset?: number;
-        extensionOvershoot?: number;
-        textOffset?: number;
-        precision?: number;
-    };
-    /** Annotation size multiplier (text/arrows/offsets). */
-    scale?: number;
-}>;
-/** Nested block instance (inputs may hold points, never object references). */
-type Block = Styled<{
-    type: "block";
-    definitionId: string;
-    /** 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[];
-}>;
-/** A table cell: plain text, or text with merge / alignment / style. */
-type TableCell = string | {
-    content?: string;
-    /** Character formatting over `content`. */
-    spans?: readonly TextSpan[];
-    /** Merge from this (top-left) cell; covered cells are ignored. */
-    span?: {
-        cols: number;
-        rows: number;
-    };
-    hAlign?: "left" | "center" | "right";
-    vAlign?: "top" | "center" | "bottom";
-    styleId?: string;
-    styleOverride?: TextStyleOverride;
-    color?: string;
-};
-/** Grid of text cells hanging right/down from `position` (top-left);
- * rows grow to fit their wrapped text. */
-type Table = Styled<{
-    type: "table";
-    position: Vec2Like;
-    /** Column widths (mm, before `scale`). */
-    columns: readonly number[];
-    /** Row count, or per-row settings (`minHeight` mm floor). */
-    rows: number | readonly {
-        minHeight?: number;
-    }[];
-    /** Row-major `cells[row][column]`, exactly rows × columns. */
-    cells: readonly (readonly TableCell[])[];
-    rotation?: number;
-    scale?: number;
-    /** Rows above the heavier header rule. */
-    headerRows?: number;
-    /** Text inset from the cell edges (mm). */
-    cellMargin?: number;
-    borders?: "all" | "outer" | "rows" | "none";
-    styleId?: string;
-    styleOverride?: TextStyleOverride;
-}>;
-/** What a script WRITES — the union of the authoring DTOs above (what
- * `draw` returns, what `document.add` takes). Read results are
- * `StoredObject`. */
-type ObjectInput = Line | Point | Polyline | Circle | Arc | Ellipse | Hatch | Text | Dimension | Block | Table;
-/** @deprecated The input union is `ObjectInput`; in the SDK and core
- * `ModelObject` is the STORED shape, so this name misled. Kept so existing
- * scripts compile. */
-type ModelObject = ObjectInput;
-/** Identity + shared style fields every stored object carries. */
-type StoredObjectBase = {
-    id: string;
-    layerId: string;
-    /** #rrggbb override; absent = by layer. */
-    color?: string;
-    lineType?: string;
-    lineTypeScale?: number;
-    lineWidth?: number;
-    /** Paint opacity 0..1; absent = opaque. */
-    opacity?: number;
-};
-/** Flattens base + per-type fields so hovers list every member inline
- * (same trick as Styled<T> for the authoring DTOs). */
-type StoredShape<T> = {
-    [K in keyof (T & StoredObjectBase)]: (T & StoredObjectBase)[K];
-} & {};
-/** Stored polyline vertex — bulge always present (default 0 applied). */
-type StoredPolylineVertex = {
-    x: number;
-    y: number;
-    bulge: number;
-};
-type StoredLine = StoredShape<{
-    type: "line";
-    a: Vec2;
-    b: Vec2;
-}>;
-type StoredPoint = StoredShape<{
-    type: "point";
-    p: Vec2;
-}>;
-type StoredPolyline = StoredShape<{
-    type: "polyline";
-    points: readonly StoredPolylineVertex[];
-    closed: boolean;
-}>;
-type StoredCircle = StoredShape<{
-    type: "circle";
-    center: Vec2;
-    radius: number;
-}>;
-type StoredArc = StoredShape<{
-    type: "arc";
-    center: Vec2;
-    radius: number;
-    startAngle: number;
-    endAngle: number;
-}>;
-type StoredEllipse = StoredShape<{
-    type: "ellipse";
-    center: Vec2;
-    majorAxis: Vec2;
-    ratio: number;
-    startAngle: number;
-    endAngle: number;
-}>;
-type StoredHatchFill = {
-    kind: "solid";
-} | {
-    kind: "pattern";
-    name: string;
-    angle: number;
-    scale: number;
-    /** World anchor of the pattern frame; absent = the drawing origin. */
-    origin?: Vec2;
-} | {
-    kind: "lines";
-    angle: number;
-    spacing: number;
-} | {
-    kind: "gradient";
-    shape: "linear" | "radial";
-    color1: string;
-    color2: string;
-    angle: number;
-};
-type StoredHatch = StoredShape<{
-    type: "hatch";
-    /** loops[0] = outer boundary, the rest are holes (even-odd). */
-    loops: readonly {
-        points: readonly StoredPolylineVertex[];
-    }[];
-    fill: StoredHatchFill;
-    scale: number;
-}>;
-type StoredText = StoredShape<{
-    type: "text";
-    position: Vec2;
-    content: string;
-    spans?: readonly TextSpan[];
-    leaderLines: readonly (readonly Vec2[])[];
-    /** Word-wrap / frame width in mm; absent = no wrapping. */
-    width?: number;
-    hAlign: "left" | "center" | "right";
-    vAlign: "bottom" | "center" | "top";
-    frame?: "none" | "rectangle" | "circle" | "slot" | "bottom" | "firstLine";
-    styleId?: string;
-    /** Only the keys the user actually overrode on this text. */
-    styleOverride?: {
-        font?: string;
-        widthFactor?: number;
-        bold?: boolean;
-        italic?: boolean;
-        textHeight?: number;
-        arrowType?: "filled" | "open" | "tick" | "dot" | "none";
-        arrowSize?: number;
-    };
-    rotation: number;
-    scale: number;
-}>;
-type StoredDimension = StoredShape<{
-    type: "dimension";
-    kind: "linear" | "angular" | "radial" | "diameter";
-    points: readonly Vec2[];
-    rotation?: number;
-    offset?: number;
-    labels: readonly {
-        along?: number;
-        across?: number;
-        content?: string;
-        spans?: readonly TextSpan[];
-    }[];
-    styleId?: string;
-    /** Only the keys the user actually overrode on this dimension. */
-    styleOverride?: {
-        font?: string;
-        widthFactor?: number;
-        bold?: boolean;
-        italic?: boolean;
-        textHeight?: number;
-        textOffset?: number;
-        arrowType?: "filled" | "open" | "tick" | "dot" | "none";
-        arrowSize?: number;
-        extensionType?: "long" | "short";
-        extensionOffset?: number;
-        extensionOvershoot?: number;
-        precision?: number;
-    };
-    scale: number;
-}>;
-type StoredBlock = StoredShape<{
-    type: "block";
-    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)[];
-}>;
-/** Paper-space window into model space; exists only in layout spaces. */
-type StoredViewport = StoredShape<{
-    type: "viewport";
-    rect: {
-        x: number;
-        y: number;
-        w: number;
-        h: number;
-    };
-    modelCenter: Vec2;
-    /** Drawing-scale denominator (model mm per paper mm); 1:50 => 50. */
-    scale: number;
-    locked: boolean;
-    hiddenLayerIds: readonly string[];
-}>;
-/** Raster reference; pixels live in the document's assets map. */
-type StoredImage = StoredShape<{
-    type: "image";
-    assetId: string;
-    origin: Vec2;
-    width: number;
-    height: number;
-    rotation: number;
-}>;
-/** A LINKED file drawn in place (an xref); the document holds only this
- * record — the file's content is not readable from scripts. */
-type StoredReference = StoredShape<{
-    type: "reference";
-    format: "linea" | "dxf" | "dwg" | "pdf" | "png" | "jpg";
-    name: string;
-    source: {
-        kind: "path";
-        path: string;
-        cacheKey?: string;
-    } | {
-        kind: "url";
-        url: string;
-    };
-    /** Where the file's origin lands. */
-    position: Vec2;
-    rotation: number;
-    scale: number;
-    mirrored?: boolean;
-    pdfPage?: number;
-    pdfMode?: "vector" | "raster";
-    /** The file's layers not drawn, by name. */
-    hiddenLayers: readonly string[];
-    /** Switched off: not drawn. */
-    hidden?: boolean;
-    /** Locked in the References panel: drawn and snapped, never picked. */
-    locked?: boolean;
-    /** Crop rectangle in file coordinates. */
-    clip?: {
-        minX: number;
-        minY: number;
-        maxX: number;
-        maxY: number;
-    };
-    /** Content bounds in file coordinates at the last load. */
-    extent?: {
-        minX: number;
-        minY: number;
-        maxX: number;
-        maxY: number;
-    };
-}>;
-/** Review note pinned to a point; the editor shows a screen-fixed marker. */
-type StoredComment = StoredShape<{
-    type: "comment";
-    /** Tail tip of the bubble (world/sheet mm). */
-    position: Vec2;
-    text: string;
-    tags: readonly string[];
-}>;
-/** Text style keys a text, table or table cell may override. */
-type TextStyleOverride = {
-    font?: string;
-    widthFactor?: number;
-    bold?: boolean;
-    italic?: boolean;
-    textHeight?: number;
-    arrowType?: "filled" | "open" | "tick" | "dot" | "none";
-    arrowSize?: number;
-};
-/** One table cell as stored. */
-type StoredTableCell = {
-    /** Plain text; "\n" = line break. */
-    content: string;
-    spans?: readonly TextSpan[];
-    /** Merge, on the anchor (top-left) cell; covered cells are ignored. */
-    span?: {
-        cols: number;
-        rows: number;
-    };
-    hAlign?: "left" | "center" | "right";
-    vAlign?: "top" | "center" | "bottom";
-    styleId?: string;
-    styleOverride?: TextStyleOverride;
-    color?: string;
-};
-/** Grid of text cells hanging right/down from `position` (top-left). */
-type StoredTable = StoredShape<{
-    type: "table";
-    position: Vec2;
-    rotation: number;
-    scale: number;
-    /** Column widths (mm, before `scale`). */
-    columns: readonly number[];
-    rows: readonly {
-        minHeight?: number;
-    }[];
-    /** Row-major `cells[row][column]`. */
-    cells: readonly (readonly StoredTableCell[])[];
-    headerRows: number;
-    cellMargin: number;
-    borders: "all" | "outer" | "rows" | "none";
-    styleId?: string;
-    styleOverride?: TextStyleOverride;
-}>;
-/** Any object as stored in the document — what reads hand to scripts. */
-type StoredObject = StoredLine | StoredPoint | StoredPolyline | StoredCircle | StoredArc | StoredEllipse | StoredHatch | StoredText | StoredDimension | StoredBlock | StoredViewport | StoredImage | StoredComment | StoredTable | StoredReference;
-/**
- * One choice of a "Select" parameter: the value (what scripts receive) with
- * an optional properties-panel label. A plain string is shorthand for
- * `{ value }`.
- */
-type ParameterOption = string | {
-    value: string;
-    label?: string;
-    /** A `#rrggbb` color square before the option's label. */
-    swatch?: string;
-};
-/**
- * One entry of the module's optional `params` export — the block's
- * parameters table. `name` is the key scripts read from `params`, `label`
- * the properties-panel caption (defaults to the name).
- */
-/** What every params-table entry may carry: its key, panel caption and
- * tooltip. */
-type ParamBase = {
-    /** The key scripts read from `params`. */
-    name: string;
-    /** The properties-panel caption (defaults to the name). */
-    label?: string;
-    /** What the parameter means: the label's tooltip in the panel. */
-    hint?: string;
-};
-type ParamDef = (ParamBase & {
-    type: "number";
-    default: number;
-    min?: number;
-    max?: number;
-    /** Whole numbers only. */
-    integer?: boolean;
-    /** ArrowUp / ArrowDown increment in the panel (default 1). */
-    step?: number;
-    /** Shown inside the field before / after the value ("1:", "mm"). */
-    prefix?: string;
-    suffix?: string;
-    /** Standard values offered in the field's dropdown; typing stays free. */
-    presets?: readonly number[];
-}) | (ParamBase & {
-    type: "string";
-    default: string;
-    placeholder?: string;
-    /** A textarea; Shift+Enter starts a new line. */
-    multiline?: boolean;
-    presets?: readonly string[];
-}) | (ParamBase & {
-    type: "boolean";
-    default: boolean;
-    /** "toggle": a toggle button showing the label (compact, e.g. in a
-     * row beside a picker) instead of a switch. */
-    display?: "switch" | "toggle";
-})
-/** A list of numbers, edited as space-separated text with Tekla-style
- * `N*d` repeats ("0 2*7200" → [0, 7200, 7200]). */
- | (ParamBase & {
-    type: "numberList";
-    default: readonly number[];
-    /** Shown while the list is empty. */
-    placeholder?: string;
-    min?: number;
-    max?: number;
-    presets?: readonly (readonly number[])[];
-})
-/** A list of strings, edited as space-separated words; double quotes group
- * a phrase ('A "B 2"' → ["A", "B 2"]). */
- | (ParamBase & {
-    type: "stringList";
-    default: readonly string[];
-    /** Shown while the list is empty. */
-    placeholder?: string;
-    presets?: readonly (readonly string[])[];
-})
-/** A `#rrggbb` color: a swatch with a picker; presets form a palette. */
- | (ParamBase & {
-    type: "color";
-    default: string;
-    presets?: readonly string[];
-}) | (ParamBase & {
-    type: "enum";
-    default: string;
-    options: readonly ParameterOption[];
-    /** "buttons": a segmented toggle group of the options (short
-     * choices); falls back to the dropdown when they don't fit. */
-    display?: "dropdown" | "buttons";
-})
-/** Pickers over the document's resources; the value is an id / name.
- * textStyle / dimStyle: a style id ("" or unknown = the document's first
- * style — read it in draw with `styles.text(id)` / `styles.dim(id)`, or
- * hand it to children as `styleId`). font: a font id ("arial"…).
- * lineType / hatchPattern: a linetype / pattern name. */
- | (ParamBase & {
-    type: "textStyle" | "dimStyle" | "font" | "lineType" | "hatchPattern";
-    default?: string;
-})
-/** A section label between rows in the properties panel. Carries no
- * value: it never appears in the `params` record `draw` receives.
- * `name` stays the unique key (paramVisibility can hide it by name). */
- | (ParamBase & {
-    type: "label";
-})
-/** Layout only: 2–3 compact params on one panel row, each item's label a
- * short prefix ("W", "H"). Values stay flat — `params.w`, `params.h`. */
- | (ParamBase & {
-    type: "row";
-    items: readonly RowItemDef[];
-});
-/** A document text style as `draw` reads it (`styles.text(id)`). Heights
- * and arrow sizes are mm before an object's `scale`. */
-type TextStyleInfo = {
-    readonly id: string;
-    readonly name: string;
-    readonly font: string;
-    readonly widthFactor: number;
-    readonly bold?: boolean;
-    readonly italic?: boolean;
-    readonly textHeight: number;
-    readonly arrowType: "filled" | "open" | "tick" | "dot" | "none";
-    readonly arrowSize: number;
-};
-/** A document dimension style as `draw` reads it (`styles.dim(id)`). */
-type DimStyleInfo = {
-    readonly id: string;
-    readonly name: string;
-    readonly font: string;
-    readonly widthFactor: number;
-    readonly bold?: boolean;
-    readonly italic?: boolean;
-    readonly textHeight: number;
-    readonly textOffset: number;
-    readonly arrowType: "filled" | "open" | "tick" | "dot" | "none";
-    readonly arrowSize: number;
-    readonly extensionType: "long" | "short";
-    readonly extensionOffset: number;
-    readonly extensionOvershoot: number;
-    readonly precision: number;
-};
-/** `draw`'s `styles`: the document's styles by id. An empty or unknown id
- * (a deleted style, a block from another drawing) gives the document's
- * first style — the same rule a child's `styleId` follows. */
-interface BlockStyles {
-    text(id?: string): TextStyleInfo;
-    dim(id?: string): DimStyleInfo;
-}
-/** What a `row` may hold: the compact, single-line param kinds. */
-type RowItemDef = Extract<ParamDef, {
-    type: "number" | "string" | "boolean" | "enum" | "color" | "textStyle" | "dimStyle" | "font" | "lineType" | "hatchPattern";
-}>;
-/** A table entry's value-carrying params: a row's items, else itself. */
-type FlatParam<Q> = Q extends {
-    type: "row";
-    items: readonly (infer I)[];
-} ? I : Q;
-/**
- * The block's parameters table — what the `params` member of a BlockSpec
- * declares (or its function form returns).
- */
-type BlockParamDefs = readonly ParamDef[];
-/** What the script's `draw` export must return. */
-type BlockScriptResult = ObjectInput[];
-/** The value an enum option denotes (its string, or `value` of the record form). */
-type OptionValue<O extends ParameterOption> = O extends string ? O : O extends {
-    value: infer V extends string;
-} ? V : never;
-/** The runtime value type of one `params` table entry. */
-type ParamValue<Q extends ParamDef> = Q extends {
-    type: "enum";
-} ? OptionValue<Q["options"][number]> : Q extends {
-    type: "number";
-} ? number : Q extends {
-    type: "boolean";
-} ? boolean : Q extends {
-    type: "numberList";
-} ? readonly number[] : Q extends {
-    type: "stringList";
-} ? readonly string[] : string;
-/**
- * The values record a params table produces: each entry's `name` maps to
- * its runtime value type (number/string/boolean, or the enum's option
- * union). This is what `draw`/`place`/`paramVisibility` receive as
- * `params` — inside defineBlock the table type is inferred, so authors
- * never spell this out. Unwraps the function form of `params`; a non-table
- * type (an already-derived values record, or the open BlockParams default)
- * passes through unchanged.
- */
-type ParamValues<P> = P extends () => infer R ? ParamValues<R> : P extends readonly (infer Q extends ParamDef)[] ? {
-    readonly [E in FlatParam<Q> as E extends {
-        type: "label";
-    } ? never : E extends {
-        name: infer N extends string;
-    } ? N : never]: E extends ParamDef ? ParamValue<E> : never;
-} : P;
-/** A document line type definition — objects and layers name it in
- * `lineType`, ahead of the built-in catalogue. */
-type LineType = {
-    /** Case-insensitive, unique per document. */
-    name: string;
-    description?: string;
-    /** Signed dash cycle, mm per 1 mm of line width: >0 dash, <0 gap, 0 dot.
-     * Empty = continuous. */
-    dashesMm: number[];
-};
-/** One line family of a hatch pattern, in the pattern's own frame. */
-type HatchPatternLine = {
-    /** Radians CCW. */
-    angle: number;
-    /** Base point, mm. */
-    origin: Vec2;
-    /** Shift along the line between successive lines (dash phase), mm. */
-    deltaX: number;
-    /** Perpendicular spacing between successive lines, mm. */
-    deltaY: number;
-    /** Dash cycle along the line: >0 dash, <0 gap, 0 dot; absent = solid. */
-    dashesMm?: number[];
-};
-/** A document hatch pattern definition — pattern fills name it in
- * `fill.name`, ahead of the built-in catalogue. */
-type HatchPattern = {
-    /** Case-insensitive, unique per document. */
-    name: string;
-    description?: string;
-    lines: HatchPatternLine[];
-};
-/** An axis-aligned box in world mm. */
-type Box = {
-    minX: number;
-    minY: number;
-    maxX: number;
-    maxY: number;
-};
-/** Filters for Drawing.query — all present filters AND together. */
-type ObjectQuery = {
-    ids?: readonly string[];
-    type?: ObjectInput["type"];
-    /** Layer name or id. */
-    layer?: string;
-    /** #rrggbb override (objects without one inherit from their layer). */
-    color?: string;
-    lineType?: string;
-    /** Substring match on text content. */
-    content?: string;
-    /** Bounds intersect this box. */
-    bbox?: Box;
-    /** Bounds entirely inside this box. */
-    inside?: Box;
-    /** Geometry within `tol` mm of `point`. */
-    near?: {
-        point: Vec2Like;
-        tol: number;
-    };
-    /** Search this paper layout's sheet objects (name or id) instead of
-     * model space. */
-    layout?: string;
-};
-/** A STORED object as query() returns it (see StoredObject — schema
- * output: defaults applied, points always {x, y}, identity present). */
-type ExistingObject = StoredObject;
-/** Per-object measurements; null where the type has no natural value. */
-type Measurement = {
-    bbox: Box | null;
-    length: number | null;
-    area: number | null;
-};
-/** A layer as stored (defaults applied) plus the current-layer flag. */
-type LayerInfo = {
-    id: string;
-    name: string;
-    color: string;
-    lineType: string;
-    lineWidth: number;
-    opacity: number;
-    visible: boolean;
-    locked: boolean;
-    current: boolean;
-    [key: string]: unknown;
-};
-/** A paper layout as stored: sheet metadata + its sheet-space objects. */
-type LayoutInfo = {
-    id: string;
-    name: string;
-    sheet: {
-        width: number;
-        height: number;
-    };
-    printPalette: "color" | "grayscale" | "monochrome";
-    objects: readonly StoredObject[];
-};
-/** A block module's identity/metadata (from its exports). */
-type BlockInfo = {
-    id: string;
-    name: string;
-    description?: string;
-    version?: string;
-    authors?: readonly string[];
-    tags?: readonly string[];
-    dependencies?: readonly string[];
-};
-/** A command module's identity/metadata (from its exports). */
-type CommandInfo = {
-    id: string;
-    name: string;
-    description?: string;
-    version?: string;
-    authors?: readonly string[];
-    tags?: readonly string[];
-    /** Declared point inputs (labels), picked or supplied before `run`. */
-    inputs?: readonly string[];
-    /** Declared parameters (same table as a block's), prompted or supplied
-     * before `run`. */
-    params?: readonly ParamDef[];
-};
-/** What installing module sources reports. */
-/** One configured marketplace (a block / command collection). */
-type MarketplaceConfig = {
-    kind: "builtin";
-} | {
-    kind: "github";
-    spec: string;
-    token?: string;
-} | {
-    kind: "folder";
-    folder: string;
-};
-/** A configured marketplace as listed — the token itself never shows. */
-type MarketplaceInfo = {
-    key: string;
-    kind: "builtin" | "github" | "folder";
-    label: string;
-    spec?: string;
-    folder?: string;
-    hasToken: boolean;
-};
-/** A marketplace search hit: the catalog row plus where it came from and
- * how it relates to this document's modules. */
-type MarketplaceHit = {
-    kind: "block" | "command";
-    id: string;
-    name: string;
-    version: string;
-    description?: string;
-    tags: string[];
-    authors: string[];
-    dependencies: string[];
-    marketplace: MarketplaceInfo;
-    status: {
-        kind: "absent";
-    } | {
-        kind: "installed";
-        version?: string;
-    } | {
-        kind: "update";
-        from?: string;
-    };
-};
-type MergeReport = {
-    /** The full library after the merge. */
-    merged: readonly string[];
-    added: readonly {
-        script: string;
-        meta: {
-            id: string;
-            name: string;
-        };
-    }[];
-    replaced: readonly {
-        script: string;
-        meta: {
-            id: string;
-            name: string;
-        };
-    }[];
-    skipped: number;
-    rejected: readonly {
-        script: string;
-        error: string;
-    }[];
-};
-/** A sheet: a bare preset (orientation from context — landscape for a new
- * layout, the current one when patching), a preset with its orientation, or
- * explicit millimetres. */
-type SheetSpec = "A4" | "A3" | "A2" | "A1" | "A0" | {
-    name: "A4" | "A3" | "A2" | "A1" | "A0";
-    orientation: "portrait" | "landscape";
-} | {
-    width: number;
-    height: number;
-};
-/** What an import added (`objectIds` = the new objects). */
-interface ImportReport {
-    objects: number;
-    objectIds: string[];
+  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[];
 }
-/** Options for Drawing.addLayout. */
-type LayoutSpec = {
-    /** Default: A3 landscape. */
-    sheet?: SheetSpec;
-    /** Viewport scale — `"1:50"` or the denominator; default: fitted. */
-    scale?: number | string;
-    /** One fitted model viewport (default), or `false` for a bare sheet. */
-    viewport?: {
-        rect?: {
-            x: number;
-            y: number;
-            w: number;
-            h: number;
-        };
-        scale?: number | string;
-        center?: Vec2Like;
-    } | false;
-    /** Tab position; default: append. */
-    index?: number;
-};
-/** The whole document as stored (defaults applied). */
-type StoredDocument = {
-    id: string;
-    version: number;
-    layers: readonly Omit<LayerInfo, "current">[];
-    currentLayerId: string;
-    objects: readonly StoredObject[];
-    layouts: readonly LayoutInfo[];
-    /** Raw block module sources. */
-    blockDefinitions: readonly string[];
-    /** Raw command module sources. */
-    commands: readonly string[];
-    [key: string]: unknown;
-};
-/** Where a draw-order move puts the objects. */
-type ReorderPlacement = "front" | "back" | {
-    above: string;
-} | {
-    below: string;
-};
-/**
- * The document as command scripts see it — the SAME `Drawing` interface
- * the agent tools and the SDK use. Angles are RADIANS, point-valued
- * arguments accept {x, y} or [x, y], `layer` resolves by name or id.
- * Object mutations on an editor-attached drawing target the ACTIVE space.
- * Methods throw on invalid input (an uncaught throw cancels the command
- * and rolls its edits back). Reads return detached snapshots.
- */
-interface Drawing {
-    /** The document's own id. */
-    readonly id: string;
-    /** Monotonic change counter. */
-    readonly revision: number;
-    /** The full document — a detached snapshot. */
-    readonly document: StoredDocument;
-    /** Counts by type/layer, bbox, layer + layout names. */
-    summary(): {
-        name: string;
-        objectCount: number;
-        byType: Record<string, number>;
-        byLayer: Record<string, number>;
-        bbox: Box | null;
-        layers: string[];
-        layouts: {
-            name: string;
-            objectCount: number;
-        }[];
-        settings: {
-            units: "mm" | "in";
-        };
-    };
-    /** Filtered objects — model space, or one layout via `filter.layout`. */
-    listObjects(filter?: ObjectQuery): ExistingObject[];
-    /** One object from ANY space, or undefined. */
-    getObject(id: string): ExistingObject | undefined;
-    /** bbox / curve length / enclosed area of one object. */
-    measure(id: string): Measurement;
-    listLayers(): LayerInfo[];
-    listLayouts(): LayoutInfo[];
-    /** Compilable block definitions in this document. */
-    listBlockDefinitions(): BlockInfo[];
-    /** Compilable command modules travelling with this document. */
-    listUserCommands(): CommandInfo[];
-    /** Model space (or a layout via `layout`) as an SVG string. */
-    renderSvg(opts?: {
-        layout?: string;
-        bbox?: Box;
-        padding?: number;
-        palette?: "color" | "grayscale" | "monochrome";
-    }): string;
-    /** Model space (or a layout) as PNG bytes — absent on hosts that can't
-     * rasterize, so check before calling. */
-    renderPng?(opts?: {
-        layout?: string;
-        bbox?: Box;
-        padding?: number;
-        palette?: "color" | "grayscale" | "monochrome";
-        /** Output width in px (height follows). Default 1024. */
-        width?: number;
-        /** Background fill, e.g. "#ffffff". Default: the dark canvas. */
-        background?: string;
-    }): Promise<Uint8Array>;
-    /** Multi-page PDF of the layouts (default: all) — absent on hosts
-     * without fonts, so check before calling. */
-    renderPdf?(opts?: {
-        layouts?: readonly string[];
-        palette?: "color" | "grayscale" | "monochrome";
-    }): Promise<Uint8Array>;
-    /** The whole document as DXF text. */
-    toDxf(): Promise<string>;
-    /** DWG bytes (default AC1027 — AutoCAD 2013). */
-    toDwg(opts?: {
-        version?: string;
-    }): Promise<Uint8Array>;
-    /** The `.linea` file text. */
-    toLinea(): string;
-    /** Add objects (each may carry `layer` — a name — instead of an id);
-     * returns the created ids. */
-    add(objects: readonly (ObjectInput & {
-        layer?: string;
-    })[], opts?: {
-        layout?: string;
-    }): string[];
-    /** Apply per-object patches (`{ id, ...changedFields }`). */
-    update(entries: readonly ({
-        id: string;
-    } & Record<string, unknown>)[]): void;
-    /** Delete by id (unknown ids are skipped); returns how many went. */
-    remove(ids: readonly string[]): number;
-    /** Draw order: move the objects (bottom → top) to a placement. */
-    reorder(ids: readonly string[], placement: ReorderPlacement): void;
-    move(ids: readonly string[], delta: Vec2Like): void;
-    rotate(ids: readonly string[], angleRad: number, center?: Vec2Like): void;
-    scale(ids: readonly string[], factor: number, center?: Vec2Like): void;
-    mirror(ids: readonly string[], axisA: Vec2Like, axisB: Vec2Like): void;
-    /** Duplicate displaced by delta; returns the new ids. */
-    copy(ids: readonly string[], delta: Vec2Like): string[];
-    /** count TOTAL copies at multiples of delta; returns the new ids. */
-    array(ids: readonly string[], count: number, delta: Vec2Like): string[];
-    /** Create a paper layout; returns its id. */
-    addLayout(name: string, opts?: LayoutSpec): string;
-    /** Patch a layout's name / sheet / print palette. A bare preset keeps the
-     * layout's current orientation. */
-    updateLayout(nameOrId: string, patch: {
-        name?: string;
-        sheet?: SheetSpec;
-        printPalette?: "color" | "grayscale" | "monochrome";
-    }): void;
-    removeLayout(nameOrId: string): void;
-    /** Explicit total order (names or ids) — the PDF page order. */
-    reorderLayouts(order: readonly string[]): void;
-    /** Create a layer (unique name); returns its id. */
-    addLayer(props: {
-        name: string;
-        color?: string;
-    } & Record<string, unknown>): string;
-    updateLayer(nameOrId: string, patch: Record<string, unknown>): void;
-    /** Remove an EMPTY, non-current layer. */
-    removeLayer(nameOrId: string): void;
-    /** Explicit total order (names or ids, every layer exactly once). */
-    reorderLayers(order: readonly string[]): void;
-    setCurrentLayer(nameOrId: string): void;
-    /** Document-wide settings, merged over the current record. */
-    updateSettings(patch: {
-        units?: "mm" | "in";
-    }): void;
-    /** Configured marketplaces, priority order (tokens hidden). */
-    listMarketplaces(): MarketplaceInfo[];
-    /** Add marketplaces at the top of the priority list; each catalog must be
-     * fetchable. `{ kind: "github", spec: "owner/repo[@branch]", token? }` or
-     * `{ kind: "folder", folder }`. */
-    addMarketplaces(list: readonly MarketplaceConfig[]): Promise<MarketplaceInfo[]>;
-    /** Remove by key, spec, folder or label; the built-in collection stays. */
-    removeMarketplaces(names: readonly string[]): MarketplaceInfo[];
-    /** Search entries across the marketplaces, with install status. */
-    searchMarketplaces(q?: {
-        query?: string;
-        kind?: "block" | "command";
-        marketplace?: string;
-    }): Promise<MarketplaceHit[]>;
-    /** Install (or update) entries by id, dependencies first — one undo step. */
-    installMarketplaceEntries(ids: readonly string[], marketplace?: string): Promise<MergeReport>;
-    listTextStyles(): ({
-        id: string;
-        name: string;
-    } & Record<string, unknown>)[];
-    listDimStyles(): ({
-        id: string;
-        name: string;
-    } & Record<string, unknown>)[];
-    /** Create a style (unique name; unset fields take the defaults); returns
-     * its id. Styles are addressed by name or id. */
-    addTextStyle(props: {
-        name: string;
-    } & Record<string, unknown>): string;
-    updateTextStyle(nameOrId: string, patch: Record<string, unknown>): void;
-    /** Remove a style no object uses (refused otherwise). */
-    removeTextStyle(nameOrId: string): void;
-    addDimStyle(props: {
-        name: string;
-    } & Record<string, unknown>): string;
-    updateDimStyle(nameOrId: string, patch: Record<string, unknown>): void;
-    removeDimStyle(nameOrId: string): void;
-    /** @deprecated Use updateDimStyle (default here: the first style). */
-    setDimStyle(patch: Record<string, unknown>, styleId?: string): void;
-    /** @deprecated Use updateTextStyle (default here: the first style). */
-    setTextStyle(patch: Record<string, unknown>, styleId?: string): void;
-    /** The document's own line type definitions (objects and layers name
-     * them, ahead of the built-in catalogue). */
-    listLineTypes(): LineType[];
-    /** Add definitions (names unique, case-insensitive; a clash is refused). */
-    addLineTypes(lineTypes: readonly LineType[]): void;
-    updateLineType(name: string, patch: Partial<LineType>): void;
-    /** Remove a definition; objects still naming it fall back to the
-     * catalogue or continuous. */
-    removeLineType(name: string): void;
-    /** The document's own hatch pattern definitions (same model as line
-     * types: fills name them, ahead of the catalogue). */
-    listHatchPatterns(): HatchPattern[];
-    addHatchPatterns(patterns: readonly HatchPattern[]): void;
-    updateHatchPattern(name: string, patch: Partial<HatchPattern>): void;
-    removeHatchPattern(name: string): void;
-    /** Embed image pixels (a data URL); returns the content-keyed assetId
-     * that `image` objects reference. */
-    addAsset(dataUrl: string): string;
-    /** Remove an asset (refused while an image references it). */
-    removeAsset(id: string): void;
-    /** Embedded image assets and how many images use each. */
-    listAssets(): {
-        id: string;
-        mimeType: string;
-        bytes: number;
-        users: number;
-    }[];
-    /** Merge DXF text (new layers, objects, layouts); `unitOverride` = mm
-     * per drawing unit. */
-    importDxfText(text: string, opts?: {
-        unitOverride?: number;
-    }): ImportReport & {
-        layers: number;
-        layouts: number;
-        layoutIds: string[];
-    };
-    /** Merge DWG bytes (transcoded to DXF). */
-    importDwgData(data: Uint8Array, opts?: {
-        unitOverride?: number;
-    }): Promise<ImportReport & {
-        layers: number;
-        layouts: number;
-        layoutIds: string[];
-    }>;
-    /** Merge a PDF: vectors/text onto the current layer, or (`as: "image"`,
-     * not available on every host) each page as an image at true scale. */
-    importPdfData(data: ArrayBuffer | Uint8Array, opts?: {
-        as?: "vectors" | "image";
-        origin?: Vec2Like;
-    }): Promise<ImportReport & {
-        pageCount: number;
-    }>;
-    /** Merge block module sources into the document library. */
-    addBlockDefinitions(sources: readonly string[]): Promise<MergeReport>;
-    removeBlockDefinition(id: string): void;
-    addUserCommands(sources: readonly string[]): Promise<MergeReport>;
-    removeUserCommand(id: string): void;
-    /** Escape hatch: apply an already-shaped kernel op batch (validated,
-     * atomic, one undo step). */
-    applyOps(ops: readonly Record<string, unknown>[]): void;
-    /**
-     * Group edits into ONE undo step (a command run already is one; nested
-     * calls join it). A throw rolls back what the transaction applied.
-     */
-    transaction<T>(fn: () => T, label?: string): T;
-    /** Not available while a command runs (throws) — return or throw. */
-    undo(): boolean;
-    redo(): boolean;
-}
-/** The editor's state as a script sees it. */
-type EditorState = {
-    documentId: string;
-    documentName: string;
-    space: "model" | {
-        layout: string;
-    };
-    selectedIds: string[];
-    readOnly: boolean;
-    canUndo: boolean;
-    canRedo: boolean;
-};
-/** One runnable editor command (registry entry, macro, or insert-block). */
-type EditorCommandInfo = {
-    id: string;
-    label: string;
-    group: string;
-    hotkey?: string;
-};
-/**
- * The interactive half of the context — present only when the command runs
- * inside a live editor (absent when a script runs headlessly, e.g. from the
- * CLI or the MCP server; branch on it). The pickers and `prompt` REJECT
- * when the user cancels (Escape) — let that propagate to abort the command
- * (all edits roll back), or catch it to finish an open-ended collection.
- */
-interface EditorSurface {
-    state(): EditorState;
-    setActiveSpace(space: "model" | {
-        layout: string;
-    }): void;
-    setSelection(ids: readonly string[]): void;
-    /** "fit" (everything in the active space), "selection", some objects'
-     * extents (`{ ids }`), or a window (`{ bbox }`, world mm; sheet mm in a
-     * layout). */
-    zoom(to: "fit" | "selection" | {
-        ids: readonly string[];
-    } | {
-        bbox: Box;
-    }): void;
-    /** Await one snapped world point; `referencePoint` enables rubber-band
-     * + relative typed entry from there. */
-    pickPoint(opts?: {
-        label?: string;
-        referencePoint?: Vec2Like;
-    }): Promise<Vec2>;
-    /** Await one object click; resolves the object's id. */
-    pickObject(opts?: {
-        label?: string;
-    }): Promise<string>;
-    /** Await a typed value from a small input dialog. */
-    prompt(message: string, opts?: {
-        initial?: string;
-        placeholder?: string;
-    }): Promise<string>;
-    toast(message: string, kind?: "info" | "success" | "error"): void;
-    /** Registry commands + macros + insert-block entries. */
-    listCommands(): EditorCommandInfo[];
-    /** 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>;
-}
-/**
- * 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).
- */
-interface CommandContext<P = Readonly<Record<string, unknown>>> {
-    document: Drawing;
-    editor?: EditorSurface;
-    inputs: readonly Vec2[];
-    params: P;
-    /** @deprecated Use `editor.pickPoint({ label })` (throws without an editor). */
-    pickPoint(label?: string): Promise<Vec2>;
-    /** @deprecated Use `editor.pickObject({ label })`. */
-    pickObject(label?: string): Promise<string>;
-    /** @deprecated Use `editor.state().selectedIds`. */
-    selection(): string[];
-    /** @deprecated Use `editor.setSelection(ids)`. */
-    setSelection(ids: readonly string[]): void;
-    /** @deprecated Use `editor.prompt(message, options)`. */
-    prompt(message: string, options?: {
-        initial?: string;
-        placeholder?: string;
-    }): Promise<string>;
-    /** @deprecated Use `editor.toast(message, kind)`. */
-    showToast(message: string, kind?: "info" | "success" | "error"): void;
-}
-
-// Script-contract globals: aliases into the module (not re-declarations),
-// so the in-app editor's BlockParams substitution flows through them.
-declare type BlockParams = import("lineadraw").BlockParams;
-declare type BlockInputs = import("lineadraw").BlockInputs;
-declare type ResolvedObject = import("lineadraw").ResolvedObject;
-declare type ResolvedInput<T> = import("lineadraw").ResolvedInput<T>;
-declare type PlaceProps<P = BlockParams> = import("lineadraw").PlaceProps<P>;
-declare type PlaceSpec<P = BlockParams> = import("lineadraw").PlaceSpec<P>;
-declare type PlaceInputs<Pl> = import("lineadraw").PlaceInputs<Pl>;
-declare type PreviewInputs<Pl> = import("lineadraw").PreviewInputs<Pl>;
-declare type BlockSpec<
-  P extends import("lineadraw").BlockParamDefs = readonly [],
-  Pl extends PlaceSpec<P> | undefined = undefined,
-> = import("lineadraw").BlockSpec<P, Pl>;
-declare type CommandSpec<
-  P extends import("lineadraw").BlockParamDefs = readonly [],
-> = import("lineadraw").CommandSpec<P>;