lineadraw 0.5.0 → 0.7.0

package/lineadraw.d.ts

@@ -1,6 +1,6 @@
 // GENERATED — do not edit. Typings for the virtual "lineadraw" and
 // "lineadraw/helpers" modules block scripts import from, emitted from
-// packages/core/src/blocks/{blockTypes,blockHelpers}.ts. Regenerate with:
+// packages/core/src/extensions/{scriptTypes,scriptHelpers}.ts. Regenerate with:
 //   npm run gen:lineadraw-dts -w @lineadraw/core
 
 declare module "lineadraw" {
@@ -101,18 +101,22 @@ declare module "lineadraw" {
       position: Vec2Like;
       content: string;
       rotation?: number;
-      /** Where the text SITS relative to the point. */
+      /** 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" | "bottom";
+      frame?: "none" | "rectangle" | "circle" | "slot" | "bottom" | "firstLine";
       /** MLEADER-style arrow polylines pointing at the text (arrowhead at [0]). */
       leaderLines?: readonly (readonly Vec2Like[])[];
       /** 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;
@@ -152,11 +156,48 @@ declare module "lineadraw" {
       /** Applied last, about the pivot (the first input point). */
       rotation?: number;
       scale?: number;
-      params?: Record<string, number | string | boolean>;
+      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[];
   }>;
-  export type ModelObject = Line | Point | Polyline | Circle | Arc | Ellipse | Hatch | Text | Dimension | Block;
+  /** A table cell: plain text, or text with merge / alignment / style. */
+  export type TableCell = string | {
+      text?: string;
+      /** 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. */
+  export 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;
+  }>;
+  export type ModelObject = Line | Point | Polyline | Circle | Arc | Ellipse | Hatch | Text | Dimension | Block | Table;
   /** Identity + shared style fields every stored object carries. */
   export type StoredObjectBase = {
       id: string;
@@ -250,12 +291,14 @@ declare module "lineadraw" {
       width?: number;
       hAlign: "left" | "center" | "right";
       vAlign: "bottom" | "center" | "top";
-      frame?: "none" | "rectangle" | "bottom";
+      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;
@@ -274,6 +317,8 @@ declare module "lineadraw" {
       styleOverride?: {
           font?: string;
           widthFactor?: number;
+          bold?: boolean;
+          italic?: boolean;
           textHeight?: number;
           textOffset?: number;
           arrowType?: "filled" | "open" | "tick" | "dot" | "none";
@@ -290,7 +335,7 @@ declare module "lineadraw" {
       definitionId: string;
       rotation: number;
       scale: number;
-      params: Readonly<Record<string, number | string | boolean>>;
+      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)[];
   }>;
@@ -318,8 +363,100 @@ declare module "lineadraw" {
       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<{
+      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;
+      /** 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. */
+  export 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. */
+  export 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. */
+  export type StoredTableCell = {
+      /** Plain text; "\n" = line break. */
+      text: string;
+      /** 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). */
+  export 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. */
-  export type StoredObject = StoredLine | StoredPoint | StoredPolyline | StoredCircle | StoredArc | StoredEllipse | StoredHatch | StoredText | StoredDimension | StoredBlock | StoredViewport | StoredImage;
+  export 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
@@ -328,44 +465,152 @@ declare module "lineadraw" {
   export 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).
    */
-  export type ParamDef = {
+  /** 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;
+  };
+  export type ParamDef = (ParamBase & {
       type: "number";
       default: number;
       min?: number;
       max?: number;
-  } | {
-      name: string;
-      label?: string;
+      /** 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;
-  } | {
-      name: string;
-      label?: string;
+      placeholder?: string;
+      /** A textarea; Shift+Enter starts a new line. */
+      multiline?: boolean;
+      presets?: readonly string[];
+  }) | (ParamBase & {
       type: "boolean";
       default: boolean;
-  } | {
-      name: string;
-      label?: string;
+      /** "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). */
-   | {
-      name: string;
-      label?: string;
+   | (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`. */
+  export 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)`). */
+  export 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. */
+  export interface BlockStyles {
+      text(id?: string): TextStyleInfo;
+      dim(id?: string): DimStyleInfo;
+  }
+  /** 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";
+  }>;
+  /** 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).
@@ -384,7 +629,11 @@ declare module "lineadraw" {
       type: "number";
   } ? number : Q extends {
       type: "boolean";
-  } ? boolean : string;
+  } ? 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
@@ -395,10 +644,469 @@ declare module "lineadraw" {
    * passes through unchanged.
    */
   export type ParamValues<P> = P extends () => infer R ? ParamValues<R> : P extends readonly (infer Q extends ParamDef)[] ? {
-      readonly [E in Q as E extends {
+      readonly [E in FlatParam<Q> as E extends {
           type: "label";
-      } ? never : E["name"]]: ParamValue<E>;
+      } ? never : E extends {
+          name: infer N extends string;
+      } ? N : never]: E extends ParamDef ? ParamValue<E> : never;
   } : P;
+  /** 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?: ModelObject["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). */
+  export type ExistingObject = StoredObject;
+  /** 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 = {
+      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. */
+  export 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). */
+  export 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). */
+  export 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. */
+  export 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. */
+  export 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). */
+  export interface ImportReport {
+      objects: number;
+      objectIds: string[];
+  }
+  /** Options for Drawing.addLayout. */
+  export 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). */
+  export 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. */
+  export 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.
+   */
+  export 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;
+          }[];
+      };
+      /** 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 (ModelObject & {
+          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;
+      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;
+      /** 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. */
+  export 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). */
+  export 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.
+   */
+  export 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).
+   */
+  export 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 ———
 
@@ -557,6 +1265,10 @@ declare module "lineadraw" {
     draw: (props: {
       params: ParamValues<P>;
       inputs: 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;
   }
 
@@ -598,133 +1310,41 @@ declare module "lineadraw" {
   ): BlockSpec<P, (props: PlaceProps<P>) => R>;
 
   // ——— Commands (macro scripts) ———
-
-  /** An axis-aligned box in world mm. */
-  export type Box = { minX: number; minY: number; maxX: number; maxY: number };
-
-  /** Filters for CommandDocument.query — all present filters AND together. */
-  export interface ObjectQuery {
-    ids?: readonly string[];
-    type?: ModelObject["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 };
-  }
-
-  /** A STORED object as query() returns it (see StoredObject — schema
-   * output: defaults applied, points always {x, y}, identity present). */
-  export type ExistingObject = StoredObject;
-
-  /** Per-object measurements; null where the type has no natural value. */
-  export type Measurement = {
-    bbox: Box | null;
-    length: number | null;
-    area: number | null;
-  };
-
-  /**
-   * The document as command scripts see it — the same session surface the
-   * agent tools are written against. Angles are RADIANS, point-valued
-   * arguments accept {x, y} or [x, y], `layer` resolves by name or id.
-   * Object mutations target the ACTIVE space. Methods throw on invalid
-   * input (an uncaught throw cancels the command and rolls its edits back).
-   */
-  export interface CommandDocument {
-    /** Add objects (each may carry `layer` — a name — instead of an id);
-     * returns the created ids. */
-    add(
-      objects: readonly (ModelObject & { 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;
-    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[];
-    /** Filtered MODEL-space objects. */
-    query(filter: ObjectQuery): ExistingObject[];
-    /** bbox / curve length / enclosed area of one object. */
-    measure(id: string): Measurement;
-    listLayers(): {
-      id: string;
-      name: string;
-      current: boolean;
-      [key: string]: unknown;
-    }[];
-    /** 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;
-    setCurrentLayer(nameOrId: string): void;
-    /** Create a paper layout; returns its id. `scale` accepts "1:50". */
-    createLayout(
-      name: string,
-      opts: {
-        sheet?: "A4" | "A3" | "A2" | "A1" | "A0" | { width: number; height: number };
-        orientation?: "portrait" | "landscape";
-        scale?: string;
-      },
-    ): string;
-    /** Counts by type/layer, bbox, layer + layout names. */
-    summary(): Record<string, unknown>;
-  }
-
-  /**
-   * What `run` receives. 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 gracefully.
-   */
-  export interface CommandContext {
-    document: CommandDocument;
-    /** Await one snapped world point. */
-    pickPoint(label?: string): Promise<Vec2>;
-    /** Await one object click; resolves the object's id. */
-    pickObject(label?: string): Promise<string>;
-    /** Ids currently selected — a snapshot; call again after changes. */
-    selection(): string[];
-    setSelection(ids: readonly string[]): void;
-    /** Await a typed value from a small input dialog. */
-    prompt(
-      message: string,
-      options?: { initial?: string; placeholder?: string },
-    ): Promise<string>;
-    showToast(message: string, kind?: "info" | "success" | "error"): void;
-  }
+  // 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 {
+  export interface CommandSpec<P extends BlockParamDefs = readonly []> {
     id: string;
     name: string;
     description?: string;
     version?: string;
     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.
+     */
+    inputs?: readonly string[];
+    /**
+     * Parameters the command needs — the same table a block's `params`
+     * declares (number / string / boolean / enum / label rows), or a
+     * zero-arg function returning it. In the editor a dialog asks for them
+     * before `run` (prefilled with the defaults); a headless or remote
+     * caller passes them by name (unknown names and wrong types are an
+     * error). They arrive as `ctx.params`, typed from this table.
+     */
+    params?: P | (() => P);
     /**
      * The macro body. The whole call is ONE undo step: mutations apply
      * live while it runs; cancelling (Escape during a pick/prompt) or an
-     * uncaught error rolls everything back.
+     * uncaught error rolls everything back. A return value is handed to
+     * the caller (the agent tool / CLI) — the editor ignores it.
      */
-    run(ctx: CommandContext): void | Promise<void>;
+    run(ctx: CommandContext<ParamValues<P>>): unknown;
   }
 
   /**
@@ -736,18 +1356,23 @@ declare module "lineadraw" {
    *   export default defineCommand({
    *     id: "…",
    *     name: "Number the selected texts",
-   *     run: async ({ document, prompt, selection, showToast }) => {
-   *       const start = Number(await prompt("First number", { initial: "1" }));
-   *       const texts = document
-   *         .query({ ids: selection(), type: "text" });
+   *     inputs: ["Anchor"],
+   *     params: [{ name: "start", label: "First number", type: "number", default: 1 }],
+   *     run: ({ document, editor, inputs: [anchor], params: { start } }) => {
+   *       const texts = document.listObjects({
+   *         type: "text",
+   *         near: { point: anchor, tol: 500 },
+   *       });
    *       texts.forEach((t, i) =>
    *         document.update([{ id: t.id, content: String(start + i) }]),
    *       );
-   *       showToast(`Numbered ${texts.length} texts`, "success");
+   *       editor?.toast(`Numbered ${texts.length} texts`, "success");
    *     },
    *   });
    */
-  export function defineCommand(spec: CommandSpec): CommandSpec;
+  export function defineCommand<const P extends BlockParamDefs = readonly []>(
+    spec: CommandSpec<P>,
+  ): CommandSpec<P>;
 }
 
 declare module "lineadraw/helpers" {
@@ -902,18 +1527,22 @@ type Text = Styled<{
     position: Vec2Like;
     content: string;
     rotation?: number;
-    /** Where the text SITS relative to the point. */
+    /** 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" | "bottom";
+    frame?: "none" | "rectangle" | "circle" | "slot" | "bottom" | "firstLine";
     /** MLEADER-style arrow polylines pointing at the text (arrowhead at [0]). */
     leaderLines?: readonly (readonly Vec2Like[])[];
     /** 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;
@@ -953,11 +1582,48 @@ type Block = Styled<{
     /** Applied last, about the pivot (the first input point). */
     rotation?: number;
     scale?: number;
-    params?: Record<string, number | string | boolean>;
+    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[];
 }>;
-type ModelObject = Line | Point | Polyline | Circle | Arc | Ellipse | Hatch | Text | Dimension | Block;
+/** A table cell: plain text, or text with merge / alignment / style. */
+type TableCell = string | {
+    text?: string;
+    /** 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;
+}>;
+type ModelObject = Line | Point | Polyline | Circle | Arc | Ellipse | Hatch | Text | Dimension | Block | Table;
 /** Identity + shared style fields every stored object carries. */
 type StoredObjectBase = {
     id: string;
@@ -1051,12 +1717,14 @@ type StoredText = StoredShape<{
     width?: number;
     hAlign: "left" | "center" | "right";
     vAlign: "bottom" | "center" | "top";
-    frame?: "none" | "rectangle" | "bottom";
+    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;
@@ -1075,6 +1743,8 @@ type StoredDimension = StoredShape<{
     styleOverride?: {
         font?: string;
         widthFactor?: number;
+        bold?: boolean;
+        italic?: boolean;
         textHeight?: number;
         textOffset?: number;
         arrowType?: "filled" | "open" | "tick" | "dot" | "none";
@@ -1091,7 +1761,7 @@ type StoredBlock = StoredShape<{
     definitionId: string;
     rotation: number;
     scale: number;
-    params: Readonly<Record<string, number | string | boolean>>;
+    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)[];
 }>;
@@ -1119,8 +1789,100 @@ type StoredImage = StoredShape<{
     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;
+    /** 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. */
+    text: string;
+    /** 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;
+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
@@ -1129,44 +1891,152 @@ type StoredObject = StoredLine | StoredPoint | StoredPolyline | StoredCircle | S
 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).
  */
-type ParamDef = {
+/** 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;
-} | {
-    name: string;
-    label?: string;
+    /** 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;
-} | {
-    name: string;
-    label?: string;
+    placeholder?: string;
+    /** A textarea; Shift+Enter starts a new line. */
+    multiline?: boolean;
+    presets?: readonly string[];
+}) | (ParamBase & {
     type: "boolean";
     default: boolean;
-} | {
-    name: string;
-    label?: string;
+    /** "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). */
- | {
-    name: string;
-    label?: string;
+ | (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).
@@ -1185,7 +2055,11 @@ type ParamValue<Q extends ParamDef> = Q extends {
     type: "number";
 } ? number : Q extends {
     type: "boolean";
-} ? boolean : string;
+} ? 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
@@ -1196,10 +2070,469 @@ type ParamValue<Q extends ParamDef> = Q extends {
  * passes through unchanged.
  */
 type ParamValues<P> = P extends () => infer R ? ParamValues<R> : P extends readonly (infer Q extends ParamDef)[] ? {
-    readonly [E in Q as E extends {
+    readonly [E in FlatParam<Q> as E extends {
         type: "label";
-    } ? never : E["name"]]: ParamValue<E>;
+    } ? never : E extends {
+        name: infer N extends string;
+    } ? N : never]: E extends ParamDef ? ParamValue<E> : never;
 } : P;
+/** 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?: ModelObject["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. */
+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[];
+}
+/** 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;
+        }[];
+    };
+    /** 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 (ModelObject & {
+        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;
+    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;
+    /** 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.
@@ -1215,10 +2548,6 @@ declare type BlockSpec<
   P extends import("lineadraw").BlockParamDefs = readonly [],
   Pl extends PlaceSpec<P> | undefined = undefined,
 > = import("lineadraw").BlockSpec<P, Pl>;
-declare type Box = import("lineadraw").Box;
-declare type ObjectQuery = import("lineadraw").ObjectQuery;
-declare type ExistingObject = import("lineadraw").ExistingObject;
-declare type Measurement = import("lineadraw").Measurement;
-declare type CommandDocument = import("lineadraw").CommandDocument;
-declare type CommandContext = import("lineadraw").CommandContext;
-declare type CommandSpec = import("lineadraw").CommandSpec;
+declare type CommandSpec<
+  P extends import("lineadraw").BlockParamDefs = readonly [],
+> = import("lineadraw").CommandSpec<P>;