@snaptrude/plugin-core 0.9.16 → 0.9.18-edgesetbacks-20261021.1

package/src/api/core/io/import/index.ts

@@ -1,504 +1,504 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../../../types"
-import {
-  Vec3Handle,
-  UnderlayHandle,
-  TerrainHandle,
-  ImportJobHandle,
-  ComponentHandle,
-} from "../../../../handles"
-
-/**
- * A file `source` accepted by every importer: an `https://` URL or a `data:`
- * URL (base64). Validated for shape at the boundary — other schemes (`http:`,
- * `blob:`, `file:`) are rejected, since the host page (HTTPS) cannot fetch them.
- */
-export const ImportSource = z
-  .string()
-  .min(1)
-  .refine((s) => s.startsWith("https://") || s.startsWith("data:"), {
-    message: "source must be an https:// URL or a data: URL",
-  })
-
-/**
- * File import — bring external files into the Snaptrude **scene**.
- *
- * `core.io.import.*` ingests images, PDFs, CAD drawings, 3D models, and site
- * terrain and commits them to the model as traceable underlays, placed geometry,
- * or topography. It is the scene counterpart to `presentation.import.*` (which
- * drops assets on the Present canvas, not the model).
- *
- * ## The `source` argument
- * Every file importer takes a single `source` **string** — either an `https://`
- * URL or a `data:` URL (base64). A plugin worker cannot hand a browser `File`
- * across the boundary, so the host fetches `source` and rebuilds the `File`
- * itself. Both forms go through the same path.
- *
- * ## Return values
- * - `image` / `pdf` / `cadJson` → an {@linkcode UnderlayHandle} (a placed 2D
- *   reference plane; drive it with `core.io.underlay.*`).
- * - `dwg` → an {@linkcode ImportJobHandle} — DWG conversion is a long server job,
- *   so `dwg` returns immediately and you poll it with `core.io.job.*`.
- * - `model` → a {@linkcode ComponentHandle} (a placed 3D component).
- * - `terrain` → a {@linkcode TerrainHandle} (the project's single site terrain).
- *
- * Every importer **throws** on failure (bad source, unsupported format, engine
- * error). Accessed via `snaptrude.core.io.import`.
- */
-export abstract class PluginCoreIoImportApi {
-  constructor() {}
-
-  /**
-   * Import a raster image as a scene **underlay** — a flat, textured reference
-   * plane placed on a storey that you can trace over.
-   *
-   * Supported formats: PNG, JPG/JPEG, BMP. The image is placed on the target
-   * storey's "Image" layer at ~50% opacity by default.
-   *
-   * To place the image on a **Present-mode sheet** instead of the scene, use
-   * `presentation.import.image`.
-   *
-   * The plane is placed at the storey origin (the engine's import placement);
-   * there is no placement parameter — calibrate size with
-   * {@link PluginCoreIoUnderlayApi.setScale} after import.
-   *
-   * @param source - The image to import: an `https://` URL or a `data:` URL.
-   * @param storey - Target storey number. Defaults to the active storey.
-   * @param scale - Initial uniform scale factor applied to the plane. Calibrate
-   *   precisely afterwards with {@link PluginCoreIoUnderlayApi.setScale}.
-   * @param opacity - Plane opacity, `0`..`1` (default ~`0.5`).
-   * @param label - A name for the created underlay.
-   * @returns the created {@linkcode UnderlayHandle}.
-   * @throws if writes are disabled, the source can't be loaded, the format is
-   *   unsupported, or the engine fails to place the plane.
-   *
-   * @examplePrompt Import this floor plan image onto the ground floor to trace over
-   * @examplePrompt Drop this survey PNG in as a reference underlay at 30% opacity
-   * @examplePrompt Add a site plan image on storey 2
-   * @examplePrompt Bring in a sketch to trace, faded to half opacity
-   *
-   * # Example
-   * ```ts
-   * // Place a floor plan on storey 1, then calibrate it to a real-world size.
-   * const plan = await snaptrude.core.io.import.image(
-   *   "https://example.com/floorplan.png",
-   *   1,           // storey
-   *   undefined,   // scale
-   *   0.4,         // opacity
-   *   "Ground floor plan",
-   * )
-   * // Make the plan's longest side exactly 40 project-units:
-   * await snaptrude.core.io.underlay.setScale(plan, { planSize: 40 })
-   * ```
-   */
-  public abstract image(
-    source: string,
-    storey?: number,
-    scale?: number,
-    opacity?: number,
-    label?: string,
-  ): PluginApiReturn<UnderlayHandle>
-
-  /**
-   * Import one page of a PDF as a scene **underlay** (a traceable reference plane).
-   *
-   * One PDF per storey, one page per call. To bring in several pages, call once
-   * per page onto different storeys.
-   *
-   * @param source - The PDF to import: an `https://` URL or a `data:` URL.
-   * @param storey - Target storey number. Defaults to the active storey.
-   * @param page - 1-based page number to import (multi-page PDFs). Default `1`.
-   * @param scale - A drawing-scale **label** that sizes the page in real-world
-   *   units, matching the project's unit mode: metric `"1:10"`..`"1:1000"` (e.g.
-   *   `"1:100"`) or imperial `` `1/8" = 1'` `` / `` `1" = 10'` ``. Must be a valid
-   *   label for the current unit mode (invalid → throws). Defaults to `"1:100"`
-   *   in metric projects and `` `1" = 1'` `` in imperial projects. Re-calibrate
-   *   afterwards with {@link PluginCoreIoUnderlayApi.setScale}.
-   * @param opacity - Plane opacity, `0`..`1` (default ~`0.5`).
-   * @returns the created {@linkcode UnderlayHandle}.
-   * @throws if writes are disabled, the source can't be loaded, the storey
-   *   already has a PDF, the page is out of range, the scale label is invalid for
-   *   the unit mode, or the engine fails.
-   *
-   * @examplePrompt Import page 1 of this PDF floor plan onto storey 1
-   * @examplePrompt Bring in the second page of this PDF as an underlay at 1:50
-   * @examplePrompt Add this PDF plan to the ground floor to trace over
-   * @examplePrompt Place page 3 of the drawing set on storey 3
-   *
-   * # Example
-   * ```ts
-   * const sheet = await snaptrude.core.io.import.pdf(
-   *   "https://example.com/plans.pdf",
-   *   1,        // storey
-   *   2,        // page
-   *   "1:100",  // drawing scale
-   * )
-   * ```
-   */
-  public abstract pdf(
-    source: string,
-    storey?: number,
-    page?: number,
-    scale?: string,
-    opacity?: number,
-  ): PluginApiReturn<UnderlayHandle>
-
-  /**
-   * Import a **DWG** CAD drawing as a scene underlay. `.dwg` only (no DXF).
-   *
-   * DWG conversion runs on a server and can take minutes, so this **starts a job
-   * and returns immediately** with an {@linkcode ImportJobHandle}. One CAD
-   * import runs at a time: starting a second while one is in flight throws —
-   * poll the first job to completion first. Poll it with
-   * {@link PluginCoreIoJobApi.isComplete} / {@link PluginCoreIoJobApi.getStatus}, then call
-   * {@link PluginCoreIoJobApi.getResult} to get the placed {@linkcode UnderlayHandle}.
-   * For CAD you already have parsed as JSON, use {@link PluginCoreIoImportApi.cadJson}
-   * (synchronous, no server round-trip).
-   *
-   * All CAD layers are imported (there is no layer filter).
-   *
-   * @param source - The `.dwg` file: an `https://` URL or a `data:` URL.
-   * @param storey - Target storey number. Defaults to the active storey.
-   * @returns an {@linkcode ImportJobHandle} to poll via `core.io.job.*`.
-   * @throws if writes are disabled or the upload cannot be started. (Conversion
-   *   failures surface later via {@link PluginCoreIoJobApi.getError}.)
-   *
-   * @examplePrompt Import this DWG floor plan onto storey 1
-   * @examplePrompt Bring in a CAD drawing as an underlay and tell me when it's ready
-   * @examplePrompt Start importing this CAD file onto the ground floor
-   *
-   * # Example
-   * ```ts
-   * const job = await snaptrude.core.io.import.dwg("https://example.com/plan.dwg", 1)
-   * // Poll until the server-side conversion finishes — always with a timeout
-   * // (a UI-cancelled import stays "processing" forever).
-   * const deadline = Date.now() + 5 * 60_000
-   * while (!(await snaptrude.core.io.job.isComplete(job))) {
-   *   if (Date.now() > deadline) throw new Error("DWG import timed out")
-   *   await new Promise((r) => setTimeout(r, 2000))
-   * }
-   * // The DWG lands as a CAD underlay. CAD scaling isn't supported; manage it
-   * // (list / fade / delete) via core.io.underlay.*.
-   * const cad = await snaptrude.core.io.job.getResult(job)
-   * if (cad) console.log("DWG imported as CAD underlay:", cad)
-   * ```
-   */
-  public abstract dwg(
-    source: string,
-    storey?: number,
-  ): PluginApiReturn<ImportJobHandle>
-
-  /**
-   * Sketch a CAD underlay from **already-parsed CAD JSON** — synchronous, with no
-   * server round-trip. Use this when you hold parsed CAD data (e.g. produced by
-   * your own converter); use {@link PluginCoreIoImportApi.dwg} for raw `.dwg`
-   * files.
-   *
-   * All layers in the JSON are sketched (there is no layer filter), at the
-   * drawing's own coordinates.
-   *
-   * @param cad - The parsed CAD data: `{ unit, geometry: [...] }` describing the
-   *   drawing's lines/arcs/layers.
-   * @param storey - Target storey number. Defaults to the active storey.
-   * @returns the created {@linkcode UnderlayHandle}.
-   * @throws if writes are disabled, the JSON yields no drawable geometry, or the
-   *   drawing is out of bounds.
-   *
-   * @examplePrompt Sketch this parsed CAD JSON onto the active storey
-   * @examplePrompt Draw these CAD curves as an underlay on storey 2
-   * @examplePrompt Create a CAD sketch from this geometry data
-   * @examplePrompt Import my converted CAD JSON onto the ground floor
-   *
-   * # Example
-   * ```ts
-   * const cad = await snaptrude.core.io.import.cadJson(
-   *   { unit: "mm", geometry: [{ type: "line", layer: "WALLS", ... }] },
-   *   1,
-   * )
-   * ```
-   */
-  public abstract cadJson(
-    cad: CadJsonInput,
-    storey?: number,
-  ): PluginApiReturn<UnderlayHandle>
-
-  /**
-   * Import a **3D model** file and place it in the scene as a component.
-   *
-   * Supported formats: SketchUp (`.skp`), FBX (`.fbx`), OBJ (`.obj`), 3DS
-   * (`.3ds`), and zipped bundles (`.zip`). The file is converted on the server,
-   * then placed. `.glb`/`.gltf`/`.ifc`/`.stl` and Rhino/Revit are not supported.
-   *
-   * The model is placed at its source dimensions (interpreted in the file's own
-   * units); there is no import-time scale override.
-   *
-   * Unlike `dwg`, this call **waits for the server conversion**: a large model
-   * may exceed the 60-second call cap and reject at the API boundary while the
-   * import still completes in the background (the model then appears without a
-   * handle being returned — re-query the scene to find it). Keep sources small.
-   *
-   * @param source - The model file: an `https://` URL or a `data:` URL.
-   * @param storey - Target storey number. Defaults to the active storey.
-   * @param format - The file's format. Inferred from `source` when omitted.
-   * @param position - Where to place the model. Defaults to the storey origin.
-   * @param label - A name for the placed component.
-   * @returns the placed {@linkcode ComponentHandle}.
-   * @throws if writes are disabled, the source can't be loaded, the format is
-   *   unsupported, conversion/placement fails, or the converted model cannot be
-   *   found in the library after upload; `PRECONDITION_FAILED`
-   *   (`details.engineCode: "TOOL_ACTIVE"`) while the interactive furniture tool is
-   *   active — finish or cancel it first.
-   *
-   * @examplePrompt Import this SketchUp model onto storey 1
-   * @examplePrompt Bring in this OBJ file and place it at the origin
-   * @examplePrompt Add this 3D model to the ground floor
-   *
-   * # Example
-   * ```ts
-   * const model = await snaptrude.core.io.import.model(
-   *   "https://example.com/tree.skp",
-   *   1,        // storey
-   *   "skp",
-   * )
-   * ```
-   */
-  public abstract model(
-    source: string,
-    storey?: number,
-    format?: ModelFormat,
-    position?: Vec3Handle,
-    label?: string,
-  ): PluginApiReturn<ComponentHandle>
-
-  /**
-   * Import **site terrain** for a location — Mapbox topography (elevation +
-   * satellite/streets imagery, optional neighborhood buildings and parcels).
-   *
-   * One terrain per project (a singleton). `width`/`length` describe the
-   * real-world extent of the area to load **in metres** (regardless of the
-   * project's unit mode); the host converts them to the right map zoom
-   * internally — you do not pass a zoom level.
-   *
-   * @param lat - Site latitude (degrees), `-90`..`90`.
-   * @param lng - Site longitude (degrees), `-180`..`180`.
-   * @param width - East–west extent of the area to load, in metres.
-   * @param length - North–south extent of the area to load, in metres.
-   * @param elevation - Include DEM elevation (a real terrain surface). Default `true`.
-   * @param satellite - Drape satellite imagery. Default `true`.
-   * @param neighborhood - Include surrounding context buildings. Default `false`.
-   * @param parcels - Include site parcel boundaries. Default `false`.
-   * @returns the created {@linkcode TerrainHandle}.
-   * @throws if writes are disabled, a terrain already exists, or the map/mesh
-   *   generation fails.
-   *
-   * @examplePrompt Import the site terrain for this location, about 500m across
-   * @examplePrompt Load the topography at 40.7128, -74.0060 for a 300 by 300 meter site
-   * @examplePrompt Bring in satellite terrain for the site with the surrounding buildings
-   * @examplePrompt Add site elevation for a 1km by 1km area at these coordinates
-   *
-   * # Example
-   * ```ts
-   * // 300m × 300m site with elevation + satellite imagery.
-   * const terrain = await snaptrude.core.io.import.terrain(
-   *   40.7128,  // lat
-   *   -74.006,  // lng
-   *   300,      // width  (metres)
-   *   300,      // length (metres)
-   *   true,     // elevation
-   *   true,     // satellite
-   * )
-   * ```
-   */
-  public abstract terrain(
-    lat: number,
-    lng: number,
-    width: number,
-    length: number,
-    elevation?: boolean,
-    satellite?: boolean,
-    neighborhood?: boolean,
-    parcels?: boolean,
-  ): PluginApiReturn<TerrainHandle>
-
-  /**
-   * Import an **EPW weather file** into the project's weather catalog.
-   *
-   * Uploads an EnergyPlus Weather (`.epw`) file and registers it as the
-   * project's site weather, returning its catalog `weatherFileId` — the same id
-   * {@link PluginAnalysisWeatherApi.getSeries}, `program.site.getWeather`, and a
-   * daylight run's provenance report. Uploading a user file makes the site's
-   * `selectionMethod` `"user-upload"`, overriding nearest-station resolution.
-   *
-   * **Mutating**: this writes project state and is subject to the plugin
-   * write-gate — it throws when plugin writes are disabled. Unlike the file
-   * underlay/model importers it returns no scene handle (a weather file is not
-   * a scene object), only the catalog `{ weatherFileId, label }`.
-   *
-   * @param source - The `.epw` file to import: an `https://` URL or a `data:` URL.
-   * @returns A {@linkcode PluginImportEpwResult} — the catalog `weatherFileId`
-   *   and a human-readable `label` (the station/file name).
-   * @throws if writes are disabled, the source can't be loaded, or the file is
-   *   not a valid EPW.
-   *
-   * @examplePrompt Import this EPW weather file for the site
-   * @examplePrompt Upload a custom weather file for the daylight analysis
-   * @examplePrompt Use this .epw as the project's weather source
-   *
-   * # Example
-   * ```ts
-   * const { weatherFileId, label } = await snaptrude.core.io.import.epw(
-   *   "https://example.com/Chicago-OHare.epw",
-   * )
-   * console.log(`Weather set to ${label} (${weatherFileId})`)
-   * ```
-   */
-  public abstract epw(source: string): PluginApiReturn<PluginImportEpwResult>
-}
-
-/**
- * Supported 3D model import formats. `.glb`/`.gltf`/`.ifc`/`.stl` and Rhino/Revit
- * are intentionally excluded (no in-app import path).
- */
-export const ModelFormat = z.enum(["skp", "fbx", "obj", "3ds", "zip"])
-export type ModelFormat = z.infer<typeof ModelFormat>
-
-/**
- * Parsed CAD JSON accepted by {@link PluginCoreIoImportApi.cadJson}. `unit` sets
- * the drawing's length unit; `geometry` is the array of CAD entities (lines,
- * polylines, arcs, circles), each tagged with its CAD `layer`. Additional fields
- * are passed through untouched.
- */
-export const CadJsonInput = z
-  .object({
-    unit: z.string().optional(),
-    geometry: z.array(z.record(z.string(), z.unknown())).optional(),
-  })
-  .passthrough()
-export type CadJsonInput = z.infer<typeof CadJsonInput>
-
-/**
- * Arguments for {@link PluginCoreIoImportApi.image}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `source` | `string` | Image `https://` URL or `data:` URL (png/jpg/jpeg/bmp) |
- * | `storey` | `number`? | Target storey (default: active) |
- * | `scale` | `number`? | Initial uniform scale |
- * | `opacity` | `number`? | `0`..`1` (default ~`0.5`) |
- * | `label` | `string`? | Name for the underlay |
- */
-export const PluginImportImageArgs = z.object({
-  source: ImportSource,
-  storey: z.number().int().optional(),
-  scale: z.number().positive().optional(),
-  opacity: z.number().min(0).max(1).optional(),
-  label: z.string().optional(),
-})
-export type PluginImportImageArgs = z.infer<typeof PluginImportImageArgs>
-
-/**
- * Arguments for {@link PluginCoreIoImportApi.pdf}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `source` | `string` | PDF `https://` URL or `data:` URL |
- * | `storey` | `number`? | Target storey (default: active) |
- * | `page` | `number`? | 1-based page (default `1`) |
- * | `scale` | `string`? | Drawing-scale label, e.g. `"1:100"` |
- * | `opacity` | `number`? | `0`..`1` (default ~`0.5`) |
- */
-export const PluginImportPdfArgs = z.object({
-  source: ImportSource,
-  storey: z.number().int().optional(),
-  page: z.number().int().positive().optional(),
-  scale: z.string().optional(),
-  opacity: z.number().min(0).max(1).optional(),
-})
-export type PluginImportPdfArgs = z.infer<typeof PluginImportPdfArgs>
-
-/** Arguments for {@link PluginCoreIoImportApi.dwg}. */
-export const PluginImportDwgArgs = z.object({
-  source: ImportSource,
-  storey: z.number().int().optional(),
-})
-export type PluginImportDwgArgs = z.infer<typeof PluginImportDwgArgs>
-
-/** Arguments for {@link PluginCoreIoImportApi.cadJson}. */
-export const PluginImportCadJsonArgs = z.object({
-  cad: CadJsonInput,
-  storey: z.number().int().optional(),
-})
-export type PluginImportCadJsonArgs = z.infer<typeof PluginImportCadJsonArgs>
-
-/**
- * Arguments for {@link PluginCoreIoImportApi.model}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `source` | `string` | Model `https://` URL or `data:` URL |
- * | `storey` | `number`? | Target storey (default: active) |
- * | `format` | {@link ModelFormat}? | File format (inferred when omitted) |
- * | `position` | {@link Vec3Handle}? | Placement (default: storey origin) |
- * | `label` | `string`? | Name for the component |
- */
-export const PluginImportModelArgs = z.object({
-  source: ImportSource,
-  storey: z.number().int().optional(),
-  format: ModelFormat.optional(),
-  position: Vec3Handle.optional(),
-  label: z.string().optional(),
-})
-export type PluginImportModelArgs = z.infer<typeof PluginImportModelArgs>
-
-/**
- * Arguments for {@link PluginCoreIoImportApi.terrain}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `lat` | `number` | Latitude (degrees), `-90`..`90` |
- * | `lng` | `number` | Longitude (degrees), `-180`..`180` |
- * | `width` | `number` | East–west extent, metres |
- * | `length` | `number` | North–south extent, metres |
- * | `elevation` | `boolean`? | Include DEM elevation (default `true`) |
- * | `satellite` | `boolean`? | Drape satellite imagery (default `true`) |
- * | `neighborhood` | `boolean`? | Include context buildings (default `false`) |
- * | `parcels` | `boolean`? | Include parcel boundaries (default `false`) |
- */
-export const PluginImportTerrainArgs = z.object({
-  lat: z.number().min(-90).max(90),
-  lng: z.number().min(-180).max(180),
-  width: z.number().positive().finite(),
-  length: z.number().positive().finite(),
-  elevation: z.boolean().optional(),
-  satellite: z.boolean().optional(),
-  neighborhood: z.boolean().optional(),
-  parcels: z.boolean().optional(),
-})
-export type PluginImportTerrainArgs = z.infer<typeof PluginImportTerrainArgs>
-
-/**
- * Arguments for {@link PluginCoreIoImportApi.epw}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `source` | `string` | EPW `https://` URL or `data:` URL |
- */
-export const PluginImportEpwArgs = z.object({
-  source: ImportSource,
-})
-export type PluginImportEpwArgs = z.infer<typeof PluginImportEpwArgs>
-
-/**
- * Result of {@link PluginCoreIoImportApi.epw} — the imported weather file's
- * catalog entry.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `weatherFileId` | `string` | Catalog id (same key as `analysis.weather`'s `weatherFileId`) |
- * | `label` | `string` | Human-readable name (station / file name) |
- */
-export const PluginImportEpwResult = z.object({
-  weatherFileId: z.string(),
-  label: z.string(),
-})
-export type PluginImportEpwResult = z.infer<typeof PluginImportEpwResult>
+import * as z from "zod"
+import { PluginApiReturn } from "../../../../types"
+import {
+  Vec3Handle,
+  UnderlayHandle,
+  TerrainHandle,
+  ImportJobHandle,
+  ComponentHandle,
+} from "../../../../handles"
+
+/**
+ * A file `source` accepted by every importer: an `https://` URL or a `data:`
+ * URL (base64). Validated for shape at the boundary — other schemes (`http:`,
+ * `blob:`, `file:`) are rejected, since the host page (HTTPS) cannot fetch them.
+ */
+export const ImportSource = z
+  .string()
+  .min(1)
+  .refine((s) => s.startsWith("https://") || s.startsWith("data:"), {
+    message: "source must be an https:// URL or a data: URL",
+  })
+
+/**
+ * File import — bring external files into the Snaptrude **scene**.
+ *
+ * `core.io.import.*` ingests images, PDFs, CAD drawings, 3D models, and site
+ * terrain and commits them to the model as traceable underlays, placed geometry,
+ * or topography. It is the scene counterpart to `presentation.import.*` (which
+ * drops assets on the Present canvas, not the model).
+ *
+ * ## The `source` argument
+ * Every file importer takes a single `source` **string** — either an `https://`
+ * URL or a `data:` URL (base64). A plugin worker cannot hand a browser `File`
+ * across the boundary, so the host fetches `source` and rebuilds the `File`
+ * itself. Both forms go through the same path.
+ *
+ * ## Return values
+ * - `image` / `pdf` / `cadJson` → an {@linkcode UnderlayHandle} (a placed 2D
+ *   reference plane; drive it with `core.io.underlay.*`).
+ * - `dwg` → an {@linkcode ImportJobHandle} — DWG conversion is a long server job,
+ *   so `dwg` returns immediately and you poll it with `core.io.job.*`.
+ * - `model` → a {@linkcode ComponentHandle} (a placed 3D component).
+ * - `terrain` → a {@linkcode TerrainHandle} (the project's single site terrain).
+ *
+ * Every importer **throws** on failure (bad source, unsupported format, engine
+ * error). Accessed via `snaptrude.core.io.import`.
+ */
+export abstract class PluginCoreIoImportApi {
+  constructor() {}
+
+  /**
+   * Import a raster image as a scene **underlay** — a flat, textured reference
+   * plane placed on a storey that you can trace over.
+   *
+   * Supported formats: PNG, JPG/JPEG, BMP. The image is placed on the target
+   * storey's "Image" layer at ~50% opacity by default.
+   *
+   * To place the image on a **Present-mode sheet** instead of the scene, use
+   * `presentation.import.image`.
+   *
+   * The plane is placed at the storey origin (the engine's import placement);
+   * there is no placement parameter — calibrate size with
+   * {@link PluginCoreIoUnderlayApi.setScale} after import.
+   *
+   * @param source - The image to import: an `https://` URL or a `data:` URL.
+   * @param storey - Target storey number. Defaults to the active storey.
+   * @param scale - Initial uniform scale factor applied to the plane. Calibrate
+   *   precisely afterwards with {@link PluginCoreIoUnderlayApi.setScale}.
+   * @param opacity - Plane opacity, `0`..`1` (default ~`0.5`).
+   * @param label - A name for the created underlay.
+   * @returns the created {@linkcode UnderlayHandle}.
+   * @throws if writes are disabled, the source can't be loaded, the format is
+   *   unsupported, or the engine fails to place the plane.
+   *
+   * @examplePrompt Import this floor plan image onto the ground floor to trace over
+   * @examplePrompt Drop this survey PNG in as a reference underlay at 30% opacity
+   * @examplePrompt Add a site plan image on storey 2
+   * @examplePrompt Bring in a sketch to trace, faded to half opacity
+   *
+   * # Example
+   * ```ts
+   * // Place a floor plan on storey 1, then calibrate it to a real-world size.
+   * const plan = await snaptrude.core.io.import.image(
+   *   "https://example.com/floorplan.png",
+   *   1,           // storey
+   *   undefined,   // scale
+   *   0.4,         // opacity
+   *   "Ground floor plan",
+   * )
+   * // Make the plan's longest side exactly 40 project-units:
+   * await snaptrude.core.io.underlay.setScale(plan, { planSize: 40 })
+   * ```
+   */
+  public abstract image(
+    source: string,
+    storey?: number,
+    scale?: number,
+    opacity?: number,
+    label?: string,
+  ): PluginApiReturn<UnderlayHandle>
+
+  /**
+   * Import one page of a PDF as a scene **underlay** (a traceable reference plane).
+   *
+   * One PDF per storey, one page per call. To bring in several pages, call once
+   * per page onto different storeys.
+   *
+   * @param source - The PDF to import: an `https://` URL or a `data:` URL.
+   * @param storey - Target storey number. Defaults to the active storey.
+   * @param page - 1-based page number to import (multi-page PDFs). Default `1`.
+   * @param scale - A drawing-scale **label** that sizes the page in real-world
+   *   units, matching the project's unit mode: metric `"1:10"`..`"1:1000"` (e.g.
+   *   `"1:100"`) or imperial `` `1/8" = 1'` `` / `` `1" = 10'` ``. Must be a valid
+   *   label for the current unit mode (invalid → throws). Defaults to `"1:100"`
+   *   in metric projects and `` `1" = 1'` `` in imperial projects. Re-calibrate
+   *   afterwards with {@link PluginCoreIoUnderlayApi.setScale}.
+   * @param opacity - Plane opacity, `0`..`1` (default ~`0.5`).
+   * @returns the created {@linkcode UnderlayHandle}.
+   * @throws if writes are disabled, the source can't be loaded, the storey
+   *   already has a PDF, the page is out of range, the scale label is invalid for
+   *   the unit mode, or the engine fails.
+   *
+   * @examplePrompt Import page 1 of this PDF floor plan onto storey 1
+   * @examplePrompt Bring in the second page of this PDF as an underlay at 1:50
+   * @examplePrompt Add this PDF plan to the ground floor to trace over
+   * @examplePrompt Place page 3 of the drawing set on storey 3
+   *
+   * # Example
+   * ```ts
+   * const sheet = await snaptrude.core.io.import.pdf(
+   *   "https://example.com/plans.pdf",
+   *   1,        // storey
+   *   2,        // page
+   *   "1:100",  // drawing scale
+   * )
+   * ```
+   */
+  public abstract pdf(
+    source: string,
+    storey?: number,
+    page?: number,
+    scale?: string,
+    opacity?: number,
+  ): PluginApiReturn<UnderlayHandle>
+
+  /**
+   * Import a **DWG** CAD drawing as a scene underlay. `.dwg` only (no DXF).
+   *
+   * DWG conversion runs on a server and can take minutes, so this **starts a job
+   * and returns immediately** with an {@linkcode ImportJobHandle}. One CAD
+   * import runs at a time: starting a second while one is in flight throws —
+   * poll the first job to completion first. Poll it with
+   * {@link PluginCoreIoJobApi.isComplete} / {@link PluginCoreIoJobApi.getStatus}, then call
+   * {@link PluginCoreIoJobApi.getResult} to get the placed {@linkcode UnderlayHandle}.
+   * For CAD you already have parsed as JSON, use {@link PluginCoreIoImportApi.cadJson}
+   * (synchronous, no server round-trip).
+   *
+   * All CAD layers are imported (there is no layer filter).
+   *
+   * @param source - The `.dwg` file: an `https://` URL or a `data:` URL.
+   * @param storey - Target storey number. Defaults to the active storey.
+   * @returns an {@linkcode ImportJobHandle} to poll via `core.io.job.*`.
+   * @throws if writes are disabled or the upload cannot be started. (Conversion
+   *   failures surface later via {@link PluginCoreIoJobApi.getError}.)
+   *
+   * @examplePrompt Import this DWG floor plan onto storey 1
+   * @examplePrompt Bring in a CAD drawing as an underlay and tell me when it's ready
+   * @examplePrompt Start importing this CAD file onto the ground floor
+   *
+   * # Example
+   * ```ts
+   * const job = await snaptrude.core.io.import.dwg("https://example.com/plan.dwg", 1)
+   * // Poll until the server-side conversion finishes — always with a timeout
+   * // (a UI-cancelled import stays "processing" forever).
+   * const deadline = Date.now() + 5 * 60_000
+   * while (!(await snaptrude.core.io.job.isComplete(job))) {
+   *   if (Date.now() > deadline) throw new Error("DWG import timed out")
+   *   await new Promise((r) => setTimeout(r, 2000))
+   * }
+   * // The DWG lands as a CAD underlay. CAD scaling isn't supported; manage it
+   * // (list / fade / delete) via core.io.underlay.*.
+   * const cad = await snaptrude.core.io.job.getResult(job)
+   * if (cad) console.log("DWG imported as CAD underlay:", cad)
+   * ```
+   */
+  public abstract dwg(
+    source: string,
+    storey?: number,
+  ): PluginApiReturn<ImportJobHandle>
+
+  /**
+   * Sketch a CAD underlay from **already-parsed CAD JSON** — synchronous, with no
+   * server round-trip. Use this when you hold parsed CAD data (e.g. produced by
+   * your own converter); use {@link PluginCoreIoImportApi.dwg} for raw `.dwg`
+   * files.
+   *
+   * All layers in the JSON are sketched (there is no layer filter), at the
+   * drawing's own coordinates.
+   *
+   * @param cad - The parsed CAD data: `{ unit, geometry: [...] }` describing the
+   *   drawing's lines/arcs/layers.
+   * @param storey - Target storey number. Defaults to the active storey.
+   * @returns the created {@linkcode UnderlayHandle}.
+   * @throws if writes are disabled, the JSON yields no drawable geometry, or the
+   *   drawing is out of bounds.
+   *
+   * @examplePrompt Sketch this parsed CAD JSON onto the active storey
+   * @examplePrompt Draw these CAD curves as an underlay on storey 2
+   * @examplePrompt Create a CAD sketch from this geometry data
+   * @examplePrompt Import my converted CAD JSON onto the ground floor
+   *
+   * # Example
+   * ```ts
+   * const cad = await snaptrude.core.io.import.cadJson(
+   *   { unit: "mm", geometry: [{ type: "line", layer: "WALLS", ... }] },
+   *   1,
+   * )
+   * ```
+   */
+  public abstract cadJson(
+    cad: CadJsonInput,
+    storey?: number,
+  ): PluginApiReturn<UnderlayHandle>
+
+  /**
+   * Import a **3D model** file and place it in the scene as a component.
+   *
+   * Supported formats: SketchUp (`.skp`), FBX (`.fbx`), OBJ (`.obj`), 3DS
+   * (`.3ds`), and zipped bundles (`.zip`). The file is converted on the server,
+   * then placed. `.glb`/`.gltf`/`.ifc`/`.stl` and Rhino/Revit are not supported.
+   *
+   * The model is placed at its source dimensions (interpreted in the file's own
+   * units); there is no import-time scale override.
+   *
+   * Unlike `dwg`, this call **waits for the server conversion**: a large model
+   * may exceed the 60-second call cap and reject at the API boundary while the
+   * import still completes in the background (the model then appears without a
+   * handle being returned — re-query the scene to find it). Keep sources small.
+   *
+   * @param source - The model file: an `https://` URL or a `data:` URL.
+   * @param storey - Target storey number. Defaults to the active storey.
+   * @param format - The file's format. Inferred from `source` when omitted.
+   * @param position - Where to place the model. Defaults to the storey origin.
+   * @param label - A name for the placed component.
+   * @returns the placed {@linkcode ComponentHandle}.
+   * @throws if writes are disabled, the source can't be loaded, the format is
+   *   unsupported, conversion/placement fails, or the converted model cannot be
+   *   found in the library after upload; `PRECONDITION_FAILED`
+   *   (`details.engineCode: "TOOL_ACTIVE"`) while the interactive furniture tool is
+   *   active — finish or cancel it first.
+   *
+   * @examplePrompt Import this SketchUp model onto storey 1
+   * @examplePrompt Bring in this OBJ file and place it at the origin
+   * @examplePrompt Add this 3D model to the ground floor
+   *
+   * # Example
+   * ```ts
+   * const model = await snaptrude.core.io.import.model(
+   *   "https://example.com/tree.skp",
+   *   1,        // storey
+   *   "skp",
+   * )
+   * ```
+   */
+  public abstract model(
+    source: string,
+    storey?: number,
+    format?: ModelFormat,
+    position?: Vec3Handle,
+    label?: string,
+  ): PluginApiReturn<ComponentHandle>
+
+  /**
+   * Import **site terrain** for a location — Mapbox topography (elevation +
+   * satellite/streets imagery, optional neighborhood buildings and parcels).
+   *
+   * One terrain per project (a singleton). `width`/`length` describe the
+   * real-world extent of the area to load **in metres** (regardless of the
+   * project's unit mode); the host converts them to the right map zoom
+   * internally — you do not pass a zoom level.
+   *
+   * @param lat - Site latitude (degrees), `-90`..`90`.
+   * @param lng - Site longitude (degrees), `-180`..`180`.
+   * @param width - East–west extent of the area to load, in metres.
+   * @param length - North–south extent of the area to load, in metres.
+   * @param elevation - Include DEM elevation (a real terrain surface). Default `true`.
+   * @param satellite - Drape satellite imagery. Default `true`.
+   * @param neighborhood - Include surrounding context buildings. Default `false`.
+   * @param parcels - Include site parcel boundaries. Default `false`.
+   * @returns the created {@linkcode TerrainHandle}.
+   * @throws if writes are disabled, a terrain already exists, or the map/mesh
+   *   generation fails.
+   *
+   * @examplePrompt Import the site terrain for this location, about 500m across
+   * @examplePrompt Load the topography at 40.7128, -74.0060 for a 300 by 300 meter site
+   * @examplePrompt Bring in satellite terrain for the site with the surrounding buildings
+   * @examplePrompt Add site elevation for a 1km by 1km area at these coordinates
+   *
+   * # Example
+   * ```ts
+   * // 300m × 300m site with elevation + satellite imagery.
+   * const terrain = await snaptrude.core.io.import.terrain(
+   *   40.7128,  // lat
+   *   -74.006,  // lng
+   *   300,      // width  (metres)
+   *   300,      // length (metres)
+   *   true,     // elevation
+   *   true,     // satellite
+   * )
+   * ```
+   */
+  public abstract terrain(
+    lat: number,
+    lng: number,
+    width: number,
+    length: number,
+    elevation?: boolean,
+    satellite?: boolean,
+    neighborhood?: boolean,
+    parcels?: boolean,
+  ): PluginApiReturn<TerrainHandle>
+
+  /**
+   * Import an **EPW weather file** into the project's weather catalog.
+   *
+   * Uploads an EnergyPlus Weather (`.epw`) file and registers it as the
+   * project's site weather, returning its catalog `weatherFileId` — the same id
+   * {@link PluginAnalysisWeatherApi.getSeries}, `program.site.getWeather`, and a
+   * daylight run's provenance report. Uploading a user file makes the site's
+   * `selectionMethod` `"user-upload"`, overriding nearest-station resolution.
+   *
+   * **Mutating**: this writes project state and is subject to the plugin
+   * write-gate — it throws when plugin writes are disabled. Unlike the file
+   * underlay/model importers it returns no scene handle (a weather file is not
+   * a scene object), only the catalog `{ weatherFileId, label }`.
+   *
+   * @param source - The `.epw` file to import: an `https://` URL or a `data:` URL.
+   * @returns A {@linkcode PluginImportEpwResult} — the catalog `weatherFileId`
+   *   and a human-readable `label` (the station/file name).
+   * @throws if writes are disabled, the source can't be loaded, or the file is
+   *   not a valid EPW.
+   *
+   * @examplePrompt Import this EPW weather file for the site
+   * @examplePrompt Upload a custom weather file for the daylight analysis
+   * @examplePrompt Use this .epw as the project's weather source
+   *
+   * # Example
+   * ```ts
+   * const { weatherFileId, label } = await snaptrude.core.io.import.epw(
+   *   "https://example.com/Chicago-OHare.epw",
+   * )
+   * console.log(`Weather set to ${label} (${weatherFileId})`)
+   * ```
+   */
+  public abstract epw(source: string): PluginApiReturn<PluginImportEpwResult>
+}
+
+/**
+ * Supported 3D model import formats. `.glb`/`.gltf`/`.ifc`/`.stl` and Rhino/Revit
+ * are intentionally excluded (no in-app import path).
+ */
+export const ModelFormat = z.enum(["skp", "fbx", "obj", "3ds", "zip"])
+export type ModelFormat = z.infer<typeof ModelFormat>
+
+/**
+ * Parsed CAD JSON accepted by {@link PluginCoreIoImportApi.cadJson}. `unit` sets
+ * the drawing's length unit; `geometry` is the array of CAD entities (lines,
+ * polylines, arcs, circles), each tagged with its CAD `layer`. Additional fields
+ * are passed through untouched.
+ */
+export const CadJsonInput = z
+  .object({
+    unit: z.string().optional(),
+    geometry: z.array(z.record(z.string(), z.unknown())).optional(),
+  })
+  .passthrough()
+export type CadJsonInput = z.infer<typeof CadJsonInput>
+
+/**
+ * Arguments for {@link PluginCoreIoImportApi.image}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `source` | `string` | Image `https://` URL or `data:` URL (png/jpg/jpeg/bmp) |
+ * | `storey` | `number`? | Target storey (default: active) |
+ * | `scale` | `number`? | Initial uniform scale |
+ * | `opacity` | `number`? | `0`..`1` (default ~`0.5`) |
+ * | `label` | `string`? | Name for the underlay |
+ */
+export const PluginImportImageArgs = z.object({
+  source: ImportSource,
+  storey: z.number().int().optional(),
+  scale: z.number().positive().optional(),
+  opacity: z.number().min(0).max(1).optional(),
+  label: z.string().optional(),
+})
+export type PluginImportImageArgs = z.infer<typeof PluginImportImageArgs>
+
+/**
+ * Arguments for {@link PluginCoreIoImportApi.pdf}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `source` | `string` | PDF `https://` URL or `data:` URL |
+ * | `storey` | `number`? | Target storey (default: active) |
+ * | `page` | `number`? | 1-based page (default `1`) |
+ * | `scale` | `string`? | Drawing-scale label, e.g. `"1:100"` |
+ * | `opacity` | `number`? | `0`..`1` (default ~`0.5`) |
+ */
+export const PluginImportPdfArgs = z.object({
+  source: ImportSource,
+  storey: z.number().int().optional(),
+  page: z.number().int().positive().optional(),
+  scale: z.string().optional(),
+  opacity: z.number().min(0).max(1).optional(),
+})
+export type PluginImportPdfArgs = z.infer<typeof PluginImportPdfArgs>
+
+/** Arguments for {@link PluginCoreIoImportApi.dwg}. */
+export const PluginImportDwgArgs = z.object({
+  source: ImportSource,
+  storey: z.number().int().optional(),
+})
+export type PluginImportDwgArgs = z.infer<typeof PluginImportDwgArgs>
+
+/** Arguments for {@link PluginCoreIoImportApi.cadJson}. */
+export const PluginImportCadJsonArgs = z.object({
+  cad: CadJsonInput,
+  storey: z.number().int().optional(),
+})
+export type PluginImportCadJsonArgs = z.infer<typeof PluginImportCadJsonArgs>
+
+/**
+ * Arguments for {@link PluginCoreIoImportApi.model}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `source` | `string` | Model `https://` URL or `data:` URL |
+ * | `storey` | `number`? | Target storey (default: active) |
+ * | `format` | {@link ModelFormat}? | File format (inferred when omitted) |
+ * | `position` | {@link Vec3Handle}? | Placement (default: storey origin) |
+ * | `label` | `string`? | Name for the component |
+ */
+export const PluginImportModelArgs = z.object({
+  source: ImportSource,
+  storey: z.number().int().optional(),
+  format: ModelFormat.optional(),
+  position: Vec3Handle.optional(),
+  label: z.string().optional(),
+})
+export type PluginImportModelArgs = z.infer<typeof PluginImportModelArgs>
+
+/**
+ * Arguments for {@link PluginCoreIoImportApi.terrain}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `lat` | `number` | Latitude (degrees), `-90`..`90` |
+ * | `lng` | `number` | Longitude (degrees), `-180`..`180` |
+ * | `width` | `number` | East–west extent, metres |
+ * | `length` | `number` | North–south extent, metres |
+ * | `elevation` | `boolean`? | Include DEM elevation (default `true`) |
+ * | `satellite` | `boolean`? | Drape satellite imagery (default `true`) |
+ * | `neighborhood` | `boolean`? | Include context buildings (default `false`) |
+ * | `parcels` | `boolean`? | Include parcel boundaries (default `false`) |
+ */
+export const PluginImportTerrainArgs = z.object({
+  lat: z.number().min(-90).max(90),
+  lng: z.number().min(-180).max(180),
+  width: z.number().positive().finite(),
+  length: z.number().positive().finite(),
+  elevation: z.boolean().optional(),
+  satellite: z.boolean().optional(),
+  neighborhood: z.boolean().optional(),
+  parcels: z.boolean().optional(),
+})
+export type PluginImportTerrainArgs = z.infer<typeof PluginImportTerrainArgs>
+
+/**
+ * Arguments for {@link PluginCoreIoImportApi.epw}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `source` | `string` | EPW `https://` URL or `data:` URL |
+ */
+export const PluginImportEpwArgs = z.object({
+  source: ImportSource,
+})
+export type PluginImportEpwArgs = z.infer<typeof PluginImportEpwArgs>
+
+/**
+ * Result of {@link PluginCoreIoImportApi.epw} — the imported weather file's
+ * catalog entry.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `weatherFileId` | `string` | Catalog id (same key as `analysis.weather`'s `weatherFileId`) |
+ * | `label` | `string` | Human-readable name (station / file name) |
+ */
+export const PluginImportEpwResult = z.object({
+  weatherFileId: z.string(),
+  label: z.string(),
+})
+export type PluginImportEpwResult = z.infer<typeof PluginImportEpwResult>