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

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;

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

@@ -0,0 +1,145 @@
+import type { Floor, Point, ProjectDocument, Ring, SiteObject } from './types';
+/** True for the kinds that connect levels. */
+export declare const isVertical: (kind: string) => kind is "elevator" | "stairs";
+/** Which shaft this object is part of.
+ *
+ *  A shaft is one thing standing in one place reaching several levels, and that is how the document
+ *  can describe it: one object, one position, one `servedFloorIds`. Older documents — the demo among
+ *  them — instead repeat the object on every storey it serves, because that is what you had to do
+ *  before anything read the served list. Both must draw as one lift, so a shaft is identified by what
+ *  makes it the same shaft: its kind, its name, and where it stands. */
+export declare const shaftKey: (object: SiteObject) => string;
+/** Every level this shaft reaches, lowest first.
+ *
+ *  `servedFloorIds` when it is authored — that is the document's own statement and outranks any
+ *  inference. A shaft that declares nothing serves the floor it stands on and no other: better to
+ *  draw a stair going nowhere, which is visibly wrong and easy to fix, than to invent a connection
+ *  that routing would then happily send someone through. */
+export declare function servedFloors(project: ProjectDocument, object: SiteObject): Floor[];
+/** One climb between two levels the shaft serves. */
+export interface Flight {
+    from: Floor;
+    to: Floor;
+    /** Metres climbed, always positive. */
+    rise: number;
+}
+/** The climbs this shaft makes, bottom first.
+ *
+ *  Consecutive served levels, so a stair serving 0-1-2 makes two flights and a lift serving the same
+ *  three makes two hops of shaft. A level in between that the shaft passes without stopping is simply
+ *  not in the list, and the flight spanning it is the taller for it — which is the right picture: an
+ *  express lift's shaft does pass those floors, and a spiral stair's helix does wind past a mezzanine
+ *  it has no landing on. */
+export declare function flights(project: ProjectDocument, object: SiteObject): Flight[];
+/** Does this shaft reach the given level? Includes the floor it is filed under. */
+export declare const reaches: (project: ProjectDocument, object: SiteObject, floorId: string | null) => boolean;
+/** The flight arriving at a level from below, and the one leaving it upward — what you would see
+ *  standing on that level. Either may be absent at the ends of the run. */
+export declare function flightsAt(project: ProjectDocument, object: SiteObject, floorId: string | null): {
+    up?: Flight;
+    down?: Flight;
+};
+/** How far a shaft's body runs, as absolute elevations: the lowest level it serves to the highest.
+ *  Null when it serves fewer than two levels and so has no body to speak of. */
+export declare function span(project: ProjectDocument, object: SiteObject): {
+    bottom: number;
+    top: number;
+} | null;
+/** The angle a flight of this kind wants to climb at, in degrees from horizontal.
+ *
+ *  An escalator is a machine built to one geometry: 30°, the world over. A stair is free-er but a
+ *  comfortable flight is around 32°, and anything past about 42° is a ladder. These are what the
+ *  plan should be *checked against* — the footprint stays the truth of where the thing is — so a run
+ *  too short for its rise reads as the steep slope it would really be. */
+export declare const PITCH: {
+    readonly escalator: 30;
+    readonly stairs: 32;
+};
+/** The run a flight of this rise needs to climb at its natural pitch. Use it to size a shaft the
+ *  drawing has not sized, and to tell whether one it has sized is plausible. */
+export declare const runFor: (rise: number, pitch?: number) => number;
+/** The pitch a flight actually climbs at, given the run the plan gives it. */
+export declare const pitchOf: (rise: number, run: number) => number;
+/** The deepest tread that is still a tread. Past about a third of a metre a flight stops being a
+ *  stair: the going grows with the box while the rise per step does not, and what you get is a ramp
+ *  with slabs laid on it. A box longer than the climb needs keeps its length — the surplus is
+ *  landing, which is what that spare floor really is. */
+export declare const MAX_GOING = 0.32;
+/** The treads one flight of this rise gets, and how deep each is in a run of this length. Capped
+ *  both ways: a handful of boxes reads as a stair, two hundred reads as a stair and costs a level. */
+export declare function treads(rise: number, run: number): {
+    steps: number;
+    going: number;
+};
+export type StairModel = NonNullable<SiteObject['stairModel']>;
+/** How a shaft is built — as the document says, or as its own footprint implies.
+ *
+ *  A footprint that cannot take the rise at a civil pitch is describing a stair that turns, which is
+ *  what a short wide core box always is. Both the renderer and the plate it cuts its hole in have to
+ *  agree about that, so the reading lives here rather than in either of them. */
+export declare function stairModel(project: ProjectDocument, object: SiteObject): StairModel;
+/** A bank of escalators is stacked criss-cross: every other flight runs the other way, so you step
+ *  off one and turn to step onto the next. Which way round a given flight is decides which end of
+ *  the footprint it arrives at, and so which end of it the floor above has to be open. */
+export declare const flightReversed: (model: StairModel, index: number) => boolean;
+/** Where one flight's sloping part actually lies inside the box the plan drew.
+ *
+ *  The plan gives a footprint; the climb is what has to fit in it. An escalator keeps a metre of flat
+ *  comb plate at each end and then climbs at the machine's own 30°, so a box with run to spare gets a
+ *  longer landing at its foot instead of a shallower ramp — a 1.6 m rise in a 12 m box is a stair with
+ *  a lot of floor round it, not a slide. A stair's treads are capped at MAX_GOING for the same reason.
+ *  A box too short for its rise is left alone: it really is that steep and the picture should say so.
+ *
+ *  `t` runs along the object's depth axis from its centre. The foot of a flight is at +depth/2 and its
+ *  head at -depth/2, which is how the renderer has always laid one out; the surplus goes to whichever
+ *  end that leaves free — the foot of an escalator, whose comb plates must stay at the ends the plan
+ *  drew them at, and the head of a stair, which has none. */
+export interface FlightRun {
+    /** The rotation this flight is drawn at — see flightReversed. */
+    rotation: number;
+    /** A point t metres along the run from the object's centre. */
+    at: (t: number) => Point;
+    /** How long the box is along that axis, and half of it. */
+    length: number;
+    half: number;
+    /** The flat plate at each end of an escalator; zero for a stair. */
+    pad: number;
+    /** The sloping part: how long it is, and where it starts and ends along the run. */
+    incline: number;
+    topT: number;
+    footT: number;
+}
+export declare function flightRun(project: ProjectDocument, object: SiteObject, rise: number, model: StairModel, index?: number): FlightRun;
+/** The one twin that stands for the shaft: the lowest, so the flights count upward from the bottom.
+ *  A shaft described the modern way — one object — is trivially its own primary. */
+export declare function primaryShafts(project: ProjectDocument): Set<string>;
+/** Does something come up through this level's floor? The shaft starts below it and reaches it or
+ *  goes past — so a flight arrives here and the plate it arrives through has to be open.
+ *
+ *  This is one half of what `passesThrough` used to answer for both. Requiring a served level above
+ *  as well meant the flight arriving at the top of a run was drawn under an uncut slab: on Stockmann's
+ *  ninth floor all twelve shafts arrive and not one of them cut a hole, so the last flight of every
+ *  stair in the building was invisible from the storey it lands on. */
+export declare function arrivesAt(project: ProjectDocument, object: SiteObject, floorId: string): boolean;
+/** The other half: does something climb out through this level's ceiling? The shaft stands on this
+ *  level or lower and carries on above it, so the lid a walked storey gets has to be open over it —
+ *  which the bottom of a run needs just as much as the middle of one. */
+export declare function departsFrom(project: ProjectDocument, object: SiteObject, floorId: string): boolean;
+/** Does this shaft pass THROUGH a level — arriving from below and carrying on above? Both halves at
+ *  once, which is the question a level in the middle of a run answers yes to and no end of one does. */
+export declare const passesThrough: (project: ProjectDocument, object: SiteObject, floorId: string) => boolean;
+export interface VoidOptions {
+    /** `floor` (the default) cuts what arrives from below; `ceiling` cuts what departs upward. */
+    through?: 'floor' | 'ceiling';
+    /** Ignore flights that set off below this elevation. An above-ground view draws nothing under
+     *  grade, and a hole with nothing beneath it is worse than no hole at all. */
+    lowest?: number;
+}
+/** What to cut out of a level's floor plate, or out of the lid over a walked storey.
+ *
+ *  A stairwell is a hole. Drawing the slab whole and the stair beneath it puts a lid over the flight,
+ *  so from the landing above you see a plate where the opening should be and the stair appears to
+ *  climb into the ceiling. The hole is only as big as the flight needs, though: a lift or a turning
+ *  core is a shaft and takes its whole footprint, but a straight flight or an escalator lies under
+ *  the floor for most of its length and wants opening only where it comes up — see headroomBand. */
+export declare function shaftVoids(project: ProjectDocument, floorId: string, primary?: Set<string>, options?: VoidOptions): Ring[];

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

