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

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

@@ -0,0 +1,103 @@
+import type { InteriorLight, Point } from '../model/types';
+export type { InteriorLight } from '../model/types';
+/** Where the sun stands, seen from a place on the earth at a moment. */
+export interface SolarPosition {
+    /** Degrees above the horizon. Negative once the sun has set. */
+    altitude: number;
+    /** Degrees clockwise from due north: 90 is east, 180 south, 270 west. */
+    azimuth: number;
+}
+/** The sun's position over `lngLat` at `when`.
+ *
+ *  The NOAA low-precision formulae: good to about a hundredth of a degree over a century either
+ *  side of 2000, which is several orders of magnitude better than a picture of a building needs and
+ *  costs a few lines of arithmetic. Time is read in UTC, so no timezone table is involved — the
+ *  earth's rotation is the clock, and a longitude is a time of day.
+ *
+ *  Atmospheric refraction is left out. It lifts a sun on the horizon by about half a degree, which
+ *  matters to an almanac and not to which way a shadow falls. */
+export declare function solarPosition(lngLat: Point, when?: Date | number): SolarPosition;
+/** How the scene is lit at a moment: where the sun is, and whether it is low enough that the model
+ *  should wear its dusk treatment. */
+export interface Sun extends SolarPosition {
+    /** Dusk: lamps on, warm low light, dark sky. True below civil twilight. */
+    evening: boolean;
+}
+/** Civil twilight. Below this the sky is no longer doing the lighting and the lamps are what you
+ *  see by — which at 60°N in June the sun only just reaches, for an hour either side of midnight,
+ *  and that is the honest picture of a white night. */
+export declare const CIVIL_TWILIGHT = -6;
+/** The sun over a project's origin at a moment, ready to light a scene with. */
+export declare function sunAt(lngLat: Point, when?: Date | number): Sun;
+/** A sun pinned to a look rather than to a clock, for the manual override and for tests. Afternoon
+ *  and dusk, at the angles the two fixed lightings used before this file knew where the sun was. */
+export declare const FIXED: Record<'day' | 'evening', Sun>;
+/** Mix two hex colours. Exported so the basemap's sky can follow the same sun the model does
+ *  rather than snapping between a day palette and a night one. */
+export declare const mixColor: (a: string, b: string, t: number) => string;
+/** Scene axes are east, north, up. Both renderers use this world-anchored sun. */
+export declare const sunlight: (sun: Sun) => {
+    position: [number, number, number];
+    color: string;
+    intensity: number;
+    mapPosition: [number, number, number];
+};
+/** The artificial light a level burns.
+ *
+ *  A building is not lit by the sky. Offices, shop floors, garages and platforms run their own
+ *  lighting through the working day and often through the night, and what colour that light is says
+ *  as much about a space as its plan does: a 4000 K fluorescent office, a 2700 K hotel corridor and
+ *  a 5000 K operating theatre are three different rooms before anything is drawn in them. So it is
+ *  a property of the floor, authored like its name and its height, rather than a render setting. */
+/** The lamps a floor is likely to be fitted with, warmest first. Fluorescent is the default because
+ *  it is what is actually overhead in most of the buildings anyone draws: offices, shops, schools,
+ *  hospitals, car parks. */
+export declare const LAMPS: {
+    id: string;
+    label: string;
+    kelvin: number;
+}[];
+/** What a floor is lit by when it does not say: a fluorescent ceiling, fully on. Most floors are
+ *  fully lit; dimming is the thing worth authoring. */
+export declare const DEFAULT_LIGHT: InteriorLight;
+/** The nearest named lamp to a colour temperature, for showing an authored number as a choice. */
+export declare const lampFor: (kelvin: number) => {
+    id: string;
+    label: string;
+    kelvin: number;
+};
+/** A colour temperature as a light colour: relative to the adapted white above, and held at one
+ *  brightness so that changing the temperature changes the TINT and nothing else. How bright a floor
+ *  is lit is the level's job, and the two must not fight each other. */
+export declare function kelvinColor(kelvin: number): string;
+/** Everything in the picture that is not the sun.
+ *
+ *  Two contributions, and they are different in kind. The SKY is daylight bouncing off the ground
+ *  and the air, so it follows the sun down and goes out with it. The INTERIOR is the building's own
+ *  lighting, and that does not follow anything: a shop floor is lit at four in the afternoon and at
+ *  four in the morning, which is why a cutaway of a storey at midnight is legible rather than black.
+ *  Kerros draws buildings from the inside, so this is most of what you are looking at. */
+export declare function ambient(sun: Sun, light?: InteriorLight): {
+    /** Hemisphere sky and ground colours, and its strength: the outdoor half. */
+    sky: string;
+    ground: string;
+    hemisphere: number;
+    /** The image-based environment, for specular life on glass and metal. */
+    environment: number;
+    /** The building's own lights: colour and strength, both from the floor, neither following the
+     *  sun. A level that says nothing is lit by a fluorescent ceiling, because most levels are.
+     *
+     *  A ceiling, which is to say it comes from ABOVE. Drawn as light arriving equally from every
+     *  direction it lit the underside of a landing as brightly as the floor under it, and to get a
+     *  floor bright enough it had to be turned up until the walls glowed — so the floor takes the
+     *  full value and a wall about half of it, which is what a room of downlights actually does. */
+    interior: string;
+    /** What comes back UP off the floor: the same lamps, much weaker, which is the half of the
+     *  picture that keeps a soffit from going black. */
+    interiorBounce: string;
+    interiorLevel: number;
+    /** How far along the fade to night the scene is: 1 in full day, 0 after civil twilight. */
+    day: number;
+    /** What the sky alone puts on a level surface, before the ceiling makes up the difference. */
+    daylight: number;
+};

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

