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

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

@@ -0,0 +1,9 @@
+import { type Portal, type ProjectDocument } from './types';
+/** A shared virtual edge explicitly declares an unwalled connection. Read its two sides directly;
+ * sampling inset room outlines loses narrow openings near the ends of adjoining walls. */
+export declare function sharedBoundaryPortals(project: ProjectDocument): Portal[];
+/** The readable portal layer, including explicit shared openings in older saved plans. A stored
+ * portal takes precedence, including sealed and one-way passage. No document mutation is needed.
+ * Once both spaces use shared boundaries, an inferred open connection also disappears when its
+ * virtual edge is replaced by a wall. Legacy independent outlines retain their inferred portals. */
+export declare function effectivePortals(project: ProjectDocument): Portal[];

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

@@ -0,0 +1,11 @@
+/** Numerical tolerances are independent of the user's positioning grid. All values are metres. */
+export declare const GEOMETRY_EPS = 0.000001;
+export declare const JOIN_EPS = 0.001;
+export declare const MIN_WALL_LENGTH = 0.01;
+export declare const MIN_RING_EDGE = 0.001;
+/** Usable floor area, after subtracting holes and physical walls, in square metres. */
+export declare const MIN_SPACE_AREA = 1;
+/** Topological faces and holes may be smaller than a labelled space. Square metres. */
+export declare const MIN_FACE_AREA = 1e-8;
+/** Only derived polygon-clipping inputs use this precision; junctions retain their coordinates. */
+export declare const CLIP_SCALE = 10000;

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

@@ -0,0 +1,8 @@
+import type { ProjectDocument, SiteObject } from './types';
+export declare function copyProject(project: ProjectDocument): ProjectDocument;
+/** Apply dimensions in the object's own axes, then rotate and translate its polygon. */
+export declare function transformObject(object: SiteObject, patch: Partial<SiteObject>): void;
+/** The floor a viewer should open on: the document's own `initialFloorId` when it names a floor that
+ *  still exists, otherwise the ground floor, otherwise the lowest one. An explicit `null` is a real
+ *  answer — it means the outdoor site — so it is distinguished from the field being absent. */
+export declare function openingFloorId(project: ProjectDocument): string | null;

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

@@ -0,0 +1,15 @@
+import type { NavEdge, NavNode, ProjectDocument } from './types';
+/** Bind a graph node to the room whose walkable floor it can enter. Use separate nodes on the
+ * sides of a controlled portal and join those with a directed/door edge in `graph`. */
+export interface RoomAccess {
+    spaceId: string;
+    nodeId: string;
+}
+export interface RoomNavigationGraph {
+    nodes: NavNode[];
+    edges: NavEdge[];
+}
+/** Build the geometric walking graph inside rooms. Explicit access points describe connectivity;
+ * room outlines, holes, pools and wall thickness describe where a person can walk. The input
+ * document/graph are not mutated. Supplied door/vertical/directed edges are kept verbatim. */
+export declare function buildRoomNavigation(project: ProjectDocument, access: readonly RoomAccess[], graph?: RoomNavigationGraph): RoomNavigationGraph;

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

@@ -0,0 +1,11 @@
+import type { Point, ProjectDocument } from './types';
+/** Extra room for shoulders and for the route marking, in plan metres. */
+export declare const ROUTE_CLEARANCE = 0.4;
+type Bounds = [number, number, number, number];
+export declare const routeBounds: (points: Point[], pad?: number) => Bounds;
+/** A geometric guard for walking connections. It checks the whole segment, not samples along it.
+ * Walls retain their thickness; doors/gates cut their actual apertures. Pools and floor holes are
+ * obstacles even when a containing room's outer ring includes them. Build once for a document. */
+export declare function createRouteClearance(project: ProjectDocument): (floorId: string | null, extent?: Bounds) => (a: Point, b: Point) => boolean;
+export declare function routeClearance(project: ProjectDocument): (floorId: string | null, extent?: Bounds) => (a: Point, b: Point) => boolean;
+export {};

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