@@ -0,0 +1,71 @@
+import type { Point, ProjectDocument, Ring } from './types';
+/** A drag snaps in the geometry's frame. Rounding x/y independently moves an imported wall's
+ * junction off its centreline, even when the pointer follows that centreline exactly. */
+export declare function snapDragPoint(project: ProjectDocument, floorId: string | null, kind: 'junction' | 'barrier' | 'ring', id: string, raw: Point, snapping: boolean, tolerance: number, ringIndex?: number, vertexIndex?: number): Point;
+/** A segment's direction as an *axis* in [0, 180). A wall and the same wall drawn backwards describe
+ *  one line, so 10° and 190° have to compare equal or half of every alignment test misses. */
+export declare const axisOf: (a: Point, b: Point) => number;
+/** The smallest rotation carrying axis `from` onto axis `to`, in (-90, 90]. */
+export declare const axisDelta: (from: number, to: number) => number;
+/** Two directions count as the same when they are within this many degrees. Wide enough to absorb a
+ *  footprint traced by hand or imported from a cadastral outline, narrow enough that a wall set at a
+ *  deliberate angle still reads as its own direction. */
+export declare const ALIGNED = 4;
+/** The rings describing a floor's outline: its own top-level zones when it has them, else the union
+ *  of the rooms drawn on it, else the site's building footprints. Shared with `exteriorWalls` so
+ *  "the outline" means one thing across the app.
+ *
+ *  The room union is what a floor without a zone over it actually has. An imported plan is exactly
+ *  that — rooms traced off a drawing, no covering zone and no site footprint — and skipping straight
+ *  to the building objects returned nothing for it, so not one of its walls counted as exterior:
+ *  no exterior material, no facade preset, and nothing for a stacked view to draw a storey's edge
+ *  from. Cached per document, which is immutable between edits, because the union is not free. */
+export declare function floorOutline(project: ProjectDocument, floorId: string | null): Ring[];
+/** The building's main axis on this floor: the direction its outline predominantly runs, in [0, 180).
+ *  Falls back to the walls already drawn, and finally to 0 — the site grid, which for a project whose
+ *  origin carries a bearing is already the building's street alignment. */
+export declare function mainAxis(project: ProjectDocument, floorId: string | null): number;
+export interface AxisReference {
+    /** Degrees in [0, 180). New walls are held to this and its 15° multiples. */
+    angle: number;
+    source: 'wall' | 'exterior' | 'building';
+}
+/** What a wall drawn near `point` should line up with: whichever wall — interior or the building's own
+ *  exterior — it is being drawn beside, and failing that the building's main axis.
+ *
+ *  Preferring the near edge over the building-wide average is what makes irregular plans workable. A
+ *  wing set askew, or a space with a raked end, has no one true direction; next to the raked end the
+ *  raked end *is* the direction, and squaring to the far-off main axis would look wrong there. Drawn
+ *  walls win ties against the exterior at equal distance, since an interior wall is the more
+ *  deliberate signal. */
+export declare function referenceAxis(project: ProjectDocument, floorId: string | null, point: Point, reach: number): AxisReference;
+export interface WallProposal {
+    segment: [Point, Point];
+    axis: number;
+    reference: AxisReference;
+}
+/** The wall a space looks like it is missing. Hover anywhere inside one: this squares off against the
+ *  wall you are nearest (or the building, in a space that has none yet), runs a line both ways until
+ *  it meets something, and offers the whole span as one click.
+ *
+ *  Null when there is nothing worth offering — no bound on one of the two sides, a span too short to
+ *  be a wall, or a wall already running this way within `clear` metres, which means the space is
+ *  divided here already. */
+export declare function proposeWall(project: ProjectDocument, floorId: string | null, point: Point, clear?: number): WallProposal | null;
+/** Where an opening would land if you placed it here. */
+export interface OpeningFit {
+    barrierId: string;
+    offset: number;
+    position: Point;
+    /** The stretch of wall the leaf would occupy — what to draw so the placement is visible first. */
+    span: [Point, Point];
+}
+/** Fit an opening to the nearest wall (or fence, for a gate).
+ *
+ *  One rule, asked twice: the hover preview and the click that commits must agree, or the preview is
+ *  a lie. Returns null when nothing is close enough, which is what lets the tool say so before the
+ *  click rather than by throwing after it.
+ *
+ *  The offset is clamped so the leaf stays on the wall — a door centred 10 cm from the end of its
+ *  wall would otherwise hang in the air. */
+export declare function fitOpening(project: ProjectDocument, floorId: string | null, kind: 'door' | 'window' | 'gate' | 'turnstile', at: Point, width: number, reach: number, ignoreId?: string): OpeningFit | null;

