@kerros/viewer 0.0.0-stage → 0.1.0-rc.2

package/dist/types/map/walkSurfaces.d.ts

@@ -0,0 +1,27 @@
+import type { Point, ProjectDocument, Ring, SiteObject } from '../model/types';
+/** Evaluate wall solids in absolute building heights. A host wall may continue through a
+ * mezzanine, while a low partition below it and a lintel overhead do not obstruct the walker. */
+export declare function walkingWallRings(project: ProjectDocument, floorId: string | null): Ring[];
+/** Build the support lookup when geometry changes, not for every walking frame. Open-air grade
+ * and floors without authored plates stay traversable. Higher and buried plates have real edges. */
+export declare function floorSupport(project: ProjectDocument): {
+    supports: (at: Point, id: string | null) => boolean;
+    dropAt: (at: Point, id: string | null) => {
+        floorId: string;
+        distance: number;
+    } | undefined;
+};
+/** Clip a small walking step at the last supported point; never snap it onto another island. */
+export declare function supportedStep(from: Point, to: Point, supports: (at: Point) => boolean): Point;
+/** Keep a valid position across storeys, including a fall's landing. A floor picker can instead
+ * select a smaller footprint: enter it at a dry navigation point, not in the void outside it. */
+export declare function floorArrival(project: ProjectDocument, floorId: string | null, at: Point): Point;
+/** Only authored openings trigger a drop. Gaps outside the building, an undrawn floor, and
+ * overlapping areas that still provide a slab are not floor holes. */
+export declare function floorDropAt(project: ProjectDocument, floorId: string | null, at: Point): {
+    floorId: string;
+    distance: number;
+} | undefined;
+/** Rooms which span the active storey bring the geometry inside their footprint along with them.
+ * The same context supplies the lower plate seen through an opening and the gallery seen from below. */
+export declare function tallSpaceContext(project: ProjectDocument, floorId: string | null): SiteObject[];

package/dist/types/map/wallJoins.d.ts

@@ -0,0 +1,6 @@
+import type { Point, ProjectDocument, Ring } from '../model/types';
+/** Adjacent wall faces intersect once at each junction. Both walls use that same corner, so
+ * oblique L, T and four-way joins close without rectangular end caps protruding through them. */
+export declare function wallFootprints(project: ProjectDocument): Map<string, Ring>;
+/** Cut an opening across the joined footprint, retaining the mitres on the wall's outside ends. */
+export declare function wallSpan(ring: Ring, origin: Point, direction: Point, start: number | null, end: number | null): Ring;

package/dist/types/map/water.d.ts

@@ -0,0 +1,12 @@
+import * as THREE from 'three';
+import type { Point, SiteObject } from '../model/types';
+import type { MaterialLibrary } from './materials';
+export declare function makePool(o: SiteObject, xy: (p: Point) => Point, base: number, materials: MaterialLibrary, time: {
+    value: number;
+}, detailed?: boolean): THREE.Group;
+export declare function makeWaterSlide(o: SiteObject, xy: (p: Point) => Point, base: number, materials: MaterialLibrary): THREE.Group<THREE.Object3DEventMap>;
+/** Moving blue caustics from lit pools, restricted to their containing tiled chambers. This
+ * inexpensive projection approximates the focused light from small ripples; it is not ray tracing. */
+export declare function applyPoolCaustics(scene: THREE.Scene, project: import('../model/types').ProjectDocument, floorId: string, xy: (point: Point) => Point, base: number, time: {
+    value: number;
+}): void;

package/dist/types/model/authoring.d.ts