@@ -0,0 +1,4 @@
+import type { StyleSpecification } from 'maplibre-gl';
+import type { BasemapConfig } from '../model/host';
+/** Fetch the external style without replacing the working, locally rendered plan. */
+export declare function loadBasemap(config: BasemapConfig, signal: AbortSignal): Promise<StyleSpecification>;

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

@@ -0,0 +1,38 @@
+import * as THREE from 'three';
+import { type SurfaceFinish } from './textures';
+/** Small deterministic, metre-scaled textures keep exported projects independent of CDNs. */
+export declare class MaterialLibrary {
+    private materials;
+    private textures;
+    solid(color: string, roughness?: number): THREE.MeshStandardMaterial;
+    /** The active storey's own plate, when the stack has storeys under it. Opaque enough to read as
+     *  the floor you are standing on, sheer enough that the levels beneath show through it — without
+     *  this the plate is a lid and "All floors" shows one. depthWrite stays on: the plate must still
+     *  occlude its own walls' hidden faces, and the ghosts below carry depthWrite off already, so they
+     *  blend rather than fight it. */
+    plate(color: string, roughness?: number): THREE.MeshStandardMaterial;
+    /** A lit ceiling. Its underside faces down, so every light in the scene misses it and a plain
+     *  material renders it as the darkest thing in the room — which is the opposite of what a ceiling
+     *  full of fittings looks like from beneath. Emissive is the honest fix: the ceiling is not lit,
+     *  it is the thing doing the lighting, and `tint` is whatever the floor's lamps are. */
+    luminous(color: string, tint: string, strength: number, finish?: SurfaceFinish): THREE.MeshStandardMaterial;
+    /** A polished twin of a finish, for the floor you are standing on in walk mode. Seen from above a
+     *  floor is a flat patch of its own colour and matte is right; seen along at eye level it is the
+     *  one surface in the room that shows you where the light is, because a grazing angle is where
+     *  reflectance lives. The roughness map still multiplies through, so the polish keeps the finish's
+     *  own variation instead of turning the plate into a mirror. */
+    polished(base: THREE.MeshStandardMaterial, roughness?: number): THREE.MeshStandardMaterial;
+    /** A vertex-coloured twin of an existing material, so geometry can carry baked shading without
+     *  doubling the palette. Cached per source material: everything drawn with the twin must supply a
+     *  colour attribute, since a merge needs matching attributes across all its geometries. */
+    shaded(base: THREE.MeshStandardMaterial): THREE.MeshStandardMaterial;
+    /** Translucent variant for de-emphasised floors in the stacked view. */
+    ghost(color: string, opacity?: number): THREE.MeshStandardMaterial;
+    private finishes;
+    get(kind: SurfaceFinish, color: string): THREE.MeshStandardMaterial;
+    glass(evening?: boolean, lit?: boolean): THREE.MeshStandardMaterial;
+    metal(color?: string): THREE.MeshStandardMaterial;
+    /** One image per step; the UVs follow the machine's run, including rotated/reversed flights. */
+    escalator(): THREE.MeshStandardMaterial;
+    dispose(): void;
+}

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

