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

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/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/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;

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

@@ -0,0 +1,178 @@
+import type { Barrier, Building, Floor, NavEdge, NavNode, ObjectKind, Origin, Point, Portal, PortalGroup, ProjectDocument, Ring, SiteObject, Zone } from './types';
+import { type GeometryDrag } from './authoring';
+import { type TransactResult } from './validate';
+/** Every mutation the schema can execute, as data. `kind` names the operation; the rest are its
+ *  arguments, exactly as the underlying authoring function takes them. */
+export type Mutation = {
+    kind: 'addBuilding';
+    building: Building;
+} | {
+    kind: 'patchBuilding';
+    buildingId: string;
+    set: Partial<Omit<Building, 'id'>>;
+} | {
+    kind: 'addFloor';
+    floor: Floor;
+} | {
+    kind: 'patchFloor';
+    floorId: string;
+    set: Partial<Omit<Floor, 'id' | 'buildingId'>>;
+} | {
+    kind: 'removeFloor';
+    floorId: string;
+} | {
+    kind: 'duplicateFloor';
+    floorId: string;
+} | {
+    kind: 'patchProject';
+    set: Partial<Pick<ProjectDocument, 'name' | 'description' | 'datum' | 'initialFloorId'>>;
+} | {
+    kind: 'patchBarrier';
+    barrierId: string;
+    set: Partial<Omit<Barrier, 'id' | 'startId' | 'endId' | 'floorId'>>;
+} | {
+    kind: 'removeBarrier';
+    barrierId: string;
+} | {
+    kind: 'moveGeometry';
+    move: GeometryDrag;
+} | {
+    kind: 'drawBoundary';
+    a: Point;
+    b: Point;
+    floorId: string | null;
+} | {
+    kind: 'drawBarrier';
+    a: Point;
+    b: Point;
+    floorId: string | null;
+    barrierKind?: 'wall' | 'fence';
+} | {
+    kind: 'encloseRoom';
+    floorId: string | null;
+    point: Point;
+    name?: string;
+} | {
+    kind: 'addHole';
+    objectId: string;
+    ring: Ring;
+} | {
+    kind: 'patchZone';
+    zoneId: string;
+    set: Partial<Pick<Zone, 'name' | 'purpose' | 'connects' | 'metadata'>>;
+} | {
+    kind: 'addPortal';
+    portal: Omit<Portal, 'id'>;
+} | {
+    kind: 'removePortal';
+    portalId: string;
+} | {
+    kind: 'setNavigation';
+    nodes: NavNode[];
+    edges: NavEdge[];
+} | {
+    kind: 'addZone';
+    name: string;
+    spaceIds: string[];
+    purpose?: string;
+} | {
+    kind: 'removeZone';
+    zoneId: string;
+} | {
+    kind: 'setZoneMembers';
+    zoneId: string;
+    spaceIds: string[];
+    member: boolean;
+} | {
+    kind: 'nestZone';
+    parentId: string;
+    childId: string;
+} | {
+    kind: 'addPortalGroup';
+    name: string;
+    portalIds: string[];
+} | {
+    kind: 'removePortalGroup';
+    groupId: string;
+} | {
+    kind: 'setPortalGroupMembers';
+    groupId: string;
+    portalIds: string[];
+    member: boolean;
+} | {
+    kind: 'patchPortal';
+    portalId: string;
+    set: Partial<Omit<Portal, 'id' | 'a' | 'b' | 'openingId'>>;
+} | {
+    kind: 'patchObject';
+    objectId: string;
+    set: Partial<Omit<SiteObject, 'id' | 'kind'>>;
+} | {
+    kind: 'addObject';
+    objectKind: ObjectKind;
+    name: string;
+    position: Point;
+    floorId: string | null;
+    set?: Partial<Omit<SiteObject, 'id' | 'kind'>>;
+} | {
+    kind: 'removeObjects';
+    ids: string[];
+} | {
+    kind: 'refreshPortals';
+} | {
+    kind: 'pruneOntology';
+} | {
+    kind: 'addBarrier';
+    a: Point;
+    b: Point;
+    floorId: string | null;
+    barrierKind: 'wall' | 'fence';
+} | {
+    kind: 'addBoundary';
+    a: Point;
+    b: Point;
+    floorId: string | null;
+} | {
+    kind: 'connectSpace';
+    objectId: string;
+    source?: 'outline' | 'walls';
+} | {
+    kind: 'disconnectSpace';
+    objectId: string;
+} | {
+    kind: 'splitRoom';
+    roomId: string;
+    a: Point;
+    b: Point;
+    wall?: boolean;
+} | {
+    kind: 'divideSpaces';
+    floorId: string | null;
+    a: Point;
+    b: Point;
+} | {
+    kind: 'mergeSpaces';
+    keepId: string;
+    absorbedId: string;
+}
+/** Move or turn the whole site. The geometry is untouched — local metres stay what they were; only
+ *  where the frame is pinned and which way it faces change. A plan carries no heading, so this is
+ *  how an imported one is squared onto the street it actually stands on. */
+ | {
+    kind: 'setOrigin';
+    origin: Origin;
+};
+/** What a mutation reports back, beyond the new document: the entity it created, or whether it did
+ *  anything at all. Read it off the result rather than hunting the document for what changed.
+ *  Entity outcomes are views INTO the frozen result — read them freely, but editing one throws;
+ *  the next change goes through the next transaction like every other. */
+export type MutationOutcome = Zone | PortalGroup | string[] | string | boolean | number | undefined;
+export type MutationResult = TransactResult & {
+    outcomes?: MutationOutcome[];
+};
+/** Execute one mutation atomically. Sugar over `applyMutations` with a single step. */
+export declare const applyMutation: (project: ProjectDocument, mutation: Mutation) => MutationResult;
+/** Execute a sequence of mutations as ONE transaction: all of them apply and the result passes
+ *  every rule, or none of them do and `error` says why. `outcomes` reports what each step returned
+ *  (created zones, split-off ids), in order — present only on success. */
+export declare function applyMutations(project: ProjectDocument, mutations: Mutation[]): MutationResult;

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