@@ -0,0 +1,38 @@
+import type { Point, ProjectDocument, Ring } from './types';
+/** Ignore double-click duplicates; reject a crossing while the last good draft is still editable. */
+export declare function appendAreaPoint(draft: Ring, point: Point): {
+    points: Ring;
+    error?: string;
+};
+/** The wall/partition tool: divide along the endpoints actually used after welding. */
+export declare function drawBarrier(project: ProjectDocument, floorId: string | null, a: Point, b: Point, kind?: 'wall' | 'fence'): import("./types").Barrier | undefined;
+/** A completed stroke stops chaining when its tip meets an existing boundary, including an
+ * earlier segment of the same outline. Test before adding the segment: afterwards every tip
+ * belongs to a boundary. Use the model's joining tolerance, not the pointer's snap reach. */
+export declare function endsBoundaryStroke(project: ProjectDocument, floorId: string | null, a: Point, b: Point, kind?: 'wall' | 'fence' | 'boundary'): boolean;
+/** The enclose tool: creating and re-fitting use exactly the same generated outline. */
+export declare function encloseRoom(project: ProjectDocument, floorId: string | null, point: Point): {
+    room: import("./types").SiteObject;
+    existing: boolean;
+} | null;
+export type GeometryDrag = {
+    kind: 'junction';
+    id: string;
+    point: Point;
+} | {
+    kind: 'barrier';
+    id: string;
+    point: Point;
+} | {
+    kind: 'ring';
+    id: string;
+    point: Point;
+    ringIndex: number;
+    index: number;
+};
+/** Apply one requested drop to a transaction draft. The editor previews snapping alone and calls
+ * this once on release; transact either accepts the entire move or leaves the original intact. */
+export declare function applyGeometryDrag(project: ProjectDocument, move: GeometryDrag): void;
+/** Optional constrained authoring operation for hosts and scripted drawing: find a valid position
+ * along a requested movement. Interactive editor drags use applyGeometryDrag on release instead. */
+export declare function dragGeometry(project: ProjectDocument, _floorId: string | null, move: GeometryDrag): ProjectDocument;

package/dist/types/model/boundaries.d.ts

@@ -0,0 +1,41 @@
+import type { Barrier, BoundaryUse, Point, ProjectDocument, Ring, SiteObject, VirtualBoundary } from './types';
+export type BoundaryEdge = Barrier | VirtualBoundary;
+export interface BoundaryRegion {
+    loops: BoundaryUse[][];
+    /** Centreline polygon, including holes. Net footprints also subtract the physical wall bodies. */
+    rings: Ring[];
+}
+export declare const boundaryEdges: (p: ProjectDocument) => BoundaryEdge[];
+export declare const followsBoundaries: (o: SiteObject) => boolean;
+/** Keep every reference correct when a physical/virtual edge is split or replaced. */
+export declare function replaceBoundaryUses(p: ProjectDocument, edgeId: string, replacement: BoundaryUse[]): void;
+export declare function boundaryRings(p: ProjectDocument, loops: BoundaryUse[][], floorId: string | null): Ring[];
+/** Planarize a floor: one junction at each intersection, with overlaps represented once.
+ * Exact calculated intersections are shared; the input grid is not applied again here. */
+export declare function normalizeBoundaries(p: ProjectDocument, floorId: string | null): void;
+/** Bounded faces of the shared graph. Bridges do not divide a face; nested components form holes. */
+export declare function boundaryRegions(p: ProjectDocument, floorId: string | null): BoundaryRegion[];
+export declare function derivedSpaceRings(p: ProjectDocument, o: SiteObject): Ring[];
+export declare function bindSpaceToRegion(p: ProjectDocument, o: SiteObject, region: BoundaryRegion): void;
+export declare function boundaryRegionAt(p: ProjectDocument, floorId: string | null, point: Point): BoundaryRegion | null;
+export declare function addVirtualBoundary(p: ProjectDocument, floorId: string | null, a: Point, b: Point): string;
+/** The drawing tool intentionally opens any collinear wall span. Ordinary addVirtualBoundary
+ * remains non-destructive for generated space outlines and model normalization. */
+export declare function drawVirtualBoundary(p: ProjectDocument, floorId: string | null, a: Point, b: Point): string;
+/** Explicit conversion: retain the drawn shape with shared virtual edges, or adopt its enclosing
+ * walls on request. Legacy documents remain independent until this operation is chosen. */
+export declare function connectSpace(p: ProjectDocument, objectId: string, source?: 'outline' | 'walls'): void;
+export declare function disconnectSpace(p: ProjectDocument, objectId: string): void;
+export declare function addBoundaryHole(p: ProjectDocument, o: SiteObject, ring: Ring): void;
+export declare function splitBoundarySpace(p: ProjectDocument, o: SiteObject, a: Point, b: Point, wall?: boolean): string;
+/** Join centreline loops before deriving the net footprint, including the former wall's floor area. */
+export declare function mergeBoundaryGeometry(p: ProjectDocument, keep: SiteObject, absorbed: SiteObject): boolean;
+/** A removed wall leaves the semantic division as a virtual boundary. */
+export declare function preserveBoundary(p: ProjectDocument, edge: BoundaryEdge): void;
+/** Regenerate by explicit loops, subdividing identities only when a new boundary divides a space.
+ * No old/new footprint-overlap matching is involved in ordinary wall movements. */
+export declare function refreshBoundarySpaces(p: ProjectDocument, topologyChanged?: Set<string | null>): string[];
+/** One synchronization gate for UI gestures, host mutations, history and persistence. */
+export declare function synchronizeGeometry(before: ProjectDocument, p: ProjectDocument): void;
+/** Validate the explicit topology and its cache. Independent polygons retain their existing rules. */
+export declare function validateSpaceBoundaries(p: ProjectDocument): void;