@@ -0,0 +1,11 @@
+import type { ProjectDocument, SiteObject } from '../model/types';
+export interface PoolBounce {
+    room: SiteObject;
+    pool?: SiteObject;
+    strength: number;
+    height: number;
+}
+/** A diffuse approximation for white tiled rooms. Pool chambers receive the submerged fixtures;
+ * connecting chambers receive a weaker bounce through open portals. No light crosses a sealed
+ * wall, and switching off the source removes its reflected light as well. */
+export declare function poolBounces(project: ProjectDocument, floorId: string): PoolBounce[];

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

@@ -0,0 +1,9 @@
+import type { Box3, Camera, Matrix4 } from 'three';
+/** Split the map's combined matrix so PBR shading sees the same eye as projection and picking.
+ * Keeping the camera axes in world space avoids decomposing Mercator's reflected Y axis. */
+export declare function syncLightingCamera(camera: Camera, worldToClip: Matrix4, clipToWorld: Matrix4): void;
+/** Extend a Mercator scene's far plane without changing its screen position or near plane. */
+export declare function includeSceneDepth(matrix: Matrix4, bounds: Box3, scaleZ: number, near: number, far: number): void;
+/** MapLibre's near distance follows viewport pixels and can cut away a wall before the walker
+ * touches it. Give POV a 4 cm near plane in scene metres, preserving the eye, X/Y and far plane. */
+export declare function walkNearPlane(matrix: Matrix4, near: number, far: number): number;

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

@@ -0,0 +1,8 @@
+import type { ProjectDocument, Ring, Slope } from '../model/types';
+/** Clip in the slope's local frame. Clipping, rather than moving existing corner vertices, inserts
+ * the break lines where an incline meets its flat aprons, including concave outlines and holes. */
+export declare function rampBand(rings: Ring[], slope: Slope, from: number, to: number): Ring[][];
+export declare const rampSections: (rings: Ring[], slope: Slope) => Ring[][];
+/** A descending ramp replaces the upper floor. The ceiling below also needs an opening wherever
+ * the ramp comes within head height. Arrival aprons stay supported by their lower deck. */
+export declare function rampVoids(project: ProjectDocument, floorId: string, through?: 'floor' | 'ceiling'): Ring[];

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

@@ -0,0 +1,59 @@
+import type { FeatureCollection } from 'geojson';
+import type { Origin, Point, ProjectDocument } from '../model/types';
+import type { Route } from '../model/navigation';
+/** The route's own colours. A wayfinding line is not a plan colour — it is a thing laid ON the plan
+ *  for someone to follow, so it wants to be the one saturated element in a scene of pale rooms, and
+ *  it wants a white edge so it reads over a dark floor as well as a light one. Green because green
+ *  is what "this way" looks like on every floor of every building anyone has walked through. */
+export declare const ROUTE_COLOR = "#16a34a";
+/** Steps either side of the one being walked: the same green, not a different colour — the path is
+ *  one path, and only emphasis separates the part you are on from the rest of it. */
+export declare const ROUTE_SOFT = "#6fc98d";
+export declare const ROUTE_EDGE = "#ffffff";
+/** Step index owning each traversal leg, in leg order. Every walk/door/vertical step carries
+ * nodeIds for the nodes it visits (one more than its legs); depart/arrive own no legs. */
+export declare function legStepIndices(route: Route): number[];
+/** GeoJSON for the 2D route layers. Walk/door legs chain into per-step polylines (so dashes and
+ * chevrons flow continuously); vertical legs become Point features at the shaft. Every feature
+ * carries { step, active, onFloor, vertical, dir }. Outdoor legs count as on-floor everywhere,
+ * mirroring visibleOnFloor — the outdoor tail of an egress route must stay readable. */
+export declare function routeFeatures(project: ProjectDocument, route: Route, floorId: string | null, activeStep: number | null): FeatureCollection;
+/** The route as something to be walked: its contiguous same-floor stretches, in travel order, in
+ *  plan metres. A flight is a break rather than a stretch — you do not walk up a lift shaft — so each
+ *  run ends where the route leaves the floor, and the floor it ends on is the one to switch to.
+ *
+ *  This is the same decomposition the flow features use, kept apart from GeoJSON because walking a
+ *  route wants plan coordinates and a map layer wants degrees. */
+export declare function routeWalks(route: Route): {
+    floorId: string | null;
+    points: Point[];
+}[];
+/** A band of light travelling along the path, as a line-gradient over `line-progress`.
+ *
+ *  Built from stops at fixed, strictly ascending positions with the band expressed as an alpha
+ *  falling off either side of `phase` — rather than by moving the stops, which is the obvious way
+ *  and the wrong one: a moving window has to be clamped as it wraps past 0 and 1, and interpolate
+ *  refuses stops that are not strictly ascending. This way there is nothing to clamp. */
+export declare function routeFlowGradient(phase: number, color?: string, stops?: number): unknown[];
+/** 32×32 chevron sprite for the symbol-placement:'line' arrow layer (points +x; MapLibre rotates it
+ * along the travel direction). White on a halo of the path's own colour: the arrow sits ON the green
+ * track, so it has to be the light thing, and the halo is what keeps it legible where the track
+ * passes over a pale floor. Drawn on a canvas — no glyphs, no external assets. */
+export declare function routeArrowImage(color?: string): ImageData;
+/** The track's repeating tile, for the 3D ribbon: a green band with white edges and a white chevron
+ *  pointing along it, drawn once and tiled every `TRACK_TILE` metres of path.
+ *
+ *  One texture answers all of it. The ribbon is a constant width, so the tile's top and bottom edges
+ *  ARE the track's edges — mitres and corners included, which is the part a separate outline geometry
+ *  gets wrong. The chevron rides in the same tile, so the arrows are spaced in metres of walking
+ *  rather than in pixels of screen. And scrolling the tile along the path is the animation: the
+ *  arrows march towards the destination instead of sitting still and merely pointing at it. */
+export declare const TRACK_TILE = 2.6;
+/** The tile's own size in pixels, described in one place. Powers of two so it can carry mipmaps:
+ *  at eye level most of the track is seen at a grazing angle, and that is exactly where an
+ *  unmipmapped texture turns its chevrons into glitter. */
+export declare const TRACK_PIXELS: [number, number];
+export declare function routeTrackImage(color?: string, active?: boolean): ImageData;
+/** Heading in degrees from true north between two local points, computed in geographic space so a
+ * rotated Origin yields the bearing the map camera actually needs. */
+export declare function pathHeading(a: Point, b: Point, origin: Origin): number;

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