@@ -0,0 +1,70 @@
+import type { NavEdge, NavEdgeKind, NavNode, Point, ProjectDocument, SiteObject } from './types';
+import type { StatusReading } from './live';
+export declare const ELEVATOR_BASE = 25, ELEVATOR_PER_METRE = 1, STAIR_CLIMB_FACTOR = 5, DOOR_COST = 1.5;
+/** addNavNode welds onto any existing node within this range (mirrors joinAt's junction reuse). */
+export declare const NAV_WELD = 0.25;
+export declare const navNodes: (p: ProjectDocument) => NavNode[];
+export declare const navEdges: (p: ProjectDocument) => NavEdge[];
+/** Find-or-create a route node at a point on a floor, welding onto any node within NAV_WELD. */
+export declare function addNavNode(p: ProjectDocument, floorId: string | null, position: Point, objectId?: string): NavNode;
+/** Connect two nodes, reusing an existing edge of the same kind between the same pair. */
+export declare function addNavEdge(p: ProjectDocument, kind: NavEdgeKind, a: NavNode, b: NavNode, objectId?: string): NavEdge;
+/** Draw a chain of walk edges through the given points, welding onto existing nodes en route. */
+export declare function navPath(p: ProjectDocument, floorId: string | null, points: Point[]): NavNode[];
+/** Thread a vertical connection through an elevator/stairs object: one node per served floor at the object's position. Stairs chain adjacent served floors (you pass every level); an elevator gets an edge per floor pair (a ride is direct, so ELEVATOR_BASE is paid once). Per-floor twin objects share a name (see the demo lifts); pass any one of them and each edge binds the twin on its upper floor. */
+export declare function chainVertical(p: ProjectDocument, object: SiteObject): NavNode[];
+export interface RouteLeg {
+    edge: NavEdge;
+    from: NavNode;
+    to: NavNode;
+    cost: number;
+}
+export interface RouteStep {
+    kind: 'depart' | 'walk' | 'door' | 'stairs' | 'elevator' | 'arrive';
+    text: string;
+    floorId: string | null;
+    nodeIds: string[];
+    objectId?: string;
+    distance?: number;
+}
+/** Either end of a route: an object in the document by id, or a point on a floor — where the
+ *  walker is standing, which is the start most people want and no object describes. */
+export type RouteEnd = string | {
+    name?: string;
+    floorId: string | null;
+    position: Point;
+};
+/** What a route knows about its ends: enough to name them and place them, whether they came from
+ *  an object or a point. */
+export type RoutePlace = Pick<SiteObject, 'id' | 'kind' | 'name' | 'floorId' | 'position'>;
+/** The id a host uses for "where the walker is" in a picker; findRoute() never sees it. */
+export declare const HERE = "@here";
+export interface Route {
+    from: RoutePlace;
+    to: RoutePlace;
+    nodes: NavNode[];
+    legs: RouteLeg[];
+    steps: RouteStep[];
+    distance: number;
+    cost: number;
+}
+/** Metres-equivalent cost of traversing an edge; authored weight wins over the derived cost. */
+export declare function edgeCost(p: ProjectDocument, edge: NavEdge, a: NavNode, b: NavNode): number;
+/** Walking metres of an edge (horizontal run, plus the rise on vertical edges) — for display, not costing. */
+export declare function edgeLength(p: ProjectDocument, edge: NavEdge, a: NavNode, b: NavNode): number;
+/** Candidate graph entry points for a room/door/poi: nodes bound to the object at cost 0, else nodes inside an area's outer ring, else the nearest node on the object's floor. Cost is the straight-line approach in metres. */
+export declare function routeAnchors(p: ProjectDocument, object: SiteObject): {
+    node: NavNode;
+    cost: number;
+}[];
+/** Shortest route between two ends — objects (rooms, doors, POIs, …) or points on a floor — over
+ *  the authored graph, with human step instructions. Returns null when either end has no anchor or
+ *  no path exists. */
+export interface RouteOptions {
+    statuses?: ReadonlyMap<string, StatusReading>;
+}
+export declare function findRoute(p: ProjectDocument, fromEnd: RouteEnd, toEnd: RouteEnd, options?: RouteOptions): Route | null;
+/** Human name of a level: "Menswear & denim (level 3)" via Floor.code, "outside" for the site level. */
+export declare function floorPhrase(p: ProjectDocument, floorId: string | null): string;
+/** Build the human step list: walking grouped per floor, vertical rides merged per lift/stair name, doors called out — "Exit through Aleksanterinkatu entrance", "Take Lift A to Offices · buying & admin (level 8)". */
+export declare function routeSteps(p: ProjectDocument, from: RoutePlace, to: RoutePlace, path: NavNode[], legs: RouteLeg[]): RouteStep[];

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