package/dist/types/schema/index.d.ts

@@ -0,0 +1,25 @@
+export type { ProjectDocument, ProjectSummary, Building, BuildingRoof, RoofSection, Floor, InteriorLight, LightFixture, Junction, VirtualBoundary, BoundaryUse, SpaceGeometry, Barrier, SiteObject, Drawing, Origin, Point, Ring, ObjectKind, Slope, MaterialKind, ModelKind, AssetRepository, NavNode, NavEdge, NavEdgeKind, Zone, Portal, PortalGroup, } from '../model/types';
+export { spaces, spaceAt, spacePoint, inSpace } from '../model/spaces';
+export { entryInto, perimeter, captive, zoneSpaces, addZone, removeZone, setZoneMembers, nestZone, addPortalGroup, removePortalGroup, setPortalGroupMembers, pruneOntology, } from '../model/ontology';
+export { inferPortals, inferOpenBoundaries, refreshPortals, divideSpaces, spacesDividedBy, spacesRejoinedBy, mergeSpaces, } from '../model/inference';
+export { derivedGraph } from '../model/topology';
+export { sharedBoundaryPortals, effectivePortals } from '../model/portals';
+export { isArea, isDevice, isOpening, isSpace, uid, OBJECT_KINDS } from '../model/types';
+export { createObject, emptyProject } from '../model/factory';
+export { enclosedRegion, enclosedRegions, refitEnclosedRooms } from '../model/spaces';
+export { boundaryEdges, boundaryRegions, boundaryRegionAt, boundaryRings, derivedSpaceRings, bindSpaceToRegion, followsBoundaries, connectSpace, disconnectSpace, addVirtualBoundary, drawVirtualBoundary, addBoundaryHole, normalizeBoundaries, refreshBoundarySpaces, } from '../model/boundaries';
+export type { BoundaryEdge, BoundaryRegion } from '../model/boundaries';
+export { coverageOf, DEFAULT_RANGE, DEFAULT_FOV } from '../model/coverage';
+export { copyProject, openingFloorId } from '../model/project';
+export { MIN_SEGMENT, OPENING_MIN_SEGMENT, geoOrigin, moveOrigin, segmentsCross, toLngLat, toLocal, addBarrier, duplicateFloor, removeFloor, rectangle, rotate, centroid, distance, footprint, closeRing, openRing, ringArea, objectArea, pointInRing, objectPosition, objectRotation, barrierEnds, segmentProjection, slopeElevation, } from '../model/geometry';
+export { exportProject, importProject, parseExport, blobDataUrl } from '../model/document';
+export { validateProject, validateRelationships, validateRings, validateNavigation, transact, freezeProject, COORD_LIMIT, } from '../model/validate';
+export type { TransactResult } from '../model/validate';
+export { applyMutation, applyMutations } from '../model/mutations';
+export type { Mutation, MutationOutcome, MutationResult } from '../model/mutations';
+export { findRoute, navNodes, navEdges, HERE, routeSteps, routeAnchors, floorPhrase, addNavNode, addNavEdge, navPath, chainVertical, edgeCost, edgeLength, ELEVATOR_BASE, ELEVATOR_PER_METRE, STAIR_CLIMB_FACTOR, DOOR_COST, NAV_WELD, } from '../model/navigation';
+export type { Route, RouteStep, RouteLeg, RouteOptions, RouteEnd, RoutePlace } from '../model/navigation';
+export { EXTERIOR_PRESETS, type ExteriorPreset } from '../model/materials';
+export { flights, flightsAt, isVertical, passesThrough, PITCH, pitchOf, primaryShafts, reaches, runFor, servedFloors, shaftKey, shaftVoids, span, type Flight, } from '../model/vertical';
+export { buildRoomNavigation } from '../model/roomNavigation';
+export type { RoomAccess, RoomNavigationGraph } from '../model/roomNavigation';