@@ -0,0 +1,29 @@
+import type { Point, ProjectDocument, Ring } from '../model/types';
+import type { StatusReading } from '../model/live';
+export interface StairSurface {
+    flightId: string;
+    fromFloor: string;
+    toFloor: string;
+    low: number;
+    high: number;
+    ring: Ring;
+    holes?: Ring[];
+    height(at: Point): number;
+    drive?: Point;
+    rail?: true;
+}
+/** Build once per document/status/floor change, not once per walking frame. Heights are absolute
+ * floor elevations so switching the scene's floor datum cannot change the passenger's support. */
+export declare function stairSurfaces(project: ProjectDocument, statuses?: Map<string, StatusReading>): StairSurface[];
+/** Continuous walking support on the shared flights. The ramp envelope smooths the small tread
+ * risers; high side entries are solid, and leaving a flight sideways cannot step into mid-air. */
+export declare class StairWalker {
+    height: number;
+    active?: StairSurface;
+    pending?: string;
+    private floor;
+    sync(floor: string | null, elevation: number): void;
+    refresh(surfaces: StairSurface[], at: Point): void;
+    reset(elevation: number): void;
+    step(from: Point, to: Point, surfaces: StairSurface[], floor: string | null, elevation: number, supports?: (at: Point, floorId: string | null) => boolean): Point;
+}

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

