@willcgage/module-schematic 0.86.0 → 0.90.0

package/dist/index.d.cts

@@ -242,6 +242,9 @@ interface SchematicTurnout {
 interface SchematicSignal {
     id: string;
     pos: number;
+    /** Hold this signal by the piece it stands beside (ADR 0001). See
+     * {@link GraphAnchor} — a mast is planted next to a particular bit of rail. */
+    anchor?: GraphAnchor | null;
     /** Track the signal governs; absent = the primary main (lane 0). */
     track?: string;
     facing?: SignalFacing;
@@ -295,11 +298,40 @@ type IndustryLabelMode = "none" | "cars" | "inches";
  */
 /** One car-spot span of an industry on a track — an industry may have several
  * (a house track serving one customer across multiple spot tracks, #54). */
+/**
+ * ⭐ A PLACE ON THE TRACK, HELD BY THE PIECE THAT IS THERE (ADR 0001).
+ *
+ * `pos` — inches from endplate A — is a fine way to *read* where something is
+ * and a poor way to *hold* it: it is a number about the whole module, so every
+ * edit anywhere upstream silently changes what it means. A car spot belongs to
+ * the rail it is beside. Anchored to the piece, moving that piece takes the
+ * industry with it and moving anything else leaves it alone, which is what an
+ * owner dragging track expects to happen.
+ *
+ * Present = `pos` / `fromPos` / `toPos` are DERIVED from this by
+ * {@link graphToDoc}. Absent = the authored numbers stand, exactly as before —
+ * nothing migrates (ADR 0001).
+ */
+interface GraphAnchor {
+    /** The {@link TrackPiece} it sits on. */
+    piece: string;
+    /**
+     * Inches along that piece from its OWN origin end — joint `a` on flex, the
+     * throat on a turnout, and in every case the part's x=0.
+     *
+     * ⚠️ Deliberately NOT "from the end the walk came in by". Which end that is
+     * depends on where the module's endplate A happens to be, so the same spot
+     * beside the same rail would mean two different numbers on two modules.
+     */
+    atInches: number;
+}
 interface IndustrySpot {
     track: string;
     fromPos: number;
     toPos: number;
     side?: SignalSide;
+    /** Hold this spot by the piece it is beside (ADR 0001). See {@link GraphAnchor}. */
+    anchor?: GraphAnchor | null;
 }
 interface SchematicIndustry {
     id: string;
@@ -312,6 +344,10 @@ interface SchematicIndustry {
     /** The primary car-spot span along `track`, inches from endplate A. */
     fromPos: number;
     toPos: number;
+    /** Hold this span by the piece it is beside (ADR 0001). See {@link GraphAnchor}.
+     * The span's LENGTH stays authored — a dock face is as long as it is built;
+     * only where it begins is read off the track. */
+    anchor?: GraphAnchor | null;
     /** Extra car-spot spans on other tracks — the industry's house-track spots. */
     spots?: IndustrySpot[];
     /** Which side of the track the building + label sit on. */
@@ -392,6 +428,27 @@ interface ModuleSchematicDoc {
      * shape; absent = derive it as a lane offset from Main 1. Physical view only
      * (#131). */
     main2Path?: BenchworkPoint[] | null;
+    /**
+     * ⭐⭐ THE AUTHORED TRACK, when this module was drawn as PIECES (ADR 0001).
+     *
+     * Present = this is the source, and `tracks`, `turnouts` and every anchored
+     * feature's position are DERIVED from it by {@link deriveGraphDoc} — they are
+     * still written into the document so that everything downstream, Free-
+     * Dispatcher included, reads an ordinary document and is never told which way
+     * the module was authored.
+     *
+     * Absent = the module is authored the way it always was, and nothing about it
+     * changes. No document is converted (ADR 0001): converting one would mean
+     * inventing the leads, frogs and radii nobody measured.
+     */
+    graph?: {
+        pieces: TrackPiece[];
+        /** Where the main starts: the joint endplate A's track arrives at. */
+        startAt: {
+            piece: string;
+            joint: string;
+        };
+    } | null;
 }
 /** A benchwork-outline vertex, module-local inches. The edge from this vertex
  * to the NEXT one is a straight line, unless `bulge` is set — then it's a
@@ -1122,6 +1179,8 @@ interface EditorIndustry {
     carTypes: string[];
     /** freemon_industries row (single source of truth), or null for a new one. */
     moduleIndustryId: number | null;
+    /** The piece this span is held by (ADR 0001). See {@link GraphAnchor}. */
+    anchor?: GraphAnchor | null;
 }
 /** A 3rd+ endplate — a branch/junction connection off the module (#170).
  * A module may have several (e.g. a set carrying a second railroad through:
@@ -1216,6 +1275,10 @@ interface EditorState {
     mainPath: BenchworkPoint[];
     /** Authored Main 2 centre-line (double-track only) — empty = lane offset (#131). */
     main2Path: BenchworkPoint[];
+    /** ⭐ The track as PLACED PIECES (ADR 0001), when the owner drew it that way.
+     * Absent = authored the way it always was, and nothing changes. See
+     * {@link ModuleSchematicDoc.graph} and {@link deriveGraphDoc}. */
+    graph?: ModuleSchematicDoc["graph"];
 }
 /** Build the empty editor state for a module of the given length. */
 declare function emptyEditorState(lengthInches: number): EditorState;
@@ -2360,6 +2423,27 @@ declare function partGeometryGap(part: TrackPart): string | null;
  * which you got.
  */
 declare function partGeometry(part: TrackPart, library?: TrackPart[]): PartGeometry | null;
+/**
+ * The SHAPE of every route through a placed piece, in MODULE inches — the
+ * polyline a renderer draws.
+ *
+ * ⭐ The shape belongs to the PART, so it lives here rather than in either app's
+ * canvas. A diverging route drawn as a straight chord from throat to diverging
+ * end cuts the corner the closure actually turns; every renderer would have to
+ * rebuild that curve, and they would drift.
+ *
+ * ⚠️ Each polyline ENDS EXACTLY ON ITS JOINTS, by construction — the samples in
+ * between follow the closure, but the ends are the joint positions themselves.
+ * Track that stops short of its own joint would draw a gap at a connection that
+ * the graph considers made.
+ */
+declare function pieceRoutePaths(piece: TrackPiece, library?: TrackPart[]): {
+    route: [string, string];
+    points: {
+        x: number;
+        y: number;
+    }[];
+}[];
 /** Every part that can be PLACED on a board today, and every one that can only
  * be named — with the reason. The gap list is the parts backlog. */
 declare function partsPlaceable(library?: TrackPart[]): {
@@ -2446,6 +2530,45 @@ declare function placedJoints(pieces: TrackPiece[], library?: TrackPart[]): Plac
  * part carrying three joints of its own.
  */
 declare function buildTrackGraph(pieces: TrackPiece[], library?: TrackPart[], snapInches?: number): TrackGraph;
+/** A piece as the route crosses it — what an anchored feature resolves against. */
+interface RouteSpan {
+    piece: string;
+    /** The joints the route entered and left this piece by. Tell you which way
+     * round the piece's own measurements run against the route's. */
+    entryJoint: string;
+    exitJoint: string;
+    /** Inches from endplate A at the entry joint, and at the one it left by. */
+    fromPos: number;
+    toPos: number;
+}
+/** A piece moved into place against an open joint. */
+interface PieceSnap {
+    /** The piece, rotated and translated so the two joints coincide. */
+    piece: TrackPiece;
+    /** The moving joint's key, and the open joint it was brought onto. */
+    from: string;
+    to: string;
+}
+/**
+ * Bring a piece being dragged onto the nearest OPEN joint of the others.
+ *
+ * ⛔ **ONLY OPEN JOINTS ARE CANDIDATES, and that is the ADR's standing rule
+ * enforced where it can still be obeyed.** A joint already holding a connection
+ * is not offered, so an owner cannot stack a third rail end on a joint at all —
+ * rather than stacking it and having {@link buildTrackGraph} refuse all three
+ * afterwards, with a piece silently outside the layout until they notice.
+ *
+ * The piece is ROTATED as well as moved: two ends meet when they are in the same
+ * place and facing opposite ways, so the rotation falls out of the joint it is
+ * brought to. That is what makes laying a curve out of straight pieces possible
+ * without typing an angle.
+ *
+ * `withinInches` is a GRAB radius — how near counts as "meant it" — and is a
+ * different thing from {@link JOINT_SNAP_INCHES}, which is how close two joints
+ * must be to BE connected. This one is generous; that one is a hundredth of an
+ * inch.
+ */
+declare function snapPiece(moving: TrackPiece, others: TrackPiece[], library?: TrackPart[], withinInches?: number): PieceSnap | null;
 /** A route the walk found: a continuous run of pieces a train can travel. */
 interface GraphRoute {
     id: string;
@@ -2457,6 +2580,8 @@ interface GraphRoute {
     /** The turnout it runs back into. Set = a SIDING; null = it dead-ends. */
     endsAt: string | null;
     pieces: string[];
+    /** The same pieces, each with where it starts and ends along the route. */
+    spans: RouteSpan[];
     /** Furthest lateral offset reached — what gives a lane its side. */
     lateral: number;
 }
@@ -2488,6 +2613,94 @@ declare function walkTrackGraph(graph: TrackGraph, pieces: TrackPiece[], startAt
     piece: string;
     joint: string;
 }, library?: TrackPart[]): GraphWalk;
+/** Where an anchored feature turned out to be. */
+interface ResolvedAnchor {
+    /** Inches from endplate A — the number the document and the dispatcher read. */
+    pos: number;
+    /** The route the anchored piece is part of. */
+    routeId: string;
+    /** The piece's own measuring direction runs BACKWARD along the route, so
+     * increasing {@link GraphAnchor.atInches} moves toward endplate A. */
+    reversed: boolean;
+}
+/**
+ * Turn a {@link GraphAnchor} into a position along the module.
+ *
+ * The piece is measured from its own origin end, and the walk knows both ends
+ * of it, so whichever end the route arrived by, the sum comes out the same.
+ * Returns null when the anchored piece is not on any route — a spur nobody has
+ * connected yet — which is a thing to report, not to guess at.
+ */
+declare function resolveGraphAnchor(anchor: GraphAnchor, walk: GraphWalk, pieces: TrackPiece[], library?: TrackPart[]): ResolvedAnchor | null;
+/** What the graph cannot know, and therefore never invents. */
+interface GraphDocInput {
+    /** Where the main begins: the joint endplate A's track arrives at. */
+    startAt: {
+        piece: string;
+        joint: string;
+    };
+    /**
+     * The rest of the document — module id, endplate identities, the benchwork,
+     * industries and signals. Merged UNDERNEATH the derived keys, so the graph
+     * wins on length, tracks and turnouts and on nothing else.
+     *
+     * ⏸️ Industries, signals and control points are PASSED THROUGH untouched.
+     * Where they live in a graph is deliberately still open (ADR 0001 defers it
+     * to persistence); carrying them is honest, re-deriving them would be a guess.
+     */
+    base?: Partial<ModuleSchematicDoc>;
+    /**
+     * Owner metadata for a run, keyed by the piece the run STARTS at — the piece
+     * they select and name. Held here rather than on {@link TrackPiece} because
+     * it describes the whole run, not the one piece.
+     */
+    meta?: Record<string, {
+        trackName?: string;
+        capacityFeet?: number | null;
+        moduleTrackId?: number | null;
+    }>;
+    library?: TrackPart[];
+}
+interface GraphDocResult {
+    doc: ModuleSchematicDoc;
+    graph: TrackGraph;
+    walk: GraphWalk;
+    /** The walk's warnings, plus anything the emission itself had to leave out. */
+    warnings: string[];
+}
+/**
+ * Derive a `ModuleSchematicDoc` from placed pieces.
+ *
+ * ⭐ **NO HAND IS EMITTED.** A turnout's `kind` is left unset on purpose. The
+ * graph knows which side the diverging route is on — it is where the piece IS —
+ * so the lane carries the side and `moduleFeatures` keeps the lane it is given
+ * (`resolveLane` only overrides the sign for a stated left/right). Emitting a
+ * hand as well would be a second source for one fact, which is the ~120 lines
+ * of reconciliation this model exists to remove.
+ *
+ * ⚠️ ONE MAIN. The walk starts at one endplate, so a double-track module's
+ * second main is not reached — it surfaces in `warnings` as unreachable pieces
+ * rather than vanishing quietly. Emitting Main 2 needs a second start point and
+ * is not built yet.
+ */
+declare function graphToDoc(pieces: TrackPiece[], input: GraphDocInput): GraphDocResult;
+/**
+ * Bring a document up to date with the track its owner drew.
+ *
+ * A document with no `graph` is returned UNTOUCHED — that is the ADR's
+ * no-migration rule in one line, and it is why every module authored before this
+ * keeps behaving exactly as it did. With a graph, the tracks and turnouts are
+ * re-read off the pieces and written back into the ordinary document keys, so
+ * the module is stored in a form every existing reader already understands.
+ *
+ * ⭐ Owners' names, capacities and `module_tracks` links are carried across from
+ * the tracks already in the document, keyed by id. Re-deriving must never cost
+ * an owner the name they gave a siding.
+ */
+declare function deriveGraphDoc(doc: ModuleSchematicDoc, library?: TrackPart[]): {
+    doc: ModuleSchematicDoc;
+    warnings: string[];
+};
 /** A frog casting's parts, in TURNOUT-LOCAL inches: `x` = distance past the
  * points, `y` = lateral offset from the through route. */
 interface FrogCasting {
@@ -2769,4 +2982,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 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 };
+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 GraphAnchor, type GraphConflict, type GraphConnection, type GraphDocInput, type GraphDocResult, 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 PieceSnap, type PlacedJoint, RAIL_GAUGE_INCHES, type ResolvedAnchor, type ReturnLoopGeometry, type ReturnLoopShape, type RouteSpan, 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, deriveGraphDoc, divergeSideForHand, docToState, emptyEditorState, endplateCentreOffsetInches, endplateEdgePose, endplateFaceSegments, endplateLead, endplateTrackOffsetInches, endplateWidthInches, flexPartFor, flexParts, flexPieces, flexUsage, frogCasting, frogNumberFromName, fromSectionRelative, geometryTurnDegrees, graphToDoc, 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, pieceRoutePaths, placedJoints, poseNeedsManual, poseOverridesFromDoc, remapPos, resizeFlexPiece, resolveGraphAnchor, returnLoop, sampleBenchworkOutline, samplePartSegments, samplePath, scaleFeetToInches, sectionAdjacency, sectionBand, sectionBreaksFromSections, sectionComponents, sectionFootprints, sectionNeighbours, sectionSpans, sectionSpansOrWhole, sectionedCenterline, sectionedEndPose, sliceCenterline, snapPiece, spanOverhang, stateToDoc, storedPartToTrackPart, toSectionRelative, trackMeetsEndplateIssues, trackPart, trackPath, turnoutClosure, turnoutFacing, turnoutOccupiedSpan, turnoutPartForSize, usableCapacity, walkTrackGraph };

package/dist/index.d.ts

@@ -242,6 +242,9 @@ interface SchematicTurnout {
 interface SchematicSignal {
     id: string;
     pos: number;
+    /** Hold this signal by the piece it stands beside (ADR 0001). See
+     * {@link GraphAnchor} — a mast is planted next to a particular bit of rail. */
+    anchor?: GraphAnchor | null;
     /** Track the signal governs; absent = the primary main (lane 0). */
     track?: string;
     facing?: SignalFacing;
@@ -295,11 +298,40 @@ type IndustryLabelMode = "none" | "cars" | "inches";
  */
 /** One car-spot span of an industry on a track — an industry may have several
  * (a house track serving one customer across multiple spot tracks, #54). */
+/**
+ * ⭐ A PLACE ON THE TRACK, HELD BY THE PIECE THAT IS THERE (ADR 0001).
+ *
+ * `pos` — inches from endplate A — is a fine way to *read* where something is
+ * and a poor way to *hold* it: it is a number about the whole module, so every
+ * edit anywhere upstream silently changes what it means. A car spot belongs to
+ * the rail it is beside. Anchored to the piece, moving that piece takes the
+ * industry with it and moving anything else leaves it alone, which is what an
+ * owner dragging track expects to happen.
+ *
+ * Present = `pos` / `fromPos` / `toPos` are DERIVED from this by
+ * {@link graphToDoc}. Absent = the authored numbers stand, exactly as before —
+ * nothing migrates (ADR 0001).
+ */
+interface GraphAnchor {
+    /** The {@link TrackPiece} it sits on. */
+    piece: string;
+    /**
+     * Inches along that piece from its OWN origin end — joint `a` on flex, the
+     * throat on a turnout, and in every case the part's x=0.
+     *
+     * ⚠️ Deliberately NOT "from the end the walk came in by". Which end that is
+     * depends on where the module's endplate A happens to be, so the same spot
+     * beside the same rail would mean two different numbers on two modules.
+     */
+    atInches: number;
+}
 interface IndustrySpot {
     track: string;
     fromPos: number;
     toPos: number;
     side?: SignalSide;
+    /** Hold this spot by the piece it is beside (ADR 0001). See {@link GraphAnchor}. */
+    anchor?: GraphAnchor | null;
 }
 interface SchematicIndustry {
     id: string;
@@ -312,6 +344,10 @@ interface SchematicIndustry {
     /** The primary car-spot span along `track`, inches from endplate A. */
     fromPos: number;
     toPos: number;
+    /** Hold this span by the piece it is beside (ADR 0001). See {@link GraphAnchor}.
+     * The span's LENGTH stays authored — a dock face is as long as it is built;
+     * only where it begins is read off the track. */
+    anchor?: GraphAnchor | null;
     /** Extra car-spot spans on other tracks — the industry's house-track spots. */
     spots?: IndustrySpot[];
     /** Which side of the track the building + label sit on. */
@@ -392,6 +428,27 @@ interface ModuleSchematicDoc {
      * shape; absent = derive it as a lane offset from Main 1. Physical view only
      * (#131). */
     main2Path?: BenchworkPoint[] | null;
+    /**
+     * ⭐⭐ THE AUTHORED TRACK, when this module was drawn as PIECES (ADR 0001).
+     *
+     * Present = this is the source, and `tracks`, `turnouts` and every anchored
+     * feature's position are DERIVED from it by {@link deriveGraphDoc} — they are
+     * still written into the document so that everything downstream, Free-
+     * Dispatcher included, reads an ordinary document and is never told which way
+     * the module was authored.
+     *
+     * Absent = the module is authored the way it always was, and nothing about it
+     * changes. No document is converted (ADR 0001): converting one would mean
+     * inventing the leads, frogs and radii nobody measured.
+     */
+    graph?: {
+        pieces: TrackPiece[];
+        /** Where the main starts: the joint endplate A's track arrives at. */
+        startAt: {
+            piece: string;
+            joint: string;
+        };
+    } | null;
 }
 /** A benchwork-outline vertex, module-local inches. The edge from this vertex
  * to the NEXT one is a straight line, unless `bulge` is set — then it's a
@@ -1122,6 +1179,8 @@ interface EditorIndustry {
     carTypes: string[];
     /** freemon_industries row (single source of truth), or null for a new one. */
     moduleIndustryId: number | null;
+    /** The piece this span is held by (ADR 0001). See {@link GraphAnchor}. */
+    anchor?: GraphAnchor | null;
 }
 /** A 3rd+ endplate — a branch/junction connection off the module (#170).
  * A module may have several (e.g. a set carrying a second railroad through:
@@ -1216,6 +1275,10 @@ interface EditorState {
     mainPath: BenchworkPoint[];
     /** Authored Main 2 centre-line (double-track only) — empty = lane offset (#131). */
     main2Path: BenchworkPoint[];
+    /** ⭐ The track as PLACED PIECES (ADR 0001), when the owner drew it that way.
+     * Absent = authored the way it always was, and nothing changes. See
+     * {@link ModuleSchematicDoc.graph} and {@link deriveGraphDoc}. */
+    graph?: ModuleSchematicDoc["graph"];
 }
 /** Build the empty editor state for a module of the given length. */
 declare function emptyEditorState(lengthInches: number): EditorState;
@@ -2360,6 +2423,27 @@ declare function partGeometryGap(part: TrackPart): string | null;
  * which you got.
  */
 declare function partGeometry(part: TrackPart, library?: TrackPart[]): PartGeometry | null;
+/**
+ * The SHAPE of every route through a placed piece, in MODULE inches — the
+ * polyline a renderer draws.
+ *
+ * ⭐ The shape belongs to the PART, so it lives here rather than in either app's
+ * canvas. A diverging route drawn as a straight chord from throat to diverging
+ * end cuts the corner the closure actually turns; every renderer would have to
+ * rebuild that curve, and they would drift.
+ *
+ * ⚠️ Each polyline ENDS EXACTLY ON ITS JOINTS, by construction — the samples in
+ * between follow the closure, but the ends are the joint positions themselves.
+ * Track that stops short of its own joint would draw a gap at a connection that
+ * the graph considers made.
+ */
+declare function pieceRoutePaths(piece: TrackPiece, library?: TrackPart[]): {
+    route: [string, string];
+    points: {
+        x: number;
+        y: number;
+    }[];
+}[];
 /** Every part that can be PLACED on a board today, and every one that can only
  * be named — with the reason. The gap list is the parts backlog. */
 declare function partsPlaceable(library?: TrackPart[]): {
@@ -2446,6 +2530,45 @@ declare function placedJoints(pieces: TrackPiece[], library?: TrackPart[]): Plac
  * part carrying three joints of its own.
  */
 declare function buildTrackGraph(pieces: TrackPiece[], library?: TrackPart[], snapInches?: number): TrackGraph;
+/** A piece as the route crosses it — what an anchored feature resolves against. */
+interface RouteSpan {
+    piece: string;
+    /** The joints the route entered and left this piece by. Tell you which way
+     * round the piece's own measurements run against the route's. */
+    entryJoint: string;
+    exitJoint: string;
+    /** Inches from endplate A at the entry joint, and at the one it left by. */
+    fromPos: number;
+    toPos: number;
+}
+/** A piece moved into place against an open joint. */
+interface PieceSnap {
+    /** The piece, rotated and translated so the two joints coincide. */
+    piece: TrackPiece;
+    /** The moving joint's key, and the open joint it was brought onto. */
+    from: string;
+    to: string;
+}
+/**
+ * Bring a piece being dragged onto the nearest OPEN joint of the others.
+ *
+ * ⛔ **ONLY OPEN JOINTS ARE CANDIDATES, and that is the ADR's standing rule
+ * enforced where it can still be obeyed.** A joint already holding a connection
+ * is not offered, so an owner cannot stack a third rail end on a joint at all —
+ * rather than stacking it and having {@link buildTrackGraph} refuse all three
+ * afterwards, with a piece silently outside the layout until they notice.
+ *
+ * The piece is ROTATED as well as moved: two ends meet when they are in the same
+ * place and facing opposite ways, so the rotation falls out of the joint it is
+ * brought to. That is what makes laying a curve out of straight pieces possible
+ * without typing an angle.
+ *
+ * `withinInches` is a GRAB radius — how near counts as "meant it" — and is a
+ * different thing from {@link JOINT_SNAP_INCHES}, which is how close two joints
+ * must be to BE connected. This one is generous; that one is a hundredth of an
+ * inch.
+ */
+declare function snapPiece(moving: TrackPiece, others: TrackPiece[], library?: TrackPart[], withinInches?: number): PieceSnap | null;
 /** A route the walk found: a continuous run of pieces a train can travel. */
 interface GraphRoute {
     id: string;
@@ -2457,6 +2580,8 @@ interface GraphRoute {
     /** The turnout it runs back into. Set = a SIDING; null = it dead-ends. */
     endsAt: string | null;
     pieces: string[];
+    /** The same pieces, each with where it starts and ends along the route. */
+    spans: RouteSpan[];
     /** Furthest lateral offset reached — what gives a lane its side. */
     lateral: number;
 }
@@ -2488,6 +2613,94 @@ declare function walkTrackGraph(graph: TrackGraph, pieces: TrackPiece[], startAt
     piece: string;
     joint: string;
 }, library?: TrackPart[]): GraphWalk;
+/** Where an anchored feature turned out to be. */
+interface ResolvedAnchor {
+    /** Inches from endplate A — the number the document and the dispatcher read. */
+    pos: number;
+    /** The route the anchored piece is part of. */
+    routeId: string;
+    /** The piece's own measuring direction runs BACKWARD along the route, so
+     * increasing {@link GraphAnchor.atInches} moves toward endplate A. */
+    reversed: boolean;
+}
+/**
+ * Turn a {@link GraphAnchor} into a position along the module.
+ *
+ * The piece is measured from its own origin end, and the walk knows both ends
+ * of it, so whichever end the route arrived by, the sum comes out the same.
+ * Returns null when the anchored piece is not on any route — a spur nobody has
+ * connected yet — which is a thing to report, not to guess at.
+ */
+declare function resolveGraphAnchor(anchor: GraphAnchor, walk: GraphWalk, pieces: TrackPiece[], library?: TrackPart[]): ResolvedAnchor | null;
+/** What the graph cannot know, and therefore never invents. */
+interface GraphDocInput {
+    /** Where the main begins: the joint endplate A's track arrives at. */
+    startAt: {
+        piece: string;
+        joint: string;
+    };
+    /**
+     * The rest of the document — module id, endplate identities, the benchwork,
+     * industries and signals. Merged UNDERNEATH the derived keys, so the graph
+     * wins on length, tracks and turnouts and on nothing else.
+     *
+     * ⏸️ Industries, signals and control points are PASSED THROUGH untouched.
+     * Where they live in a graph is deliberately still open (ADR 0001 defers it
+     * to persistence); carrying them is honest, re-deriving them would be a guess.
+     */
+    base?: Partial<ModuleSchematicDoc>;
+    /**
+     * Owner metadata for a run, keyed by the piece the run STARTS at — the piece
+     * they select and name. Held here rather than on {@link TrackPiece} because
+     * it describes the whole run, not the one piece.
+     */
+    meta?: Record<string, {
+        trackName?: string;
+        capacityFeet?: number | null;
+        moduleTrackId?: number | null;
+    }>;
+    library?: TrackPart[];
+}
+interface GraphDocResult {
+    doc: ModuleSchematicDoc;
+    graph: TrackGraph;
+    walk: GraphWalk;
+    /** The walk's warnings, plus anything the emission itself had to leave out. */
+    warnings: string[];
+}
+/**
+ * Derive a `ModuleSchematicDoc` from placed pieces.
+ *
+ * ⭐ **NO HAND IS EMITTED.** A turnout's `kind` is left unset on purpose. The
+ * graph knows which side the diverging route is on — it is where the piece IS —
+ * so the lane carries the side and `moduleFeatures` keeps the lane it is given
+ * (`resolveLane` only overrides the sign for a stated left/right). Emitting a
+ * hand as well would be a second source for one fact, which is the ~120 lines
+ * of reconciliation this model exists to remove.
+ *
+ * ⚠️ ONE MAIN. The walk starts at one endplate, so a double-track module's
+ * second main is not reached — it surfaces in `warnings` as unreachable pieces
+ * rather than vanishing quietly. Emitting Main 2 needs a second start point and
+ * is not built yet.
+ */
+declare function graphToDoc(pieces: TrackPiece[], input: GraphDocInput): GraphDocResult;
+/**
+ * Bring a document up to date with the track its owner drew.
+ *
+ * A document with no `graph` is returned UNTOUCHED — that is the ADR's
+ * no-migration rule in one line, and it is why every module authored before this
+ * keeps behaving exactly as it did. With a graph, the tracks and turnouts are
+ * re-read off the pieces and written back into the ordinary document keys, so
+ * the module is stored in a form every existing reader already understands.
+ *
+ * ⭐ Owners' names, capacities and `module_tracks` links are carried across from
+ * the tracks already in the document, keyed by id. Re-deriving must never cost
+ * an owner the name they gave a siding.
+ */
+declare function deriveGraphDoc(doc: ModuleSchematicDoc, library?: TrackPart[]): {
+    doc: ModuleSchematicDoc;
+    warnings: string[];
+};
 /** A frog casting's parts, in TURNOUT-LOCAL inches: `x` = distance past the
  * points, `y` = lateral offset from the through route. */
 interface FrogCasting {
@@ -2769,4 +2982,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 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 };
+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 GraphAnchor, type GraphConflict, type GraphConnection, type GraphDocInput, type GraphDocResult, 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 PieceSnap, type PlacedJoint, RAIL_GAUGE_INCHES, type ResolvedAnchor, type ReturnLoopGeometry, type ReturnLoopShape, type RouteSpan, 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, deriveGraphDoc, divergeSideForHand, docToState, emptyEditorState, endplateCentreOffsetInches, endplateEdgePose, endplateFaceSegments, endplateLead, endplateTrackOffsetInches, endplateWidthInches, flexPartFor, flexParts, flexPieces, flexUsage, frogCasting, frogNumberFromName, fromSectionRelative, geometryTurnDegrees, graphToDoc, 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, pieceRoutePaths, placedJoints, poseNeedsManual, poseOverridesFromDoc, remapPos, resizeFlexPiece, resolveGraphAnchor, returnLoop, sampleBenchworkOutline, samplePartSegments, samplePath, scaleFeetToInches, sectionAdjacency, sectionBand, sectionBreaksFromSections, sectionComponents, sectionFootprints, sectionNeighbours, sectionSpans, sectionSpansOrWhole, sectionedCenterline, sectionedEndPose, sliceCenterline, snapPiece, spanOverhang, stateToDoc, storedPartToTrackPart, toSectionRelative, trackMeetsEndplateIssues, trackPart, trackPath, turnoutClosure, turnoutFacing, turnoutOccupiedSpan, turnoutPartForSize, usableCapacity, walkTrackGraph };