@expofp/wayfinding-compiler 0.0.0-bootstrap.0

package/dist/lib/transitions.d.ts

@@ -0,0 +1,72 @@
+import type { Vec2 } from './geom/types.js';
+import type { RouteNetwork } from './graph-types.js';
+import type { SourceTransition, SourceTransitionPoint, WayfindingLayerSource, WayfindingSource, WfV1Graph } from './types.js';
+/** A stop that never reached the graph, reported per point. */
+export interface TransitionOrphan {
+    /** The transition the stop belongs to, when the host gave it an id. */
+    readonly transitionId?: string;
+    /** The host's own label for the stop. */
+    readonly pointId?: string;
+    /** Layer the stop claims. */
+    readonly layer: string;
+    /** Stop x, in plan units. */
+    readonly x: number;
+    /** Stop y, in plan units. */
+    readonly y: number;
+    /** `unknown-layer` — no such layer in the source; `no-dock` — the footprint got no docking stub. */
+    readonly reason: 'unknown-layer' | 'no-dock';
+}
+/** One stop and the destination whose dock it rides in on. */
+interface PlannedStop {
+    readonly transition: SourceTransition;
+    readonly point: SourceTransitionPoint;
+    /** The destination carrying the dock: an existing one, or a pad stood up for this stop. */
+    readonly destinationId: string;
+    /** True when the stop stands in the open and got a pad of its own. */
+    readonly pad: boolean;
+    /** Other destinations the stop also stands in; it rides in on the first. */
+    readonly alsoIn: readonly string[];
+}
+/** A shaft whose attached stops all stand on one floor: it joins nothing after docking. */
+export interface SingleFloorTransition {
+    /** The shaft. */
+    readonly transition: SourceTransition;
+    /** The one layer its attached stops stand on. */
+    readonly layer: string;
+    /** The docked stops' tips on that layer, in meters. */
+    readonly at: readonly Vec2[];
+}
+/** What emitting the shafts found out. */
+interface TransitionEmit {
+    /** Stops that reached no dock, besides those {@link planTransitions} already rejected. */
+    readonly orphans: readonly TransitionOrphan[];
+    /** Shafts left with attached stops on one floor only. */
+    readonly singleFloor: readonly SingleFloorTransition[];
+}
+/** The layers to compile plus the stops to wire up once their networks exist. */
+export interface TransitionPlan {
+    /** Layer sources, with a footprint added wherever a stop landed in the open. */
+    readonly layers: readonly WayfindingLayerSource[];
+    /** Stops that found a layer, in source order. */
+    readonly stops: readonly PlannedStop[];
+    /** Stops that will never reach the graph. */
+    readonly orphans: readonly TransitionOrphan[];
+}
+/**
+ * How every stop reaches its floor's network, decided before the layers compile. A stop inside an existing
+ * footprint rides in on its dock; a stop in the open gets a crossable pad, docked like any destination.
+ * @param source The plan, in meters, with its transitions.
+ * @returns The layers to compile, the stops to wire up, and the stops that cannot be wired.
+ */
+export declare function planTransitions(source: WayfindingSource): TransitionPlan;
+/**
+ * Emit each shaft as a clique over its stops, appending into `out`: one edge per pair of stops on different
+ * layers, so floor 1 to 3 is a single edge. Pairs on one layer are walking, not a shaft, and are skipped.
+ * @param plan The stops resolved by {@link planTransitions}.
+ * @param networks The compiled route network per layer.
+ * @param out The graph being built; mutated.
+ * @returns Stops that reached no dock, and shafts whose attached stops stand on one floor only.
+ */
+export declare function emitTransitionEdges(plan: TransitionPlan, networks: ReadonlyMap<string, RouteNetwork>, out: WfV1Graph): TransitionEmit;
+export {};
+//# sourceMappingURL=transitions.d.ts.map

package/dist/lib/transitions.js

