@expofp/wayfinding-compiler 0.0.0-bootstrap.0

package/README.md

@@ -0,0 +1,446 @@
+# @expofp/wayfinding-compiler
+
+Framework-neutral **wayfinding compiler** for the ExpoFP SDK: it turns raw plan geometry into a routing
+graph: `lines` and `lineEnds`, in the shape of the v1 graph format, its lines not cut where they meet
+(see "The emitted graph"). Pure functions only — no React, no MobX, no live stores,
+no I/O. The same input always yields the same output (covered by a determinism test).
+
+This package is the production home of the #1365 auto-routing spike. The plan and per-task status live
+in the tracker: #1221 (phase 1), #1441 (phase 2), #1442 (phase 3). The route-network model it ships —
+`steiner` — is described under "Route network" below.
+
+## Entry points
+
+```ts
+import { compileWayfinding, type WayfindingSource } from '@expofp/wayfinding-compiler';
+
+const source: WayfindingSource = {
+  layers: [{ layer: '1', walls, destinations }], // walls: flat [x,y,…] polylines; destinations: footprints
+};
+
+const { graph, report } = compileWayfinding(source); // graph: { lines, lineEnds } (v1 shape)
+const debug = compileWayfinding(source, { debug: true }); // + layers, reachability, diagnostics
+```
+
+- **`compileWayfinding(source)`** — the main entry. Returns `{ graph, report }`: the graph in the v1
+  shape (`lines` + `lineEnds`, not cut where they meet), and the report a designer reads — `outcome` (`built` / `built-with-gaps` / `not-built`), a one-line
+  `summary`, POI `counts`, and `problems` grouped by floor and reason, each with the POI names and where
+  to look on the plan.
+- **`compileWayfinding(source, { debug: true })`** — the same single pass, adding every stage's artifacts
+  per layer (raw inputs, walkable area, route network), the `reachability` of the emitted graph (its
+  connected parts and the part every POI is bound to) and `diagnostics` — every technical fact, stage
+  by stage — as plain serializable data: what a debug overlay draws. The full catalog of facts is the
+  debug-report table under "Diagnostics and the report" below. `debug: { invariants: true }` also
+  checks the emitted graph against the geometric invariants (`graph-invariants.ts`: no line through a
+  wall or an unserved POI, every dock ending inside its ring; lines may cross or end on one another,
+  the converter cuts them there) and appends
+  the findings as the `graph` stage. The sweep is pairwise and costs a sizable share of the compile on
+  a large plan — about a third more on the largest fixture — so it is opted into, never implied by
+  `debug: true`.
+- **`validateWayfindingSource(source)`** — what is wrong with a plan, as a list of `SourceIssue`
+  (`severity`, `code`, `message`, and the layer, id and position it belongs to). The same findings are
+  part of every compile's report and diagnostics.
+
+### The emitted graph
+
+The graph has the shape of the v1 format, `lines` + `lineEnds`, with one difference from what
+`wf.data.js` holds: its lines are not cut where they meet. An aisle is one line, a stub ends on its span,
+and two aisles cross whole — as a designer draws them. The graph is not written to `wf.data.js` as it
+stands. Designer saves its lines like hand-drawn ones, and the converter that builds `wf.data.js` from
+the saved lines (`fpsync2`) cuts every line where another crosses it or ends within 0.1 plan units of it
+— 3 cm in feet, 10 cm in meters. The report counts an end joined within the same 0.1 plan units, so it
+says what the converter will join on any scale. An end the compiler emits lies within 2 cm of the line it
+stops at, since a line off the plan's axes holds no point of the centimeter grid exactly: on a drawing in
+tenths (before `fp-ver 5`, 1 cm or 3 mm per 0.1 unit) such an end may stay unjoined, and the report shows
+it so. What a viewer reads is joined end to end, which is all the current runtime (`@expofp/wayfinding`
+on `main`) and every released viewer join lines by. A reader that takes the compiler's graph directly has
+to cut the lines itself.
+
+A transition edge joins two stops of one shaft on different floors and carries:
+
+- `virtual: true` — how the current runtime (`@expofp/wayfinding` on `main`, and every released viewer)
+  tells a floor change from a walk, prices it and places the floor-change markers.
+- `kind` (`stairs`, `escalator` or `elevator`) and `transitionId` — v1 extensions the current runtime
+  ignores. The v2 runtime (`feat/wayfinding-v2-graph-format`) reads them first: `kind` makes the edge a
+  transition priced by its policy, `transitionId` keeps a lift serving three floors one shaft.
+
+`@expofp/schema` describes the fields the current runtime reads; the extensions join it with the runtime
+that reads them.
+
+### What the report says
+
+`compileWayfinding` never throws over the plan: a plan it cannot read at all — an unnamed layer, a scale
+that is not a scale — comes back `not-built`, with an empty graph and a `plan-invalid` problem. A
+coordinate that is not a number stops only what it touches: a wall skips its floor (a `plan-invalid`
+problem for that floor), a POI or a transition is left out and reported, and the rest of the plan
+compiles. Everything else a compile can carry on around is compiled around and reported: a floor
+that got no floor, or spans more than routes are built over (a plan in the wrong units, a stray drawing
+far off), POI that got no dock (with the reason the stage proved — a POI standing outside the building
+outline is told apart from one with no floor in front, and the problem points at the stub tip where the
+failing way in ends, when one is known), POI on a part of the network the main
+part does not reach, and shafts that name no kind, do not join their floors, or are left docked on one
+floor only. POI that share an id, or
+have none, each dock by their own geometry. One fact makes one problem — a floor that is not built is one
+problem, not one per POI standing on it — and the main part of the network is the one most POI are bound
+to. The reachability behind it is read off the emitted graph by the graph's own rules: nodes joined by
+exact coordinates, lines joined where one ends within 0.1 plan units of another's span or crosses it
+(the converter cuts the lines there), a POI bound to the `lineEnds` inside its `dock ?? polygon`.
+
+### Diagnostics and the report
+
+One compile speaks to two readers. The **user report** (`CompileResult.report`, built by `report.ts`)
+is for the designer: problems grouped by floor and reason, one fact — one message, in ready English.
+The **debug report** (`WayfindingDebugResult.diagnostics`, produced stage by stage in
+`diagnostics.ts`) is every technical fact the compile established, as plain data for a debug overlay.
+Both are documented here in full; the tables are the contract.
+
+#### User report
+
+`report.outcome` is `built` when the graph has lines and no problem is left, `built-with-gaps` when it
+has lines and problems, `not-built` when nothing was emitted. `report.counts` counts source POI only
+(`poi`, `poiConnected`, `poiNotConnected`, `poiOnDetachedParts`, `networkParts`,
+`floorsWithoutFloor`); transition pads are not counted. Each problem carries the `poi` it touches
+(with the names the plan gave) and a `highlight` saying where to look, in plan units.
+
+Substitutions, used throughout: `{floor}` is the floor's name — `Floor "BG"`, or `The floor` for the
+one unnamed floor (`floor "BG"` / `the floor` inside a sentence); `{n}` is a count; `{names}` lists up
+to 8 POI names and counts the rest (`A, B and 3 more`), a POI with no id as `unnamed POI`; singular and
+plural (`is`/`are`, `it`/`they`) follow the count.
+
+| Kind                   | Cause                              | When                                                                               | Message                                                                                                                                                                              |
+| ---------------------- | ---------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `plan-invalid`         | `layer-id-missing`                 | a layer has no id; the plan is not built                                           | `A floor has no id; the plan cannot be built.`                                                                                                                                       |
+| `plan-invalid`         | `units-per-meter-invalid`          | the scale is not a positive finite number                                          | `The plan's units per meter is {value}; it must be a positive number. Check the plan's units and map anchors.`                                                                       |
+| `plan-invalid`         | `wall-coordinate-not-finite`       | a wall coordinate is `NaN`/infinite; that floor alone is skipped                   | `{floor}: a wall has a coordinate that is not a number; the floor is not built.`                                                                                                     |
+| `nothing-to-build`     | `no-floors`                        | the plan has no layers                                                             | `Nothing to build: the plan has no floors.`                                                                                                                                          |
+| `nothing-to-build`     | `nothing-drawn`                    | every layer has neither walls nor POI                                              | `Nothing to build: the plan has no walls and no POI.`                                                                                                                                |
+| `floor-not-built`      | `no-walls`                         | the layer has POI but no walls                                                     | `{floor}: no floor could be built — the floor has no walls, so there is nothing to build routes inside. {n} POI stand on it.`                                                        |
+| `floor-not-built`      | `outline-open`                     | no wall run closes into an outer contour                                           | `{floor}: no floor could be built — the outer walls do not close into a contour. Check the outer walls of this floor.`                                                               |
+| `floor-not-built`      | `carved-away`                      | walls and footprints cover the whole contour                                       | `{floor}: no floor could be built — the walls and POI drawn on it cover it whole.`                                                                                                   |
+| `floor-not-built`      | `too-large`                        | the floor spans more than routes are built over                                    | `{floor}: no floor could be built — it spans more than routes are built over. Check the plan's units, and any wall or POI drawn far from the hall.`                                  |
+| `poi-not-connected`    | `coordinate-not-finite`            | a footprint coordinate is `NaN`/infinite                                           | `{floor}: {n} POI is/are not connected to the routes — it has/they have a coordinate that is not a number: {names}.`                                                                 |
+| `poi-not-connected`    | `footprint-empty`                  | the footprint encloses no area                                                     | `… — they have no outline the plan can read: {names}.`                                                                                                                               |
+| `poi-not-connected`    | `dock-empty`                       | the `dock` ring encloses no area                                                   | `… — the rectangle routes arrive at has no area: {names}.`                                                                                                                           |
+| `poi-not-connected`    | `outside-building`                 | `no-floor` with the POI outside the outline                                        | `… — it stands/they stand outside the building outline; routes are built inside it only: {names}.`                                                                                   |
+| `poi-not-connected`    | `entrance-far-from-walls`          | an entrance outside the building with no wall within 10 m                          | `… — it stands/they stand more than 10 m from the nearest wall; an entrance outside the building is connected only within 10 m of a wall: {names}.`                                  |
+| `poi-not-connected`    | `no-floor-behind-wall`             | an entrance outside the building whose walls in reach have no floor behind them    | `… — no wall near it/them opens onto floor; check that the building outline closes and that nothing stands right behind the wall: {names}.`                                          |
+| `poi-not-connected`    | `no-floor-in-front`                | `no-floor` inside the building                                                     | `… — there is no floor to stand on in front of it/them: {names}.`                                                                                                                    |
+| `poi-not-connected`    | `no-way-in`                        | walled in on every side                                                            | `… — they have no open side and no doorway: {names}.`                                                                                                                                |
+| `poi-not-connected`    | `approach-blocked`                 | every way in breaks a dock rule (`way-in-blocked`)                                 | `… — a wall or another POI stands right in front of every way in: {names}.`                                                                                                          |
+| `poi-not-connected`    | `cut-off`                          | its floor is a pocket no route reaches                                             | `… — the floor in front of them is a pocket no route reaches: {names}.`                                                                                                              |
+| `poi-not-connected`    | `lost-while-tidying`               | attached, then lost to a later pass (`detached`)                                   | `… — they were attached, then lost while the routes were tidied — reason unknown: {names}.`                                                                                          |
+| `poi-not-connected`    | `unknown`                          | no stage proved a cause                                                            | `… — reason unknown: {names}.`                                                                                                                                                       |
+| `network-split`        | `no-link-found`                    | a POI is bound off the main part AND the network stage recorded the refusal to tie | `{floor}: the routes fall into {n} separate parts: the growth found no lawful link and no floor path between the parts. {n} POI is/are on parts not connected to the rest: {names}.` |
+| `network-split`        | `unknown`                          | a POI is bound off the main part, with no recorded refusal                         | `{floor}: the routes fall into {n} separate parts. {n} POI is/are on parts not connected to the rest: {names}.`                                                                      |
+| `floors-not-connected` | `floor-detached`                   | the main part never reaches this floor, and a POI stands on it                     | `{floor}: its routes are not connected to the rest of the plan; no transition joins them. {n} POI is/are cut off: {names}.`                                                          |
+| `floors-not-connected` | `transition-kind-missing`          | a transition names no kind                                                         | `{transition} names no kind (stairs, escalator, elevator…) and is left out.`                                                                                                         |
+| `floors-not-connected` | `transition-coordinate-not-finite` | a stop coordinate is `NaN`/infinite                                                | `{transition} has a stop whose coordinate is not a number and is left out.`                                                                                                          |
+| `floors-not-connected` | `transition-too-few-stops`         | fewer than two known floors served                                                 | `{transition} serves fewer than two floors.`                                                                                                                                         |
+| `floors-not-connected` | `transition-stop-unknown-layer`    | a stop names a layer the plan lacks                                                | `{transition} names a floor the plan does not have: "{layer}".`                                                                                                                      |
+| `floors-not-connected` | `transition-single-floor`          | the shaft docked on one floor only                                                 | `{transition} is connected to the routes of {floor} only, so it joins no floors.`                                                                                                    |
+| `floors-not-connected` | `transition-stop-no-dock`          | a stop got no dock on its layer; the stop is named when it has an id               | `{transition} does not reach the routes of {floor} (stop "{id}").`                                                                                                                   |
+
+`{transition}` is `Transition "{id}"`, or `A transition` when the plan gave none. Problems are sorted
+by kind (the order of the table) and then by the plan's layer order. The one-line `summary` restates
+the outcome with the counts.
+
+#### Debug report
+
+Every fact is a `Diagnostic`: `code`, `severity` (`error` — the plan or part of it cannot be read;
+`warning` — part of the result is lost or doubtful; `info` — what a stage did), `stage`, one technical
+English `message`, and where it applies: `layer`, a `ref` into the source (`kind` +
+`layer`/`index`/`id`), `geometry` to draw (`bounds`/`point`/`lines`, plan units; `lines` are indices
+into `graph.lines`), and `facts` — the stage's own numbers. Stages come in run order: `input`,
+`scale`, then per layer `normalize` → `walkable` → `network` → `emit`, then `transitions`,
+`reachability`, and — only under `debug: { invariants: true }` — `graph` last.
+
+| Code                                | Severity                            | Stage        | When                                                                                            | Message                                                                                                                                                                                                                                     | Context                                                                                                              |
+| ----------------------------------- | ----------------------------------- | ------------ | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `no-layers`                         | warning                             | input        | the plan has no layers                                                                          | `the plan has no layers`                                                                                                                                                                                                                    | —                                                                                                                    |
+| `layer-id-missing`                  | error                               | input        | a layer has no id                                                                               | `a layer has no id`                                                                                                                                                                                                                         | —                                                                                                                    |
+| `layer-id-duplicate`                | warning                             | input        | two layers share an id                                                                          | `two layers share an id`                                                                                                                                                                                                                    | ref layer                                                                                                            |
+| `destination-id-missing`            | warning                             | input        | a destination has no id                                                                         | `a destination has no id`                                                                                                                                                                                                                   | ref destination (layer, index)                                                                                       |
+| `destination-id-duplicate`          | warning                             | input        | two destinations on one layer share an id                                                       | `two destinations share an id`                                                                                                                                                                                                              | ref destination                                                                                                      |
+| `destination-coordinate-not-finite` | warning                             | input        | a footprint coordinate is `NaN`/infinite; the POI is left out                                   | `a coordinate of the footprint is not a finite number`                                                                                                                                                                                      | ref destination                                                                                                      |
+| `destination-footprint-empty`       | warning                             | input        | no ring of the footprint encloses area                                                          | `the footprint encloses no area`                                                                                                                                                                                                            | ref destination                                                                                                      |
+| `destination-dock-empty`            | warning                             | input        | the `dock` ring encloses no area                                                                | `the dock ring encloses no area`                                                                                                                                                                                                            | ref destination                                                                                                      |
+| `wall-coordinate-not-finite`        | error                               | input        | a wall coordinate is `NaN`/infinite; the floor is skipped                                       | `a wall coordinate is not a finite number`                                                                                                                                                                                                  | ref layer                                                                                                            |
+| `transition-kind-missing`           | warning                             | input        | a transition names no kind; it is left out                                                      | `a transition names no kind`                                                                                                                                                                                                                | ref transition (id)                                                                                                  |
+| `transition-coordinate-not-finite`  | warning                             | input        | a stop coordinate is `NaN`/infinite; the transition is left out                                 | `a transition stop coordinate is not a finite number`                                                                                                                                                                                       | ref transition (id, index)                                                                                           |
+| `transition-too-few-stops`          | warning                             | input        | fewer than two known floors served                                                              | `a transition serves fewer than two floors`                                                                                                                                                                                                 | ref transition (id)                                                                                                  |
+| `units-per-meter-invalid`           | error                               | input        | the scale is not a positive finite number                                                       | `unitsPerMeter must be a finite number above zero`                                                                                                                                                                                          | —                                                                                                                    |
+| `units-assumed-meters`              | info                                | scale        | the plan states no `unitsPerMeter`                                                              | `the plan states no units per meter; it is read as meters`                                                                                                                                                                                  | —                                                                                                                    |
+| `wall-entry-empty`                  | warning                             | normalize    | a wall entry cleans to nothing                                                                  | `the wall entry cleans to no wall piece and is dropped`                                                                                                                                                                                     | ref wall (entry index)                                                                                               |
+| `wall-entry-split`                  | info                                | normalize    | one entry holds several runs                                                                    | `the wall entry describes {n} separate runs, not one polyline`                                                                                                                                                                              | ref wall; facts `runs`                                                                                               |
+| `wall-entry-odd-length`             | warning                             | normalize    | an entry holds an odd count of numbers                                                          | `the wall entry holds an odd count of numbers; the last one names no point and is dropped`                                                                                                                                                  | ref wall                                                                                                             |
+| `footprint-shape`                   | info / warning (`bounds-oversized`) | normalize    | a footprint drawn as pieces got its outline                                                     | one sentence per shape: `traced`, `hull`, `rectilinear`, `bounds`, `bounds-oversized`, `dock` (see `SHAPE_MESSAGES`)                                                                                                                        | ref destination; facts `how`, `parts`                                                                                |
+| `footprint-clipped`                 | info                                | normalize    | the walls cut the footprint back                                                                | `the footprint ran over its walls and is cut back to the largest piece they leave`                                                                                                                                                          | ref destination                                                                                                      |
+| `crossable-inferred`                | warning                             | normalize    | a destination is read as walk-through                                                           | `the footprint holds other destinations, so it is walked in, not around` / `the footprint stands before the only way into another destination, so routes may cross it`                                                                      | ref destination; facts `by`, `victims?`                                                                              |
+| `entrance-openings`                 | info                                | normalize    | an entrance is reached through a wall or a doorway the walls leave                              | `routes reach the entrance through the wall inside its bounds, at {n} place(s)` / `the entrance stands {d} m outside the building; routes reach it through the doorway the walls leave` / `… through the nearest wall with floor behind it` | ref destination; geometry points (where the docks cross the wall); facts `by`, `openings`, `distance?`               |
+| `entrance-no-wall`                  | info                                | normalize    | an entrance inside the building stands across no wall                                           | `the entrance stands across no wall and is reached like any POI`                                                                                                                                                                            | ref destination                                                                                                      |
+| `layer-no-walls`                    | warning                             | walkable     | POI but no walls                                                                                | `the layer has POI but no walls, so no floor is built`                                                                                                                                                                                      | ref layer; facts counts, `destinations`                                                                              |
+| `layer-no-outer-contour`            | warning                             | walkable     | no closed outer contour                                                                         | `no wall run closes into an outer contour, so no floor is built`                                                                                                                                                                            | ref layer; facts counts, `destinations`                                                                              |
+| `floor-carved-away`                 | warning                             | walkable     | the contour closes but nothing is left                                                          | `the outer contour closes, but walls and footprints cover all of it`                                                                                                                                                                        | ref layer; facts counts, `destinations`                                                                              |
+| `floor-built`                       | info                                | walkable     | the floor is built                                                                              | `the floor is built`                                                                                                                                                                                                                        | ref layer; facts counts, `areaM2`                                                                                    |
+| `floor-too-large`                   | warning                             | walkable     | the floor exceeds the raster budget                                                             | `the floor spans more than routes are built over, so no floor is built`                                                                                                                                                                     | ref layer; facts `widthM`, `heightM`, `destinations`                                                                 |
+| `destination-unreached`             | warning                             | network      | the POI got no dock; shows in the report as `poi-not-connected` with the mapped cause           | `the POI got no dock a route can end at ({reason})`                                                                                                                                                                                         | ref destination; geometry point (the failing tip); facts `reason`, `outside?`, `nearestWall?`, `floorBehind?`, `by?` |
+| `doorways-found`                    | info                                | network      | the stage ran; the count may be 0                                                               | `the walls leave {n} doorway(s) on the layer`                                                                                                                                                                                               | ref layer; facts `count`                                                                                             |
+| `network-shortcuts`                 | info                                | network      | shortcut links were cut in                                                                      | `{n} shortcut link(s) are cut in where the network sent a route the long way round`                                                                                                                                                         | ref layer; facts `count`                                                                                             |
+| `network-pieces-untied`             | warning                             | network      | the ties gave up with pieces left; proves `network-split.cause = 'no-link-found'` on its floor  | `the layer's network is left in {n} pieces: the growth found no lawful link and no floor path between them`                                                                                                                                 | ref layer; facts `pieces` (total, not extra)                                                                         |
+| `floor-pieces-unserved`             | info                                | network      | walkable pieces serve nothing and are left out                                                  | `{n} walkable floor piece(s) hold no destination and no doorway, so no network is built over them`                                                                                                                                          | ref layer; facts `count`                                                                                             |
+| `network-parts-before-emit`         | info                                | network      | the part count before the emit                                                                  | `the layer's network has {n} part(s) before the emit, shafts not counted`                                                                                                                                                                   | ref layer; facts `count`                                                                                             |
+| `path-segment-collapsed`            | info                                | emit         | segments shorter than the centimeter grid were skipped                                          | `{n} path segment(s) collapse to a point on the centimeter grid and emit no line`                                                                                                                                                           | ref layer; facts `count`                                                                                             |
+| `dock-collapsed`                    | warning                             | emit         | a dock's ends snap to one node: its `lineEnd` stands with no line                               | `the dock collapses to a point on the centimeter grid: its line end is emitted with no line of its own`                                                                                                                                     | ref destination (source index when known)                                                                            |
+| `transition-stop-bound`             | info                                | transitions  | where a stop rides in                                                                           | `the transition stop stands in the open and gets a pad of its own` / `the transition stop rides in on the dock of "{name}"`                                                                                                                 | ref transition-stop; geometry point; facts `pointId?`, `pad`, `destination?`                                         |
+| `transition-stop-ambiguous`         | warning                             | transitions  | a stop stands in several destinations                                                           | `the transition stop stands in {n} destinations and rides in on the smallest`                                                                                                                                                               | ref transition-stop; geometry point; facts `pointId?`, `destinations`                                                |
+| `transition-stop-no-dock`           | warning                             | transitions  | the stop's floor gave it no dock                                                                | `a transition stop got no dock on its layer, so the shaft does not reach that floor`                                                                                                                                                        | ref transition-stop; geometry point; facts `reason`, `pointId?`                                                      |
+| `transition-stop-unknown-layer`     | warning                             | transitions  | the stop names a layer the plan lacks                                                           | `a transition stop names a layer the plan does not have`                                                                                                                                                                                    | ref transition-stop; facts `reason`, `pointId?`                                                                      |
+| `transition-single-floor`           | warning                             | transitions  | the shaft docked on one floor only                                                              | `the shaft docked on one floor only, so it connects nothing`                                                                                                                                                                                | ref transition; geometry points; facts `kind`                                                                        |
+| `network-split`                     | warning                             | reachability | the emitted graph falls into parts                                                              | `the emitted graph falls into {n} parts`                                                                                                                                                                                                    | facts `nodes[]`, `poi[]` per part                                                                                    |
+| `destination-on-detached-part`      | warning                             | reachability | the POI is bound off the main part                                                              | `the POI is bound to a part of the graph the main part does not reach`                                                                                                                                                                      | ref destination; facts `part`                                                                                        |
+| `destination-unbound`               | warning                             | reachability | no `lineEnd` lies inside the POI                                                                | `no line end lies inside the POI`                                                                                                                                                                                                           | ref destination                                                                                                      |
+| `destination-split-across-parts`    | warning                             | reachability | the POI has ends on several parts                                                               | `the POI has line ends on more than one part`                                                                                                                                                                                               | ref destination                                                                                                      |
+| `binding-mismatch`                  | warning                             | reachability | the network stage and the binding disagree, on a floor the stage ran on, for a POI it was given | `the network stage reports the POI unreached, yet a line end lies inside it` / `…reached, yet no line end lies inside it`                                                                                                                   | ref destination                                                                                                      |
+| `line-end-unowned`                  | warning                             | reachability | ends inside no POI that start no shaft                                                          | `{n} line end(s) lie inside no POI and start no shaft`                                                                                                                                                                                      | facts `ends`                                                                                                         |
+| `line-end-shared`                   | warning                             | reachability | ends inside more than one POI                                                                   | `{n} line end(s) lie inside more than one POI`                                                                                                                                                                                              | facts `ends`                                                                                                         |
+| `line-crosses-wall`                 | warning                             | graph        | a segment or a dock crosses a wall                                                              | `the line crosses a wall of its layer`                                                                                                                                                                                                      | ref layer; geometry lines (+ point for a dock)                                                                       |
+| `line-crosses-poi`                  | warning                             | graph        | a segment or a dock passes through a POI it is not serving                                      | `the line passes through a destination it is not serving`                                                                                                                                                                                   | ref layer; geometry lines (+ point for a dock)                                                                       |
+| `dock-outside-ring`                 | warning                             | graph        | a dock's tip lies inside no `dock ?? polygon` ring                                              | `the dock ends inside no ring a destination is bound by`                                                                                                                                                                                    | ref layer; geometry lines + point                                                                                    |
+
+Where a fact is also visible in the user report, the two differ on purpose: the diagnostic is the
+technical fact with the stage's own words and numbers (`destination-unreached` with
+`facts.reason: 'way-in-blocked'`), the report problem is the proven cause in ready text
+(`poi-not-connected`, cause `approach-blocked`). The mapping: `destination-unreached` reasons
+`no-floor`/`no-way-in`/`way-in-blocked`/`cut-off`/`detached` become `poi-not-connected` causes
+`no-floor-in-front` (or `outside-building` by `facts.outside` — for an entrance, `no-floor-behind-wall` by
+`facts.floorBehind` or `entrance-far-from-walls` by `facts.nearestWall`)/`no-way-in`/`approach-blocked`/
+`cut-off`/`lost-while-tidying`; input facts `destination-coordinate-not-finite`,
+`destination-dock-empty`, `destination-footprint-empty` take priority in that order;
+`network-pieces-untied` turns `network-split`'s cause to `no-link-found`; the `graph` stage never
+reaches the report.
+
+### Reusing the walkable area
+
+The walkable stage depends only on the walls and the carved footprints — never on the route network.
+`compileWayfinding(source, { walkable })` takes ready areas by layer id and skips the stage for each of
+them, so a caller iterating on the route-network generator, or holding the artifacts of an earlier
+compile of the same geometry, pays for the network alone. `CompileProgress.cached` says which stages
+were handed their artifact rather than running. The saving is small — the walkable stage is some 6–17%
+of a compile on real plans, the network is the rest.
+
+The compile is synchronous and takes seconds on a large plan: call it from a worker. On the main
+thread `onProgress` fires, but nothing is repainted until the compile returns.
+
+```ts
+const first = compileWayfinding(source, { debug: true });
+const walkable = Object.fromEntries(first.layers.map((l) => [l.layer, l.walkable]));
+
+const again = compileWayfinding(source, { debug: true, walkable }); // route network only
+```
+
+The package is **booth-agnostic**: a `destination` is any footprint a route must reach (obstacle + POI +
+connection point). The efp glue maps a booth to one; the compiler never sees the word "booth". A
+destination with `crossable: true` (a bag check, a
+security gate) stays walkable and the route may pass through it. The caller states that flag, and the
+compiler adds two readings of its own: a destination holding smaller destinations inside it is a zone
+people walk about in rather than an obstacle, and a footprint that leaves another destination no lawful
+way in at all — while being reachable itself — is the ground a route has to cross to arrive.
+A destination with `entrance: true` is a way into the building: routes reach it through the wall it
+stands across, inside its bounds, and one outside the building through the nearest wall with floor
+behind it (see [Entrances go through the walls](#entrances-go-through-the-walls)).
+
+### Footprints given as pieces, and where a route lands
+
+A destination whose real shape is not a polygon the plan can state — a round bar, an L-shaped lounge, a
+cloverleaf hall, a pictogram in two parts — supplies **`parts`** instead: the raw pieces (triangles,
+sub-shapes) it is drawn from. They replace `polygon`. The compiler reads the outline off the mesh's own
+edges — an edge no two pieces share is on the boundary (`geom/mesh-outline.ts`) — and carves the largest
+outer ring as it is, however many corners it turns. A mesh whose edges do not close falls back to the
+older reading (`geom/footprint.ts`): its convex hull when the pieces fill ≥ 95 % of it and the hull has at
+most six vertices, a traced outline when it is one loop of at most twelve axis-aligned edges, and its
+bounding box otherwise; a mesh of more than 64 pieces is boxed without tracing.
+
+The drawing and the `dock` rectangle are two statements about one place, so the footprint is the two
+joined. A piece identical to the rectangle is the rectangle delivered twice and is left out of the
+reading: laid over the drawing it runs along the drawing's own edges, those edges are then seen twice,
+and the ring that closed through them disappears with them — a room read as a frame around itself. Where
+the drawing falls into separate blocks, the footprint is the block the rectangle stands in, read from the
+drawing's own rings rather than from the traced answer, which gives one ring and gives the biggest. The
+other blocks are drawn all the same, so they are carved out of the floor as obstacles no route arrives
+at.
+
+A destination may also name a **`dock`** — a CONVEX ring inside the footprint that a route endpoint must
+land in. Supply it when the host identifies a destination by a rectangle of its own, especially when its
+containment test only accepts convex polygons. The ways in are then laid from the ring: the middle of each
+of its sides is where the dock ends, and the side's outward normal carries it to the footprint, where the
+whisker leaves — dock end, foot and tip on one line.
+
+## Stages
+
+`compile-wayfinding.ts` runs the plan: validation and scale, the transition stops, each layer through
+`compile-layer.ts` (the destinations read as the stages see them, then the stages below), the emit and the
+report.
+
+| Stage         | Module               | What it does                                                                                                                                                                                                                                                                                                          |
+| ------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Normalize     | `geom/normalize.ts`  | Reads raw wall entries into their real runs (`cleanPolylineRuns`; `geom/walls.ts` runs it over every entry) and cleans destination rings (`cleanRing`).                                                                                                                                                               |
+| Walkable area | `walkable.ts`        | interior(building outlines) − obstacles − wall strips; the outlines come from `@expofp/wayfinding-geometry`.                                                                                                                                                                                                          |
+| Route network | `steiner-network.ts` | The network along the directions the plan is drawn in, one module per pass (named below): a stub per open face, the aisle axes the stub tips define, rows and perimeters on them, one growth over an eroded raster joining the pieces and lone tips with every path laid on those axes, then the passes listed below. |
+| Emit v1       | `emit-v1.ts`         | Restates the network as `lines` + `lineEnds` (the v1 graph), moving no point; what collapses on the centimeter grid is counted and reported (`path-segment-collapsed`, `dock-collapsed`).                                                                                                                             |
+
+### The floor a plan draws
+
+The floor starts inside the building outlines the walls draw (`buildingOutlines` of
+`@expofp/wayfinding-geometry`, the rule the runtime reads the same walls with; the rule is in that
+package's README). The compiler sets no `maxBridge`, so every opening closes and some floor is built. A
+bridge closing an outline borders the floor and is no wall: strips, blockers and doorways read the walls
+as drawn. Walls that draw no outline leave the layer with walls but no floor (`floor-not-built`, cause
+`outline-open`).
+
+### Entrances go through the walls
+
+An `entrance` destination (`openings.ts`) is a way into the building. The walls stay whole — the
+walkable area, the blockers and the invariants read them as drawn — and the entrance gets an opening:
+a doorway it owns, standing on the floor half a person past the wall's thickness, from which its dock
+runs back through the wall. That dock is the one line that may cross a wall, and only inside the
+opening's span (`Blockers.passes`); the entrance is reached through its openings alone, never from a
+face. An opening on a doorway the walls already leave is that doorway.
+
+- **Across a wall**: every wall piece inside the entrance's bounds (`dock`, else `polygon`) is an
+  opening, through its middle, onto each side with floor behind the wall. Pieces on one line (within a
+  wall's thickness) are one opening, however many vertices or polylines draw the wall. A piece shorter
+  than a person makes no opening, nor does a wall with no floor on either side.
+- **Outside the building**, across no wall: a doorway the walls already leave comes first — the
+  stretch of the building outline no wall runs along, at least a person wide, nearest the entrance's
+  middle within 10 m (`ENTRANCE_REACH`), with floor behind it and no wall between; the dock runs through
+  it and crosses no wall. Only with no such doorway in reach: of the walls within 10 m of its bounds,
+  the one nearest to its middle that has floor and a person's clearance on the side away from the
+  entrance, with no other wall between, is the opening, where the bounds project onto it, at least a
+  person wide around the entrance's middle; the dock runs from it through the wall to the entrance. The
+  choice is deterministic, so an entrance between two buildings joins the nearer one. No wall in reach,
+  or none that qualifies (an outline that does not close, a second line right behind the wall), opens
+  nothing: the entrance is reported with the distance and whether such a wall was found
+  (`destination-unreached`, facts `nearestWall`, `floorBehind`), never joined by guesswork.
+- Inside the building and across no wall, an entrance is reached like any POI (`entrance-no-wall`).
+
+The graph invariants let an entrance's dock cross a wall (`line-crosses-wall` is not raised for a dock
+that ends in an entrance); every other line keeps the rule.
+
+### Route network: the steiner network
+
+The raster router works on a soft-eroded clearance field (≥ 0.8 m free; 0.3–0.8 m passable at ~9× cost,
+so a doorway is taken only when no wider path exists) with turn and wall-proximity penalties, which keeps
+axes straight and centered. Doorways come from the gaps the walls leave: a gap counts when nothing is drawn
+across its span — no wall, and no outline of a destination nobody walks through, unless that destination is
+the one the doorway opens into. Gaps between two wall pieces on one line are read first; the line closing a polyline's own
+ends counts where the polyline turns more than half a turn and neither end is already a jamb of such a gap.
+A doorway opens into the destination whose outline it lies on or in; the one destination standing in the room the polyline encloses, POI walked through such as an exit or a stair left out — a room holding more is a hall, its door a way into the space the network reaches; or the outline straight ahead within a person's clearance. The passes, in order:
+
+1. **Directions, mask and router** (`floor-grids.ts`, `mask.ts`, `router.ts`) — the directions the destinations are drawn in (`geom/frames.ts`: each by
+   its longest side, two sides being one direction while the raster cannot tell them apart along their
+   length; a destination whose reach — a stub's length around it — meets no other's of the same direction
+   is a stand set at an angle and opens none, and so do stands turned in a hall drawn square: the hall is
+   read from the first wall along each of the direction's four ways from each stand's middle, by the length
+   that runs along the direction against the length along the plan's axes). For each, the walkable rings without the pieces of floor
+   nobody stands in (no destination, no transition stop), a clearance field, and a coarser router grid whose
+   seams block steps across thin walls — the plan's own grid over the whole floor, a turned direction's over
+   its destinations and their reach. The router walks all the grids as one: a cell with room to turn steps
+   onto the same spot of another grid at the cost of a turn (anywhere, on a grid with no room to turn), so
+   along an aisle the grid of its own direction wins, running straight where the others climb stairs. A
+   doorway is open only at its middle — one person's clearance and a cell either side; the rest of the gap is
+   closed in the mask and blocked like the wall beside it. Every doorway's throat counts a person's
+   clearance at its middle, however narrow the gap, so a route can pass a door the wall's own thickness
+   would otherwise strangle.
+2. **Stubs** (`stubs.ts`) — every way into a destination (`entries.ts`, over `blockers.ts` and `strip.ts`: each edge with room in front of it and every
+   doorway that opens into it, measured by exact rays rather than raster probes; a destination with a
+   docking ring is entered from the ring's sides, a doorway dock runs along the doorway's normal, or else to
+   the ring side facing it) gets a stub, one per side (one in all for a `terminal` destination, doorways
+   first): square out of the face to the middle of the aisle ahead, so the stubs from both sides of an
+   aisle meet on one line. The aisle is as wide as what stands across the face — other destinations'
+   outlines, or wall lines (their doorways included) that a destination entered through doorways lines
+   within a person's width behind them — over half the face's width or more (a doorway reads its own
+   width), so a room corner or a gap in the row across does not set it, and a hall wall has no row
+   across. The stub runs to the middle when the rows on both sides may run that far: a row is two or
+   more ways whose aisle middles lie on one line, however their fronts step, and its stubs may run past
+   their own length while the run is still a stub (at most `MAX_STRETCH` more of its own length) and
+   the detour that adds for two neighbors along the row, out and back, stays within `MAX_STRETCH` of
+   the walk along their fronts — the row's pitch. A lone face has no row to share a line with (the side
+   across answers by its face alone when it has no row), and an aisle narrower than a person is none.
+   Otherwise — open floor, a hall wall, a row across that may not — the stub is half the free run and
+   its own length at most. Each with a lawful dock from there; the dock is one straight run from the
+   tip to its end. A way in whose dock would cross a wall,
+   another destination's outline or a doorway is not laid at all, and the destination is reported with a
+   reason.
+3. **Aisle axes** (`axes.ts`; `stubs.ts` defines them from the stubs and runs the stubs to them) — per
+   direction, tips the raster cannot tell apart across (one cell) lie on
+   one row; a row's line reaches along as far as a person walks beyond its end tips (a strip half a
+   person wide either side, clear of walls, outlines and doorways, and never past the floor's own
+   size). Rows within one aisle's width (twice the clearance) of each other whose lines' reaches
+   overlap along share an axis when one line may serve them all — no nearer than a comfortable
+   clearance to any tip's face or to what stands across it; a row whose tips' bands share no line is
+   bounded by the tips themselves — at the lower median of their tips across, within that. The stubs that end mid-aisle
+   define the aisles' lines first; a stub with open floor ahead runs to such a line ahead of it when no
+   corridor fits between the two or its row may run that far, and the rest line up among themselves.
+   Each stub then runs to its aisle's axis when its dock stays lawful, over floor only. Destinations
+   people walk through frame nothing.
+4. **Rows, rungs and perimeters** (`framing.ts`) — the row along each axis between neighboring tips (a tip
+   that could not reach the axis gets a leg to it); a rung between two stubs that face each other on one
+   line across an aisle — the shortest way between the two stands, and the line both stubs run along —
+   laid onto an aisle's axis running their way within a corridor's width when there is one (legs bring
+   the tips over, and only the parts its row has not laid yet), so an aisle keeps one line; and each
+   destination's tips chained into a perimeter with square corners, along the direction's axes. A link
+   is laid wherever the floor is free, at any length.
+5. **Growth** (`connect.ts`; each path laid by `place-path.ts`, its runs placed by `runs.ts`) — one search
+   over the raster from the largest piece of the network to every
+   other piece and every tip standing off it, reseeded from what it cannot reach, so islands the main
+   network cannot reach still meet. Every straight run of a path is laid on the line its place defines —
+   the doorway's middle where it passes one, its aisle's axis, else the middle of its corridor (nearest
+   blocker each side along its whole length; an open hall wider than the run is long has none). A run is
+   pulled no farther than a tip stands from its axis plus half a cell (the clearance plus half a pitch),
+   and "along" or "across" is read as the raster tells directions apart over the length in question. Each
+   end meets what it joins at a node: square across the line its own line meets, along a line running the
+   same way, else by an elbow. A piece the router cannot reach — its cells too tight, or claimed by
+   another piece — is tied by an elbow from one of its nodes, else by a raster path from its own cells.
+   The pieces the growth and the ties could not join are returned as a count and land in
+   `stats.untiedPieces`.
+6. **Attach** (`attach.ts`) — each stub ends where it first meets the network: a line, or another stub, which then
+   ends there too, so the meeting is a node. A stub that has attached is a whisker (`Whisker`, and `anatomy.whiskers` in the
+   debug artifacts): its foot on the face, its tip a node of the network. A stub that meets nothing is taken to the network by an
+   elbow to the nearest line a free way reaches, else by a raster path laid like a growth path; a stub
+   whose tip no line can reach is reported with a reason. Then every line that ends nowhere goes: growth
+   reached tips whose stubs met a nearer line, and a dangling end that is no tip serves nothing.
+7. **`completeLines`** (`post-passes.ts`) — a dangling end along an axis of any direction is extended to the first line it
+   meets, until no end is left to extend.
+8. **`shortcutDetours`** (`post-passes.ts`) — a link is cut in where the walk along the network is over twice the walk
+   across the floor, one link per network point; laid like a growth path. No link laid after the attach
+   crosses a stub short of its tip: a route would walk past that destination and back. The links cut
+   in are returned as a count and land in `stats.shortcuts`.
+9. **Emit** (`emit-network.ts`) — a doorway dock that turns for a side of its ring gets a line of the network from its tip to
+   the doorway's middle and leaves from there; `splitCrossings` (`geom/split-crossings.ts`) makes every
+   meeting a vertex; the docks are drawn from the tips into the destinations. A straight run is emitted as
+   one line through every meeting on it (`joinStraightRuns`, `network-graph.ts`): an aisle is one line, movable as one in the editor, the stubs
+   meeting it end on its span, and two aisles cross whole. The converter cuts a line where another
+   ends on it or crosses it when it builds `wf.data.js`. Of the network's pieces, the one with most docks is
+   emitted, and each further piece only when it docks a destination no emitted piece does — a piece the
+   floor cuts off serves what nothing else can, and nothing else. Every destination without a dock is
+   listed in `stats.unreached` with why, and with the facts the stage proved: whether it stands outside
+   the building, where the failing way in ends, and which emit check took a `detached` one's whisker.
+   Besides `unreached` and `components`, `stats` carries the layer's counts: the doorways found
+   (`doorways`), the shortcut links (`shortcuts`), the pieces left untied (`untiedPieces`, only when
+   some are), and the walkable floor pieces no destination or doorway serves (`unservedFloorPieces`,
+   likewise).
+
+Network sizes: fixed in `network-sizes.ts` (`NETWORK_SIZES`), validated on the fixture plans. Every
+other distance the stage reads is derived from them or from the plan: the raster cell for what lies on
+one line, the clearance for what shares an aisle, exact rays for how far a line reaches; the shortcut
+limits (`MAX_STRETCH` and the pass budgets) are the one open item.
+
+## Boundaries
+
+- **Pure & deterministic.** No I/O, no globals, no framework coupling — safe in Node and the browser.
+- **Geometry cleanup is owned here.** Mechanical normalization of the raw geometry (vertex dedup,
+  run splitting, collinear collapse) happens in this compiler, not in the data pipeline.
+- **Boolean ops isolated.** All `clipper2-ts` calls sit behind the internal `BooleanOps` adapter
+  (`geom/clipper2-ops.ts` is the only module importing clipper) — swapping the backend is one file.
+- **Self-contained geometry.** Coordinate primitives (`Ring`, `Vec2`) live in `geom/types.ts`;
+  `clipper2-ts` is the package's only runtime dependency besides `tslib`.

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export { compileWayfinding } from './lib/compile-wayfinding.js';
+export type { SourceDestination, SourceTransition, SourceTransitionPoint, WayfindingLayerSource, WayfindingSource, } from './lib/types.js';
+export type { WfV1Graph, WfV1Line, WfV1Point } from './lib/types.js';
+export type { SourceIssue } from './lib/validate-source.js';
+export { validateWayfindingSource } from './lib/validate-source.js';
+export type { CompileOptions, CompileProgress, CompileResult, LayerDebug, WayfindingDebugResult, } from './lib/compile-wayfinding.js';
+export type { Diagnostic, Highlight, Severity, SourceRef, Stage } from './lib/diagnostics.js';
+export type { WallLine } from './lib/geom/normalize.js';
+export type { RouteNetwork, RouteNetworkDock, UnreachedReason } from './lib/graph-types.js';
+export type { NetworkPart, PoiBinding, PoiRef, Reachability } from './lib/reachability.js';
+export type { CompileReport, Outcome, Problem, ProblemKind } from './lib/report.js';
+export type { WalkableArea } from './lib/walkable.js';
+export type { Ring, Vec2 } from './lib/geom/types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,3 @@
+// Public API: entry points and their data contracts. Everything else is internal.
+export { compileWayfinding } from './lib/compile-wayfinding.js';
+export { validateWayfindingSource } from './lib/validate-source.js';

package/dist/lib/attach.d.ts

@@ -0,0 +1,43 @@
+import type { Connector } from './connect.js';
+import { type Whisker } from './entries.js';
+import type { Segment } from './geom/types.js';
+import type { NetworkBuild } from './network-build.js';
+import type { NetworkStore } from './network-store.js';
+import type { Router } from './router.js';
+import { type StubPlan } from './stubs.js';
+/**
+ * The first network line a ray meets. A line lying along the ray is met at its nearer end when that is
+ * ahead, else at its far end.
+ * @param store The network.
+ * @param ox Ray origin x.
+ * @param oy Ray origin y.
+ * @param nx Ray direction x.
+ * @param ny Ray direction y.
+ * @param maxT How far to look.
+ * @returns The segment id and distance, or null within `maxT`.
+ */
+export declare function firstNetworkAlong(store: NetworkStore, ox: number, oy: number, nx: number, ny: number, maxT: number): {
+    id: number;
+    t: number;
+} | null;
+/** What attaching the stubs reads and extends. */
+interface Attaching extends NetworkBuild {
+    /** The stubs planned, and how to retry one that fails. */
+    readonly plan: StubPlan;
+    /** The network; extended in place. */
+    readonly store: NetworkStore;
+    /** Lays the links and the raster paths. */
+    readonly connector: Connector;
+    /** The raster router. */
+    readonly router: Router;
+    /** Whether a line may be laid. */
+    readonly mayLay: (seg: Segment) => boolean;
+}
+/**
+ * Attaches every stub to the network, retrying a destination's next way in when one fails.
+ * @param attaching What the attach reads and extends.
+ * @returns The whiskers: the stubs attached, in the order they attached.
+ */
+export declare function attachStubs(attaching: Attaching): Whisker[];
+export {};
+//# sourceMappingURL=attach.d.ts.map