@snaptrude/plugin-core 0.5.0 → 0.6.0

package/dist/api/core/io/import/index.d.ts

@@ -0,0 +1,392 @@
+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 declare const ImportSource: z.ZodString;
+/**
+ * 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 declare 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.
+     *
+     * 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 })
+     * ```
+     */
+    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
+     * )
+     * ```
+     */
+    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)
+     * ```
+     */
+    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,
+     * )
+     * ```
+     */
+    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.
+     *
+     * @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",
+     * )
+     * ```
+     */
+    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
+     * )
+     * ```
+     */
+    abstract terrain(lat: number, lng: number, width: number, length: number, elevation?: boolean, satellite?: boolean, neighborhood?: boolean, parcels?: boolean): PluginApiReturn<TerrainHandle>;
+}
+/**
+ * Supported 3D model import formats. `.glb`/`.gltf`/`.ifc`/`.stl` and Rhino/Revit
+ * are intentionally excluded (no in-app import path).
+ */
+export declare const ModelFormat: z.ZodEnum<{
+    skp: "skp";
+    fbx: "fbx";
+    obj: "obj";
+    "3ds": "3ds";
+    zip: "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 declare const CadJsonInput: z.ZodObject<{
+    unit: z.ZodOptional<z.ZodString>;
+    geometry: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+}, z.core.$loose>;
+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 declare const PluginImportImageArgs: z.ZodObject<{
+    source: z.ZodString;
+    storey: z.ZodOptional<z.ZodNumber>;
+    scale: z.ZodOptional<z.ZodNumber>;
+    opacity: z.ZodOptional<z.ZodNumber>;
+    label: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+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 declare const PluginImportPdfArgs: z.ZodObject<{
+    source: z.ZodString;
+    storey: z.ZodOptional<z.ZodNumber>;
+    page: z.ZodOptional<z.ZodNumber>;
+    scale: z.ZodOptional<z.ZodString>;
+    opacity: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type PluginImportPdfArgs = z.infer<typeof PluginImportPdfArgs>;
+/** Arguments for {@link PluginCoreIoImportApi.dwg}. */
+export declare const PluginImportDwgArgs: z.ZodObject<{
+    source: z.ZodString;
+    storey: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type PluginImportDwgArgs = z.infer<typeof PluginImportDwgArgs>;
+/** Arguments for {@link PluginCoreIoImportApi.cadJson}. */
+export declare const PluginImportCadJsonArgs: z.ZodObject<{
+    cad: z.ZodObject<{
+        unit: z.ZodOptional<z.ZodString>;
+        geometry: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    }, z.core.$loose>;
+    storey: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+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 declare const PluginImportModelArgs: z.ZodObject<{
+    source: z.ZodString;
+    storey: z.ZodOptional<z.ZodNumber>;
+    format: z.ZodOptional<z.ZodEnum<{
+        skp: "skp";
+        fbx: "fbx";
+        obj: "obj";
+        "3ds": "3ds";
+        zip: "zip";
+    }>>;
+    position: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<import("../../../..").Handle<"vec3">, string>>>;
+    label: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+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 declare const PluginImportTerrainArgs: z.ZodObject<{
+    lat: z.ZodNumber;
+    lng: z.ZodNumber;
+    width: z.ZodNumber;
+    length: z.ZodNumber;
+    elevation: z.ZodOptional<z.ZodBoolean>;
+    satellite: z.ZodOptional<z.ZodBoolean>;
+    neighborhood: z.ZodOptional<z.ZodBoolean>;
+    parcels: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type PluginImportTerrainArgs = z.infer<typeof PluginImportTerrainArgs>;
+//# sourceMappingURL=index.d.ts.map

package/dist/api/core/io/import/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/api/core/io/import/index.ts"],"names":[],"mappings":"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"}

package/dist/api/core/io/index.d.ts

@@ -0,0 +1,35 @@
+import { PluginCoreIoImportApi } from "./import";
+import { PluginCoreIoJobApi } from "./job";
+import { PluginCoreIoUnderlayApi } from "./underlay";
+import { PluginCoreIoTerrainApi } from "./terrain";
+import { PluginCoreIoQueryApi } from "./query";
+/**
+ * I/O — bring external files into the project and manage what was imported.
+ *
+ * - {@linkcode PluginCoreIoApi.import} — import images, PDFs, CAD, 3D models, terrain
+ * - {@linkcode PluginCoreIoApi.query} — read source metadata before importing (pdf pages, cad layers)
+ * - {@linkcode PluginCoreIoApi.job} — poll long-running async imports (e.g. DWG)
+ * - {@linkcode PluginCoreIoApi.underlay} — inspect/scale/opacity/delete placed underlays
+ * - {@linkcode PluginCoreIoApi.terrain} — inspect/edit the site terrain (datum, layers, delete)
+ *
+ * Accessed via `snaptrude.core.io`.
+ */
+export declare abstract class PluginCoreIoApi {
+    /** Import external files into the scene. See {@linkcode PluginCoreIoImportApi}. */
+    abstract import: PluginCoreIoImportApi;
+    /** Read source metadata before import. See {@linkcode PluginCoreIoQueryApi}. */
+    abstract query: PluginCoreIoQueryApi;
+    /** Poll long-running import jobs. See {@linkcode PluginCoreIoJobApi}. */
+    abstract job: PluginCoreIoJobApi;
+    /** Inspect and edit placed underlays. See {@linkcode PluginCoreIoUnderlayApi}. */
+    abstract underlay: PluginCoreIoUnderlayApi;
+    /** Inspect and manage the site terrain. See {@linkcode PluginCoreIoTerrainApi}. */
+    abstract terrain: PluginCoreIoTerrainApi;
+    constructor();
+}
+export * from "./import";
+export * from "./job";
+export * from "./underlay";
+export * from "./terrain";
+export * from "./query";
+//# sourceMappingURL=index.d.ts.map

package/dist/api/core/io/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/api/core/io/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAA;AAChD,OAAO,EAAE,kBAAkB,EAAE,MAAM,OAAO,CAAA;AAC1C,OAAO,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAA;AACpD,OAAO,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAA;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAA;AAE9C;;;;;;;;;;GAUG;AACH,8BAAsB,eAAe;IACnC,mFAAmF;IACnF,SAAgB,MAAM,EAAE,qBAAqB,CAAA;IAC7C,gFAAgF;IAChF,SAAgB,KAAK,EAAE,oBAAoB,CAAA;IAC3C,yEAAyE;IACzE,SAAgB,GAAG,EAAE,kBAAkB,CAAA;IACvC,kFAAkF;IAClF,SAAgB,QAAQ,EAAE,uBAAuB,CAAA;IACjD,mFAAmF;IACnF,SAAgB,OAAO,EAAE,sBAAsB,CAAA;;CAGhD;AAED,cAAc,UAAU,CAAA;AACxB,cAAc,OAAO,CAAA;AACrB,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,SAAS,CAAA"}

package/dist/api/core/io/job/index.d.ts

@@ -0,0 +1,139 @@
+import * as z from "zod";
+import { PluginApiReturn } from "../../../../types";
+import { ImportJobHandle, UnderlayHandle } from "../../../../handles";
+/**
+ * Import jobs — poll a long-running asynchronous import.
+ *
+ * Some imports run on a server and take a while (today: `core.io.import.dwg`,
+ * whose DWG → Snaptrude conversion can take minutes). Those importers return an
+ * {@linkcode ImportJobHandle} immediately instead of blocking; you drive the job
+ * to completion here:
+ *
+ * 1. poll {@link PluginCoreIoJobApi.isComplete} (or read {@link PluginCoreIoJobApi.getStatus}),
+ * 2. once complete, call {@link PluginCoreIoJobApi.getResult} for the placed handle,
+ * 3. or read {@link PluginCoreIoJobApi.getError} if it failed.
+ *
+ * **Always poll with a timeout.** If the import is cancelled from the app UI
+ * (or the tab reloads mid-conversion), the job never reaches a terminal state
+ * and `getStatus` keeps returning `"processing"` — an unbounded poll loop would
+ * spin forever. Give up after a few minutes and surface that to the user.
+ *
+ * Accessed via `snaptrude.core.io.job`.
+ */
+export declare abstract class PluginCoreIoJobApi {
+    constructor();
+    /**
+     * Read a job's current status: `"pending"` (queued), `"processing"` (running),
+     * `"complete"` (result ready), or `"failed"`.
+     *
+     * Limitation: a job cancelled from the app UI never turns `"failed"` — it
+     * stays `"processing"` indefinitely. Bound your poll loop with a timeout.
+     *
+     * @param job - The import job to inspect.
+     * @returns the {@linkcode ImportJobStatus}.
+     * @throws {@link HandleInvalidError} if the job handle is unknown.
+     *
+     * @examplePrompt What's the status of my DWG import?
+     * @examplePrompt Is the CAD import still processing?
+     * @examplePrompt Check where the import job is up to
+     * @examplePrompt Did the import job fail?
+     *
+     * # Example
+     * ```ts
+     * const job = await snaptrude.core.io.import.dwg(url, 1)
+     * console.log(await snaptrude.core.io.job.getStatus(job)) // "processing"
+     * ```
+     */
+    abstract getStatus(job: ImportJobHandle): PluginApiReturn<ImportJobStatus>;
+    /**
+     * Whether the job has finished successfully (status is `"complete"` and a
+     * result is ready). Returns `false` while pending/processing and on failure.
+     *
+     * @param job - The import job to inspect.
+     * @throws {@link HandleInvalidError} if the job handle is unknown.
+     *
+     * @examplePrompt Is the DWG import done yet?
+     * @examplePrompt Has the CAD import finished?
+     * @examplePrompt Tell me when the import job completes
+     * @examplePrompt Is my import ready?
+     *
+     * # Example
+     * ```ts
+     * const job = await snaptrude.core.io.import.dwg(url, 1)
+     * const deadline = Date.now() + 5 * 60_000 // cap the poll — see getStatus limitation
+     * 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))
+     * }
+     * ```
+     */
+    abstract isComplete(job: ImportJobHandle): PluginApiReturn<boolean>;
+    /**
+     * The imported result once the job is complete — the placed
+     * {@linkcode UnderlayHandle}. Returns `null` while the job is still
+     * pending/processing or if it failed (check {@link PluginCoreIoJobApi.getError}).
+     *
+     * @param job - The completed import job.
+     * @throws {@link HandleInvalidError} if the job handle is unknown.
+     *
+     * @examplePrompt Get the underlay from my finished DWG import
+     * @examplePrompt Give me the result of the CAD import job
+     * @examplePrompt Fetch the imported CAD sketch once it's ready
+     * @examplePrompt Return the handle for the completed import
+     *
+     * # Example
+     * ```ts
+     * const job = await snaptrude.core.io.import.dwg(url, 1)
+     * 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))
+     * }
+     * // DWG results are CAD underlays (CAD scaling isn't supported); manage them
+     * // via core.io.underlay.* (list / setOpacity / delete).
+     * const cad = await snaptrude.core.io.job.getResult(job)
+     * if (cad) console.log("import complete:", cad)
+     * ```
+     */
+    abstract getResult(job: ImportJobHandle): PluginApiReturn<UnderlayHandle | null>;
+    /**
+     * The failure message if the job's status is `"failed"`; otherwise `null`.
+     *
+     * @param job - The import job to inspect.
+     * @throws {@link HandleInvalidError} if the job handle is unknown.
+     *
+     * @examplePrompt Why did my DWG import fail?
+     * @examplePrompt What went wrong with the CAD import?
+     * @examplePrompt Show the error from the failed import job
+     * @examplePrompt Did the import error out, and why?
+     *
+     * # Example
+     * ```ts
+     * const job = await snaptrude.core.io.import.dwg(url, 1)
+     * if ((await snaptrude.core.io.job.getStatus(job)) === "failed") {
+     *   console.error(await snaptrude.core.io.job.getError(job))
+     * }
+     * ```
+     */
+    abstract getError(job: ImportJobHandle): PluginApiReturn<string | null>;
+}
+/** Lifecycle status of an asynchronous import job. */
+export declare const ImportJobStatus: z.ZodEnum<{
+    pending: "pending";
+    processing: "processing";
+    complete: "complete";
+    failed: "failed";
+}>;
+export type ImportJobStatus = z.infer<typeof ImportJobStatus>;
+/**
+ * Arguments for the `core.io.job.*` readers.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `job` | {@link ImportJobHandle} | The import job to inspect |
+ */
+export declare const PluginImportJobArgs: z.ZodObject<{
+    job: z.ZodPipe<z.ZodString, z.ZodTransform<ImportJobHandle, string>>;
+}, z.core.$strip>;
+export type PluginImportJobArgs = z.infer<typeof PluginImportJobArgs>;
+//# sourceMappingURL=index.d.ts.map

package/dist/api/core/io/job/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/api/core/io/job/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AACnD,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAErE;;;;;;;;;;;;;;;;;;GAkBG;AACH,8BAAsB,kBAAkB;;IAGtC;;;;;;;;;;;;;;;;;;;;;OAqBG;aACa,SAAS,CAAC,GAAG,EAAE,eAAe,GAAG,eAAe,CAAC,eAAe,CAAC;IAEjF;;;;;;;;;;;;;;;;;;;;;OAqBG;aACa,UAAU,CAAC,GAAG,EAAE,eAAe,GAAG,eAAe,CAAC,OAAO,CAAC;IAE1E;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;aACa,SAAS,CAAC,GAAG,EAAE,eAAe,GAAG,eAAe,CAAC,cAAc,GAAG,IAAI,CAAC;IAEvF;;;;;;;;;;;;;;;;;;OAkBG;aACa,QAAQ,CAAC,GAAG,EAAE,eAAe,GAAG,eAAe,CAAC,MAAM,GAAG,IAAI,CAAC;CAC/E;AAED,sDAAsD;AACtD,eAAO,MAAM,eAAe;;;;;EAA0D,CAAA;AACtF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAA;AAE7D;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB;;iBAE9B,CAAA;AACF,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAA"}

package/dist/api/core/io/query/index.d.ts

@@ -0,0 +1,74 @@
+import * as z from "zod";
+import { PluginApiReturn } from "../../../../types";
+import { CadJsonInput } from "../import";
+/**
+ * Import queries — read metadata about a source **before** importing it.
+ *
+ * These reads let a plugin discover a source's shape before importing it:
+ * how many pages a PDF has (for `import.pdf`'s `page`), and which CAD layers a
+ * drawing defines (imports always bring in every layer — there is no filter —
+ * but the names tell you what the drawing contains).
+ *
+ * Accessed via `snaptrude.core.io.query`.
+ */
+export declare abstract class PluginCoreIoQueryApi {
+    constructor();
+    /**
+     * Count the pages of a PDF without importing it. `null` if the source can't be
+     * read as a PDF.
+     *
+     * @param source - The PDF: an `https://` URL or a `data:` URL.
+     * @returns the page count, or `null`.
+     *
+     * @examplePrompt How many pages does this PDF have?
+     * @examplePrompt Count the pages in the drawing set before importing
+     * @examplePrompt Get the PDF page count
+     * @examplePrompt Is this a multi-page PDF, and how many?
+     *
+     * # Example
+     * ```ts
+     * const pages = await snaptrude.core.io.query.getPdfPageCount(url)
+     * for (let p = 1; p <= (pages ?? 0); p++) {
+     *   await snaptrude.core.io.import.pdf(url, p, p) // one page per storey
+     * }
+     * ```
+     */
+    abstract getPdfPageCount(source: string): PluginApiReturn<number | null>;
+    /**
+     * List the distinct CAD layer names tagged on a parsed CAD JSON's entities.
+     * Read-only inspection: imports always bring in **every** layer (there is no
+     * layer filter on {@link core.io.import.dwg} / {@link core.io.import.cadJson}) —
+     * use the names to decide whether to import at all, or what to tell the user.
+     *
+     * @param cad - Parsed CAD JSON (same shape `import.cadJson` accepts).
+     * @returns the layer names (empty array if none).
+     *
+     * @examplePrompt What CAD layers are in this drawing?
+     * @examplePrompt List the layers before importing the CAD
+     * @examplePrompt Show the DWG layer names so I can pick which to import
+     * @examplePrompt Enumerate the CAD JSON layers
+     *
+     * # Example
+     * ```ts
+     * const layers = await snaptrude.core.io.query.listCadLayers(cad)
+     * if (layers.some((l) => l.toUpperCase().includes("WALL"))) {
+     *   await snaptrude.core.io.import.cadJson(cad, 1) // all layers import together
+     * }
+     * ```
+     */
+    abstract listCadLayers(cad: CadJsonInput): PluginApiReturn<string[]>;
+}
+/** Arguments for {@link PluginCoreIoQueryApi.getPdfPageCount}. */
+export declare const PluginQueryPdfPageCountArgs: z.ZodObject<{
+    source: z.ZodString;
+}, z.core.$strip>;
+export type PluginQueryPdfPageCountArgs = z.infer<typeof PluginQueryPdfPageCountArgs>;
+/** Arguments for {@link PluginCoreIoQueryApi.listCadLayers}. */
+export declare const PluginQueryCadLayersArgs: z.ZodObject<{
+    cad: z.ZodObject<{
+        unit: z.ZodOptional<z.ZodString>;
+        geometry: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    }, z.core.$loose>;
+}, z.core.$strip>;
+export type PluginQueryCadLayersArgs = z.infer<typeof PluginQueryCadLayersArgs>;
+//# sourceMappingURL=index.d.ts.map

package/dist/api/core/io/query/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/api/core/io/query/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAExC;;;;;;;;;GASG;AACH,8BAAsB,oBAAoB;;IAGxC;;;;;;;;;;;;;;;;;;;OAmBG;aACa,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,CAAC,MAAM,GAAG,IAAI,CAAC;IAE/E;;;;;;;;;;;;;;;;;;;;;OAqBG;aACa,aAAa,CAAC,GAAG,EAAE,YAAY,GAAG,eAAe,CAAC,MAAM,EAAE,CAAC;CAC5E;AAED,kEAAkE;AAClE,eAAO,MAAM,2BAA2B;;iBAA0C,CAAA;AAClF,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAA;AAErF,gEAAgE;AAChE,eAAO,MAAM,wBAAwB;;;;;iBAAkC,CAAA;AACvE,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAA"}