@@ -0,0 +1,191 @@
+// Vertical connections: a transition is a shaft with one stop per floor it serves, and every pair of stops on
+// different layers becomes one graph edge, priced by the runtime from its `kind`. Walking between two shafts
+// on one floor is the route network's job.
+import { line, point } from './emit-v1.js';
+import { snapCm } from './geom/point-key.js';
+import { pointInRing, signedArea } from './geom/primitives.js';
+/**
+ * Half-side, in meters, of the pad stood up for a stop in the open: a 2 m square, about a lift cabin. Its
+ * faces are long enough to pass the network's face filter and let the stub line up with the aisle.
+ */
+const PAD_METERS = 1;
+/**
+ * The destinations a stop stands in — a lift is usually drawn as a POI, and may stand in a hall drawn
+ * as one too.
+ * @param destinations The layer's destinations, in canonical order.
+ * @param x Stop x.
+ * @param y Stop y.
+ * @returns Every destination whose dock or outline holds the stop, the smallest first; canonical
+ * order between equals.
+ */
+function footprintsAt(destinations, x, y) {
+    return destinations
+        .filter((d) => (d.dock !== undefined && pointInRing(d.dock, [x, y])) || pointInRing(d.polygon, [x, y]))
+        .map((d, index) => ({ d, area: Math.abs(signedArea(d.polygon)), index }))
+        .sort((a, b) => a.area - b.area || a.index - b.index)
+        .map(({ d }) => d);
+}
+/**
+ * A square footprint around a stop standing in the open, so the network docks into it like any other.
+ * @param x Stop x.
+ * @param y Stop y.
+ * @param pad Half-side.
+ * @returns The ring.
+ */
+function padRing(x, y, pad) {
+    return [
+        [x - pad, y - pad],
+        [x + pad, y - pad],
+        [x + pad, y + pad],
+        [x - pad, y + pad],
+    ];
+}
+/**
+ * How every stop reaches its floor's network, decided before the layers compile. A stop inside an existing
+ * footprint rides in on its dock; a stop in the open gets a crossable pad, docked like any destination.
+ * @param source The plan, in meters, with its transitions.
+ * @returns The layers to compile, the stops to wire up, and the stops that cannot be wired.
+ */
+export function planTransitions(source) {
+    // A transition that names no kind is left out; the validator reports it.
+    const transitions = (source.transitions ?? []).filter((transition) => transition.kind?.trim());
+    if (transitions.length === 0)
+        return { layers: source.layers, stops: [], orphans: [] };
+    const pad = PAD_METERS;
+    const added = new Map();
+    const stops = [];
+    const orphans = [];
+    for (const transition of transitions)
+        for (const point of transition.points) {
+            const layer = source.layers.find((candidate) => candidate.layer === point.layer);
+            if (!layer) {
+                orphans.push({
+                    transitionId: transition.id,
+                    pointId: point.id,
+                    layer: point.layer,
+                    x: point.x,
+                    y: point.y,
+                    reason: 'unknown-layer',
+                });
+                continue;
+            }
+            const [standing, ...alsoIn] = footprintsAt(layer.destinations, point.x, point.y);
+            if (standing) {
+                stops.push({
+                    transition,
+                    point,
+                    destinationId: standing.id,
+                    pad: false,
+                    alsoIn: alsoIn.map((d) => d.id),
+                });
+                continue;
+            }
+            // Named by where it stands, so ids never collide and the order of the transitions changes
+            // nothing; shafts stopping on one spot share the pad.
+            const id = `transition:${point.layer}:${snapCm(point.x)},${snapCm(point.y)}`;
+            const list = added.get(point.layer) ?? [];
+            // Terminal: a shaft is entered the way its doors face, so one connection is the whole approach.
+            if (!list.some((d) => d.id === id)) {
+                const ring = padRing(point.x, point.y, pad);
+                list.push({ id, polygon: ring, dock: ring, crossable: true, terminal: true });
+            }
+            added.set(point.layer, list);
+            stops.push({ transition, point, destinationId: id, pad: true, alsoIn: [] });
+        }
+    const layers = source.layers.map((layer) => {
+        const extra = added.get(layer.layer);
+        if (!extra)
+            return layer;
+        return { ...layer, destinations: [...layer.destinations, ...extra] };
+    });
+    return { layers, stops, orphans };
+}
+/**
+ * The dock tip of the stop's destination closest to the stop.
+ * @param network The layer's route network.
+ * @param destinationId The destination the stop rides in on.
+ * @param x Stop x.
+ * @param y Stop y.
+ * @returns The tip, or null when the destination has no dock.
+ */
+function dockNear(network, destinationId, x, y) {
+    let best = null;
+    let bestDistance = Infinity;
+    for (const dock of network.docks) {
+        if (dock.id !== destinationId)
+            continue;
+        const distance = (dock.to[0] - x) ** 2 + (dock.to[1] - y) ** 2;
+        if (distance < bestDistance) {
+            bestDistance = distance;
+            best = dock.to;
+        }
+    }
+    return best;
+}
+/**
+ * One edge of a shaft's clique, priced by the runtime from its kind.
+ * @param transition The shaft.
+ * @param p0 One stop.
+ * @param p1 The other stop.
+ * @returns The edge.
+ */
+function transitionLine(transition, p0, p1) {
+    // `virtual` is how the v1 runtime tells a floor change from a walk; a reader of `kind` ignores it.
+    return {
+        ...line(p0, p1),
+        virtual: true,
+        unaccessible: transition.accessible === false,
+        kind: transition.kind,
+        ...(transition.id != null ? { transitionId: transition.id } : {}),
+    };
+}
+/**
+ * Emit each shaft as a clique over its stops, appending into `out`: one edge per pair of stops on different
+ * layers, so floor 1 to 3 is a single edge. Pairs on one layer are walking, not a shaft, and are skipped.
+ * @param plan The stops resolved by {@link planTransitions}.
+ * @param networks The compiled route network per layer.
+ * @param out The graph being built; mutated.
+ * @returns Stops that reached no dock, and shafts whose attached stops stand on one floor only.
+ */
+export function emitTransitionEdges(plan, networks, out) {
+    const orphans = [];
+    const singleFloor = [];
+    const attached = new Map();
+    for (const stop of plan.stops) {
+        const network = networks.get(stop.point.layer);
+        const tip = network ? dockNear(network, stop.destinationId, stop.point.x, stop.point.y) : null;
+        if (!tip) {
+            orphans.push({
+                transitionId: stop.transition.id,
+                pointId: stop.point.id,
+                layer: stop.point.layer,
+                x: stop.point.x,
+                y: stop.point.y,
+                reason: 'no-dock',
+            });
+            continue;
+        }
+        const list = attached.get(stop.transition) ?? [];
+        list.push(point(tip[0], tip[1], stop.point.layer));
+        attached.set(stop.transition, list);
+    }
+    const known = new Set(plan.layers.map((layer) => layer.layer));
+    for (const [transition, points] of attached) {
+        const layers = new Set(points.map((p) => p.layer));
+        // Floors the shaft was planned for among the plan's own: an unknown layer is its stop's own
+        // fact, not a floor this shaft could have joined.
+        const planned = new Set(transition.points.map((p) => p.layer).filter((layer) => known.has(layer)));
+        // Planned for several floors, docked on one: the shaft joins nothing.
+        if (layers.size === 1 && planned.size > 1)
+            singleFloor.push({
+                transition,
+                layer: points[0].layer,
+                at: points.map((p) => [p.x, p.y]),
+            });
+        for (let i = 0; i < points.length; i++)
+            for (let j = i + 1; j < points.length; j++)
+                if (points[i].layer !== points[j].layer)
+                    out.lines.push(transitionLine(transition, points[i], points[j]));
+    }
+    return { orphans, singleFloor };
+}