@@ -0,0 +1,43 @@
+import { type Portal, type PortalGroup, type ProjectDocument, type Zone } from './types';
+/** Which way you must cross `portal` to arrive in `spaceId`, or null if you cannot get there that way.
+ *  Direction is asked, never stored: a door's entry side is relative to the area you mean. */
+export declare function entryInto(portal: Portal, spaceId: string): 'a-to-b' | 'b-to-a' | null;
+/** Every space in `zone`, including those reached through nested zones. */
+export declare const zoneSpaces: (project: ProjectDocument, zone: Zone) => string[];
+/** Portals on the boundary of `zone` — one side in, one side out. These are the ways in, and the
+ *  thing software without a floor plan to ask makes you enumerate by hand. Derived, so it cannot go
+ *  stale when the building is redrawn. */
+export declare function perimeter(project: ProjectDocument, zone: Zone): Portal[];
+/** Portals wholly inside `zone`. Not decorative: anything tracking where somebody ended up needs to
+ *  know that crossing one of these does not change which zone you are in. */
+export declare function captive(project: ProjectDocument, zone: Zone): Portal[];
+/** Create a zone over the given spaces. Ids that are not spaces are dropped rather than rejected —
+ *  a selection usually contains a door or a fixture alongside the rooms, and losing the whole gesture
+ *  over that would be tiresome. */
+export declare function addZone(project: ProjectDocument, name: string, spaceIds: string[], purpose?: string): Zone;
+/** Remove a zone, and any nesting reference to it. A dangling childZoneIds entry fails validation. */
+export declare function removeZone(project: ProjectDocument, zoneId: string): void;
+/** Add or remove spaces on a zone. Membership is a set: adding twice is not an error, and neither is
+ *  removing something that was never there. */
+export declare function setZoneMembers(project: ProjectDocument, zoneId: string, spaceIds: string[], member: boolean): void;
+/** Nest one zone inside another, refusing anything that would make a cycle. Zones form a DAG, and a
+ *  cycle is the one shape the validator will not accept. */
+export declare function nestZone(project: ProjectDocument, parentId: string, childId: string): boolean;
+/** Create a portal group over the given portals. The escape hatch for sets that are not a zone
+ *  boundary — "all loading-bay shutters", "every door on the night circuit". Where a set *is* a zone
+ *  boundary, derive it with `perimeter` instead; a derived list cannot go stale. Ids that are not
+ *  portals are dropped rather than rejected, mirroring addZone. */
+export declare function addPortalGroup(project: ProjectDocument, name: string, portalIds: string[]): PortalGroup;
+/** Remove a portal group. Nothing references groups, so nothing needs cleaning up after one. */
+export declare function removePortalGroup(project: ProjectDocument, groupId: string): void;
+/** Add or remove portals on a group. Membership is a set, exactly as setZoneMembers. */
+export declare function setPortalGroupMembers(project: ProjectDocument, groupId: string, portalIds: string[], member: boolean): void;
+/** Drop ontology references to things that no longer exist.
+ *
+ *  Every reference here is validated, so a delete that skips this step produces an invalid document
+ *  and gets refused — from the outside that looks like the delete silently doing nothing, which is
+ *  the worst way for a bug to present. Call it after removing objects, from every path that can.
+ *
+ *  A portal whose opening is gone goes with it: the door was the way through, and keeping a portal
+ *  that no longer has one would quietly turn a closed doorway into an open boundary. */
+export declare function pruneOntology(project: ProjectDocument): void;

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

@@ -0,0 +1,2 @@
+/** Openings a person can cross. Windows are openings, but never walkable portals. */
+export declare const TRAVERSABLE: Set<string>;