package/dist/types/model/coverage.d.ts

@@ -0,0 +1,8 @@
+import { type ProjectDocument, type SiteObject } from './types';
+export declare const DEFAULT_RANGE = 12;
+export declare const DEFAULT_FOV = 70;
+/** Ids of the spaces and openings inside `camera`'s cone with an unobstructed line to it.
+ *
+ *  Sightlines stop at walls, with one exception: the opening being tested is itself a hole in the
+ *  wall it sits on, so that wall cannot be what hides it. */
+export declare function coverageOf(project: ProjectDocument, camera: SiteObject): string[];

package/dist/types/model/document.d.ts

@@ -0,0 +1,9 @@
+import type { AssetRepository, ProjectDocument } from './types';
+export declare function blobDataUrl(blob: Blob): Promise<string>;
+export declare function exportProject(project: ProjectDocument, assets: AssetRepository): Promise<string>;
+export declare function importProject(json: string, assets: AssetRepository): Promise<ProjectDocument>;
+/** Display semantics: ids and updatedAt untouched, nothing written anywhere — unlike importProject, which rewrites both for import-for-editing. Unsupported embedded entries resolve to undefined at get time rather than throwing. */
+export declare function parseExport(json: string): {
+    project: ProjectDocument;
+    assets: AssetRepository;
+};

package/dist/types/model/doors.d.ts

@@ -0,0 +1,19 @@
+import type { Point, ProjectDocument, SiteObject } from './types';
+/** One hinge and signed rotation for plan symbols, drag previews and the animated 3D leaf. */
+export declare function doorGeometry(project: ProjectDocument, door: SiteObject): {
+    hinge: Point;
+    swing: number;
+    tip: (degrees: number) => Point;
+    arc: Point[];
+};
+/** A small dead zone retains the original side during an ordinary along-wall drag. */
+export declare function draggedDoorSwing(project: ProjectDocument, door: SiteObject, pointer: Point): 1 | -1;
+/** All moving leaves, shared by the plan and 3D renderer. Double doors meet in the centre. */
+export declare function doorLeaves(project: ProjectDocument, door: SiteObject): {
+    hinge: Point;
+    swing: number;
+    tip: (degrees: number) => Point;
+    arc: Point[];
+}[];
+/** Architectural symbol (or a feed's current state), including a rail and travel arrow for sliders. */
+export declare function doorSymbol(project: ProjectDocument, door: SiteObject, open?: boolean): Point[][];

package/dist/types/model/factory.d.ts

@@ -0,0 +1,5 @@
+import type { ObjectKind, Origin, Point, ProjectDocument, SiteObject } from './types';
+/** An empty, valid single-floor project anchored at an explicit EPSG:3067 origin (with optional site bearing). */
+export declare function emptyProject(origin: Origin, name?: string, datum?: string): ProjectDocument;
+/** Create a site object of the given kind at a position, seeded with sensible default dimensions. */
+export declare function createObject(kind: ObjectKind, position: Point, floorId: string | null, name?: string): SiteObject;

package/dist/types/model/geometry.d.ts