@@ -0,0 +1,36 @@
+import * as THREE from 'three';
+/** The scene renders on two layers. Everything is on OUTSIDE-or-INSIDE: the sun and the sky light
+ *  both, but the building's own ceiling lighting is on INSIDE alone, so turning the lamps up to read
+ *  a shop floor does not also floodlight the pavement at midnight. */
+export declare const INSIDE = 0, OUTSIDE = 1;
+/** Batch static surfaces by material, retaining triangle ownership for picking/highlights. */
+export declare class SurfaceBatch {
+    private pending;
+    private meshes;
+    /** Side of the square cells the batch is cut into, in scene metres; 0 batches a whole material
+     *  into one mesh. Looking down on a floor from above, every part of it is in the frame and one
+     *  mesh per material is the cheapest way to draw it. Standing on it, most of it is behind you or
+     *  round a corner, and a lamp's shadow reaches twelve metres — but a mesh is culled whole or not
+     *  at all, and one floor-sized mesh is never culled. Cut into cells, the frustum and every
+     *  shadow pass keep only the cells they can see. */
+    chunk: number;
+    /** `outdoor` puts the surface on the OUTSIDE layer, out of reach of the interior lighting. It is
+     *  part of the bucket key as well as a property of the mesh: two surfaces that share a material
+     *  but not a side of the wall cannot be merged into one mesh, because a mesh sits on one layer. */
+    add(geometry: THREE.BufferGeometry, material: THREE.Material, id: string, outdoor?: boolean): void;
+    /** Fold a built object tree (a furniture group, a roof) into the batch, baking each mesh's world
+     *  transform into its geometry. makeFixture emits one mesh per box, so a demo with a few hundred
+     *  cars and columns was contributing thousands of draw calls and as many buffer uploads; merged by
+     *  material they cost a handful. Instanced children are left alone — they are already batched. */
+    addObject(root: THREE.Object3D, id: string, outdoor?: boolean): THREE.Object3D<THREE.Object3DEventMap>[];
+    finish(scene: THREE.Scene): void;
+    outline(id: string, color: string): THREE.LineSegments | null;
+    clear(): void;
+}
+export declare function hitEntity(hit: THREE.Intersection): string | null;
+/** Use distances along each face, not a world-axis projection that squashes diagonal façades. */
+export declare function metricUVs(geometry: THREE.BufferGeometry, horizontalAxis?: readonly [number, number]): void;
+/** Transfer an extrusion's vertical face to a separate material, without overlapping triangles.
+ * The supplied edge is in scene coordinates. Caps and the other sides remain in `geometry`.
+ * ExtrudeGeometry is non-indexed; retaining indices here preserves its UVs and contact shading. */
+export declare function splitWallFace(geometry: THREE.BufferGeometry, edge: [[number, number], [number, number]]): THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap> | null;

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

@@ -0,0 +1,8 @@
+import * as THREE from 'three';
+import type { MaterialKind } from '../model/types';
+/** `roof` and `ceiling` are finishes with no authorable material behind them: nobody writes "this
+ *  wall is made of roof". They exist because the renderer draws two surfaces the document never
+ *  names — the cap over a building, and the soffit walk mode puts over the storey you are in. */
+export type SurfaceFinish = MaterialKind | 'roof' | 'ceiling' | 'veneer';
+/** Separate colour, relief and roughness maps: a dark stain must not become a dent in the wall. */
+export declare function surfaceTextures(kind: SurfaceFinish): THREE.CanvasTexture[];

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

@@ -0,0 +1,30 @@
+import type { Floor, ProjectDocument, SiteObject } from '../model/types';
+export declare const DEPTH_CAP = 96;
+export declare const MAX_CAGE_LEVELS = 32;
+/** The camera, model, overlays and depth label must use the same presentation transform. */
+export declare function undergroundView(project: ProjectDocument, floorId: string | null, stack: boolean): {
+    active: Floor | undefined;
+    levels: Floor[];
+    buried: boolean;
+    depthScale: number;
+    elevation: (z: number) => number;
+    focusElevation: number;
+    compressed: boolean;
+};
+export type UndergroundView = ReturnType<typeof undergroundView>;
+interface FloorIndex {
+    floors: Map<string, Floor>;
+    objects: Map<string | null, SiteObject[]>;
+    outlines: Map<string, SiteObject>;
+    /** Ids of the objects that stand for their shaft — see primaryShafts. Anything vertical NOT in
+     *  here is a twin of one that is, and is left to it to draw. */
+    primary: Set<string>;
+    /** Shafts that reach a floor without being filed under it. A stair lives on one storey and climbs
+     *  to another, and the storey it arrives at has to draw it or the flight appears to come from
+     *  nowhere — which is exactly what it did. Kept apart from `objects` so that everything already
+     *  counting a floor's own objects keeps counting the same ones. */
+    reaching: Map<string, SiteObject[]>;
+}
+/** Project documents are immutable between edits. Floor navigation reuses this index. */
+export declare function floorIndex(project: ProjectDocument): FloorIndex;
+export {};

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

