@willcgage/module-schematic 0.97.1 → 0.101.0

package/dist/index.d.cts

@@ -677,6 +677,12 @@ interface ModuleFootprintInput {
     /** A balloon / return loop — the centre-line turns back on itself, so its far
      * end is the THROAT, not an endplate; only endplate A's face is emitted (#loop). */
     loop?: boolean;
+    /**
+     * The document already places track along a main (see {@link
+     * moduleCenterline}). Set from the doc's own `tracks`; without it a module
+     * whose track was authored before it had a geometry draws as a bare board.
+     */
+    hasPlacedTrack?: boolean;
     /** Axial endplate configs (A first, then B), same as
      * {@link ModuleGeometryInput.endplateConfigs}. `"none"` at B means the module
      * presents no far endplate, so no face is emitted there (#184/#191). */
@@ -2151,6 +2157,19 @@ interface PartExtent {
     aheadOfPoints: number;
     /** Frog → the far end. How much turnout there still is past the frog. */
     pastFrog: number;
+    /**
+     * Frog → the NEAR end of the tie strip.
+     *
+     * ⭐⭐ **THIS IS THE ONE A BODY IS MEASURED BACK FROM.** A document's `pos` is
+     * the FROG (Will, 2026-07-27), so a turnout occupies
+     * `[pos − behindFrog, pos + pastFrog]`. Anchoring on the points instead put
+     * every turnout body `lead` too far along — 3.59″ on an Atlas #7.
+     *
+     * ⚠️ Falls back to `behindPoints` when the frog was never measured: without a
+     * frog reading there is nowhere to anchor, and the points is the only landmark
+     * left. `pastFrog` degrades the same way, so the pair stays consistent.
+     */
+    behindFrog: number;
 }
 /**
  * A part's real extent, or **null when it hasn't been measured**.
@@ -2744,6 +2763,35 @@ declare function snapPiece(moving: TrackPiece, others: TrackPiece[], library?: T
  * owner's curve to reach something is not a fit, it is a guess.
  */
 declare function fitFlexBetween(piece: TrackPiece, others: TrackPiece[], library?: TrackPart[], withinInches?: number): TrackPiece | null;
+/** A run cut in two to let a piece in. */
+interface RunInsertion {
+    /** The whole set: the host shortened, the new piece, and the remainder. */
+    pieces: TrackPiece[];
+    /** The run that was cut, and the piece that went into it. */
+    hostId: string;
+    insertedId: string;
+}
+/**
+ * Drop a piece ONTO a run and cut the run to take it.
+ *
+ * ⭐ Will, 2026-07-27: *"When I drop a turnout on the track, it should cut the
+ * track there and automatically snap to the new joints."* Snapping alone cannot
+ * do this: the middle of a run has no open joint, so there is nothing to snap
+ * TO — the joints have to be made by cutting, which is exactly what a builder
+ * does with a razor saw.
+ *
+ * ⚠️ ONLY FLEX CAN BE CUT. A turnout or a sectional piece is a moulding: you
+ * cannot saw one in half and have two of anything. Dropping onto one is refused
+ * rather than fudged.
+ *
+ * ⚠️ AND THE PIECE HAS TO FIT. It consumes length along the run — a #7 is six
+ * inches of it — so an insertion that would run off the end is refused instead
+ * of silently producing a remainder of negative length.
+ */
+declare function insertIntoRun(pieces: TrackPiece[], fresh: TrackPiece, at: {
+    x: number;
+    y: number;
+}, library?: TrackPart[], withinInches?: number): RunInsertion | null;
 /** A route the walk found: a continuous run of pieces a train can travel. */
 interface GraphRoute {
     id: string;
@@ -2893,6 +2941,177 @@ declare function deriveGraphDoc(doc: ModuleSchematicDoc, library?: TrackPart[]):
     doc: ModuleSchematicDoc;
     warnings: string[];
 };
+/**
+ * What a turnout in a 1-D document would become as a piece — or what it is
+ * missing before it can become anything.
+ *
+ * ⭐⭐ **IDENTITY IS THE GATE, NOT GEOMETRY.** This is the thing that surprised
+ * us and it is worth stating plainly: converting a drawn module to pieces is
+ * blocked far more often by not knowing WHICH TURNOUT IT IS than by any missing
+ * measurement. Across the production database not one turnout names a part, and
+ * most state no frog number either — so for those there is nothing to look up.
+ * No amount of measuring fixes that; only the owner knows what they laid, which
+ * is exactly why conversion asks instead of guessing.
+ */
+interface TurnoutIdentity {
+    /** The turnout's id in the document. */
+    id: string;
+    name?: string | null;
+    pos: number;
+    /** The frog number the document states, if any. */
+    size?: number | null;
+    /** A part the document already names — the strongest possible answer. */
+    statedPartId?: string | null;
+    /** The part this turnout converts to; null = the owner has to say. */
+    partId: string | null;
+    /** How `partId` was arrived at. */
+    from: "named" | "frog-number" | "unresolved";
+    /**
+     * The weakest provenance behind the chosen part's geometry, so a caller can
+     * tell a turnout placed from real readings from one placed off a catalogue
+     * figure. Null when unresolved.
+     */
+    source: DimensionSource | null;
+    /** Why it cannot be resolved — null when it can. */
+    why: string | null;
+    /**
+     * Parts the owner could reasonably pick, best first: an exact frog match
+     * ahead of the rest. Only PLACEABLE parts are offered — listing one that
+     * cannot be drawn would be an answer that does not answer.
+     */
+    candidates: string[];
+}
+/** Something that stops a whole document converting, whatever the owner says. */
+interface ConversionBlocker {
+    /** `crossing` · `curved-turnout` · `loop` — the shapes with no piece to be. */
+    kind: string;
+    /** The document object it came from, where there is one. */
+    ref?: string;
+    why: string;
+}
+/**
+ * A track the document draws but nothing in it connects — no turnout diverges
+ * onto it.
+ *
+ * ⚠️⚠️ **THE 1-D MODEL TOLERATES THIS AND THE GRAPH CANNOT.** A siding is drawn
+ * from its `lane` and its `fromPos`/`toPos` alone, so a document can carry a
+ * named, capacity-bearing yard track that joins nothing at all and still look
+ * completely normal. Real ones do: Idaho Falls Grain Yard has five yard tracks
+ * and not one turnout. A piece, by contrast, has to be joined to something.
+ *
+ * So these are surfaced rather than converted. Dropping them would lose an
+ * owner's named track and its capacity silently, and inventing a turnout to
+ * reach it would be exactly the fabrication ADR 0001 forbids — the owner is the
+ * only one who knows where it actually joins.
+ */
+interface OrphanTrack {
+    id: string;
+    trackName?: string;
+    role: TrackRole;
+    why: string;
+}
+interface ModuleConversionReport {
+    /** Already authored as pieces — there is nothing to convert. */
+    alreadyGraph: boolean;
+    /**
+     * The rebuild can be offered. False when {@link blockers} is non-empty: those
+     * are shapes no answer can supply, so offering would promise something that
+     * cannot finish.
+     */
+    offerable: boolean;
+    /**
+     * True when the rebuild could run right now with nothing asked.
+     *
+     * ⚠️ Requires BOTH that every turnout resolves and that no track is orphaned.
+     * Checking only the turnouts claimed four production modules were ready when
+     * converting them would have quietly dropped nine named tracks.
+     */
+    readyWithoutAsking: boolean;
+    turnouts: TurnoutIdentity[];
+    /** Ids of the turnouts the owner must identify first. */
+    unanswered: string[];
+    orphanTracks: OrphanTrack[];
+    blockers: ConversionBlocker[];
+}
+/**
+ * What would happen if this document were rebuilt as pieces — WITHOUT rebuilding
+ * anything.
+ *
+ * This exists so an owner can be shown the offer and its cost before they accept
+ * it (ADR 0001 amendment, 2026-07-27: conversion is opt-in PER MODULE, never
+ * silent). It is pure, cheap, reads no geometry, and is safe to run on every
+ * module in a list.
+ *
+ * ⚠️ **A document with a graph is NOT re-reported.** It is already the thing
+ * conversion produces.
+ */
+declare function moduleConversionReport(doc: ModuleSchematicDoc, library?: TrackPart[]): ModuleConversionReport;
+/**
+ * What the owner said when offered the rebuild.
+ *
+ * ⭐ **ONE ANSWER FOR THE WHOLE MODULE.** Owners lay one kind of turnout
+ * throughout, or at most two, so asking per turnout asks the same question eight
+ * times on a yard. The module-wide answer IS the question; `overrides` is for the
+ * odd one out. (Will's call, 2026-07-27 — it turns 41 questions across the
+ * production database into 14.)
+ */
+interface ConversionAnswers {
+    /** "The turnouts on this module are…" — a part id from the library. */
+    turnoutPartId?: string | null;
+    /** The exceptions, by turnout id. Beats {@link turnoutPartId}. */
+    overrides?: Record<string, string>;
+}
+interface DocToGraphResult {
+    /** The graph to store, or null when the document could not be converted. */
+    graph: NonNullable<ModuleSchematicDoc["graph"]> | null;
+    /** Why the whole conversion was refused — null when it ran. */
+    refused: string | null;
+    /**
+     * Track the conversion could not lay, each with a reason.
+     *
+     * ⚠️ **A REAL LOSS, AND THE OWNER MUST SEE IT.** Unshown, a "successful"
+     * rebuild would quietly be missing a named siding.
+     */
+    notLaid: {
+        id: string;
+        why: string;
+    }[];
+    warnings: string[];
+}
+/**
+ * Rebuild a 1-D document as a graph of placed pieces.
+ *
+ * ⭐ **THE OWNER ASKED FOR THIS ONE MODULE** (ADR 0001 amendment, 2026-07-27).
+ * Nothing calls it on a schedule, on load, or in bulk. Conversion supplies
+ * geometry the 1-D document never recorded, which is what the original
+ * constraint forbade doing behind an owner's back; done in front of them, having
+ * shown them {@link moduleConversionReport} and taken their answer, it is an
+ * edit they made.
+ *
+ * ⚠️ **STRAIGHT HOSTS ONLY.** A run is laid along its host's axis, so a module
+ * whose main is DRAWN with bends is refused rather than quietly straightened.
+ * Every module in production today has a straight main; the refusal is there so
+ * the first curved one is a message and not a flattened drawing.
+ *
+ * ⭐ **PIECES CHAIN FROM MEASURED JOINTS, NOT FROM ABSOLUTE ARITHMETIC.** Each
+ * piece is placed, its real joints are read back with {@link placedJoints}, and
+ * the next starts from one of those. Connection then holds BY CONSTRUCTION
+ * rather than by two independent calculations agreeing to within
+ * {@link JOINT_SNAP_INCHES} — a hundredth of an inch is far too tight to hit by
+ * coincidence.
+ *
+
+ * ⭐ A TURNOUT'S THROAT GOES AT `pos − frogOffset`: a document's `pos` is the
+ * That is the inverse of what {@link walkTrackGraph} reports, which is the only
+ * thing that makes convert-then-derive an identity. It is deliberately NOT
+ * {@link turnoutOccupiedSpan}'s anchor, and the two disagree by
+ * `lead − pointsOffset` — 2.97″ on an Atlas #7. That disagreement is real and
+ * unresolved: see the note on {@link moduleConversionReport}. Because of it the
+ * flex gaps here are measured off the placed pieces' OWN joints rather than
+ * through the 1-D helper, so whichever anchor turns out to be right, the track
+ * still meets the turnout it was cut for.
+ */
+declare function docToGraph(doc: ModuleSchematicDoc, answers?: ConversionAnswers, library?: TrackPart[]): DocToGraphResult;
 /** A frog casting's parts, in TURNOUT-LOCAL inches: `x` = distance past the
  * points, `y` = lateral offset from the through route. */
 interface FrogCasting {
@@ -3174,4 +3393,4 @@ declare function poseOverridesFromDoc(doc: ModuleSchematicDoc): Record<string, {
     heading: number;
 }>;
 
-export { ATLAS_CODE55_N, BUILT_IN_TRACK_PARTS, BUMPER_DRAWN_INCHES, 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_MAIN_MIN_RADIUS_INCHES, FREEMO_REVERSE_CURVE_STRAIGHT_INCHES, FREEMO_TRACK_SPACING_INCHES, type FlexPiece, type FlexPieceEnd, type FrogCasting, GENERIC_END_OF_TRACK, 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, TRACK_PART_KINDS, 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, fitFlexBetween, flexPartFor, flexParts, flexPieces, flexRunEnd, 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, pieceHand, piecePartNumber, pieceRoutePaths, placedJoints, poseNeedsManual, poseOverridesFromDoc, remapPos, resizeFlexPiece, resolveGraphAnchor, returnLoop, sampleBenchworkOutline, samplePartSegments, samplePath, scaleFeetToInches, sectionAdjacency, sectionBand, sectionBreaksFromSections, sectionComponents, sectionFootprints, sectionNeighbours, sectionSpans, sectionSpansOrWhole, sectionalArcInches, sectionedCenterline, sectionedEndPose, sliceCenterline, snapPiece, spanOverhang, stateToDoc, storedPartToTrackPart, toSectionRelative, trackMeetsEndplateIssues, trackPart, trackPath, turnoutClosure, turnoutFacing, turnoutOccupiedSpan, turnoutPartForSize, usableCapacity, walkTrackGraph };
+export { ATLAS_CODE55_N, BUILT_IN_TRACK_PARTS, BUMPER_DRAWN_INCHES, type BenchworkPoint, type BranchConnector, CLEARANCE_SPACING_INCHES, CODE55_RAIL_HEIGHT_INCHES, type ConversionAnswers, type ConversionBlocker, DEFAULT_FLEX_PART_ID, type DimensionSource, type DocToGraphResult, 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_MAIN_MIN_RADIUS_INCHES, FREEMO_REVERSE_CURVE_STRAIGHT_INCHES, FREEMO_TRACK_SPACING_INCHES, type FlexPiece, type FlexPieceEnd, type FrogCasting, GENERIC_END_OF_TRACK, 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 ModuleConversionReport, type ModuleFeatures, type ModuleFootprint, type ModuleFootprintInput, type ModuleGeometryInput, type ModuleSchematicDoc, type ModuleTrackRow, N_CAR_LENGTH_INCHES, N_SCALE_RATIO, type OccupiedSpan, type OrphanTrack, 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 RunInsertion, 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, TRACK_PART_KINDS, TURNOUT_LEAD_INCHES_PER_FROG, type TrackConfig, type TrackGraph, type TrackPart, type TrackPiece, type TrackRole, type TurnoutClosure, type TurnoutIdentity, type TurnoutKind, type UsableCapacity, WHOLE_MODULE_SECTION_ID, asModuleSchematic, assessSectionEnd, assessSectionJoint, benchworkBand, benchworkOutline, buildCrossover, buildPassingSiding, buildTrackGraph, buildTransition, carCapacity, checkEndplateWidth, clearancePointPastFrogInches, crossoverPinches, deriveEndplatePoses, deriveGraphDoc, divergeSideForHand, docToGraph, docToState, emptyEditorState, endplateCentreOffsetInches, endplateEdgePose, endplateFaceSegments, endplateLead, endplateTrackOffsetInches, endplateWidthInches, fitFlexBetween, flexPartFor, flexParts, flexPieces, flexRunEnd, flexUsage, frogCasting, frogNumberFromName, fromSectionRelative, geometryTurnDegrees, graphToDoc, hasNoFarEndplate, importedPartToTrackPart, inchesToScaleFeet, insertIntoRun, isLoopDoc, isTransitionTurnout, laneOffsetAt, leadInchesForSize, maxFlexPieceInches, mergeImportedParts, mergeStoredParts, moduleCenterline, moduleConversionReport, moduleFeatures, moduleFootprint, moduleLengthFromSections, moduleSections, nextId, parseXtpLibrary, partExtent, partExtentForSize, partGeometry, partGeometryGap, partOutlineAtFrog, partsPlaceable, pastFrogInchesForSize, pathLengthInches, pieceHand, piecePartNumber, pieceRoutePaths, placedJoints, poseNeedsManual, poseOverridesFromDoc, remapPos, resizeFlexPiece, resolveGraphAnchor, returnLoop, sampleBenchworkOutline, samplePartSegments, samplePath, scaleFeetToInches, sectionAdjacency, sectionBand, sectionBreaksFromSections, sectionComponents, sectionFootprints, sectionNeighbours, sectionSpans, sectionSpansOrWhole, sectionalArcInches, sectionedCenterline, sectionedEndPose, sliceCenterline, snapPiece, spanOverhang, stateToDoc, storedPartToTrackPart, toSectionRelative, trackMeetsEndplateIssues, trackPart, trackPath, turnoutClosure, turnoutFacing, turnoutOccupiedSpan, turnoutPartForSize, usableCapacity, walkTrackGraph };

package/dist/index.d.ts

@@ -677,6 +677,12 @@ interface ModuleFootprintInput {
     /** A balloon / return loop — the centre-line turns back on itself, so its far
      * end is the THROAT, not an endplate; only endplate A's face is emitted (#loop). */
     loop?: boolean;
+    /**
+     * The document already places track along a main (see {@link
+     * moduleCenterline}). Set from the doc's own `tracks`; without it a module
+     * whose track was authored before it had a geometry draws as a bare board.
+     */
+    hasPlacedTrack?: boolean;
     /** Axial endplate configs (A first, then B), same as
      * {@link ModuleGeometryInput.endplateConfigs}. `"none"` at B means the module
      * presents no far endplate, so no face is emitted there (#184/#191). */
@@ -2151,6 +2157,19 @@ interface PartExtent {
     aheadOfPoints: number;
     /** Frog → the far end. How much turnout there still is past the frog. */
     pastFrog: number;
+    /**
+     * Frog → the NEAR end of the tie strip.
+     *
+     * ⭐⭐ **THIS IS THE ONE A BODY IS MEASURED BACK FROM.** A document's `pos` is
+     * the FROG (Will, 2026-07-27), so a turnout occupies
+     * `[pos − behindFrog, pos + pastFrog]`. Anchoring on the points instead put
+     * every turnout body `lead` too far along — 3.59″ on an Atlas #7.
+     *
+     * ⚠️ Falls back to `behindPoints` when the frog was never measured: without a
+     * frog reading there is nowhere to anchor, and the points is the only landmark
+     * left. `pastFrog` degrades the same way, so the pair stays consistent.
+     */
+    behindFrog: number;
 }
 /**
  * A part's real extent, or **null when it hasn't been measured**.
@@ -2744,6 +2763,35 @@ declare function snapPiece(moving: TrackPiece, others: TrackPiece[], library?: T
  * owner's curve to reach something is not a fit, it is a guess.
  */
 declare function fitFlexBetween(piece: TrackPiece, others: TrackPiece[], library?: TrackPart[], withinInches?: number): TrackPiece | null;
+/** A run cut in two to let a piece in. */
+interface RunInsertion {
+    /** The whole set: the host shortened, the new piece, and the remainder. */
+    pieces: TrackPiece[];
+    /** The run that was cut, and the piece that went into it. */
+    hostId: string;
+    insertedId: string;
+}
+/**
+ * Drop a piece ONTO a run and cut the run to take it.
+ *
+ * ⭐ Will, 2026-07-27: *"When I drop a turnout on the track, it should cut the
+ * track there and automatically snap to the new joints."* Snapping alone cannot
+ * do this: the middle of a run has no open joint, so there is nothing to snap
+ * TO — the joints have to be made by cutting, which is exactly what a builder
+ * does with a razor saw.
+ *
+ * ⚠️ ONLY FLEX CAN BE CUT. A turnout or a sectional piece is a moulding: you
+ * cannot saw one in half and have two of anything. Dropping onto one is refused
+ * rather than fudged.
+ *
+ * ⚠️ AND THE PIECE HAS TO FIT. It consumes length along the run — a #7 is six
+ * inches of it — so an insertion that would run off the end is refused instead
+ * of silently producing a remainder of negative length.
+ */
+declare function insertIntoRun(pieces: TrackPiece[], fresh: TrackPiece, at: {
+    x: number;
+    y: number;
+}, library?: TrackPart[], withinInches?: number): RunInsertion | null;
 /** A route the walk found: a continuous run of pieces a train can travel. */
 interface GraphRoute {
     id: string;
@@ -2893,6 +2941,177 @@ declare function deriveGraphDoc(doc: ModuleSchematicDoc, library?: TrackPart[]):
     doc: ModuleSchematicDoc;
     warnings: string[];
 };
+/**
+ * What a turnout in a 1-D document would become as a piece — or what it is
+ * missing before it can become anything.
+ *
+ * ⭐⭐ **IDENTITY IS THE GATE, NOT GEOMETRY.** This is the thing that surprised
+ * us and it is worth stating plainly: converting a drawn module to pieces is
+ * blocked far more often by not knowing WHICH TURNOUT IT IS than by any missing
+ * measurement. Across the production database not one turnout names a part, and
+ * most state no frog number either — so for those there is nothing to look up.
+ * No amount of measuring fixes that; only the owner knows what they laid, which
+ * is exactly why conversion asks instead of guessing.
+ */
+interface TurnoutIdentity {
+    /** The turnout's id in the document. */
+    id: string;
+    name?: string | null;
+    pos: number;
+    /** The frog number the document states, if any. */
+    size?: number | null;
+    /** A part the document already names — the strongest possible answer. */
+    statedPartId?: string | null;
+    /** The part this turnout converts to; null = the owner has to say. */
+    partId: string | null;
+    /** How `partId` was arrived at. */
+    from: "named" | "frog-number" | "unresolved";
+    /**
+     * The weakest provenance behind the chosen part's geometry, so a caller can
+     * tell a turnout placed from real readings from one placed off a catalogue
+     * figure. Null when unresolved.
+     */
+    source: DimensionSource | null;
+    /** Why it cannot be resolved — null when it can. */
+    why: string | null;
+    /**
+     * Parts the owner could reasonably pick, best first: an exact frog match
+     * ahead of the rest. Only PLACEABLE parts are offered — listing one that
+     * cannot be drawn would be an answer that does not answer.
+     */
+    candidates: string[];
+}
+/** Something that stops a whole document converting, whatever the owner says. */
+interface ConversionBlocker {
+    /** `crossing` · `curved-turnout` · `loop` — the shapes with no piece to be. */
+    kind: string;
+    /** The document object it came from, where there is one. */
+    ref?: string;
+    why: string;
+}
+/**
+ * A track the document draws but nothing in it connects — no turnout diverges
+ * onto it.
+ *
+ * ⚠️⚠️ **THE 1-D MODEL TOLERATES THIS AND THE GRAPH CANNOT.** A siding is drawn
+ * from its `lane` and its `fromPos`/`toPos` alone, so a document can carry a
+ * named, capacity-bearing yard track that joins nothing at all and still look
+ * completely normal. Real ones do: Idaho Falls Grain Yard has five yard tracks
+ * and not one turnout. A piece, by contrast, has to be joined to something.
+ *
+ * So these are surfaced rather than converted. Dropping them would lose an
+ * owner's named track and its capacity silently, and inventing a turnout to
+ * reach it would be exactly the fabrication ADR 0001 forbids — the owner is the
+ * only one who knows where it actually joins.
+ */
+interface OrphanTrack {
+    id: string;
+    trackName?: string;
+    role: TrackRole;
+    why: string;
+}
+interface ModuleConversionReport {
+    /** Already authored as pieces — there is nothing to convert. */
+    alreadyGraph: boolean;
+    /**
+     * The rebuild can be offered. False when {@link blockers} is non-empty: those
+     * are shapes no answer can supply, so offering would promise something that
+     * cannot finish.
+     */
+    offerable: boolean;
+    /**
+     * True when the rebuild could run right now with nothing asked.
+     *
+     * ⚠️ Requires BOTH that every turnout resolves and that no track is orphaned.
+     * Checking only the turnouts claimed four production modules were ready when
+     * converting them would have quietly dropped nine named tracks.
+     */
+    readyWithoutAsking: boolean;
+    turnouts: TurnoutIdentity[];
+    /** Ids of the turnouts the owner must identify first. */
+    unanswered: string[];
+    orphanTracks: OrphanTrack[];
+    blockers: ConversionBlocker[];
+}
+/**
+ * What would happen if this document were rebuilt as pieces — WITHOUT rebuilding
+ * anything.
+ *
+ * This exists so an owner can be shown the offer and its cost before they accept
+ * it (ADR 0001 amendment, 2026-07-27: conversion is opt-in PER MODULE, never
+ * silent). It is pure, cheap, reads no geometry, and is safe to run on every
+ * module in a list.
+ *
+ * ⚠️ **A document with a graph is NOT re-reported.** It is already the thing
+ * conversion produces.
+ */
+declare function moduleConversionReport(doc: ModuleSchematicDoc, library?: TrackPart[]): ModuleConversionReport;
+/**
+ * What the owner said when offered the rebuild.
+ *
+ * ⭐ **ONE ANSWER FOR THE WHOLE MODULE.** Owners lay one kind of turnout
+ * throughout, or at most two, so asking per turnout asks the same question eight
+ * times on a yard. The module-wide answer IS the question; `overrides` is for the
+ * odd one out. (Will's call, 2026-07-27 — it turns 41 questions across the
+ * production database into 14.)
+ */
+interface ConversionAnswers {
+    /** "The turnouts on this module are…" — a part id from the library. */
+    turnoutPartId?: string | null;
+    /** The exceptions, by turnout id. Beats {@link turnoutPartId}. */
+    overrides?: Record<string, string>;
+}
+interface DocToGraphResult {
+    /** The graph to store, or null when the document could not be converted. */
+    graph: NonNullable<ModuleSchematicDoc["graph"]> | null;
+    /** Why the whole conversion was refused — null when it ran. */
+    refused: string | null;
+    /**
+     * Track the conversion could not lay, each with a reason.
+     *
+     * ⚠️ **A REAL LOSS, AND THE OWNER MUST SEE IT.** Unshown, a "successful"
+     * rebuild would quietly be missing a named siding.
+     */
+    notLaid: {
+        id: string;
+        why: string;
+    }[];
+    warnings: string[];
+}
+/**
+ * Rebuild a 1-D document as a graph of placed pieces.
+ *
+ * ⭐ **THE OWNER ASKED FOR THIS ONE MODULE** (ADR 0001 amendment, 2026-07-27).
+ * Nothing calls it on a schedule, on load, or in bulk. Conversion supplies
+ * geometry the 1-D document never recorded, which is what the original
+ * constraint forbade doing behind an owner's back; done in front of them, having
+ * shown them {@link moduleConversionReport} and taken their answer, it is an
+ * edit they made.
+ *
+ * ⚠️ **STRAIGHT HOSTS ONLY.** A run is laid along its host's axis, so a module
+ * whose main is DRAWN with bends is refused rather than quietly straightened.
+ * Every module in production today has a straight main; the refusal is there so
+ * the first curved one is a message and not a flattened drawing.
+ *
+ * ⭐ **PIECES CHAIN FROM MEASURED JOINTS, NOT FROM ABSOLUTE ARITHMETIC.** Each
+ * piece is placed, its real joints are read back with {@link placedJoints}, and
+ * the next starts from one of those. Connection then holds BY CONSTRUCTION
+ * rather than by two independent calculations agreeing to within
+ * {@link JOINT_SNAP_INCHES} — a hundredth of an inch is far too tight to hit by
+ * coincidence.
+ *
+
+ * ⭐ A TURNOUT'S THROAT GOES AT `pos − frogOffset`: a document's `pos` is the
+ * That is the inverse of what {@link walkTrackGraph} reports, which is the only
+ * thing that makes convert-then-derive an identity. It is deliberately NOT
+ * {@link turnoutOccupiedSpan}'s anchor, and the two disagree by
+ * `lead − pointsOffset` — 2.97″ on an Atlas #7. That disagreement is real and
+ * unresolved: see the note on {@link moduleConversionReport}. Because of it the
+ * flex gaps here are measured off the placed pieces' OWN joints rather than
+ * through the 1-D helper, so whichever anchor turns out to be right, the track
+ * still meets the turnout it was cut for.
+ */
+declare function docToGraph(doc: ModuleSchematicDoc, answers?: ConversionAnswers, library?: TrackPart[]): DocToGraphResult;
 /** A frog casting's parts, in TURNOUT-LOCAL inches: `x` = distance past the
  * points, `y` = lateral offset from the through route. */
 interface FrogCasting {
@@ -3174,4 +3393,4 @@ declare function poseOverridesFromDoc(doc: ModuleSchematicDoc): Record<string, {
     heading: number;
 }>;
 
-export { ATLAS_CODE55_N, BUILT_IN_TRACK_PARTS, BUMPER_DRAWN_INCHES, 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_MAIN_MIN_RADIUS_INCHES, FREEMO_REVERSE_CURVE_STRAIGHT_INCHES, FREEMO_TRACK_SPACING_INCHES, type FlexPiece, type FlexPieceEnd, type FrogCasting, GENERIC_END_OF_TRACK, 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, TRACK_PART_KINDS, 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, fitFlexBetween, flexPartFor, flexParts, flexPieces, flexRunEnd, 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, pieceHand, piecePartNumber, pieceRoutePaths, placedJoints, poseNeedsManual, poseOverridesFromDoc, remapPos, resizeFlexPiece, resolveGraphAnchor, returnLoop, sampleBenchworkOutline, samplePartSegments, samplePath, scaleFeetToInches, sectionAdjacency, sectionBand, sectionBreaksFromSections, sectionComponents, sectionFootprints, sectionNeighbours, sectionSpans, sectionSpansOrWhole, sectionalArcInches, sectionedCenterline, sectionedEndPose, sliceCenterline, snapPiece, spanOverhang, stateToDoc, storedPartToTrackPart, toSectionRelative, trackMeetsEndplateIssues, trackPart, trackPath, turnoutClosure, turnoutFacing, turnoutOccupiedSpan, turnoutPartForSize, usableCapacity, walkTrackGraph };
+export { ATLAS_CODE55_N, BUILT_IN_TRACK_PARTS, BUMPER_DRAWN_INCHES, type BenchworkPoint, type BranchConnector, CLEARANCE_SPACING_INCHES, CODE55_RAIL_HEIGHT_INCHES, type ConversionAnswers, type ConversionBlocker, DEFAULT_FLEX_PART_ID, type DimensionSource, type DocToGraphResult, 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_MAIN_MIN_RADIUS_INCHES, FREEMO_REVERSE_CURVE_STRAIGHT_INCHES, FREEMO_TRACK_SPACING_INCHES, type FlexPiece, type FlexPieceEnd, type FrogCasting, GENERIC_END_OF_TRACK, 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 ModuleConversionReport, type ModuleFeatures, type ModuleFootprint, type ModuleFootprintInput, type ModuleGeometryInput, type ModuleSchematicDoc, type ModuleTrackRow, N_CAR_LENGTH_INCHES, N_SCALE_RATIO, type OccupiedSpan, type OrphanTrack, 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 RunInsertion, 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, TRACK_PART_KINDS, TURNOUT_LEAD_INCHES_PER_FROG, type TrackConfig, type TrackGraph, type TrackPart, type TrackPiece, type TrackRole, type TurnoutClosure, type TurnoutIdentity, type TurnoutKind, type UsableCapacity, WHOLE_MODULE_SECTION_ID, asModuleSchematic, assessSectionEnd, assessSectionJoint, benchworkBand, benchworkOutline, buildCrossover, buildPassingSiding, buildTrackGraph, buildTransition, carCapacity, checkEndplateWidth, clearancePointPastFrogInches, crossoverPinches, deriveEndplatePoses, deriveGraphDoc, divergeSideForHand, docToGraph, docToState, emptyEditorState, endplateCentreOffsetInches, endplateEdgePose, endplateFaceSegments, endplateLead, endplateTrackOffsetInches, endplateWidthInches, fitFlexBetween, flexPartFor, flexParts, flexPieces, flexRunEnd, flexUsage, frogCasting, frogNumberFromName, fromSectionRelative, geometryTurnDegrees, graphToDoc, hasNoFarEndplate, importedPartToTrackPart, inchesToScaleFeet, insertIntoRun, isLoopDoc, isTransitionTurnout, laneOffsetAt, leadInchesForSize, maxFlexPieceInches, mergeImportedParts, mergeStoredParts, moduleCenterline, moduleConversionReport, moduleFeatures, moduleFootprint, moduleLengthFromSections, moduleSections, nextId, parseXtpLibrary, partExtent, partExtentForSize, partGeometry, partGeometryGap, partOutlineAtFrog, partsPlaceable, pastFrogInchesForSize, pathLengthInches, pieceHand, piecePartNumber, pieceRoutePaths, placedJoints, poseNeedsManual, poseOverridesFromDoc, remapPos, resizeFlexPiece, resolveGraphAnchor, returnLoop, sampleBenchworkOutline, samplePartSegments, samplePath, scaleFeetToInches, sectionAdjacency, sectionBand, sectionBreaksFromSections, sectionComponents, sectionFootprints, sectionNeighbours, sectionSpans, sectionSpansOrWhole, sectionalArcInches, sectionedCenterline, sectionedEndPose, sliceCenterline, snapPiece, spanOverhang, stateToDoc, storedPartToTrackPart, toSectionRelative, trackMeetsEndplateIssues, trackPart, trackPath, turnoutClosure, turnoutFacing, turnoutOccupiedSpan, turnoutPartForSize, usableCapacity, walkTrackGraph };