package/dist/lib/types.d.ts

@@ -0,0 +1,126 @@
+import type { Ring } from './geom/types.js';
+/** A footprint a route must reach: obstacle, POI and connection point in one, booth-agnostic. */
+export interface SourceDestination {
+    /** Stable identifier; labels the destination's docks and diagnostics. */
+    readonly id: string;
+    /** Footprint polygon in plan units; an obstacle unless {@link crossable}. */
+    readonly polygon: Ring;
+    /**
+     * The footprint as raw pieces (a mesh, sub-shapes) for a shape {@link polygon} cannot state.
+     * Replaces `polygon`: the outline is read off the pieces (`geom/footprint.ts`). Plan units,
+     * already positioned.
+     */
+    readonly parts?: readonly Ring[];
+    /**
+     * A CONVEX ring inside the footprint that route endpoints land in, for a host that identifies the
+     * destination by a rectangle of its own. Ways in are laid from its sides: a dock ends at a side's
+     * middle and runs along its outward normal to the footprint.
+     */
+    readonly dock?: Ring;
+    /** A route may pass THROUGH it (a bag check, a gate); it stays part of the walkable area. */
+    readonly crossable?: boolean;
+    /**
+     * ONE connection is the whole approach, from the face that reaches the network first (a toilet, a
+     * lift door). Otherwise every open face grows a stub.
+     */
+    readonly terminal?: boolean;
+    /**
+     * A way into the building: routes reach it through the wall it stands across, inside its bounds
+     * ({@link dock}, else {@link polygon}), and one outside the building through the nearest wall with
+     * floor behind it. The walls stay whole; the entrance's dock is the one line through them.
+     */
+    readonly entrance?: boolean;
+}
+/** One layer's (floor's) raw geometry input. */
+export interface WayfindingLayerSource {
+    /** Globally unique layer id, carried onto every emitted point. */
+    readonly layer: string;
+    /** Wall polylines as flat `[x0, y0, x1, y1, …]` runs, raw; the compiler cleans them. */
+    readonly walls: readonly (readonly number[])[];
+    /** Footprints on this layer to route to. */
+    readonly destinations: readonly SourceDestination[];
+}
+/** Where a shaft opens onto one floor; bound to the floor's network by position. */
+export interface SourceTransitionPoint {
+    /** The host's label for this stop, for diagnostics. */
+    readonly id?: string;
+    /** A {@link WayfindingLayerSource.layer}. */
+    readonly layer: string;
+    /** Horizontal coordinate in plan units. */
+    readonly x: number;
+    /** Vertical coordinate in plan units. */
+    readonly y: number;
+}
+/**
+ * One shaft: a lift serving three floors is one transition with three points, each pair linked.
+ * Points on the same layer are never linked; walking between them is the route network's job.
+ */
+export interface SourceTransition {
+    /** Host identifier; labels emitted edges and diagnostics. */
+    readonly id?: string;
+    /** `'stairs' | 'escalator' | 'elevator' | …`; the routing policy prices the transition by it. */
+    readonly kind: string;
+    /** One point per floor served. */
+    readonly points: readonly SourceTransitionPoint[];
+    /** `false` excludes it from accessible-only routes. */
+    readonly accessible?: boolean;
+}
+/** Raw plan geometry the compiler consumes, one entry per layer. */
+export interface WayfindingSource {
+    /** Per-layer geometry. */
+    readonly layers: readonly WayfindingLayerSource[];
+    /** Vertical connections between layers. */
+    readonly transitions?: readonly SourceTransition[];
+    /**
+     * Plan units per meter: `1` for meters, about `3.28` for feet, ten times that for tenths. Scales
+     * the compiler's thresholds; absent, the plan is read as meters.
+     */
+    readonly unitsPerMeter?: number;
+}
+/** A vertex of the emitted v1 graph. */
+export interface WfV1Point {
+    /** Horizontal coordinate in plan units. */
+    readonly x: number;
+    /** Vertical coordinate in plan units. */
+    readonly y: number;
+    /** Globally unique layer id. */
+    readonly layer: string;
+}
+/** An edge of the emitted v1 graph. */
+export interface WfV1Line {
+    /** Start vertex. */
+    readonly p0: WfV1Point;
+    /** End vertex. */
+    readonly p1: WfV1Point;
+    /**
+     * True on a transition edge: how the v1 runtime tells a floor change from a walk. A runtime that
+     * reads {@link kind} ignores it.
+     */
+    readonly virtual: boolean;
+    /** Excluded when routing accessible-only. */
+    readonly unaccessible: boolean;
+    /** One-way edge; always false. */
+    readonly unidirection: boolean;
+    /** `0`: the edge costs its length. */
+    readonly weight: number;
+    /**
+     * Transition edges only: `'stairs'`, `'escalator'` or `'elevator'`. A v1 extension the current
+     * runtime ignores; the v2 runtime prices the edge by it.
+     */
+    readonly kind?: string;
+    /** Transition edges only: the shaft this edge belongs to. A v1 extension, read like {@link kind}. */
+    readonly transitionId?: string;
+}
+/**
+ * The compiled graph in the shape of the v1 format; its lines are not cut where they meet, the
+ * converter that builds wf.data.js cuts them.
+ */
+export interface WfV1Graph {
+    /** Route-network segments plus docks. */
+    readonly lines: WfV1Line[];
+    /**
+     * One point per dock, just inside its destination: a destination is reached through the ends inside its ring.
+     */
+    readonly lineEnds: WfV1Point[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/lib/types.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/validate-source.d.ts

@@ -0,0 +1,41 @@
+import type { SourceDestination, WayfindingSource } from './types.js';
+/** What is wrong with the plan handed to the compiler, and where. */
+export interface SourceIssue {
+    /**
+     * `'error'` leaves the plan unbuilt — or, when the issue names a layer, that floor alone;
+     * `'warning'` is reported and compiled around, leaving out the object it names when it must.
+     */
+    readonly severity: 'error' | 'warning';
+    /** Stable machine-readable code. */
+    readonly code: string;
+    /** What is wrong, in one sentence. */
+    readonly message: string;
+    /** The layer it belongs to, when it belongs to one. */
+    readonly layer?: string;
+    /** The id of the destination or transition, when the source gave one. */
+    readonly id?: string;
+    /** A destination's index in its layer's `destinations`, or a transition's in `transitions`. */
+    readonly index?: number;
+}
+/**
+ * Whether every ring of a destination is made of finite points. The compile leaves a destination
+ * failing this out; the validator reports it.
+ * @param destination The destination.
+ * @returns True when `polygon`, `parts` and `dock` hold no `NaN` or infinite coordinate.
+ */
+export declare function destinationFinite(destination: SourceDestination): boolean;
+/**
+ * Whether a layer's walls are made of finite numbers. The compile skips a floor failing this; the
+ * validator reports it.
+ * @param walls The layer's raw wall entries.
+ * @returns True when no coordinate is `NaN` or infinite.
+ */
+export declare function wallsFinite(walls: readonly (readonly number[])[]): boolean;
+/**
+ * Check the structure of a plan before it is compiled: ids, references between the parts, rings that
+ * enclose nothing, coordinates that are not finite numbers, and transitions that name no kind.
+ * @param source The plan to check.
+ * @returns Every issue found, errors and warnings together.
+ */
+export declare function validateWayfindingSource(source: WayfindingSource): SourceIssue[];
+//# sourceMappingURL=validate-source.d.ts.map

package/dist/lib/validate-source.js

@@ -0,0 +1,133 @@
+import { cleanRing } from './geom/normalize.js';
+import { POINT_EPS } from './geom/point-key.js';
+/** The fewest vertices a ring can enclose an area with. */
+const MIN_RING_VERTICES = 3;
+function issue(severity, code, message, where = {}) {
+    return {
+        severity,
+        code,
+        message,
+        ...(where.layer !== undefined && { layer: where.layer }),
+        ...(where.id !== undefined && { id: where.id }),
+        ...(where.index !== undefined && { index: where.index }),
+    };
+}
+/**
+ * Whether every vertex of a ring is a finite point.
+ * @param ring The ring.
+ * @returns True when no coordinate is `NaN` or infinite.
+ */
+function finiteRing(ring) {
+    return ring.every(([x, y]) => Number.isFinite(x) && Number.isFinite(y));
+}
+/**
+ * Whether every ring of a destination is made of finite points. The compile leaves a destination
+ * failing this out; the validator reports it.
+ * @param destination The destination.
+ * @returns True when `polygon`, `parts` and `dock` hold no `NaN` or infinite coordinate.
+ */
+export function destinationFinite(destination) {
+    return [destination.polygon, ...(destination.parts ?? []), destination.dock ?? []].every(finiteRing);
+}
+/**
+ * Whether a layer's walls are made of finite numbers. The compile skips a floor failing this; the
+ * validator reports it.
+ * @param walls The layer's raw wall entries.
+ * @returns True when no coordinate is `NaN` or infinite.
+ */
+export function wallsFinite(walls) {
+    return walls.every((run) => run.every(Number.isFinite));
+}
+function checkLayers(layers, out) {
+    const known = new Set();
+    // An empty plan has nothing drawn yet and compiles to an empty graph.
+    if (!layers.length)
+        out.push(issue('warning', 'no-layers', 'the plan has no layers'));
+    for (const layer of layers) {
+        // `''` is a valid id (the single unnamed layer); only a missing id is an error.
+        if (layer.layer === undefined) {
+            out.push(issue('error', 'layer-id-missing', 'a layer has no id'));
+            continue;
+        }
+        // Duplicate ids still compile and their graphs merge, but the route network is kept per id, so a
+        // transition may dock into the wrong one.
+        if (known.has(layer.layer))
+            out.push(issue('warning', 'layer-id-duplicate', 'two layers share an id', { layer: layer.layer }));
+        known.add(layer.layer);
+    }
+    return known;
+}
+function checkDestination(destination, layer, index, eps, seen, out) {
+    const where = { layer, id: destination.id, index };
+    // A blank or repeated id is reported; the destination still docks by its geometry.
+    if (!destination.id) {
+        out.push(issue('warning', 'destination-id-missing', 'a destination has no id', { layer, index }));
+    }
+    else {
+        if (seen.has(destination.id))
+            out.push(issue('warning', 'destination-id-duplicate', 'two destinations share an id', where));
+        seen.add(destination.id);
+    }
+    // The rest of the plan compiles; this destination is left out and reported unconnected.
+    if (!destinationFinite(destination)) {
+        out.push(issue('warning', 'destination-coordinate-not-finite', 'a coordinate of the footprint is not a finite number', where));
+        return;
+    }
+    // As the compiler reads it: `parts` enclosing nothing fall back to the polygon, and a footprint with no
+    // shape left is a warning — the rest of the plan compiles.
+    const parts = [...(destination.parts ?? []), destination.polygon];
+    // Measured after the compiler's cleanup: repeated and collinear vertices removed.
+    const usable = parts.filter((ring) => cleanRing(ring, eps).length >= MIN_RING_VERTICES);
+    if (!usable.length)
+        out.push(issue('warning', 'destination-footprint-empty', 'the footprint encloses no area', where));
+    // A dock of no area (a zero-width rectangle) is kept: no route arrives in it, so the destination is
+    // reported unconnected.
+    if (destination.dock && cleanRing(destination.dock, eps).length < MIN_RING_VERTICES)
+        out.push(issue('warning', 'destination-dock-empty', 'the dock ring encloses no area', where));
+}
+/**
+ * Check the structure of a plan before it is compiled: ids, references between the parts, rings that
+ * enclose nothing, coordinates that are not finite numbers, and transitions that name no kind.
+ * @param source The plan to check.
+ * @returns Every issue found, errors and warnings together.
+ */
+export function validateWayfindingSource(source) {
+    const issues = [];
+    const layers = checkLayers(source.layers, issues);
+    // The compiler cleans rings in meters, so the epsilon is scaled to plan units here.
+    const unit = source.unitsPerMeter;
+    const eps = POINT_EPS * (unit !== undefined && Number.isFinite(unit) && unit > 0 ? unit : 1);
+    // Ids are unique per layer — the scope the network docks in.
+    for (const layer of source.layers) {
+        const seen = new Set();
+        if (!wallsFinite(layer.walls))
+            issues.push(issue('error', 'wall-coordinate-not-finite', 'a wall coordinate is not a finite number', {
+                layer: layer.layer,
+            }));
+        layer.destinations.forEach((destination, index) => checkDestination(destination, layer.layer, index, eps, seen, issues));
+    }
+    for (const [index, transition] of (source.transitions ?? []).entries()) {
+        // The kind prices the shaft and tells it from a walk; without one it is left out.
+        if (!transition.kind?.trim()) {
+            issues.push(issue('warning', 'transition-kind-missing', 'a transition names no kind', {
+                id: transition.id,
+            }));
+            continue;
+        }
+        // The rest of the plan compiles; this transition is left out.
+        if (!finiteRing(transition.points.map(({ x, y }) => [x, y]))) {
+            issues.push(issue('warning', 'transition-coordinate-not-finite', 'a transition stop coordinate is not a finite number', { id: transition.id, index }));
+            continue;
+        }
+        const onKnownLayers = transition.points.filter((point) => layers.has(point.layer));
+        // Floors, not stops: two stops on one layer connect nothing and yield no edge.
+        if (new Set(onKnownLayers.map((point) => point.layer)).size < 2)
+            issues.push(issue('warning', 'transition-too-few-stops', 'a transition serves fewer than two floors', {
+                id: transition.id,
+            }));
+    }
+    if (source.unitsPerMeter !== undefined &&
+        !(Number.isFinite(source.unitsPerMeter) && source.unitsPerMeter > 0))
+        issues.push(issue('error', 'units-per-meter-invalid', 'unitsPerMeter must be a finite number above zero'));
+    return issues;
+}

package/dist/lib/walkable.d.ts

@@ -0,0 +1,104 @@
+import type { BooleanOps } from './geom/boolean-ops.js';
+import type { WallLine } from './geom/normalize.js';
+import type { Ring, Segment, Vec2 } from './geom/types.js';
+import { type PreparedWalls } from './geom/walls.js';
+/**
+ * Wall half-thickness in meters. Square caps extend each jamb by it, so a doorway narrows by twice
+ * this.
+ */
+export declare const WALL_HALF_WIDTH = 0.12;
+/** One layer's raw geometry the walkable stage consumes. */
+interface WalkableInput {
+    /** Wall polylines as flat `[x0, y0, x1, y1, …]` runs in meters, raw; cleaned internally. */
+    readonly walls: readonly (readonly number[])[];
+    /** Obstacle footprints to carve out, already cut back by {@link carveFootprints}. */
+    readonly obstacles: readonly Ring[];
+}
+/**
+ * Wall geometry already built for this layer, shared by the stages. Strips: same walls, same
+ * half-width.
+ */
+interface SharedWalls {
+    /** The layer's walls, read once. */
+    readonly walls?: PreparedWalls;
+    /** The wall strips, from {@link wallStripsOf}. */
+    readonly strips?: readonly Ring[];
+    /** The outer contours, from {@link outerContoursOf}. */
+    readonly contours?: readonly Ring[];
+}
+/** The walkable area: a polygon with holes, plus overlay layers and stats. */
+export interface WalkableArea {
+    /** Outer rings plus hole rings (obstacles, wall thickness). */
+    readonly rings: Ring[];
+    /** The building's outline: the outer contours joined, before carving. */
+    readonly outline: Ring[];
+    /** Union of the wall strips, for the overlay. */
+    readonly wallStrips: Ring[];
+    /** Cleaned wall centerlines, for the overlay. */
+    readonly wallLines: WallLine[];
+    /** Counts and walkable area (m²), for diagnostics. */
+    readonly stats: {
+        readonly walls: number;
+        readonly outerContours: number;
+        readonly rings: number;
+        /** Rounded to 0.1 m², for the overlay. */
+        readonly area: number;
+        /** As computed, so a tiny floor does not read as none; absent in artifacts built before it. */
+        readonly areaExact?: number;
+    };
+}
+/**
+ * Whether a destination stands on a piece of floor: its middle or a corner lies inside it, or a
+ * corner lies on its boundary.
+ * @param piece The piece of floor.
+ * @param ring The destination's ring.
+ * @returns True when the destination stands on it.
+ */
+export declare function standsOn(piece: Ring, ring: Ring): boolean;
+/**
+ * Whether a point is inside the building: inside its outline and not in a courtyard.
+ * @param outline The building's outline, from {@link WalkableArea.outline}.
+ * @param point The point.
+ * @returns True inside.
+ */
+export declare function inBuilding(outline: readonly Ring[], point: Vec2): boolean;
+/**
+ * The walls as strips wound positive, one per wall segment.
+ * @param ops Polygon boolean backend.
+ * @param segments The wall segments, loops' closing pieces included ({@link prepareWalls}).
+ * @param halfWidth Wall half-thickness in meters.
+ * @returns One strip per wall segment.
+ */
+export declare function wallStripsOf(ops: BooleanOps, segments: readonly Segment[], halfWidth: number): Ring[];
+/**
+ * Footprints cut back to the walls that bound them, in input order: the shapes the floor is carved
+ * with.
+ * @param obstacles The obstacle rings, in any winding.
+ * @param strips The wall strips, from {@link wallStripsOf}.
+ * @param ops Polygon boolean backend.
+ * @returns One ring per obstacle, in input order, and which of them the walls cut back.
+ */
+export declare function carveFootprints(obstacles: readonly Ring[], strips: readonly Ring[], ops: BooleanOps): {
+    rings: Ring[];
+    clipped: boolean[];
+};
+/**
+ * The outer contours: the building outlines the walls draw, openings closed with no width limit. A
+ * bridge closing an outline borders the floor and is no wall.
+ * @param walls Cleaned wall centerlines with their closed/open flag.
+ * @returns The outlines, largest first, wound positive.
+ */
+export declare function outerContoursOf(walls: readonly WallLine[]): Ring[];
+/**
+ * Build one layer's walkable area:
+ *
+ *   walkable = interior(outer contours) − ⋃(obstacles) − ⋃(wall strips)
+ * @param input One layer's walls (flat polylines) and obstacles from {@link carveFootprints}.
+ * @param ops Polygon boolean backend; defaults to clipper2, which is the only one there is.
+ * @param halfWidth Wall half-thickness in meters.
+ * @param shared The same walls already read and offset, when the caller holds them.
+ * @returns The walkable polygon with holes, plus diagnostic layers and stats.
+ */
+export declare function buildWalkableArea(input: WalkableInput, ops?: BooleanOps, halfWidth?: number, shared?: SharedWalls): WalkableArea;
+export {};
+//# sourceMappingURL=walkable.d.ts.map