@@ -0,0 +1,99 @@
+import type { Barrier, Drawing, Origin, Point, ProjectDocument, Ring, SiteObject, Slope, VirtualBoundary } from './types';
+export declare const distance: (a: Point, b: Point) => number;
+export declare const rotate: (p: Point, degrees: number) => Point;
+export declare const geoOrigin: (lngLat: Point, bearing?: number) => Origin;
+/** Shift a site anchor by a distance on the ground, in metres east and north.
+ *
+ *  Nudging a building into place is a thing you do in metres — "half a metre that way" — and the
+ *  anchor is stored in degrees, where the useful step depends on latitude and differs between the
+ *  two axes. Deliberately NOT rotated by the site bearing: this moves the site across the world,
+ *  and the directions that make sense for that are the compass ones, not the plan's own grid. */
+export declare const moveOrigin: (origin: Origin, east: number, north: number) => Origin;
+export declare const toLocal: (lngLat: Point, origin: Origin) => Point;
+export declare const toLngLat: (p: Point, origin: Origin) => Point;
+export declare const add: (a: Point, b: Point) => Point;
+export declare const closeRing: (ring: Ring) => Ring;
+export declare const openRing: (ring: Ring) => Ring;
+export declare const ringArea: (ring: Ring) => number;
+export declare const objectArea: (object: SiteObject) => number;
+export declare const centroid: (ring: Ring) => Point;
+export declare const rectangle: (center: Point, width: number, depth: number, rotation?: number) => Ring;
+/** Do the two open segments cross? Used for line of sight: a wall between two points blocks it.
+ *  Touching at an endpoint does not count — walls meet at shared junctions, and a sightline grazing
+ *  such a corner is not obstructed by it. */
+export declare function segmentsCross(a: Point, b: Point, c: Point, d: Point): boolean;
+export declare function segmentProjection(p: Point, a: Point, b: Point): {
+    point: Point;
+    t: number;
+    distance: number;
+    length: number;
+};
+/** Elevation of a sloped area at a point: project onto the slope axis and lerp high → low. Points
+ * beyond either end clamp, so a footprint wider than its axis keeps flat aprons at both ends. */
+export declare function slopeElevation(slope: Slope, point: Point): number;
+/** The ground an object covers. Most areas carry an explicit outline; anything placed by size falls
+ *  back to the rectangle its width, depth and rotation describe. One definition, so the model and the
+ *  renderer cannot disagree about where a thing is. */
+export declare const footprint: (o: SiteObject) => Ring[];
+export declare function barrierEnds(project: ProjectDocument, barrier: Barrier | VirtualBoundary): [Point, Point];
+export declare function objectPosition(project: ProjectDocument, object: SiteObject): Point;
+export declare function objectRotation(project: ProjectDocument, object: SiteObject): number;
+export declare function pointInRing(point: Point, ring: Ring): boolean;
+/** Whether segments a–b and c–d cross or touch, endpoints included. */
+export declare function intersects(a: Point, b: Point, c: Point, d: Point): boolean;
+export declare function containedBy(child: Ring[], parent: Ring[]): boolean;
+export declare function snapPoint(project: ProjectDocument, floorId: string | null, point: Point, tolerance: number, previous?: Point, grid?: boolean, 
+/** Direction the segment from `previous` is held to, with its 15° multiples. Default 0 is the site
+ *  grid; pass `referenceAxis(...).angle` to hold to the building or to a neighbouring wall instead. */
+axis?: number): {
+    point: Point;
+    label: string;
+};
+export declare function holdAngle(previous: Point, point: Point, axis: number, tolerance: number): {
+    point: Point;
+    degrees: number;
+    quarter: number;
+} | null;
+/** One centimetre is the model's degeneracy guard, independent of the drawing grid and zoom.
+ *  Short returns, jambs and staggered junctions are real geometry; their screen handles spread
+ *  apart when necessary so they remain editable. */
+export declare const MIN_SEGMENT = 0.01;
+/** An opening needs a valid wall AND enough length for its actual width. Kept as an exported
+ *  base limit for callers; there is no additional one-metre restriction on narrow doors/windows. */
+export declare const OPENING_MIN_SEGMENT = 0.01;
+/** Automatic joins only absorb sub-millimetre coordinate noise. Interactive snapping has its
+ *  own screen-based reach, so a deliberate centimetre-scale feature survives with snapping off. */
+/** Weld a connection near the end of a wall to that end. The snap preview and the actual
+ *  junction use the same rule, so an ordinary T-junction cannot leave an uneditable stub. */
+export declare function barrierJoinPoint(project: ProjectDocument, point: Point, floorId: string | null): Point;
+/** A preview can check a connection without partially splitting any walls. */
+export declare function junctionIssue(project: ProjectDocument, point: Point, floorId: string | null): string | null;
+/** Preflight the complete stroke, including openings crossed between its endpoints. */
+export declare function barrierStrokeIssue(project: ProjectDocument, a: Point, b: Point, floorId: string | null): string | null;
+export declare function joinAt(project: ProjectDocument, point: Point, floorId: string | null): string;
+/** Take a wall out of the document, with everything that only existed because it was there.
+ *
+ *  A wall is never alone: doors and windows hang in it, junctions exist to hold its ends, and route
+ *  nodes may be bound to those openings. Removing the barrier alone leaves each of those pointing at
+ *  something that is gone, and the document refuses the whole edit — so the delete appears to do
+ *  nothing at all, which is worse than either outcome. Everything that removes a wall goes through
+ *  here so that cannot happen in one place and not another.
+ *
+ *  A junction survives if any other wall still ends there; the ontology is pruned by the caller,
+ *  which knows whether spaces are also being merged. */
+export declare function removeBarrier(project: ProjectDocument, barrierId: string): void;
+export declare function addBarrier(project: ProjectDocument, a: Point, b: Point, floorId: string | null, kind: 'wall' | 'fence'): Barrier | undefined;
+export declare function splitRoom(project: ProjectDocument, roomId: string, pa: Point, pb: Point, 
+/** Build the partition wall along the cut. False when a wall already exists there — splitting a
+ *  space *because* someone drew a wall must not draw a second one on top of it. */
+wall?: boolean): string;
+/** Delete a floor and everything anchored to it. The cascade is the whole job: a floor owns junctions,
+ *  barriers, objects and drawings, and those are in turn referenced from elsewhere — openings hang off
+ *  barriers, cameras watch objects, lifts serve floors, nested zones name a parent, the nav graph binds
+ *  both, a building may roof this level, and the document may open on it. Anything missed here surfaces
+ *  later as a validation failure on load, so it is all handled up front.
+ *  Refuses to remove the last floor: a project must always have one. Returns the ids that were removed. */
+export declare function removeFloor(project: ProjectDocument, floorId: string): string[];
+export declare function duplicateFloor(project: ProjectDocument, floorId: string): string;
+export declare function alignDrawing(imagePoints: [Point, Point], mapPoints: [Point, Point]): Pick<Drawing, 'origin' | 'scale' | 'rotation'>;
+export declare const drawingCorners: (d: Drawing) => Point[];

