@willcgage/module-schematic 0.84.0 → 0.86.0

package/dist/index.d.cts

@@ -34,6 +34,14 @@ interface SchematicEndplate {
         pos: number;
         side: "up" | "down";
     };
+    /** ⭐ THE ENDPLATE'S EDGE OF THE BENCHWORK (ADR 0001). When present it WINS
+     * over `pose` and over derivation, and position, heading and width are all
+     * read off the polygon — so they cannot drift apart from the board.
+     *
+     * `pose` remains for modules authored before this and for shapes with no
+     * benchwork polygon to bind to. Nothing is auto-converted: guessing which
+     * edge an owner's freehand pose meant would be inventing an intent. */
+    edge?: EndplateEdge | null;
     /** Manual pose override (#175 phase 1b) — the endplate's module-local track
      * point (x, y inches) + outward-normal heading (°). Hand-entered for shapes
      * the geometry fields can't derive (wye, freeform, loop); wins over
@@ -1184,6 +1192,9 @@ interface EditorState {
     /** Authored per-endplate TRACK offsets by id — the primary track's signed
      * distance from the plate centre, inches. Absent id = the §2.0 default. */
     endplateTrackOffsets: Record<string, number>;
+    /** Endplate EDGE bindings by id (ADR 0001) — an endplate that is part of the
+     * benchwork. Wins over a pose; nothing is auto-converted from one. */
+    endplateEdges?: Record<string, EndplateEdge>;
     /** Benchwork footprint outline — polygon vertices in module-local inches
      * (endplate A's track point at the origin, mainline +x, perpendicular +y up).
      * Empty = no authored outline (fall back to the endplate-width band). */
@@ -2358,6 +2369,125 @@ declare function partsPlaceable(library?: TrackPart[]): {
         why: string;
     }[];
 };
+/** A part placed on the benchwork. */
+interface TrackPiece {
+    id: string;
+    /** A slug from the parts library. */
+    partId: string;
+    /** Where the part's own origin sits, in module-local inches. */
+    x: number;
+    y: number;
+    /** Rotation about that origin, degrees. */
+    rotationDeg: number;
+    /** Mirrored across its own through route — a left-hand turnout from a right. */
+    flipped?: boolean;
+    /** FLEX ONLY: how long this run is. The one piece a builder cuts (ADR 0001). */
+    lengthInches?: number;
+    /** Owner's label, carried onto whatever route this piece ends up in. */
+    name?: string;
+}
+/** A piece's joint, in MODULE coordinates. */
+interface PlacedJoint {
+    /** `"<pieceId>.<jointId>"` — stable, and what connections refer to. */
+    key: string;
+    piece: string;
+    joint: string;
+    role: PartJointRole;
+    x: number;
+    y: number;
+    headingDeg: number;
+}
+/** Two joints in the same place. That is the entire connection rule. */
+interface GraphConnection {
+    a: string;
+    b: string;
+}
+/**
+ * More than two joints in one place — REFUSED, not resolved.
+ *
+ * ⚠️ THIS IS THE GAP THE SPIKE FOUND, and the one that would bite owners. With
+ * three ends stacked on a point, picking a pair silently drops a piece out of
+ * the layout: the walk never reaches it, and nothing says so. So none of them
+ * connect and the ambiguity is reported. Refusing is the only honest answer —
+ * the model cannot know which two the owner meant.
+ */
+interface GraphConflict {
+    x: number;
+    y: number;
+    joints: string[];
+    reason: string;
+}
+interface TrackGraph {
+    joints: PlacedJoint[];
+    connections: GraphConnection[];
+    /** Joints connected to nothing — an unfinished layout, which is a real thing
+     * to show an owner rather than quietly draw as if it were joined. */
+    open: string[];
+    conflicts: GraphConflict[];
+    /** Pieces whose part has no derivable geometry (see {@link partGeometryGap}). */
+    unplaceable: {
+        piece: string;
+        partId: string;
+        why: string;
+    }[];
+}
+/** How close two joints must be to count as connected. A hundredth of an inch:
+ * tight enough that nothing joins by accident, loose enough to absorb the
+ * rounding of a drag. */
+declare const JOINT_SNAP_INCHES = 0.01;
+/** Every piece's joints, transformed onto the board. */
+declare function placedJoints(pieces: TrackPiece[], library?: TrackPart[]): PlacedJoint[];
+/**
+ * Build the graph: which joints are connected, which are open, and where the
+ * layout is ambiguous.
+ *
+ * ⭐ A JOINT HOLDS AT MOST ONE CONNECTION. Rail has two ends; a place where
+ * three meet is a mistake, not a junction — a junction is a TURNOUT, which is a
+ * part carrying three joints of its own.
+ */
+declare function buildTrackGraph(pieces: TrackPiece[], library?: TrackPart[], snapInches?: number): TrackGraph;
+/** A route the walk found: a continuous run of pieces a train can travel. */
+interface GraphRoute {
+    id: string;
+    /** Inches from endplate A, ALONG THE RAIL, to where this route begins. */
+    fromPos: number;
+    toPos: number;
+    /** The turnout this route branched from; null for the main. */
+    bornAt: string | null;
+    /** The turnout it runs back into. Set = a SIDING; null = it dead-ends. */
+    endsAt: string | null;
+    pieces: string[];
+    /** Furthest lateral offset reached — what gives a lane its side. */
+    lateral: number;
+}
+interface GraphTurnout {
+    id: string;
+    /** ⚠️ The FROG's distance from endplate A (#132), measured along the rail. */
+    pos: number;
+    onRoute: string;
+    divergeRoute: string | null;
+}
+interface GraphWalk {
+    routes: GraphRoute[];
+    turnouts: GraphTurnout[];
+    /** Every reason this walk is not the whole layout. */
+    warnings: string[];
+}
+/**
+ * Walk the graph from an endplate and read the topology off it.
+ *
+ * ⚠️ POSITIONS ARE ARC LENGTH ALONG THE RAIL, never x. On a curved module the
+ * two differ by inches — a 90°/R30 corner runs 47.1″ of rail across a 42.4″
+ * chord — and it is the rail a train travels.
+ *
+ * Nesting falls out for free: a turnout found on a branch queues the branch IT
+ * opens, so a yard ladder resolves to whatever depth it actually has. That is
+ * the case the 1-D model can only approximate.
+ */
+declare function walkTrackGraph(graph: TrackGraph, pieces: TrackPiece[], startAt: {
+    piece: string;
+    joint: string;
+}, library?: TrackPart[]): GraphWalk;
 /** A frog casting's parts, in TURNOUT-LOCAL inches: `x` = distance past the
  * points, `y` = lateral offset from the through route. */
 interface FrogCasting {
@@ -2414,6 +2544,62 @@ flipped?: boolean | null): -1 | 0 | 1;
  */
 declare function moduleFeatures(doc: ModuleSchematicDoc): ModuleFeatures;
 type GeometryType = "straight" | "corner_45" | "corner_90" | "curve" | "offset" | "dead_end" | "wye" | "other";