@@ -0,0 +1,46 @@
+import { type Point, type ProjectDocument, type Ring, type SiteObject } from './types';
+/** The enclosed region a point stands in, read off the walls around it.
+ *
+ *  A floor's open area is its extent minus the bodies of its walls, and that difference falls apart
+ *  into exactly the regions the walls divide it into — so the room under a click is whichever of
+ *  those contains the click. No tracing, no flood fill, no tolerance to tune: the walls say where
+ *  the rooms are, and this reads the answer.
+ *
+ *  Doorways do not leak, because a door is an object ON a continuous wall rather than a hole in the
+ *  run of it. A doorless passage does leak, and should: the drawing said those two places flow into
+ *  one another. Returns null when the point is not enclosed — outside the building, or inside a
+ *  boundary with a gap in it, where the region reaches the edge of the extent. */
+export declare function enclosedRegion(project: ProjectDocument, floorId: string | null, point: Point): Ring | null;
+/** Every enclosed region on a floor, largest first.
+ *
+ *  Outer rings only: a region with a walled island inside it comes back with the island filled in,
+ *  so its area overstates the floor you could stand on by the island's footprint. Carrying the holes
+ *  through as further rings is the complete answer and changes this signature; until then the island
+ *  is its own region in the list, and enclosedRegion returns it for a click inside it.
+ *
+ *  The same difference as `enclosedRegion`, read whole rather than probed: one subtraction gives all
+ *  the rooms the walls describe. Regions touching the extent are open to the outside and dropped,
+ *  and slivers below `minArea` — the gap between two walls that nearly meet — with them. */
+export declare function enclosedRegions(project: ProjectDocument, floorId: string | null, minArea?: number): Ring[];
+/** Re-fit the rooms that the walls were defining, after those walls have moved.
+ *
+ *  A room stores its own outline, which is what lets a space exist where no wall does — a zone over
+ *  an open floor, a parcel, an area someone drew freehand. The cost is that moving a wall used to
+ *  leave the room it bounded exactly where it was, so the two drifted apart and had to be kept in
+ *  step by hand.
+ *
+ *  They do not have to be. Pass the regions as they stood BEFORE the edit: a room whose outline was
+ *  one of them was being defined by the walls, so it takes the region that now stands in its place.
+ *  A room that matched nothing was drawn rather than enclosed, and is left alone. Identity is never
+ *  touched — the name, colour, bindings and id are the room; only its shape came from the walls. */
+export declare function refitEnclosedRooms(project: ProjectDocument, floorId: string | null, before: Ring[]): number;
+/** Spaces are objects you can stand in — the areas already in the document, plus lifts and stairs.
+ *  Nothing new is stored for them: a room *is* a space, and zones and portals reference it by id. */
+export declare const spaces: (project: ProjectDocument) => SiteObject[];
+/** Where a space sits for routing. Its footprint's centroid, falling back to its placed position. */
+export declare function spacePoint(project: ProjectDocument, space: SiteObject): Point;
+/** True when `point` falls inside a space's footprint — inside its outline and outside its holes. */
+export declare function inSpace(space: SiteObject, point: Point): boolean;
+/** The space a point falls in: the *smallest* one containing it, since a room inside a zone inside a
+ *  floor plate are all true and only the innermost is useful. */
+export declare function spaceAt(project: ProjectDocument, floorId: string | null, point: Point): SiteObject | null;

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

@@ -0,0 +1,14 @@
+import { type NavEdge, type NavNode } from './types';
+import type { ProjectDocument } from './types';
+/** Node id for a space. Prefixed so a derived graph can never collide with an authored entity id. */
+export declare const spaceNodeId: (spaceId: string) => string;
+export declare function derivedGraph(project: ProjectDocument): {
+    nodes: NavNode[];
+    edges: NavEdge[];
+};
+export declare function topology(project: ProjectDocument): {
+    nodes: NavNode[];
+    edges: NavEdge[];
+};
+/** Straight-line length of a derived edge, for cost comparisons against an authored graph. */
+export declare const edgeSpan: (nodes: Map<string, NavNode>, edge: NavEdge) => number;

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

