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

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

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/ramps.d.ts

@@ -0,0 +1,7 @@
+import type { ProjectDocument, SiteObject } from './types';
+export declare const rampJoins: (o: SiteObject, elevation: number) => boolean;
+/** Only the end levels in the ramp's building are connected, never a storey it passes through. */
+export declare function rampFloors(project: ProjectDocument, o: SiteObject): {
+    low: import("./types").Floor | undefined;
+    high: import("./types").Floor | undefined;
+};

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/stairGeometry.d.ts

@@ -0,0 +1,27 @@
+import type { Point, Ring, SiteObject } from './types';
+import { type FlightRun, type StairModel } from './vertical';
+export interface StairLane {
+    foot: Point;
+    head: Point;
+    width: number;
+    base: number;
+    rise: number;
+    steps: number;
+}
+export interface StairLanding {
+    ring: Ring;
+    height: number;
+}
+/** One description of the steps and landings, used by both rendering and walking support. */
+export declare function stairGeometry(o: SiteObject, run: FlightRun, rise: number, model: StairModel): {
+    lanes: StairLane[];
+    landings: StairLanding[];
+};
+/** The same wedge treads for the spiral mesh and its walkable support. */
+export declare function spiralGeometry(o: SiteObject, position: Point, rise: number): {
+    inner: number;
+    wedges: {
+        ring: Ring;
+        height: number;
+    }[];
+};

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

@@ -0,0 +1,8 @@
+import type { Point, ProjectDocument, SiteObject } from './types';
+/** The tread/landing centreline shared with physical walking, in travel order. */
+export declare function stairTraversal(project: ProjectDocument, object: SiteObject, from: string, to: string): {
+    points: Point[];
+    up: boolean;
+    escalator: boolean;
+    speed: number;
+} | 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;