@willcgage/module-schematic 0.85.0 → 0.89.0

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;
@@ -2369,6 +2432,226 @@ 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 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 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[];
+    /** 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;
+}
+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;
+/** 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 {
@@ -2650,4 +2933,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 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, 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, 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 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 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, placedJoints, poseNeedsManual, poseOverridesFromDoc, remapPos, resizeFlexPiece, resolveGraphAnchor, 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 };