package/dist/types/model/host.d.ts

@@ -0,0 +1,154 @@
+import type { ReactNode } from 'react';
+import type { StyleSpecification, RequestTransformFunction } from 'maplibre-gl';
+import type { ProjectDocument, ProjectRepository, AssetRepository, SiteObject, Point } from './types';
+import type { StatusFeed, StatusReading } from './live';
+/** A named coordinate system a host offers for footprint import — converts the file's coordinates to
+ *  lng/lat (WGS84). The core carries no projections; a host supplies these (e.g. via proj4). */
+export interface ImportProjection {
+    label: string;
+    toLngLat(p: Point): Point;
+}
+/** Describes a basemap's vector-tile schema so the built-in adoption, 3D-city, cadastre and
+ *  below-grade context features can read it. The library ships no schema of its own — a host names its
+ *  tiles' layers/fields here (see the reference `mmlBasemap` for Finland's MML). Each part is optional;
+ *  a feature is enabled only when its part is present. */
+export interface BasemapVectorSchema {
+    /** Building footprints — powers the adopt tool and the 3D-city massing. */
+    footprints?: {
+        sourceLayer: string;
+        idField: string;
+        /** Estimated storey count from a footprint's properties (adopt seeds this many floors). */
+        storeys?: (props: Record<string, unknown>) => number;
+        /** Human name for an adopted footprint from its properties. */
+        name?: (props: Record<string, unknown>) => string | undefined;
+        /** A MapLibre expression for the 3D extrusion height (paint can't call a JS fn); omit → flat. */
+        heightExpression?: unknown;
+    };
+    /** Below-grade context layers (soil ghosts) drawn when viewing a basement floor. */
+    context?: {
+        waterLayer?: string;
+        roadLayer?: string;
+        buildingLayer?: string;
+    };
+    /** Cadastral parcel overlay from a separate vector tilejson. */
+    cadastre?: {
+        tilejson: string;
+        attribution: string;
+        parcelLayer: string;
+        boundaryLayer: string;
+        markLayer: string;
+        labelLayer: string;
+        labelField: string;
+        font: string;
+    };
+}
+export interface BasemapConfig {
+    style: string | StyleSpecification;
+    /** Last chance to adjust the style before it is handed to the map: recolour layers, drop clutter,
+     *  swap in a dusk palette. Runs for a fetched style and an inline one alike, after relative URLs
+     *  have been resolved, so a host can tune a published basemap without forking and maintaining it.
+     *  Mutating the argument and returning it is fine — the style is not shared. */
+    styleTransform?: (style: StyleSpecification) => StyleSpecification;
+    transformRequest?: RequestTransformFunction;
+    /** Name shown for this basemap in the editor's map-settings picker (host-branded); defaults to "Map background". */
+    label?: string;
+    /** Vector-tile schema for the built-in adoption/3D-city/cadastre features (host-supplied). */
+    vectorSchema?: BasemapVectorSchema;
+}
+export interface PlannerAdapters {
+    projects: ProjectRepository;
+    assets: AssetRepository;
+    /** Live status readings. Optional: a host that only models premises omits it, and the editor then
+     *  drops its monitoring surface entirely rather than showing an empty one. */
+    status?: StatusFeed;
+    basemap?: BasemapConfig;
+    /** Extra coordinate systems offered in the footprint-import dialog (beyond lng/lat, always available). */
+    importProjections?: ImportProjection[];
+    /** Optional server-backed AI import. Credentials and tool execution belong to the host backend. */
+    aiImport?: AiImportAdapter;
+    /** Host-side PDF page conversion. The editor never loads a PDF parser or worker. */
+    pdfDrawing?: PdfDrawingAdapter;
+}
+export interface PdfDrawingAdapter {
+    render(file: File, page: number): Promise<Blob>;
+}
+export interface AiImportAdapter {
+    /** Queue human instructions for the next provider turn of an already running job. */
+    sendInstruction?(jobId: string, instruction: import('../import/instructions').ImportInstruction): Promise<void>;
+    run(file: File, options: {
+        origin: ProjectDocument['origin'];
+        instructions: string;
+        brief?: import('../import/brief').ImportBrief;
+        base?: ProjectDocument;
+        checkpoint?: import('../import/checkpoint').ImportCheckpoint;
+        budget?: import('../import/checkpoint').ImportBudget;
+        onCheckpoint?: (checkpoint: import('../import/checkpoint').ImportCheckpoint) => void | Promise<void>;
+        onPause?: (pause: import('../import/checkpoint').ImportPause) => void | Promise<void>;
+        onAnalysis?: (preview: import('../import/analysisPreview').ImportAnalysisPreview) => void | Promise<void>;
+        onSession?: (jobId: string) => void | Promise<void>;
+        signal: AbortSignal;
+        onProgress: (event: {
+            type: 'text' | 'tool' | 'status';
+            detail: string;
+        }) => void | Promise<void>;
+        /** Await acceptance/persistence before consuming the next event. */
+        onDocument: (document: ProjectDocument) => void | Promise<void>;
+        /** Cumulative usage for this run; a continuation starts a new run. */
+        onUsage?: (usage: import('../import/usage').AiTokenUsage) => void | Promise<void>;
+    }): Promise<ProjectDocument>;
+}
+/** Map camera pose. Part of ViewState; hosts persist and restore it (e.g. encoded in a deep link). */
+export interface CameraState {
+    center: [number, number];
+    zoom: number;
+    bearing: number;
+    pitch: number;
+}
+/** Camera + floor + mode snapshot — supplied via `initialView` and emitted through `onViewChange`; hosts persist it (e.g. as a deep link). */
+export interface ViewState {
+    floor?: string | null;
+    threeD?: boolean;
+    stack?: boolean;
+    /** First-person walk-through. Implies threeD; stack is ignored while it is on. */
+    walk?: boolean;
+    camera?: CameraState;
+    /** Which map background to open on: the host's basemap, or the plain drawing ground. A project
+     *  that is nowhere in particular — a sample, a fiction, a plan not yet placed — has nothing to
+     *  gain from the city under it and pays to draw it. Absent means the host's basemap if it has one. */
+    basemap?: 'plan' | 'host';
+    /** Which surface to open on. Absent means the plan viewer — right for a link someone was sent,
+     *  wrong for a project the host just created or imported, where the point is to start drawing. */
+    mode?: PlannerMode;
+}
+/** The editor's three surfaces: pure plan viewer, authoring editor, live monitoring. */
+export type PlannerMode = 'view' | 'edit' | 'live';
+/** Context for a host-rendered status panel in the inspector (controls, a simulator, a work-order link, …). */
+export interface StatusPanelContext {
+    object: SiteObject;
+    status?: StatusReading;
+    editing: boolean;
+    live: boolean;
+}
+/** Optional host commands for passenger lifts. Readings stay transient; the host owns sequencing. */
+export interface ElevatorControls {
+    statuses: StatusReading[];
+    call(feedId: string, floorId: string): void;
+    hold(feedId: string, open: boolean): void;
+}
+export interface SitePlannerProps {
+    /** The document to edit. The editor owns edits through its own history, so this is the *initial*
+     *  document; pass a new one with a different `id` to load a different project (same-id updates are
+     *  ignored). Observe edits via `onChange`. */
+    project: ProjectDocument;
+    adapters: PlannerAdapters;
+    onChange?: (project: ProjectDocument) => void;
+    onSelectionChange?: (id: string | null) => void;
+    onBack?: () => void;
+    initialView?: ViewState;
+    onViewChange?: (view: ViewState) => void;
+    /** Notified when the editor switches surface — a host can, e.g., start/stop its live feed's traffic. */
+    onModeChange?: (mode: PlannerMode) => void;
+    /** Render host-specific controls for a selected bound object (return null to show none). Keeps command/simulation vocabulary out of the library. */
+    renderStatusPanel?: (ctx: StatusPanelContext) => ReactNode;
+    elevators?: ElevatorControls;
+}