@@ -0,0 +1,369 @@
+import type { ExteriorPreset } from './materials';
+export type Point = [number, number];
+/** Geographic anchor of the local tangent frame — [lng, lat] in WGS84 degrees; an optional third
+ * element rotates the site clockwise from true north (degrees). */
+export type Origin = [number, number] | [number, number, number];
+export type Ring = Point[];
+/** The built-in taxonomy of drawable things, spanning the toolkit's use-cases (spaces, openings,
+ * devices, logistics, safety). It is intentionally broad rather than tied to one domain; model
+ * host-specific subtypes (e.g. a turnstile variety, a sensor class) as `category`/`metadata` on the
+ * object rather than by extending this union. Runtime tuple so the type and the document validator
+ * share one source of truth. */
+export declare const OBJECT_KINDS: readonly ["zone", "room", "parcel", "building", "office", "container", "storage", "door", "window", "gate", "turnstile", "reader", "camera", "elevator", "stairs", "poi", "fixture", "light", "landscape", "sensor", "alarm", "equipment", "evacuation"];
+export type ObjectKind = (typeof OBJECT_KINDS)[number];
+export type MaterialKind = 'brick' | 'stone' | 'plaster' | 'timber' | 'oak' | 'tile' | 'terrazzo' | 'grass' | 'paving' | 'carpet' | 'wallpaper';
+export type ModelKind = 'bed' | 'sofa' | 'dining' | 'cabinet' | 'counter' | 'toilet' | 'basin' | 'shower' | 'sauna' | 'tree' | 'shrub' | 'lamp' | 'car' | 'chimney' | 'vent' | 'post';
+export interface RoofSection {
+    footprint: Ring;
+    ridge: [Point, Point];
+    eave: number;
+    peak: number;
+}
+export interface BuildingRoof {
+    floorId: string;
+    color: string;
+    sections: RoofSection[];
+}
+/** mezzanine marks an intermediate (entresol) level: the plan draws it in context of the levels around it. */
+export interface Floor {
+    id: string;
+    buildingId: string;
+    name: string;
+    elevation: number;
+    height: number;
+    mezzanine?: boolean;
+    code?: string;
+    /** The artificial light this level burns — colour temperature and how brightly. Absent means a
+     *  fluorescent ceiling at working brightness, which is what is actually overhead in most of the
+     *  buildings anyone draws. A building's own lighting does not follow the sun, so this is what
+     *  keeps a storey legible in a plan opened after dark. */
+    light?: InteriorLight;
+    /** What this level sounds like from inside it — the default for every space on it that does not
+     *  say otherwise. Absent is silence. */
+    ambience?: Ambience;
+}
+/** The sound of a space, heard at eye level: a named soundscape or musical preset,
+ *  and how loud, 0 to 1 (absent is 1). Kept in
+ *  the document rather than the renderer for the same reason light is: what a room sounds like
+ *  describes the room. */
+export interface Ambience {
+    preset: AmbiencePreset;
+    level?: number;
+}
+export type AmbiencePreset = 'silent' | 'office' | 'backrooms' | 'plant' | 'baths' | 'elevator';
+export declare const AMBIENCE_PRESETS: AmbiencePreset[];
+/** Colour temperature in kelvin (2700 tungsten, 4000 fluorescent, 6500 daylight) and how brightly,
+ *  0 to 1. Kept here rather than in the renderer: what a space is lit by describes the space. */
+export interface InteriorLight {
+    kelvin: number;
+    level: number;
+    /** Optional colour cast from the fittings or reflected surroundings. */
+    tint?: string;
+}
+/** A ceiling luminaire. Object height is the mounting height above the floor, intensity is candela,
+ * range is metres, and flicker is the optional 0..1 depth of intermittent ballast dimming. */
+export interface LightFixture {
+    /** Optional mounting elevation above the floor; negative values place a lamp inside a pool. */
+    mountHeight?: number;
+    kelvin: number;
+    intensity: number;
+    range: number;
+    flicker?: number;
+}
+export interface Building {
+    id: string;
+    name: string;
+    roof?: BuildingRoof;
+    /** Provenance id of the basemap footprint a building was adopted from — the value of the host's
+     * configured footprints.idField (a string or number, depending on the tile source); absent for
+     * hand-drawn buildings. */
+    sourceId?: string | number;
+    exteriorPreset?: ExteriorPreset;
+}
+export interface Junction {
+    id: string;
+    floorId: string | null;
+    position: Point;
+}
+/** An unwalled space boundary. Physical boundaries use Barrier IDs and endpoints directly. */
+export interface VirtualBoundary {
+    id: string;
+    floorId: string | null;
+    startId: string;
+    endId: string;
+}
+export interface BoundaryUse {
+    edgeId: string;
+    /** Traverse from endId to startId. Absent means startId to endId. */
+    reversed?: boolean;
+}
+export type SpaceGeometry = {
+    mode: 'independent';
+} | {
+    mode: 'boundaries';
+    loops: BoundaryUse[][];
+};
+export interface Barrier {
+    id: string;
+    floorId: string | null;
+    startId: string;
+    endId: string;
+    kind: 'wall' | 'fence';
+    thickness: number;
+    height: number;
+    name: string;
+    color?: string;
+    material?: MaterialKind;
+    category?: string;
+    metadata?: Record<string, unknown>;
+}
+/** A sloped area: the footprint falls linearly from `high` at `axis[0]` to `low` at `axis[1]`, and
+ * stays flat beyond either end — so a footprint longer than its axis keeps level aprons where it
+ * meets the decks it joins. Elevations are absolute metres in the same frame as Floor.elevation, so a
+ * ramp can span floors (a garage ramp, a loading incline, a sloped plaza). Any area object may carry
+ * one; without it an area is flat. The axis always runs downhill: `high` >= `low`. */
+export interface Slope {
+    axis: [Point, Point];
+    high: number;
+    low: number;
+}
+export interface SiteObject {
+    id: string;
+    kind: ObjectKind;
+    floorId: string | null;
+    name: string;
+    position: Point;
+    rotation: number;
+    rings?: Ring[];
+    /** Boundary-driven spaces keep rings and dimensions as a validated, generated cache.
+     * Absent is an independent outline, preserving existing/imported projects without guessing. */
+    geometry?: SpaceGeometry;
+    /** Makes this area a sloped plane rather than a flat plate; see Slope. */
+    slope?: Slope;
+    /** Clear ceiling height above this floor's datum; omitted uses the storey height.
+     * A room spanning storeys uses this with holes in the plates above it. */
+    ceilingHeight?: number;
+    /** A basin below this area's walking surface, filled with clear water. */
+    water?: {
+        depth: number;
+        ripple?: number;
+    };
+    /** Open water-slide centreline, in metres relative to the object's position and rotation.
+     * The third coordinate is height above its floor. */
+    slide?: {
+        path: [number, number, number][];
+        radius: number;
+    };
+    /** Bottom of a raised fixture, metres above the floor surface (e.g. a doorway lintel). */
+    baseHeight?: number;
+    width: number;
+    depth: number;
+    height: number;
+    parentId?: string;
+    barrierId?: string;
+    offset?: number;
+    /** Door hinge at the wall start (left, default) or end (right). */
+    doorHinge?: 'left' | 'right';
+    /** Door mechanism. Omitted means a conventional single hinged leaf. */
+    doorType?: 'hinged' | 'sliding' | 'double';
+    /** Door opens to the left (+1, default) or right (-1) of the directed wall. */
+    doorSwing?: 1 | -1;
+    feedId?: string;
+    symbol?: 'personnel' | 'service' | 'driveway' | 'parking' | 'assembly' | 'info' | 'aed' | 'extinguisher' | 'firstaid' | 'exit' | 'firealarm';
+    servedFloorIds?: string[];
+    /** Stairs only: which geometry this climb has.
+     *
+     *  `straight` is one run. `switchback` turns back on itself around a half-landing — the half-turn
+     *  stair that fits a storey into a short core box, and what most building stairs actually are.
+     *  `dogleg` turns a quarter at its landing, for a stair in the corner of a plan. `spiral` winds
+     *  around a pole and can land on every level it passes. `escalator` is a machine: a fixed 30° pitch
+     *  and a flat comb plate at each end.
+     *
+     *  All of them connect the same floors and route identically, which is why this is one field rather
+     *  than five kinds — the difference is what it looks like and how much run it needs. Absent picks
+     *  the shape that fits: a straight run where the footprint allows a civil pitch, a switchback where
+     *  it does not, since a plan that gives a 4.5 m box to a 4.4 m storey means a stair that turns, not
+     *  a ladder. */
+    stairModel?: 'straight' | 'switchback' | 'dogleg' | 'spiral' | 'escalator';
+    /** Stairs with the same group on a level share one rectangular floor/ceiling opening. */
+    wellGroup?: string;
+    /** Escalators only: which way the machine carries you.
+     *
+     *  It is a property of the machine, not of the drawing and not of its name: an escalator runs one
+     *  way, a bank of them runs alternate ways, and which way this one runs is the first thing anyone
+     *  asks of it. The same vocabulary as `Zone.connects`, so the described layer and the object never
+     *  need translating between them. Absent means up, which is what a lone escalator nearly always
+     *  does. A stair that is not an escalator ignores it — a stair carries you both ways.
+     *
+     *  An imported escalator arrives once per storey it is drawn on; the twin standing lowest is the
+     *  one the model draws and routes from, so that is the one to author. */
+    travel?: 'up' | 'down';
+    /** Elevators only: which faces of the car open, relative to the object's own rotation. A through-car
+     *  opens front and back; a corner lobby car opens front and one side. Absent means the front alone,
+     *  which is what almost every lift does. Which FLOORS it opens on is `servedFloorIds` — a level the
+     *  shaft passes without serving has no doors on any side. */
+    doorSides?: ('front' | 'back' | 'left' | 'right')[];
+    coverageAngle?: number;
+    coverageRange?: number;
+    color?: string;
+    /** Camera: ids of the doors, rooms and elevators this camera observes (event footage lookup). */
+    watchedIds?: string[];
+    material?: MaterialKind;
+    model?: ModelKind;
+    light?: LightFixture;
+    /** A space's own sound, overriding its floor's. See Floor.ambience. */
+    ambience?: Ambience;
+    /** Host-defined subtype/category (e.g. 'meeting-room', 'speedgate', 'cold-store') for styling, filtering and event handlers. */
+    category?: string;
+    /** Arbitrary host metadata; ignored by the core, available to style hooks and event handlers. */
+    metadata?: Record<string, unknown>;
+}
+export interface Drawing {
+    id: string;
+    floorId: string | null;
+    assetId: string;
+    name: string;
+    width: number;
+    height: number;
+    origin: Point;
+    scale: number;
+    rotation: number;
+    opacity: number;
+    visible: boolean;
+    locked: boolean;
+}
+/** A named set of spaces — the area objects listed in `spaceIds`.
+ *
+ *  A zone is a *membership*, not a shape: it has no geometry of its own, which is exactly what lets it
+ *  span floors, skip buildings, and overlap other zones freely. (Contrast `SiteObject.parentId`, which
+ *  is the strict single-parent, same-floor, geometrically-contained tree.) A lift shaft is a zone of
+ *  its per-floor lift spaces; a security area is a zone of the rooms inside it. */
+export interface Zone {
+    id: string;
+    name: string;
+    spaceIds: string[];
+    /** Zones may contain zones: a DAG, not a tree. Cycles are rejected; several parents are fine.
+     *  Membership does NOT imply access inheritance — that is policy, and policy is the host's. */
+    childZoneIds?: string[];
+    /** How the spaces within this zone reach each other, when they are not joined by portals.
+     *  'all'      — every space mutually reachable: a lift serving all of its landings.
+     *  'adjacent' — reachable in elevation order, both ways: a stair, passing each level in turn.
+     *  'up'/'down'— adjacent but one-way: an escalator, which carries you in a single direction.
+     *  omitted    — no implied connectivity; the zone is a grouping only. */
+    connects?: 'all' | 'adjacent' | 'up' | 'down';
+    /** Host vocabulary ('security', 'evacuation', 'hvac', …). The core never interprets it. */
+    purpose?: string;
+    metadata?: Record<string, unknown>;
+}
+/** A traversable connection between exactly two spaces.
+ *
+ *  Direction is deliberately not baked in: a door's entry and exit sides are relative to whichever
+ *  area you are asking about, so the two sides are stored symmetrically and direction is derived
+ *  (see `entryInto`). Applications that attach a rule per direction of travel split a two-way door into
+ *  two objects; that is the right shape for an application layer and the wrong shape for a topology one. */
+export interface Portal {
+    id: string;
+    /** The opening object (door/gate/turnstile) crossed here; absent for a virtual portal — an open
+     *  boundary between two spaces with no physical separator, which malls and open-plan floors need.
+     *  Kept as a reference rather than folded in, so two portals can be known to share one door leaf. */
+    openingId?: string;
+    /** The two sides. Order is storage, not meaning — ask `entryInto` rather than reading it. */
+    a: string;
+    b: string;
+    /** Which way passage is possible at all. Default 'both'. */
+    passage?: 'both' | 'a-to-b' | 'b-to-a' | 'none';
+    /** How far a crossing here can be trusted to have actually happened.
+     *  'confirmed' — a sensor saw it (a door monitor opening and closing).
+     *  'assumed'   — inferred from a grant; nobody watched. The default for a plain door.
+     *  'none'      — the crossing is a *request*, not an event: a lift floor button, where the
+     *                passenger may go anywhere. Anything counting crossings must ignore these. */
+    attests?: 'confirmed' | 'assumed' | 'none';
+    name?: string;
+    metadata?: Record<string, unknown>;
+}
+/** An explicit set of portals, for sets that are not a zone boundary — "all loading-bay shutters",
+ *  "every door with a reader". Where a set *is* a zone boundary, derive it instead: see `perimeter`. */
+export interface PortalGroup {
+    id: string;
+    name: string;
+    portalIds: string[];
+    metadata?: Record<string, unknown>;
+}
+/** Authored route-graph node for indoor navigation. objectId binds it to a SiteObject (door, elevator, stairs, room, poi) so routing can anchor at that object and instructions can name it. */
+export interface NavNode {
+    id: string;
+    floorId: string | null;
+    position: Point;
+    objectId?: string;
+}
+export type NavEdgeKind = 'walk' | 'door' | 'stairs' | 'elevator';
+/** Undirected route-graph edge. walk stays on one floor; door stays on one floor or steps outside (one end floorId null); stairs/elevator join different floors and bind the serving object via objectId. weight overrides the derived metres-equivalent cost. */
+export interface NavEdge {
+    id: string;
+    kind: NavEdgeKind;
+    aId: string;
+    bId: string;
+    /** Passable from `aId` to `bId` only. Escalators and one-way doors; absent means both ways. */
+    directed?: boolean;
+    objectId?: string;
+    weight?: number;
+}
+export interface ProjectDocument {
+    schemaVersion: 1;
+    id: string;
+    name: string;
+    description: string;
+    updatedAt: string;
+    origin: Origin;
+    datum: string;
+    buildings: Building[];
+    floors: Floor[];
+    junctions: Junction[];
+    barriers: Barrier[];
+    virtualBoundaries?: VirtualBoundary[];
+    objects: SiteObject[];
+    drawings: Drawing[];
+    referenceNote?: string;
+    /** The floor a viewer should open on — the document's own front door, so a project that is really
+     *  about its offices does not always land on the street. `null` means the outdoor site; omit it
+     *  entirely to let the viewer pick (ground floor, else the lowest). Hosts can still override per
+     *  session via ViewState.floor / FloorViewer's `floorId`. */
+    initialFloorId?: string | null;
+    /** The spatial ontology layered over the geometry: which spaces group together, and what connects
+     *  to what. Spaces themselves are the ringed area objects in `objects` — nothing is duplicated. */
+    zones?: Zone[];
+    portals?: Portal[];
+    portalGroups?: PortalGroup[];
+    /** Optional authored navigation graph. When absent, the graph is derived from spaces and portals
+     *  (see model/topology.ts) — the plan is then the single source of truth and cannot drift out of
+     *  step with a hand-kept copy of itself. */
+    navNodes?: NavNode[];
+    navEdges?: NavEdge[];
+}
+export interface ProjectSummary {
+    id: string;
+    name: string;
+    updatedAt: string;
+}
+export interface ProjectRepository {
+    list(): Promise<ProjectSummary[]>;
+    load(id: string): Promise<ProjectDocument | null>;
+    save(project: ProjectDocument): Promise<void>;
+    delete(id: string): Promise<void>;
+}
+export interface AssetRepository {
+    get(id: string): Promise<Blob | undefined>;
+    put(id: string, asset: Blob): Promise<void>;
+    delete(id: string): Promise<void>;
+}
+export type Tool = 'select' | 'pan' | 'wall' | 'boundary' | 'partition' | 'fence' | 'zone' | 'room' | 'rectangle' | 'enclose' | 'hole' | 'door' | 'window' | 'gate' | 'turnstile' | 'reader' | 'camera' | 'elevator' | 'stairs' | 'office' | 'container' | 'storage' | 'poi' | 'measure' | 'adopt' | 'split' | 'route' | 'sensor' | 'light' | 'alarm' | 'equipment' | 'evacuation';
+/** A fresh entity id. A bare UUIDv4 (no type prefix) so ids drop straight into a database `uuid`
+ * column and validate there; the entity's type is already given by which collection it lives in. */
+export declare const uid: () => `${string}-${string}-${string}-${string}-${string}`;
+export declare const isArea: (kind: ObjectKind) => boolean;
+export declare const isDevice: (kind: ObjectKind) => boolean;
+export declare const isOpening: (kind: ObjectKind) => kind is "door" | "window" | "gate";
+/** A *space* is somewhere you can stand — the unit the ontology groups and connects. Areas qualify,
+ *  and so do lifts and stairs: the inside of a car is as much a place as the lobby it opens onto, and
+ *  the through-car case depends on being able to say so. */
+export declare const isSpace: (kind: ObjectKind) => boolean;

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