+/**
+ * An endplate bound to a BENCHWORK EDGE (ADR 0001).
+ *
+ * Will Gage, 2026-07-26: *"Endplates are a part of the benchwork. We have
+ * separated them causing some challenges."* A {@link SchematicEndplate.pose} is
+ * a point floating in module space, so it can disagree with the board — and has:
+ * a junction plate landed on the module CENTRE LINE rather than the fascia, a
+ * derived pose written back silently PINNED a plate so it went stale when the
+ * length changed (which is the only reason `poseAuthored` exists), and a face
+ * drawn flat across a tapered edge is flush only at its midpoint.
+ *
+ * Bind it to an edge and none of those are expressible. Position, heading and
+ * WIDTH all come from the edge, so they cannot drift apart.
+ */
+interface EndplateEdge {
+    /** The section whose outline owns this edge; absent = the module outline. */
+    section?: string | null;
+    /** Which edge: the segment from vertex `index` to vertex `index + 1`. */
+    index: number;
+    /** Optional span along that edge, 0…1. Absent = the whole edge — which is the
+     * common case, because a board's end IS the endplate. */
+    fromT?: number | null;
+    toT?: number | null;
+}
+/** What an {@link EndplateEdge} resolves to. Everything here is READ OFF the
+ * polygon; nothing is stored, so nothing can go stale. */
+interface EndplateEdgePose {
+    x: number;
+    y: number;
+    /** The edge's OUTWARD normal, degrees. */
+    heading: number;
+    /** The span's length — the face's real width, not a separate number that
+     * might disagree with the board. */
+    widthInches: number;
+    /** The face's two ends. On a tapered board this follows the slope, which a
+     * stored pose + width could never do. */
+    face: [{
+        x: number;
+        y: number;
+    }, {
+        x: number;
+        y: number;
+    }];
+}
+/**
+ * Resolve an endplate's edge binding against a benchwork polygon.
+ *
+ * ⚠️ REFUSES A CURVED EDGE. Free-moN §2.0 requires the track crossing an
+ * endplate to be perpendicular, straight and level for 4″ — so an endplate face
+ * is flat by the standard, and a bulged edge is not somewhere one can go. That
+ * is a rule, not a missing feature.
+ *
+ * Returns null when the edge doesn't exist or isn't usable, so a caller can say
+ * why rather than drawing something wrong.
+ */
+declare function endplateEdgePose(outline: BenchworkPoint[] | null | undefined, edge: EndplateEdge): EndplateEdgePose | null;
 interface EndplatePose {
     /** Endplate id — "A"/"B" axial, "C"/"D"… branch. */
     id: string;
@@ -2426,6 +2612,19 @@ interface EndplatePose {
     trackConfig: "single" | "double";
     /** Lateral track offsets from the crossing anchor (0 = centred single). */
     trackOffsets: number[];
+    /** Set when this pose came from an {@link EndplateEdge} — read off the
+     * benchwork rather than stored. Its width and face are the board's own. */
+    boundToEdge?: boolean;
+    /** The face's real width, when bound to an edge. */
+    widthInches?: number;
+    /** The face's two ends, when bound to an edge — follows a tapered board. */
+    face?: [{
+        x: number;
+        y: number;
+    }, {
+        x: number;
+        y: number;
+    }];
     /** True when the pose was hand-entered, not derived (wye/loop/other). */
     manual?: boolean;
 }
@@ -2476,6 +2675,12 @@ interface ModuleGeometryInput {
         side: "up" | "down";
         config?: "single" | "double" | null;
     }[];
+    /** ⭐ Endplate EDGE bindings by id (ADR 0001) — an endplate that is part of
+     * the benchwork rather than a point floating beside it. Wins over
+     * `poseOverrides` and over derivation. */
+    endplateEdges?: Record<string, EndplateEdge>;
+    /** The module's benchwork polygon, needed to resolve `endplateEdges`. */
+    outline?: BenchworkPoint[] | null;
     /** Hand-entered pose overrides by endplate id — win over derivation. */
     poseOverrides?: Record<string, {
         x: number;
@@ -2564,4 +2769,4 @@ declare function poseOverridesFromDoc(doc: ModuleSchematicDoc): Record<string, {
     heading: number;
 }>;
 
-export { ATLAS_CODE55_N, BUILT_IN_TRACK_PARTS, type BenchworkPoint, type BranchConnector, CLEARANCE_SPACING_INCHES, CODE55_RAIL_HEIGHT_INCHES, DEFAULT_FLEX_PART_ID, type DimensionSource, type DrawCrossing, type DrawCrossover, type DrawIndustry, type DrawSignal, type DrawTrack, type DrawTurnout, ENDPLATE_FASCIA_CLEAR_INCHES, ENDPLATE_LEAD_INCHES, type EditorBranch, type EditorControlPoint, type EditorCpSignal, type EditorCrossing, type EditorIndustry, type EditorState, type EditorTrack, type EditorTurnout, type EndplateBConfig, type EndplatePose, type EndplateTrackIssue, type EndplateWidthIssue, FAST_TRACKS_N_ME55, FAST_TRACKS_N_ME55_CROSSOVERS, FLEX_TRACK_PARTS, FREEMO_ENDPLATE_TRACK_FASCIA_CLEARANCE_INCHES, FREEMO_ENDPLATE_WIDTH_MIN_INCHES, FREEMO_ENDPLATE_WIDTH_RECOMMENDED_INCHES, FREEMO_TRACK_SPACING_INCHES, type FlexPiece, type FlexPieceEnd, type FrogCasting, type GeometryType, type ImportedPart, type IndustryLabelMode, type IndustrySpot, type LanePinch, MAIN2_TRACK_ID, MAIN_TRACK_ID, type ModuleFeatures, type ModuleFootprint, type ModuleFootprintInput, type ModuleGeometryInput, type ModuleSchematicDoc, type ModuleTrackRow, N_CAR_LENGTH_INCHES, N_SCALE_RATIO, type OccupiedSpan, type OutlineFace, PINCH_EASE_INCHES, type PartAngle, type PartDimension, type PartEnd, type PartExtent, type PartGeometry, type PartJoint, type PartJointRole, type PartSegment, RAIL_GAUGE_INCHES, type ReturnLoopGeometry, type ReturnLoopShape, type SchematicBlock, type SchematicControlPoint, type SchematicCrossing, type SchematicEndplate, type SchematicEndplateTrack, type SchematicIndustry, type SchematicSection, type SchematicSignal, type SchematicTrack, type SchematicTurnout, type SectionAdjacency, type SectionEnd, type SectionEndAssessment, type SectionFootprint, type SectionJointAssessment, type SectionRelativePos, type SignalFacing, type SignalSide, type SpanOverhang, type StoredTrackPart, TIE_HALF_LENGTH_INCHES, TURNOUT_LEAD_INCHES_PER_FROG, type TrackConfig, type TrackPart, type TrackRole, type TurnoutClosure, type TurnoutKind, type UsableCapacity, WHOLE_MODULE_SECTION_ID, asModuleSchematic, assessSectionEnd, assessSectionJoint, benchworkBand, benchworkOutline, buildCrossover, buildPassingSiding, buildTransition, carCapacity, checkEndplateWidth, clearancePointPastFrogInches, crossoverPinches, deriveEndplatePoses, divergeSideForHand, docToState, emptyEditorState, endplateCentreOffsetInches, endplateFaceSegments, endplateLead, endplateTrackOffsetInches, endplateWidthInches, flexPartFor, flexParts, flexPieces, flexUsage, frogCasting, frogNumberFromName, fromSectionRelative, geometryTurnDegrees, hasNoFarEndplate, importedPartToTrackPart, inchesToScaleFeet, isLoopDoc, isTransitionTurnout, laneOffsetAt, leadInchesForSize, maxFlexPieceInches, mergeImportedParts, mergeStoredParts, moduleCenterline, moduleFeatures, moduleFootprint, moduleLengthFromSections, moduleSections, nextId, parseXtpLibrary, partExtent, partExtentForSize, partGeometry, partGeometryGap, partOutlineAtFrog, partsPlaceable, pastFrogInchesForSize, pathLengthInches, poseNeedsManual, poseOverridesFromDoc, remapPos, resizeFlexPiece, returnLoop, sampleBenchworkOutline, samplePartSegments, samplePath, scaleFeetToInches, sectionAdjacency, sectionBand, sectionBreaksFromSections, sectionComponents, sectionFootprints, sectionNeighbours, sectionSpans, sectionSpansOrWhole, sectionedCenterline, sectionedEndPose, sliceCenterline, spanOverhang, stateToDoc, storedPartToTrackPart, toSectionRelative, trackMeetsEndplateIssues, trackPart, trackPath, turnoutClosure, turnoutFacing, turnoutOccupiedSpan, turnoutPartForSize, usableCapacity };
+export { ATLAS_CODE55_N, BUILT_IN_TRACK_PARTS, type BenchworkPoint, type BranchConnector, CLEARANCE_SPACING_INCHES, CODE55_RAIL_HEIGHT_INCHES, DEFAULT_FLEX_PART_ID, type DimensionSource, type DrawCrossing, type DrawCrossover, type DrawIndustry, type DrawSignal, type DrawTrack, type DrawTurnout, ENDPLATE_FASCIA_CLEAR_INCHES, ENDPLATE_LEAD_INCHES, type EditorBranch, type EditorControlPoint, type EditorCpSignal, type EditorCrossing, type EditorIndustry, type EditorState, type EditorTrack, type EditorTurnout, type EndplateBConfig, type EndplateEdge, type EndplateEdgePose, type EndplatePose, type EndplateTrackIssue, type EndplateWidthIssue, FAST_TRACKS_N_ME55, FAST_TRACKS_N_ME55_CROSSOVERS, FLEX_TRACK_PARTS, FREEMO_ENDPLATE_TRACK_FASCIA_CLEARANCE_INCHES, FREEMO_ENDPLATE_WIDTH_MIN_INCHES, FREEMO_ENDPLATE_WIDTH_RECOMMENDED_INCHES, FREEMO_TRACK_SPACING_INCHES, type FlexPiece, type FlexPieceEnd, type FrogCasting, type GeometryType, type GraphConflict, type GraphConnection, type GraphRoute, type GraphTurnout, type GraphWalk, type ImportedPart, type IndustryLabelMode, type IndustrySpot, JOINT_SNAP_INCHES, type LanePinch, MAIN2_TRACK_ID, MAIN_TRACK_ID, type ModuleFeatures, type ModuleFootprint, type ModuleFootprintInput, type ModuleGeometryInput, type ModuleSchematicDoc, type ModuleTrackRow, N_CAR_LENGTH_INCHES, N_SCALE_RATIO, type OccupiedSpan, type OutlineFace, PINCH_EASE_INCHES, type PartAngle, type PartDimension, type PartEnd, type PartExtent, type PartGeometry, type PartJoint, type PartJointRole, type PartSegment, type PlacedJoint, RAIL_GAUGE_INCHES, type ReturnLoopGeometry, type ReturnLoopShape, type SchematicBlock, type SchematicControlPoint, type SchematicCrossing, type SchematicEndplate, type SchematicEndplateTrack, type SchematicIndustry, type SchematicSection, type SchematicSignal, type SchematicTrack, type SchematicTurnout, type SectionAdjacency, type SectionEnd, type SectionEndAssessment, type SectionFootprint, type SectionJointAssessment, type SectionRelativePos, type SignalFacing, type SignalSide, type SpanOverhang, type StoredTrackPart, TIE_HALF_LENGTH_INCHES, TURNOUT_LEAD_INCHES_PER_FROG, type TrackConfig, type TrackGraph, type TrackPart, type TrackPiece, type TrackRole, type TurnoutClosure, type TurnoutKind, type UsableCapacity, WHOLE_MODULE_SECTION_ID, asModuleSchematic, assessSectionEnd, assessSectionJoint, benchworkBand, benchworkOutline, buildCrossover, buildPassingSiding, buildTrackGraph, buildTransition, carCapacity, checkEndplateWidth, clearancePointPastFrogInches, crossoverPinches, deriveEndplatePoses, divergeSideForHand, docToState, emptyEditorState, endplateCentreOffsetInches, endplateEdgePose, endplateFaceSegments, endplateLead, endplateTrackOffsetInches, endplateWidthInches, flexPartFor, flexParts, flexPieces, flexUsage, frogCasting, frogNumberFromName, fromSectionRelative, geometryTurnDegrees, hasNoFarEndplate, importedPartToTrackPart, inchesToScaleFeet, isLoopDoc, isTransitionTurnout, laneOffsetAt, leadInchesForSize, maxFlexPieceInches, mergeImportedParts, mergeStoredParts, moduleCenterline, moduleFeatures, moduleFootprint, moduleLengthFromSections, moduleSections, nextId, parseXtpLibrary, partExtent, partExtentForSize, partGeometry, partGeometryGap, partOutlineAtFrog, partsPlaceable, pastFrogInchesForSize, pathLengthInches, placedJoints, poseNeedsManual, poseOverridesFromDoc, remapPos, resizeFlexPiece, returnLoop, sampleBenchworkOutline, samplePartSegments, samplePath, scaleFeetToInches, sectionAdjacency, sectionBand, sectionBreaksFromSections, sectionComponents, sectionFootprints, sectionNeighbours, sectionSpans, sectionSpansOrWhole, sectionedCenterline, sectionedEndPose, sliceCenterline, spanOverhang, stateToDoc, storedPartToTrackPart, toSectionRelative, trackMeetsEndplateIssues, trackPart, trackPath, turnoutClosure, turnoutFacing, turnoutOccupiedSpan, turnoutPartForSize, usableCapacity, walkTrackGraph };

package/dist/index.d.ts

@@ -34,6 +34,14 @@ interface SchematicEndplate {
         pos: number;
         side: "up" | "down";
     };
+    /** ⭐ THE ENDPLATE'S EDGE OF THE BENCHWORK (ADR 0001). When present it WINS
+     * over `pose` and over derivation, and position, heading and width are all
+     * read off the polygon — so they cannot drift apart from the board.
+     *
+     * `pose` remains for modules authored before this and for shapes with no
+     * benchwork polygon to bind to. Nothing is auto-converted: guessing which
+     * edge an owner's freehand pose meant would be inventing an intent. */
+    edge?: EndplateEdge | null;
     /** Manual pose override (#175 phase 1b) — the endplate's module-local track
      * point (x, y inches) + outward-normal heading (°). Hand-entered for shapes
      * the geometry fields can't derive (wye, freeform, loop); wins over
@@ -1184,6 +1192,9 @@ interface EditorState {
     /** Authored per-endplate TRACK offsets by id — the primary track's signed
      * distance from the plate centre, inches. Absent id = the §2.0 default. */
     endplateTrackOffsets: Record<string, number>;
+    /** Endplate EDGE bindings by id (ADR 0001) — an endplate that is part of the
+     * benchwork. Wins over a pose; nothing is auto-converted from one. */
+    endplateEdges?: Record<string, EndplateEdge>;
     /** Benchwork footprint outline — polygon vertices in module-local inches
      * (endplate A's track point at the origin, mainline +x, perpendicular +y up).
      * Empty = no authored outline (fall back to the endplate-width band). */
@@ -2358,6 +2369,125 @@ declare function partsPlaceable(library?: TrackPart[]): {
         why: string;
     }[];
 };
+/** A part placed on the benchwork. */
+interface TrackPiece {
+    id: string;
+    /** A slug from the parts library. */
+    partId: string;
+    /** Where the part's own origin sits, in module-local inches. */
+    x: number;
+    y: number;
+    /** Rotation about that origin, degrees. */
+    rotationDeg: number;
+    /** Mirrored across its own through route — a left-hand turnout from a right. */
+    flipped?: boolean;
+    /** FLEX ONLY: how long this run is. The one piece a builder cuts (ADR 0001). */
+    lengthInches?: number;
+    /** Owner's label, carried onto whatever route this piece ends up in. */
+    name?: string;
+}
+/** A piece's joint, in MODULE coordinates. */
+interface PlacedJoint {
+    /** `"<pieceId>.<jointId>"` — stable, and what connections refer to. */
+    key: string;
+    piece: string;
+    joint: string;
+    role: PartJointRole;
+    x: number;
+    y: number;
+    headingDeg: number;
+}
+/** Two joints in the same place. That is the entire connection rule. */
+interface GraphConnection {
+    a: string;
+    b: string;
+}
+/**
+ * More than two joints in one place — REFUSED, not resolved.
+ *
+ * ⚠️ THIS IS THE GAP THE SPIKE FOUND, and the one that would bite owners. With
+ * three ends stacked on a point, picking a pair silently drops a piece out of
+ * the layout: the walk never reaches it, and nothing says so. So none of them
+ * connect and the ambiguity is reported. Refusing is the only honest answer —
+ * the model cannot know which two the owner meant.
+ */
+interface GraphConflict {
+    x: number;
+    y: number;
+    joints: string[];
+    reason: string;
+}
+interface TrackGraph {
+    joints: PlacedJoint[];
+    connections: GraphConnection[];
+    /** Joints connected to nothing — an unfinished layout, which is a real thing
+     * to show an owner rather than quietly draw as if it were joined. */
+    open: string[];
+    conflicts: GraphConflict[];
+    /** Pieces whose part has no derivable geometry (see {@link partGeometryGap}). */
+    unplaceable: {
+        piece: string;
+        partId: string;
+        why: string;
+    }[];
+}
+/** How close two joints must be to count as connected. A hundredth of an inch:
+ * tight enough that nothing joins by accident, loose enough to absorb the
+ * rounding of a drag. */
+declare const JOINT_SNAP_INCHES = 0.01;
+/** Every piece's joints, transformed onto the board. */
+declare function placedJoints(pieces: TrackPiece[], library?: TrackPart[]): PlacedJoint[];
+/**
+ * Build the graph: which joints are connected, which are open, and where the
+ * layout is ambiguous.
+ *
+ * ⭐ A JOINT HOLDS AT MOST ONE CONNECTION. Rail has two ends; a place where
+ * three meet is a mistake, not a junction — a junction is a TURNOUT, which is a
+ * part carrying three joints of its own.
+ */
+declare function buildTrackGraph(pieces: TrackPiece[], library?: TrackPart[], snapInches?: number): TrackGraph;
+/** A route the walk found: a continuous run of pieces a train can travel. */
+interface GraphRoute {
+    id: string;
+    /** Inches from endplate A, ALONG THE RAIL, to where this route begins. */
+    fromPos: number;
+    toPos: number;
+    /** The turnout this route branched from; null for the main. */
+    bornAt: string | null;
+    /** The turnout it runs back into. Set = a SIDING; null = it dead-ends. */
+    endsAt: string | null;
+    pieces: string[];
+    /** Furthest lateral offset reached — what gives a lane its side. */
+    lateral: number;
+}
+interface GraphTurnout {
+    id: string;
+    /** ⚠️ The FROG's distance from endplate A (#132), measured along the rail. */
+    pos: number;
+    onRoute: string;
+    divergeRoute: string | null;
+}
+interface GraphWalk {
+    routes: GraphRoute[];
+    turnouts: GraphTurnout[];
+    /** Every reason this walk is not the whole layout. */
+    warnings: string[];
+}
+/**
+ * Walk the graph from an endplate and read the topology off it.
+ *
+ * ⚠️ POSITIONS ARE ARC LENGTH ALONG THE RAIL, never x. On a curved module the
+ * two differ by inches — a 90°/R30 corner runs 47.1″ of rail across a 42.4″
+ * chord — and it is the rail a train travels.
+ *
+ * Nesting falls out for free: a turnout found on a branch queues the branch IT
+ * opens, so a yard ladder resolves to whatever depth it actually has. That is
+ * the case the 1-D model can only approximate.
+ */
+declare function walkTrackGraph(graph: TrackGraph, pieces: TrackPiece[], startAt: {
+    piece: string;
+    joint: string;
+}, library?: TrackPart[]): GraphWalk;
 /** A frog casting's parts, in TURNOUT-LOCAL inches: `x` = distance past the
  * points, `y` = lateral offset from the through route. */
 interface FrogCasting {
@@ -2414,6 +2544,62 @@ flipped?: boolean | null): -1 | 0 | 1;
  */
 declare function moduleFeatures(doc: ModuleSchematicDoc): ModuleFeatures;
 type GeometryType = "straight" | "corner_45" | "corner_90" | "curve" | "offset" | "dead_end" | "wye" | "other";
+/**
+ * An endplate bound to a BENCHWORK EDGE (ADR 0001).
+ *
+ * Will Gage, 2026-07-26: *"Endplates are a part of the benchwork. We have
+ * separated them causing some challenges."* A {@link SchematicEndplate.pose} is
+ * a point floating in module space, so it can disagree with the board — and has:
+ * a junction plate landed on the module CENTRE LINE rather than the fascia, a
+ * derived pose written back silently PINNED a plate so it went stale when the
+ * length changed (which is the only reason `poseAuthored` exists), and a face
+ * drawn flat across a tapered edge is flush only at its midpoint.
+ *
+ * Bind it to an edge and none of those are expressible. Position, heading and
+ * WIDTH all come from the edge, so they cannot drift apart.
+ */
+interface EndplateEdge {
+    /** The section whose outline owns this edge; absent = the module outline. */
+    section?: string | null;
+    /** Which edge: the segment from vertex `index` to vertex `index + 1`. */
+    index: number;
+    /** Optional span along that edge, 0…1. Absent = the whole edge — which is the
+     * common case, because a board's end IS the endplate. */
+    fromT?: number | null;
+    toT?: number | null;
+}
+/** What an {@link EndplateEdge} resolves to. Everything here is READ OFF the
+ * polygon; nothing is stored, so nothing can go stale. */
+interface EndplateEdgePose {
+    x: number;
+    y: number;
+    /** The edge's OUTWARD normal, degrees. */
+    heading: number;
+    /** The span's length — the face's real width, not a separate number that
+     * might disagree with the board. */
+    widthInches: number;
+    /** The face's two ends. On a tapered board this follows the slope, which a
+     * stored pose + width could never do. */
+    face: [{
+        x: number;
+        y: number;
+    }, {
+        x: number;
+        y: number;
+    }];
+}
+/**
+ * Resolve an endplate's edge binding against a benchwork polygon.
+ *
+ * ⚠️ REFUSES A CURVED EDGE. Free-moN §2.0 requires the track crossing an
+ * endplate to be perpendicular, straight and level for 4″ — so an endplate face
+ * is flat by the standard, and a bulged edge is not somewhere one can go. That
+ * is a rule, not a missing feature.
+ *
+ * Returns null when the edge doesn't exist or isn't usable, so a caller can say
+ * why rather than drawing something wrong.
+ */
+declare function endplateEdgePose(outline: BenchworkPoint[] | null | undefined, edge: EndplateEdge): EndplateEdgePose | null;
 interface EndplatePose {
     /** Endplate id — "A"/"B" axial, "C"/"D"… branch. */
     id: string;
@@ -2426,6 +2612,19 @@ interface EndplatePose {
     trackConfig: "single" | "double";
     /** Lateral track offsets from the crossing anchor (0 = centred single). */
     trackOffsets: number[];
+    /** Set when this pose came from an {@link EndplateEdge} — read off the
+     * benchwork rather than stored. Its width and face are the board's own. */
+    boundToEdge?: boolean;
+    /** The face's real width, when bound to an edge. */
+    widthInches?: number;
+    /** The face's two ends, when bound to an edge — follows a tapered board. */
+    face?: [{
+        x: number;
+        y: number;
+    }, {
+        x: number;
+        y: number;
+    }];
     /** True when the pose was hand-entered, not derived (wye/loop/other). */
     manual?: boolean;
 }
@@ -2476,6 +2675,12 @@ interface ModuleGeometryInput {
         side: "up" | "down";
         config?: "single" | "double" | null;
     }[];
+    /** ⭐ Endplate EDGE bindings by id (ADR 0001) — an endplate that is part of
+     * the benchwork rather than a point floating beside it. Wins over
+     * `poseOverrides` and over derivation. */
+    endplateEdges?: Record<string, EndplateEdge>;
+    /** The module's benchwork polygon, needed to resolve `endplateEdges`. */
+    outline?: BenchworkPoint[] | null;
     /** Hand-entered pose overrides by endplate id — win over derivation. */
     poseOverrides?: Record<string, {
         x: number;
@@ -2564,4 +2769,4 @@ declare function poseOverridesFromDoc(doc: ModuleSchematicDoc): Record<string, {
     heading: number;
 }>;
 
-export { ATLAS_CODE55_N, BUILT_IN_TRACK_PARTS, type BenchworkPoint, type BranchConnector, CLEARANCE_SPACING_INCHES, CODE55_RAIL_HEIGHT_INCHES, DEFAULT_FLEX_PART_ID, type DimensionSource, type DrawCrossing, type DrawCrossover, type DrawIndustry, type DrawSignal, type DrawTrack, type DrawTurnout, ENDPLATE_FASCIA_CLEAR_INCHES, ENDPLATE_LEAD_INCHES, type EditorBranch, type EditorControlPoint, type EditorCpSignal, type EditorCrossing, type EditorIndustry, type EditorState, type EditorTrack, type EditorTurnout, type EndplateBConfig, type EndplatePose, type EndplateTrackIssue, type EndplateWidthIssue, FAST_TRACKS_N_ME55, FAST_TRACKS_N_ME55_CROSSOVERS, FLEX_TRACK_PARTS, FREEMO_ENDPLATE_TRACK_FASCIA_CLEARANCE_INCHES, FREEMO_ENDPLATE_WIDTH_MIN_INCHES, FREEMO_ENDPLATE_WIDTH_RECOMMENDED_INCHES, FREEMO_TRACK_SPACING_INCHES, type FlexPiece, type FlexPieceEnd, type FrogCasting, type GeometryType, type ImportedPart, type IndustryLabelMode, type IndustrySpot, type LanePinch, MAIN2_TRACK_ID, MAIN_TRACK_ID, type ModuleFeatures, type ModuleFootprint, type ModuleFootprintInput, type ModuleGeometryInput, type ModuleSchematicDoc, type ModuleTrackRow, N_CAR_LENGTH_INCHES, N_SCALE_RATIO, type OccupiedSpan, type OutlineFace, PINCH_EASE_INCHES, type PartAngle, type PartDimension, type PartEnd, type PartExtent, type PartGeometry, type PartJoint, type PartJointRole, type PartSegment, RAIL_GAUGE_INCHES, type ReturnLoopGeometry, type ReturnLoopShape, type SchematicBlock, type SchematicControlPoint, type SchematicCrossing, type SchematicEndplate, type SchematicEndplateTrack, type SchematicIndustry, type SchematicSection, type SchematicSignal, type SchematicTrack, type SchematicTurnout, type SectionAdjacency, type SectionEnd, type SectionEndAssessment, type SectionFootprint, type SectionJointAssessment, type SectionRelativePos, type SignalFacing, type SignalSide, type SpanOverhang, type StoredTrackPart, TIE_HALF_LENGTH_INCHES, TURNOUT_LEAD_INCHES_PER_FROG, type TrackConfig, type TrackPart, type TrackRole, type TurnoutClosure, type TurnoutKind, type UsableCapacity, WHOLE_MODULE_SECTION_ID, asModuleSchematic, assessSectionEnd, assessSectionJoint, benchworkBand, benchworkOutline, buildCrossover, buildPassingSiding, buildTransition, carCapacity, checkEndplateWidth, clearancePointPastFrogInches, crossoverPinches, deriveEndplatePoses, divergeSideForHand, docToState, emptyEditorState, endplateCentreOffsetInches, endplateFaceSegments, endplateLead, endplateTrackOffsetInches, endplateWidthInches, flexPartFor, flexParts, flexPieces, flexUsage, frogCasting, frogNumberFromName, fromSectionRelative, geometryTurnDegrees, hasNoFarEndplate, importedPartToTrackPart, inchesToScaleFeet, isLoopDoc, isTransitionTurnout, laneOffsetAt, leadInchesForSize, maxFlexPieceInches, mergeImportedParts, mergeStoredParts, moduleCenterline, moduleFeatures, moduleFootprint, moduleLengthFromSections, moduleSections, nextId, parseXtpLibrary, partExtent, partExtentForSize, partGeometry, partGeometryGap, partOutlineAtFrog, partsPlaceable, pastFrogInchesForSize, pathLengthInches, poseNeedsManual, poseOverridesFromDoc, remapPos, resizeFlexPiece, returnLoop, sampleBenchworkOutline, samplePartSegments, samplePath, scaleFeetToInches, sectionAdjacency, sectionBand, sectionBreaksFromSections, sectionComponents, sectionFootprints, sectionNeighbours, sectionSpans, sectionSpansOrWhole, sectionedCenterline, sectionedEndPose, sliceCenterline, spanOverhang, stateToDoc, storedPartToTrackPart, toSectionRelative, trackMeetsEndplateIssues, trackPart, trackPath, turnoutClosure, turnoutFacing, turnoutOccupiedSpan, turnoutPartForSize, usableCapacity };
+export { ATLAS_CODE55_N, BUILT_IN_TRACK_PARTS, type BenchworkPoint, type BranchConnector, CLEARANCE_SPACING_INCHES, CODE55_RAIL_HEIGHT_INCHES, DEFAULT_FLEX_PART_ID, type DimensionSource, type DrawCrossing, type DrawCrossover, type DrawIndustry, type DrawSignal, type DrawTrack, type DrawTurnout, ENDPLATE_FASCIA_CLEAR_INCHES, ENDPLATE_LEAD_INCHES, type EditorBranch, type EditorControlPoint, type EditorCpSignal, type EditorCrossing, type EditorIndustry, type EditorState, type EditorTrack, type EditorTurnout, type EndplateBConfig, type EndplateEdge, type EndplateEdgePose, type EndplatePose, type EndplateTrackIssue, type EndplateWidthIssue, FAST_TRACKS_N_ME55, FAST_TRACKS_N_ME55_CROSSOVERS, FLEX_TRACK_PARTS, FREEMO_ENDPLATE_TRACK_FASCIA_CLEARANCE_INCHES, FREEMO_ENDPLATE_WIDTH_MIN_INCHES, FREEMO_ENDPLATE_WIDTH_RECOMMENDED_INCHES, FREEMO_TRACK_SPACING_INCHES, type FlexPiece, type FlexPieceEnd, type FrogCasting, type GeometryType, type GraphConflict, type GraphConnection, type GraphRoute, type GraphTurnout, type GraphWalk, type ImportedPart, type IndustryLabelMode, type IndustrySpot, JOINT_SNAP_INCHES, type LanePinch, MAIN2_TRACK_ID, MAIN_TRACK_ID, type ModuleFeatures, type ModuleFootprint, type ModuleFootprintInput, type ModuleGeometryInput, type ModuleSchematicDoc, type ModuleTrackRow, N_CAR_LENGTH_INCHES, N_SCALE_RATIO, type OccupiedSpan, type OutlineFace, PINCH_EASE_INCHES, type PartAngle, type PartDimension, type PartEnd, type PartExtent, type PartGeometry, type PartJoint, type PartJointRole, type PartSegment, type PlacedJoint, RAIL_GAUGE_INCHES, type ReturnLoopGeometry, type ReturnLoopShape, type SchematicBlock, type SchematicControlPoint, type SchematicCrossing, type SchematicEndplate, type SchematicEndplateTrack, type SchematicIndustry, type SchematicSection, type SchematicSignal, type SchematicTrack, type SchematicTurnout, type SectionAdjacency, type SectionEnd, type SectionEndAssessment, type SectionFootprint, type SectionJointAssessment, type SectionRelativePos, type SignalFacing, type SignalSide, type SpanOverhang, type StoredTrackPart, TIE_HALF_LENGTH_INCHES, TURNOUT_LEAD_INCHES_PER_FROG, type TrackConfig, type TrackGraph, type TrackPart, type TrackPiece, type TrackRole, type TurnoutClosure, type TurnoutKind, type UsableCapacity, WHOLE_MODULE_SECTION_ID, asModuleSchematic, assessSectionEnd, assessSectionJoint, benchworkBand, benchworkOutline, buildCrossover, buildPassingSiding, buildTrackGraph, buildTransition, carCapacity, checkEndplateWidth, clearancePointPastFrogInches, crossoverPinches, deriveEndplatePoses, divergeSideForHand, docToState, emptyEditorState, endplateCentreOffsetInches, endplateEdgePose, endplateFaceSegments, endplateLead, endplateTrackOffsetInches, endplateWidthInches, flexPartFor, flexParts, flexPieces, flexUsage, frogCasting, frogNumberFromName, fromSectionRelative, geometryTurnDegrees, hasNoFarEndplate, importedPartToTrackPart, inchesToScaleFeet, isLoopDoc, isTransitionTurnout, laneOffsetAt, leadInchesForSize, maxFlexPieceInches, mergeImportedParts, mergeStoredParts, moduleCenterline, moduleFeatures, moduleFootprint, moduleLengthFromSections, moduleSections, nextId, parseXtpLibrary, partExtent, partExtentForSize, partGeometry, partGeometryGap, partOutlineAtFrog, partsPlaceable, pastFrogInchesForSize, pathLengthInches, placedJoints, poseNeedsManual, poseOverridesFromDoc, remapPos, resizeFlexPiece, returnLoop, sampleBenchworkOutline, samplePartSegments, samplePath, scaleFeetToInches, sectionAdjacency, sectionBand, sectionBreaksFromSections, sectionComponents, sectionFootprints, sectionNeighbours, sectionSpans, sectionSpansOrWhole, sectionedCenterline, sectionedEndPose, sliceCenterline, spanOverhang, stateToDoc, storedPartToTrackPart, toSectionRelative, trackMeetsEndplateIssues, trackPart, trackPath, turnoutClosure, turnoutFacing, turnoutOccupiedSpan, turnoutPartForSize, usableCapacity, walkTrackGraph };