package/dist/types/model/inference.d.ts

@@ -0,0 +1,46 @@
+import { type Point, type Portal, type ProjectDocument, type SiteObject } from './types';
+export { TRAVERSABLE } from './passages';
+/** Infer the portals a plan already describes: for each opening, the space on either side of the wall
+ *  it sits in. This is the move software without a plan cannot make — it has to be told which
+ *  doors bound an area, because none of them has a floor plan to ask.
+ *
+ *  Openings whose sides cannot be resolved are skipped rather than guessed at: an unbounded or
+ *  open-plan side is a real modelling gap, and inventing a portal there would hide it. */
+export declare function inferPortals(project: ProjectDocument): Portal[];
+/** Infer the portals that have no door in them: two spaces that share a boundary with nothing built
+ *  across it. Open-plan floors are made of these — a department opening onto a gallery, a lift car
+ *  onto its lobby — and a model that only knows about door objects cannot see any of them.
+ *
+ * Shared virtual edges give exact connectivity. For independent outlines, walk the outline and
+ * accumulate stretches that can step across into a neighbour without crossing a wall. */
+export declare function inferOpenBoundaries(project: ProjectDocument): Portal[];
+/** Re-read the portals from the plan, keeping what a person has decided.
+ *
+ *  Hand-authored portals (any id inference would not mint) survive wholesale. On re-inferred ones the
+ *  geometry is the plan's to change — which spaces, through which opening — but the semantic fields a
+ *  person may have set (`passage`, `attests`, `name`, `metadata`) are carried onto the replacement:
+ *  sealing a doorway or marking it monitored must survive the plan being redrawn around it. A portal
+ *  the plan no longer describes goes, and its edits go with it — they were about a way through that
+ *  no longer exists. */
+export declare function refreshPortals(project: ProjectDocument): number;
+/** Spaces the segment a→b cuts clean across: it enters and leaves, so the space really is in two
+ *  pieces. Touching a corner or stopping halfway inside does not divide anything. */
+export declare function spacesDividedBy(project: ProjectDocument, floorId: string | null, a: Point, b: Point): SiteObject[];
+/** Split every space a new wall cuts across, so the plan cannot claim two walled-apart halves are one
+ *  place. Returns the ids of the pieces created.
+ *
+ *  The wall is assumed to exist already — this is called *because* one was drawn — so no partition is
+ *  built. splitRoom would otherwise lay a second wall along the first.
+ *
+ *  Splitting is safe in a way that joining is not: one space becomes two and both inherit everything,
+ *  where merging two spaces would have to destroy one identity — its name, its feed binding, whichever
+ *  zones it had joined. That asymmetry is why this happens automatically and merging never will. */
+export declare function divideSpaces(project: ProjectDocument, floorId: string | null, a: Point, b: Point): string[];
+/** Spaces that a wall was the only thing keeping apart: remove it and they are one room again.
+ *
+ *  Answered before the wall goes, because afterwards the evidence is gone. Two spaces qualify when
+ *  they share a boundary that this barrier runs along, and nothing else is built across it. */
+export declare function spacesRejoinedBy(project: ProjectDocument, barrierId: string): [SiteObject, SiteObject] | null;
+/** Merge `absorbed` into `keep`, uniting their footprints. The survivor keeps its own name, colour and
+ *  bindings; that is the whole reason this is never automatic — something is always discarded. */
+export declare function mergeSpaces(project: ProjectDocument, keepId: string, absorbedId: string): boolean;