@@ -0,0 +1,232 @@
+import type { Map as GLMap } from 'maplibre-gl';
+import type { Origin, Point, Ring } from '../model/types';
+import { type StairSurface } from './stairSurfaces';
+/** Eye above the slab it stands on. A constant, not the floor's height: a mezzanine and a hall are
+ *  different rooms but the same visitor. */
+export { EYE, BODY, HEAD_ROOM } from './walkDimensions';
+/** Shoulder radius. Generous enough that you do not clip a corner, tight enough for a 0.9 m door. */
+/** Faster than anyone walks a corridor, because on a screen the corridor is the size of a hand and
+ *  a literal 1.4 m/s reads as wading. Games settle around 3–4 m/s for the same reason. */
+export declare const WALK_SPEED = 3;
+export declare const RUN_SPEED = 6;
+/** Following a route on its own. A touch over walking pace, because nobody watches a demonstration
+ *  dawdle, and short of the run — a tour is for looking about you, and at eye level 6 m/s is a
+ *  sprint. */
+export declare const TOUR_SPEED = 3.5;
+/** How fast the head can swing while a route is driving. A corner taken at the full rate still
+ *  reads as a turn rather than as a cut, and anything quicker is the sharp turn this replaced. */
+export declare const TURN_RATE = 120;
+/** How far up the path to look while following it. Aiming at a point ahead rather than at the
+ *  segment you are on is what makes the camera begin its turn before the corner instead of at it —
+ *  it is also what a person does, which is why it looks right. */
+export declare const LOOK_AHEAD = 2.6;
+/** Pitch is MapLibre's: 0 looks straight down at the ground, 90 is level with it. The head can drop
+ *  to 55° below level — enough to read a floor marking at your feet — and rise to a degree short of
+ *  level. Not level itself: at 90° the point the map looks at leaves the ground, and MapLibre then
+ *  has to invent a target in the sky, which pulls its zoom (and every zoom-gated layer) down to
+ *  what a satellite would use. At 89° the target is a hundred-odd metres up the corridor, the
+ *  horizon is a degree above the middle of the frame, and nothing has to be invented. */
+export declare const MIN_PITCH = 35, MAX_PITCH = 89;
+/** Where the head rests: a few degrees below level, so the near floor is in frame and walking reads
+ *  as walking, with room to look up from. */
+export declare const REST_PITCH = 86;
+/** The plan camera's zoom ceiling, and the one the walk raises it to while it has the map. MapLibre
+ *  puts its camera at the eye by choosing a zoom for the ground point the eye looks at, and jumpTo
+ *  clamps that zoom to the ceiling without a word — a ceiling the solve can hit is a ceiling that
+ *  silently lifts the eye off the floor. A 2 m eye looking 55° down on a 4K display at the equator
+ *  needs 26.6, so the walk's ceiling is 28. Kept here so MapCanvas and the solve agree. */
+export declare const MAX_MAP_ZOOM = 26, WALK_ZOOM = 28;
+/** The most device pixels per CSS pixel the walk will draw. A retina display asks for two, which
+ *  is four times the pixels of one, and at eye level every one of them is lit by the sun, the sky
+ *  and four lamps with shadows: a dense floor measured at 11 frames a second at two and 35 at one.
+ *  A plan is read; a walk is watched, and a watched picture has to move. 1.25 keeps most of the
+ *  crispness of a retina display for a third of its cost. */
+export declare const WALK_PIXEL_RATIO = 1.25;
+/** Horizontal field of view in degrees. Kept stable when side panels resize the viewport. */
+export declare const DEFAULT_WALK_FOV = 100, MIN_WALK_FOV = 60, MAX_WALK_FOV = 120;
+export declare function walkFieldOfView(value: number): number;
+/** MapLibre takes a vertical angle; tan(h/2) = aspect · tan(v/2). */
+export declare function verticalFieldOfView(horizontal: number, aspect: number): number;
+/** Degrees the view turns per pixel while dragging to look around. */
+export declare const DRAG_LOOK = 0.22;
+export declare const TURN_SPEED = 120;
+/** Where the walker is, kept apart from the camera: the camera is whatever mode you are in, the
+ *  avatar is the person, and they persist across leaving the walk and coming back to it. */
+export interface WalkAvatar {
+    floorId: string | null;
+    /** Plan metres. */
+    position: Point;
+    /** Clockwise from plan +Y, as WalkPose.heading. */
+    heading: number;
+    pitch?: number;
+}
+export interface WalkPose {
+    /** Where the walker stands, in plan metres. */
+    position: Point;
+    /** Clockwise from plan +Y, matching the plan's own grid rather than the compass. */
+    heading: number;
+    pitch: number;
+    /** True while the mouse is held down and dragged to aim the view. */
+    looking: boolean;
+}
+/** Push a walker of radius `r` out of every wall it overlaps.
+ *
+ *  Resolving each wall independently and in sequence is what produces sliding for free: walking into
+ *  a wall at an angle leaves the along-wall component of the move untouched and cancels only the
+ *  component that would have gone through it. Two passes settle inside corners, where pushing out of
+ *  one wall can push you into its neighbour. */
+export declare function unstick(p: Point, walls: Ring[], r?: number): Point;
+/** The MapLibre camera that stands at `eye`, `alt` metres up, facing `bearing` and tilted `pitch`:
+ *  the ground point it looks at and the zoom that puts it that far away.
+ *
+ *  This is MapLibre's calculateCenterFromCameraLngLatAlt() for a camera that looks at the ground —
+ *  the ray from the eye meets the ground alt/cos(pitch) away, and the zoom is the one at which that
+ *  distance fills cameraToCenterDistance pixels. MapLibre's own copy gives up within six degrees of
+ *  level and invents a target ten kilometres off instead, which is fine for a plane and is a 700 m
+ *  eye for a person; this one holds to the ground right up to MAX_PITCH. The mercator scale is
+ *  taken at the target rather than the eye, iterated, because a metre is a different fraction of
+ *  the world at each latitude and the target is the point the zoom is measured at. */
+export declare function eyeCamera(view: {
+    cameraToCenterDistance: number;
+    tileSize: number;
+}, eye: [number, number], alt: number, bearing: number, pitch: number): {
+    center: [number, number];
+    zoom: number;
+};
+/** What a mouse movement does to where you are looking. Right turns you right; up looks up — which
+ *  in MapLibre's terms is a LARGER pitch, 90 being level and 0 the floor. The head stops at the
+ *  limits rather than wrapping: nobody looks at the ceiling by looking too far at their feet. */
+export declare function aim(heading: number, pitch: number, dx: number, dy: number, perPixel?: number): {
+    heading: number;
+    pitch: number;
+};
+/** One frame of walking: what the held keys do to a heading and a position over `dt` seconds.
+ *
+ *  Pulled out of the controller because it is the part with an opinion in it — which key turns you
+ *  and which key carries you — and that opinion is worth stating somewhere a test can read it.
+ *  Returns the new heading and the step to take, in plan metres, before any wall gets a say. */
+export declare function stride(keys: ReadonlySet<string>, heading: number, dt: number): {
+    heading: number;
+    step?: Point;
+};
+/** Where you are after walking `travelled` metres along a polyline, and which way the path is
+ *  heading `ahead` metres further on. Clamped at both ends, and `done` once the path runs out. */
+export declare function alongPath(points: Point[], travelled: number, ahead?: number): {
+    at: Point;
+    heading: number;
+    done: boolean;
+    left: number;
+};
+/** Turn `from` towards `to` by at most `step` degrees, the short way round. */
+export declare function easeHeading(from: number, to: number, step: number): number;
+export interface WalkTerrain {
+    /** Solid wall bodies on the floor being walked, in plan metres. */
+    walls: Ring[];
+    /** Eye height above the presented ground plane: EYE plus whatever lifts the slab. */
+    eye: number;
+    floorId?: string | null;
+    elevation?: number;
+    stairs?: StairSurface[];
+    /** Whether a storey's slab supports the point, or an intentional drop has a landing below. */
+    supports?: (at: Point, floorId: string | null) => boolean;
+    dropAt?: (at: Point) => {
+        floorId: string;
+        distance: number;
+    } | undefined;
+}
+export interface WalkCallbacks {
+    /** Rebase at a stair landing, or before descending below the active scene's datum. */
+    onFloor?(floorId: string): void;
+    /** A real opening has a landing below. Rebase the scene onto that floor before animating descent. */
+    onDrop?(floorId: string): void;
+    /** Fired when the position, heading, pitch or look gesture changes. */
+    onPose(pose: WalkPose): void;
+    /** The walker asked to change level (F, or Shift+F for down). The host decides whether there is
+     *  anywhere to go from where they are standing. */
+    onUse(down: boolean): void;
+    /** Escape: the host leaves walk mode. */
+    onExit(): void;
+    /** M: the walker wants the sound on or off. */
+    onSound?(): void;
+}
+/** The keys, by physical position rather than by letter so the layout survives a French or a Dvorak
+ *  keyboard. W and S walk, A and D turn — the way Doom bound the arrows, and what a person
+ *  walking a floor plan reaches for: the point of A is to look down the other corridor, not to
+ *  sidle towards it. Q and E sidestep for whoever wants it, the arrows mirror the letters, and Shift
+ *  runs. */
+export declare const KEYS: Record<string, string>;
+export declare class WalkController {
+    private readonly on;
+    private map?;
+    private origin;
+    private terrain;
+    private keys;
+    private frame;
+    private last;
+    private handlers;
+    private maxPitch;
+    private maxZoom;
+    private pixelRatio;
+    private planFov;
+    private fieldOfView;
+    private running;
+    private dragPointer;
+    private drag;
+    private path;
+    private travelled;
+    private arrive?;
+    private followOptions?;
+    private fall?;
+    private stairs;
+    position: Point;
+    heading: number;
+    pitch: number;
+    constructor(on: WalkCallbacks);
+    attach(map: GLMap, origin: Origin, start: {
+        position: Point;
+        heading: number;
+        pitch?: number;
+    }): void;
+    detach(): void;
+    /** The floor under the walker changed, or its walls were edited. */
+    setTerrain(terrain: WalkTerrain): void;
+    /** Widen the lens without changing the person's position, heading or eye height. */
+    setFieldOfView(value: number): void;
+    private resize;
+    /** Walk a path on its own, as far as it goes on this floor, then call `onArrive`. Taking any
+     *  control cancels it: a tour you cannot interrupt is a video. */
+    follow(points: Point[], onArrive: () => void, options?: {
+        speed?: number;
+        physical?: boolean;
+        onCancel?: () => void;
+    }): void;
+    cancelFollow(notify?: boolean): void;
+    get following(): boolean;
+    /** Put the walker somewhere — arriving at a new floor, or jumping to a route's start. */
+    place(position: Point, heading?: number): void;
+    /** Inspect something from the current position. Only the walker writes a POV camera: panning
+     *  its ground target like a plan camera would move the eye far behind the selected object. */
+    lookAt(point: Point): void;
+    get pose(): WalkPose;
+    get onStairs(): boolean;
+    /** Drag to look. Capture only delivers the remainder of this gesture if it leaves the canvas;
+     *  the cursor stays visible and is free to operate panels as soon as the button is released. */
+    private grab;
+    private drop;
+    private endDrag;
+    private release;
+    private look;
+    private down;
+    private up;
+    private tick;
+    /** Stop at the first substep entering a hole, even when running over a narrow opening. */
+    private beginFall;
+    /** One frame of being carried along a route. The heading is rate-limited towards a point further
+     *  up the path rather than snapped to the segment underfoot, which is what turns a corner into a
+     *  turn instead of a cut. */
+    private advance;
+    /** One camera write per frame. The eye is where the walker stands, `terrain.eye` metres up, facing
+     *  `heading` and tilted `pitch`; eyeCamera() turns that into the ground point the camera looks at
+     *  and how far away it is, which is all a MapLibre camera can be told. */
+    private apply;
+}

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