@@ -0,0 +1,38 @@
+import type { ProjectDocument, Ring } from './types';
+/** How far from the site origin a coordinate may sit, in metres. A guard against corrupt data, not a
+ *  modelling limit: no site is 100 km across, but a NaN that became 1e15 through arithmetic would
+ *  otherwise sail through every finite() check and break projection math much later and much worse. */
+export declare const COORD_LIMIT = 100000;
+/** Geometric sanity of an area's rings: a real outer boundary, no self-crossings, holes inside and
+ *  disjoint. Returns an error message or null. */
+export declare function validateRings(rings: Ring[], minEdge?: number, minArea?: number): string | null;
+/** Spatial relationships between entities: ring sanity per object, parent containment without
+ *  cycles, and openings that actually fit the barriers they sit in. */
+export declare function validateRelationships(project: ProjectDocument): string | null;
+/** Semantic validation of the navigation graph — authored or derived; structural checks (ids,
+ *  uniqueness) live in validateProject. Returns an error message or null. */
+export declare function validateNavigation(p: ProjectDocument): string | null;
+/** Parse and validate an unknown value into a ProjectDocument; throws with a reason on any failure.
+ *  Every rule the schema has lives behind this one entry point. */
+export declare function validateProject(value: unknown): ProjectDocument;
+/** Deep-freeze a document in place and return it. Writes to a frozen document throw (modules run in
+ *  strict mode), so an out-of-band mutation — one that dodged `transact` — fails at the assignment
+ *  that would have corrupted the document, not three renders later. */
+export declare function freezeProject(project: ProjectDocument): ProjectDocument;
+export type TransactResult = {
+    ok: true;
+    project: ProjectDocument;
+} | {
+    ok: false;
+    error: string;
+};
+/** Apply a change atomically: work on a clone, run every rule, and only then hand the result back —
+ *  frozen, so nothing can edit it except the next transaction. If the change throws, or the outcome
+ *  breaks any rule, the original is untouched and the reason comes back as `error`; there is no
+ *  state in which a caller holds a partly-applied or invalid document.
+ *
+ *  `updatedAt` is deliberately not stamped here — that belongs to whoever owns persistence and
+ *  history (see commitHistory), which also stamps undo and redo. */
+export declare function transact(project: ProjectDocument, change: (draft: ProjectDocument) => void, options?: {
+    freeze?: boolean;
+}): TransactResult;