package/dist/types/model/live.d.ts

@@ -0,0 +1,60 @@
+import type { ProjectDocument } from './types';
+export interface StatusMetrics {
+    occupancy?: number;
+    capacity?: number;
+    presence?: boolean;
+    co2?: number;
+    lux?: number;
+    temperature?: number;
+}
+/** Severity the viewer colours by, most-to-least urgent. Domain-neutral: `critical` is whatever the
+ *  host deems an urgent condition (a security alarm, an offline sensor, an over-capacity space, …). */
+export type StatusTone = 'critical' | 'warning' | 'normal' | 'unknown';
+export interface StatusReading {
+    feedId: string;
+    /** How the viewer colours the bound object. */
+    tone: StatusTone;
+    /** Human-readable status text the viewer shows (host-authored). */
+    label: string;
+    /** Epoch-ms of the reading. Enables the viewer's staleness warning; omit to opt out. */
+    timestamp?: number;
+    /** Generic space/environment telemetry the viewer renders (occupancy rollups, etc.). */
+    metrics?: StatusMetrics;
+    /** For a door, gate or turnstile: whether the leaf is standing open right now. The plan draws it —
+     *  an open leaf swings, a closed one sits in the frame. Distinct from `tone`, which says whether
+     *  anyone should be worried: a door can be open and perfectly normal, or closed and in alarm.
+     *  Omitted means unknown, and an unknown door is drawn with the architectural swing symbol. */
+    open?: boolean;
+    /** For a lift: the floor its car is standing at right now, as a floor id. The plan draws the car
+     *  there and slides it when the value changes, which is the difference between a shaft and a lift
+     *  you can watch. Omitted means unknown, and an unknown car rests at the lowest level it serves —
+     *  where an idle lift really does wait. Sits beside `open`, which says whether its doors are
+     *  standing open, for the same reason: both are what the thing is doing, not whether to worry. */
+    carFloorId?: string;
+    /** Destination while travelling; carFloorId remains the last arrived landing. */
+    targetFloorId?: string;
+    /** Expected travel duration for the current car movement, in seconds. Hosts can compress demo
+     * trips; absent means the renderer's ordinary 1.5 m/s. Arrival readings remain authoritative. */
+    carTravelSeconds?: number;
+    /** Travel or door movement is in progress; passengers cannot board or leave yet. */
+    moving?: boolean;
+    /** For an escalator: whether it is running right now. A stopped escalator is a stair, and the
+     *  plan draws it as one — the steps stand still. Omitted means unknown and draws it running,
+     *  because an escalator that is working is the ordinary case and a stopped one is the exception
+     *  worth reporting. Sits beside `open` and `carFloorId` for the same reason: all three say what
+     *  the thing is doing, not whether anyone should worry, which is `tone`. */
+    running?: boolean;
+    /** For an escalator that can be reversed: which way it is carrying people at this moment, which a
+     *  station or a shopping centre flips between the morning and the evening peak. Overrides the
+     *  object's authored `travel` for as long as the reading stands. Pass readings to findRoute's
+     *  options to route with the current direction; the stored graph remains unchanged. */
+    travel?: 'up' | 'down';
+    /** Opaque host state, passed through untouched — the library never reads it. */
+    details?: Record<string, unknown>;
+}
+/** The live-status contract: a source of StatusReading snapshots keyed to SiteObjects by feedId.
+ *  Deliberately minimal — just subscribe. Interactive concerns (commanding something, simulating
+ *  traffic) are host-specific and belong to the host's own feed and UI, not this contract. */
+export interface StatusFeed {
+    subscribe(project: ProjectDocument, listener: (statuses: StatusReading[]) => void): () => void;
+}

package/dist/types/model/materials.d.ts

@@ -0,0 +1,28 @@
+export declare const EXTERIOR_PRESETS: {
+    readonly limestone: {
+        readonly name: "Limestone";
+        readonly material: "stone";
+        readonly color: "#e2e4e6";
+    };
+    readonly brick: {
+        readonly name: "Warm brick";
+        readonly material: "brick";
+        readonly color: "#9b705b";
+    };
+    readonly darkBrick: {
+        readonly name: "Dark brick";
+        readonly material: "brick";
+        readonly color: "#7a4636";
+    };
+    readonly plaster: {
+        readonly name: "Ivory render";
+        readonly material: "plaster";
+        readonly color: "#e0ddd4";
+    };
+    readonly timber: {
+        readonly name: "Cedar cladding";
+        readonly material: "timber";
+        readonly color: "#ab8b68";
+    };
+};
+export type ExteriorPreset = keyof typeof EXTERIOR_PRESETS;