@@ -0,0 +1,11 @@
+import type { Floor, ProjectDocument, Ring } from '../model/types';
+/** Build the structural surroundings of both landings before a passenger starts climbing.
+ * The selected floor remains the walking datum; these levels only supply visible context. */
+export declare function walkConnectionContext(project: ProjectDocument, active: Floor, primary?: Set<string>): Floor[];
+/** Structural storeys seen through an authored atrium. Stops at a plate that closes the opening;
+ * room fit-out is deliberately left on its own floor. A room nested in a zone adds no new void. */
+export declare function walkVoidContext(project: ProjectDocument, active: Floor, ceilingFloor: Floor): {
+    levels: Floor[];
+    roof: Floor | undefined;
+    ceilingOpenings: Ring[];
+};

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

@@ -0,0 +1,5 @@
+/** Eye height and shoulder radius in scene metres. Shared by stair rails and planar collision. */
+export declare const EYE = 1.7;
+export declare const BODY = 0.28;
+/** Walls starting above this band are lintels the walker can pass beneath. */
+export declare const HEAD_ROOM = 1.25;

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

@@ -0,0 +1,33 @@
+import type { ElevatorControls } from '../model/host';
+import type { StatusReading } from '../model/live';
+import type { Route } from '../model/navigation';
+import type { Point, ProjectDocument } from '../model/types';
+export interface WalkJourneyHost {
+    project: ProjectDocument;
+    floor(): string | null;
+    changeFloor(id: string | null): Promise<void>;
+    position(): Point;
+    walk(points: Point[], options?: {
+        speed?: number;
+        physical?: boolean;
+    }): Promise<void>;
+    controls(): ElevatorControls | undefined;
+    status(feedId: string): StatusReading | undefined;
+    ride(id: string | null): void;
+    message(text: string): void;
+    step(index: number): void;
+}
+/** Stateful playback uses the same lift commands/readings as a passenger. Vertical legs must not
+ * disappear when a route is split into floor runs: that used to teleport straight past the ride. */
+export declare class WalkJourney {
+    private host;
+    private stopped;
+    private timer?;
+    private rejectWait?;
+    constructor(host: WalkJourneyHost);
+    stop(): void;
+    private waitUntil;
+    private object;
+    private entry;
+    play(route: Route): Promise<void>;
+}