@willcgage/module-schematic 0.71.0 → 0.72.0

package/dist/index.d.cts

@@ -123,6 +123,14 @@ interface SchematicTrack {
      * the main centre-line + lane, as before. Physical view only; the operations
      * view stays positional (#2d-track). */
     path?: BenchworkPoint[] | null;
+    /** The flex product this run is laid with — a slug from the parts library
+     * (#193). Absent = the default. Per TRACK, so a module can have its mains in
+     * one product and a siding in another. */
+    flexPartId?: string | null;
+    /** Authored rail joints, inches along this run. Absent = derived from the
+     * product's maximum piece length. Present = these are the ONLY joints, so an
+     * owner's deliberate cut survives a change elsewhere on the module. */
+    flexCuts?: number[] | null;
 }
 interface SchematicTurnout {
     id: string;
@@ -897,6 +905,19 @@ interface EditorState {
         y: number;
         heading: number;
     }>;
+    /**
+     * Flex track settings by TRACK id (#193) — which product a run is laid with,
+     * and where the owner has decided its rail joints fall.
+     *
+     * One map rather than fields, because the MAINS aren't `extraTracks` (the main
+     * IS the centre-line), so per-track settings would otherwise need a separate
+     * pair of fields for Main 1 and Main 2 — four ways to say one thing. Round-trips
+     * onto each track in the doc, where it's self-describing for Free-Dispatcher.
+     */
+    flexByTrack: Record<string, {
+        partId?: string;
+        cuts?: number[];
+    }>;
     /** Authored endplate face widths by endplate id, inches (Free-moN 12″ min,
      * 24″ recommended). Absent id = the recommended default. */
     endplateWidths: Record<string, number>;
@@ -1242,7 +1263,10 @@ interface TrackPart {
     line: string;
     scale: "N";
     name: string;
-    kind: "turnout" | "wye" | "curved-turnout" | "crossing";
+    /** `flex` is track sold by the length rather than as a fixed geometry — its
+     * {@link overallLength} is the LONGEST piece you can lay from it, not a shape
+     * (#193). */
+    kind: "turnout" | "wye" | "curved-turnout" | "crossing" | "flex";
     /** Manufacturer part numbers by hand, where the part has a hand. */
     partNumbers?: {
         left?: string;
@@ -1350,10 +1374,164 @@ declare const CODE55_RAIL_HEIGHT_INCHES = 0.055;
  * everything else is a tooling decision. **Measure the part. Do not model it.**
  */
 declare const ATLAS_CODE55_N: TrackPart[];
+/**
+ * Flex track — the stuff every run that isn't a turnout or a crossing is made
+ * of (#193). A length of flex has no fixed geometry, so the only dimension it
+ * carries is **how long a piece you can lay from one**: past that you have
+ * another length, with a rail joint between them.
+ *
+ * ⚠️ These lengths are the NOMINAL PRODUCT LENGTHS as reported by Will Gage
+ * (2026-07-26), not values read off a spec sheet or measured. They are what the
+ * product is sold as — "30 inch flex track" — which is exactly the number a
+ * builder plans cuts against, so they're recorded as `manufacturer` with the
+ * source named. Correct them if a listing says otherwise.
+ *
+ * No part numbers here: I don't have them confirmed, and a wrong part number is
+ * worse than none — someone would order against it.
+ */
+declare const FLEX_TRACK_PARTS: TrackPart[];
+/** What a track is laid with when nobody has said — the commonest N-scale flex. */
+declare const DEFAULT_FLEX_PART_ID = "atlas-c55-n-flex";
 /** Every built-in part, across manufacturers. */
 declare const BUILT_IN_TRACK_PARTS: TrackPart[];
+/** Every flex product a track can be laid with. */
+declare function flexParts(library?: TrackPart[]): TrackPart[];
+/**
+ * The flex product a track is laid with, falling back to the default rather
+ * than to nothing: every non-turnout inch of track IS some product, and a run
+ * whose owner hasn't chosen still gets cut into buyable lengths.
+ */
+declare function flexPartFor(id: string | null | undefined, library?: TrackPart[]): TrackPart | null;
+/** How long a single piece of this product can be, inches. */
+declare function maxFlexPieceInches(id: string | null | undefined, library?: TrackPart[]): number;
 /** Look a part up by its slug. */
 declare function trackPart(id: string, library?: TrackPart[]): TrackPart | null;
+/** One length of flex track in a run — a real object you could pick up (#193). */
+interface FlexPiece {
+    /** Position in the run, west to east. Stable enough to select and label by. */
+    index: number;
+    /** Inches along the RUN, not the module — the same coordinate turnouts,
+     * industries and signals use, so a piece can be placed without a second
+     * geometry to keep in step. */
+    fromPos: number;
+    toPos: number;
+    lengthInches: number;
+    /** Longer than the product allows. Only reachable from AUTHORED cuts, or from
+     * a run that grew after they were authored — which is precisely when someone
+     * needs telling. */
+    overlong: boolean;
+    /** What this piece butts against at each end: another piece, a part (turnout
+     * or crossing), or the end of the run. */
+    fromEnd: FlexPieceEnd;
+    toEnd: FlexPieceEnd;
+}
+/** What a flex piece meets at one of its ends. */
+type FlexPieceEnd = "piece" | "part" | "runEnd";
+/**
+ * A stretch of a run that is NOT flex — a turnout's or a crossing's own body.
+ *
+ * A **zero-length** span is meaningful: it's a break in the run at a point whose
+ * own length we don't know. That's a crossing today — the run stops and starts
+ * there, giving a rail joint, but we've measured no crossing part so claiming an
+ * extent for it would be inventing one.
+ */
+interface OccupiedSpan {
+    fromPos: number;
+    toPos: number;
+}
+/**
+ * Cut a run into lengths of flex track.
+ *
+ * The model (#193): everything that isn't a turnout or a crossing is flex, flex
+ * comes in pieces of a maximum length, and where two pieces meet is a rail
+ * joint — the same joint a turnout makes with the track past it (#189). A 96″
+ * main isn't one piece of track; it's four lengths of Atlas flex with three
+ * joints in it, which is what someone actually buys and lays.
+ *
+ * Pieces are **spans of the run**, not free-floating geometry. That's deliberate:
+ * `pos` — inches along the run — is what every turnout, industry and signal is
+ * placed in, so a piece that carried its own shape would be a second geometry to
+ * keep in step with the first. As spans they get identity, a length you can
+ * change, and ends that meet their neighbours by construction.
+ *
+ * `cuts` is the owner's authoring and is **complete when present**: those are
+ * the only joints, and a piece that ends up too long is flagged rather than
+ * silently re-cut. Absent, the cuts are derived — full lengths from the start of
+ * each gap, remainder at the end, which is how you lay it. That's what lets
+ * every existing module arrive already cut up without anyone touching it.
+ */
+declare function flexPieces(input: {
+    fromPos: number;
+    toPos: number;
+    /** Longest single piece of the product this run is laid with. */
+    maxPieceInches: number;
+    /** Stretches the run gives up to parts — turnout bodies, crossings. */
+    occupied?: OccupiedSpan[] | null;
+    /** Authored joint positions, inches along the run. Absent = derive. */
+    cuts?: number[] | null;
+}): FlexPiece[];
+/**
+ * Which way a turnout faces along its host track: `+1` = its points look toward
+ * increasing pos, `-1` = the other way.
+ *
+ * ⭐ ONE definition. The canvas had this inline for drawing the leg, and the
+ * flex solver needs the same answer to know which side of `pos` the moulding
+ * extends — a turnout's body is NOT symmetric about its points (an Atlas #7 is
+ * about 0.9″ behind them and 5.1″ ahead), so getting the facing wrong moves a
+ * rail joint four inches (#193).
+ *
+ * The rule: the turnout faces the way its diverging track LEAVES, because that's
+ * where the frog is. `flipped` is the owner's override — rotating the part 180°
+ * faces the points the other way, which is the only thing that can be right for
+ * a siding pinned at a module end where the geometry reads ambiguously.
+ *
+ * `divergeFarPos` is whatever the caller can measure best: the canvas projects
+ * the diverging track's real far end back onto the main, the editor uses its
+ * authored extent. Same rule either way; only the precision of the input differs.
+ */
+declare function turnoutFacing(input: {
+    pos: number;
+    /** Where the diverging track ends up, in the same coordinate as `pos`. */
+    divergeFarPos?: number | null;
+    flipped?: boolean;
+}): 1 | -1;
+/**
+ * The stretch of its host run a turnout's moulding occupies (#193) — what flex
+ * track has to stop short of on each side.
+ *
+ * Null when the part hasn't been measured, exactly as {@link partExtent} is:
+ * without a real length we don't know where the moulding stops, and a guessed
+ * body would put a rail joint on track nobody has checked.
+ */
+declare function turnoutOccupiedSpan(input: {
+    pos: number;
+    extent: PartExtent | null | undefined;
+    facing: 1 | -1;
+}): OccupiedSpan | null;
+/**
+ * Retype one piece's length: move the rail joint at its far end, and let its
+ * NEIGHBOUR take up the difference (#193).
+ *
+ * That's what cutting one piece longer actually does — the run doesn't grow, so
+ * the next piece gets shorter by the same amount. The pair's total is fixed,
+ * which is why the value is clamped to it: without that, asking for a length
+ * past the next joint silently reorders the cuts and you get back something you
+ * didn't ask for.
+ *
+ * Returns the run's COMPLETE new cut list (`flexCuts`), or null when the piece
+ * has no neighbour to trade with — the last piece in a gap butts a turnout or
+ * the endplate, and its length is set by what it meets, not by preference.
+ */
+declare function resizeFlexPiece(pieces: FlexPiece[], index: number, nextLengthInches: number): number[] | null;
+/** What a run costs in flex, for someone about to order it (#193). */
+declare function flexUsage(pieces: FlexPiece[]): {
+    /** How many separate lengths have to be cut. */
+    pieces: number;
+    /** Total flex laid, inches — the run minus whatever the parts occupy. */
+    totalInches: number;
+    /** Pieces the product can't actually supply in one length. */
+    overlong: number;
+};
 /** Half an N-scale tie, inches — a 8′6″ tie is 102″ prototype, /160 ≈ 0.638″.
  * The half-width a tie strip extends either side of the rail it carries, which
  * is what gives a drawn turnout body its width. */
@@ -1844,4 +2022,4 @@ declare function poseOverridesFromDoc(doc: ModuleSchematicDoc): Record<string, {
     heading: number;
 }>;
 
-export { ATLAS_CODE55_N, BUILT_IN_TRACK_PARTS, type BenchworkPoint, type BranchConnector, CODE55_RAIL_HEIGHT_INCHES, type DimensionSource, type DrawCrossing, type DrawCrossover, type DrawIndustry, type DrawSignal, type DrawTrack, type DrawTurnout, ENDPLATE_FASCIA_CLEAR_INCHES, ENDPLATE_LEAD_INCHES, type EditorBranch, type EditorControlPoint, type EditorCpSignal, type EditorCrossing, type EditorIndustry, type EditorState, type EditorTrack, type EditorTurnout, type EndplateBConfig, type EndplatePose, type EndplateTrackIssue, type EndplateWidthIssue, FREEMO_ENDPLATE_TRACK_FASCIA_CLEARANCE_INCHES, FREEMO_ENDPLATE_WIDTH_MIN_INCHES, FREEMO_ENDPLATE_WIDTH_RECOMMENDED_INCHES, FREEMO_TRACK_SPACING_INCHES, type FrogCasting, type GeometryType, type ImportedPart, type IndustryLabelMode, type IndustrySpot, 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 OutlineFace, type PartAngle, type PartDimension, type PartEnd, type PartExtent, 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 SectionFootprint, type SectionRelativePos, type SignalFacing, type SignalSide, type StoredTrackPart, TIE_HALF_LENGTH_INCHES, TURNOUT_LEAD_INCHES_PER_FROG, type TrackConfig, type TrackPart, type TrackRole, type TurnoutClosure, type TurnoutKind, WHOLE_MODULE_SECTION_ID, asModuleSchematic, benchworkBand, benchworkOutline, buildCrossover, buildPassingSiding, buildTransition, carCapacity, checkEndplateWidth, deriveEndplatePoses, divergeSideForHand, docToState, emptyEditorState, endplateCentreOffsetInches, endplateFaceSegments, endplateLead, endplateTrackOffsetInches, endplateWidthInches, frogCasting, frogNumberFromName, fromSectionRelative, geometryTurnDegrees, hasNoFarEndplate, importedPartToTrackPart, inchesToScaleFeet, isLoopDoc, isTransitionTurnout, leadInchesForSize, mergeImportedParts, mergeStoredParts, moduleCenterline, moduleFeatures, moduleFootprint, moduleLengthFromSections, moduleSections, nextId, parseXtpLibrary, partExtent, partExtentForSize, partOutlineAtFrog, pastFrogInchesForSize, pathLengthInches, poseNeedsManual, poseOverridesFromDoc, remapPos, returnLoop, sampleBenchworkOutline, samplePartSegments, samplePath, scaleFeetToInches, sectionAdjacency, sectionBand, sectionBreaksFromSections, sectionComponents, sectionFootprints, sectionNeighbours, sectionSpans, sectionSpansOrWhole, sectionedCenterline, sectionedEndPose, sliceCenterline, stateToDoc, storedPartToTrackPart, toSectionRelative, trackMeetsEndplateIssues, trackPart, trackPath, turnoutClosure, turnoutPartForSize };
+export { ATLAS_CODE55_N, BUILT_IN_TRACK_PARTS, type BenchworkPoint, type BranchConnector, CODE55_RAIL_HEIGHT_INCHES, DEFAULT_FLEX_PART_ID, type DimensionSource, type DrawCrossing, type DrawCrossover, type DrawIndustry, type DrawSignal, type DrawTrack, type DrawTurnout, ENDPLATE_FASCIA_CLEAR_INCHES, ENDPLATE_LEAD_INCHES, type EditorBranch, type EditorControlPoint, type EditorCpSignal, type EditorCrossing, type EditorIndustry, type EditorState, type EditorTrack, type EditorTurnout, type EndplateBConfig, type EndplatePose, type EndplateTrackIssue, type EndplateWidthIssue, 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, 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, type PartAngle, type PartDimension, type PartEnd, type PartExtent, 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 SectionFootprint, type SectionRelativePos, type SignalFacing, type SignalSide, type StoredTrackPart, TIE_HALF_LENGTH_INCHES, TURNOUT_LEAD_INCHES_PER_FROG, type TrackConfig, type TrackPart, type TrackRole, type TurnoutClosure, type TurnoutKind, WHOLE_MODULE_SECTION_ID, asModuleSchematic, benchworkBand, benchworkOutline, buildCrossover, buildPassingSiding, buildTransition, carCapacity, checkEndplateWidth, deriveEndplatePoses, divergeSideForHand, docToState, emptyEditorState, endplateCentreOffsetInches, endplateFaceSegments, endplateLead, endplateTrackOffsetInches, endplateWidthInches, flexPartFor, flexParts, flexPieces, flexUsage, frogCasting, frogNumberFromName, fromSectionRelative, geometryTurnDegrees, hasNoFarEndplate, importedPartToTrackPart, inchesToScaleFeet, isLoopDoc, isTransitionTurnout, leadInchesForSize, maxFlexPieceInches, mergeImportedParts, mergeStoredParts, moduleCenterline, moduleFeatures, moduleFootprint, moduleLengthFromSections, moduleSections, nextId, parseXtpLibrary, partExtent, partExtentForSize, partOutlineAtFrog, pastFrogInchesForSize, pathLengthInches, poseNeedsManual, poseOverridesFromDoc, remapPos, resizeFlexPiece, returnLoop, sampleBenchworkOutline, samplePartSegments, samplePath, scaleFeetToInches, sectionAdjacency, sectionBand, sectionBreaksFromSections, sectionComponents, sectionFootprints, sectionNeighbours, sectionSpans, sectionSpansOrWhole, sectionedCenterline, sectionedEndPose, sliceCenterline, stateToDoc, storedPartToTrackPart, toSectionRelative, trackMeetsEndplateIssues, trackPart, trackPath, turnoutClosure, turnoutFacing, turnoutOccupiedSpan, turnoutPartForSize };

package/dist/index.d.ts

@@ -123,6 +123,14 @@ interface SchematicTrack {
      * the main centre-line + lane, as before. Physical view only; the operations
      * view stays positional (#2d-track). */
     path?: BenchworkPoint[] | null;
+    /** The flex product this run is laid with — a slug from the parts library
+     * (#193). Absent = the default. Per TRACK, so a module can have its mains in
+     * one product and a siding in another. */
+    flexPartId?: string | null;
+    /** Authored rail joints, inches along this run. Absent = derived from the
+     * product's maximum piece length. Present = these are the ONLY joints, so an
+     * owner's deliberate cut survives a change elsewhere on the module. */
+    flexCuts?: number[] | null;
 }
 interface SchematicTurnout {
     id: string;
@@ -897,6 +905,19 @@ interface EditorState {
         y: number;
         heading: number;
     }>;
+    /**
+     * Flex track settings by TRACK id (#193) — which product a run is laid with,
+     * and where the owner has decided its rail joints fall.
+     *
+     * One map rather than fields, because the MAINS aren't `extraTracks` (the main
+     * IS the centre-line), so per-track settings would otherwise need a separate
+     * pair of fields for Main 1 and Main 2 — four ways to say one thing. Round-trips
+     * onto each track in the doc, where it's self-describing for Free-Dispatcher.
+     */
+    flexByTrack: Record<string, {
+        partId?: string;
+        cuts?: number[];
+    }>;
     /** Authored endplate face widths by endplate id, inches (Free-moN 12″ min,
      * 24″ recommended). Absent id = the recommended default. */
     endplateWidths: Record<string, number>;
@@ -1242,7 +1263,10 @@ interface TrackPart {
     line: string;
     scale: "N";
     name: string;
-    kind: "turnout" | "wye" | "curved-turnout" | "crossing";
+    /** `flex` is track sold by the length rather than as a fixed geometry — its
+     * {@link overallLength} is the LONGEST piece you can lay from it, not a shape
+     * (#193). */
+    kind: "turnout" | "wye" | "curved-turnout" | "crossing" | "flex";
     /** Manufacturer part numbers by hand, where the part has a hand. */
     partNumbers?: {
         left?: string;
@@ -1350,10 +1374,164 @@ declare const CODE55_RAIL_HEIGHT_INCHES = 0.055;
  * everything else is a tooling decision. **Measure the part. Do not model it.**
  */
 declare const ATLAS_CODE55_N: TrackPart[];
+/**
+ * Flex track — the stuff every run that isn't a turnout or a crossing is made
+ * of (#193). A length of flex has no fixed geometry, so the only dimension it
+ * carries is **how long a piece you can lay from one**: past that you have
+ * another length, with a rail joint between them.
+ *
+ * ⚠️ These lengths are the NOMINAL PRODUCT LENGTHS as reported by Will Gage
+ * (2026-07-26), not values read off a spec sheet or measured. They are what the
+ * product is sold as — "30 inch flex track" — which is exactly the number a
+ * builder plans cuts against, so they're recorded as `manufacturer` with the
+ * source named. Correct them if a listing says otherwise.
+ *
+ * No part numbers here: I don't have them confirmed, and a wrong part number is
+ * worse than none — someone would order against it.
+ */
+declare const FLEX_TRACK_PARTS: TrackPart[];
+/** What a track is laid with when nobody has said — the commonest N-scale flex. */
+declare const DEFAULT_FLEX_PART_ID = "atlas-c55-n-flex";
 /** Every built-in part, across manufacturers. */
 declare const BUILT_IN_TRACK_PARTS: TrackPart[];
+/** Every flex product a track can be laid with. */
+declare function flexParts(library?: TrackPart[]): TrackPart[];
+/**
+ * The flex product a track is laid with, falling back to the default rather
+ * than to nothing: every non-turnout inch of track IS some product, and a run
+ * whose owner hasn't chosen still gets cut into buyable lengths.
+ */
+declare function flexPartFor(id: string | null | undefined, library?: TrackPart[]): TrackPart | null;
+/** How long a single piece of this product can be, inches. */
+declare function maxFlexPieceInches(id: string | null | undefined, library?: TrackPart[]): number;
 /** Look a part up by its slug. */
 declare function trackPart(id: string, library?: TrackPart[]): TrackPart | null;
+/** One length of flex track in a run — a real object you could pick up (#193). */
+interface FlexPiece {
+    /** Position in the run, west to east. Stable enough to select and label by. */
+    index: number;
+    /** Inches along the RUN, not the module — the same coordinate turnouts,
+     * industries and signals use, so a piece can be placed without a second
+     * geometry to keep in step. */
+    fromPos: number;
+    toPos: number;
+    lengthInches: number;
+    /** Longer than the product allows. Only reachable from AUTHORED cuts, or from
+     * a run that grew after they were authored — which is precisely when someone
+     * needs telling. */
+    overlong: boolean;
+    /** What this piece butts against at each end: another piece, a part (turnout
+     * or crossing), or the end of the run. */
+    fromEnd: FlexPieceEnd;
+    toEnd: FlexPieceEnd;
+}
+/** What a flex piece meets at one of its ends. */
+type FlexPieceEnd = "piece" | "part" | "runEnd";
+/**
+ * A stretch of a run that is NOT flex — a turnout's or a crossing's own body.
+ *
+ * A **zero-length** span is meaningful: it's a break in the run at a point whose
+ * own length we don't know. That's a crossing today — the run stops and starts
+ * there, giving a rail joint, but we've measured no crossing part so claiming an
+ * extent for it would be inventing one.
+ */
+interface OccupiedSpan {
+    fromPos: number;
+    toPos: number;
+}
+/**
+ * Cut a run into lengths of flex track.
+ *
+ * The model (#193): everything that isn't a turnout or a crossing is flex, flex
+ * comes in pieces of a maximum length, and where two pieces meet is a rail
+ * joint — the same joint a turnout makes with the track past it (#189). A 96″
+ * main isn't one piece of track; it's four lengths of Atlas flex with three
+ * joints in it, which is what someone actually buys and lays.
+ *
+ * Pieces are **spans of the run**, not free-floating geometry. That's deliberate:
+ * `pos` — inches along the run — is what every turnout, industry and signal is
+ * placed in, so a piece that carried its own shape would be a second geometry to
+ * keep in step with the first. As spans they get identity, a length you can
+ * change, and ends that meet their neighbours by construction.
+ *
+ * `cuts` is the owner's authoring and is **complete when present**: those are
+ * the only joints, and a piece that ends up too long is flagged rather than
+ * silently re-cut. Absent, the cuts are derived — full lengths from the start of
+ * each gap, remainder at the end, which is how you lay it. That's what lets
+ * every existing module arrive already cut up without anyone touching it.
+ */
+declare function flexPieces(input: {
+    fromPos: number;
+    toPos: number;
+    /** Longest single piece of the product this run is laid with. */
+    maxPieceInches: number;
+    /** Stretches the run gives up to parts — turnout bodies, crossings. */
+    occupied?: OccupiedSpan[] | null;
+    /** Authored joint positions, inches along the run. Absent = derive. */
+    cuts?: number[] | null;
+}): FlexPiece[];
+/**
+ * Which way a turnout faces along its host track: `+1` = its points look toward
+ * increasing pos, `-1` = the other way.
+ *
+ * ⭐ ONE definition. The canvas had this inline for drawing the leg, and the
+ * flex solver needs the same answer to know which side of `pos` the moulding
+ * extends — a turnout's body is NOT symmetric about its points (an Atlas #7 is
+ * about 0.9″ behind them and 5.1″ ahead), so getting the facing wrong moves a
+ * rail joint four inches (#193).
+ *
+ * The rule: the turnout faces the way its diverging track LEAVES, because that's
+ * where the frog is. `flipped` is the owner's override — rotating the part 180°
+ * faces the points the other way, which is the only thing that can be right for
+ * a siding pinned at a module end where the geometry reads ambiguously.
+ *
+ * `divergeFarPos` is whatever the caller can measure best: the canvas projects
+ * the diverging track's real far end back onto the main, the editor uses its
+ * authored extent. Same rule either way; only the precision of the input differs.
+ */
+declare function turnoutFacing(input: {
+    pos: number;
+    /** Where the diverging track ends up, in the same coordinate as `pos`. */
+    divergeFarPos?: number | null;
+    flipped?: boolean;
+}): 1 | -1;
+/**
+ * The stretch of its host run a turnout's moulding occupies (#193) — what flex
+ * track has to stop short of on each side.
+ *
+ * Null when the part hasn't been measured, exactly as {@link partExtent} is:
+ * without a real length we don't know where the moulding stops, and a guessed
+ * body would put a rail joint on track nobody has checked.
+ */
+declare function turnoutOccupiedSpan(input: {
+    pos: number;
+    extent: PartExtent | null | undefined;
+    facing: 1 | -1;
+}): OccupiedSpan | null;
+/**
+ * Retype one piece's length: move the rail joint at its far end, and let its
+ * NEIGHBOUR take up the difference (#193).
+ *
+ * That's what cutting one piece longer actually does — the run doesn't grow, so
+ * the next piece gets shorter by the same amount. The pair's total is fixed,
+ * which is why the value is clamped to it: without that, asking for a length
+ * past the next joint silently reorders the cuts and you get back something you
+ * didn't ask for.
+ *
+ * Returns the run's COMPLETE new cut list (`flexCuts`), or null when the piece
+ * has no neighbour to trade with — the last piece in a gap butts a turnout or
+ * the endplate, and its length is set by what it meets, not by preference.
+ */
+declare function resizeFlexPiece(pieces: FlexPiece[], index: number, nextLengthInches: number): number[] | null;
+/** What a run costs in flex, for someone about to order it (#193). */
+declare function flexUsage(pieces: FlexPiece[]): {
+    /** How many separate lengths have to be cut. */
+    pieces: number;
+    /** Total flex laid, inches — the run minus whatever the parts occupy. */
+    totalInches: number;
+    /** Pieces the product can't actually supply in one length. */
+    overlong: number;
+};
 /** Half an N-scale tie, inches — a 8′6″ tie is 102″ prototype, /160 ≈ 0.638″.
  * The half-width a tie strip extends either side of the rail it carries, which
  * is what gives a drawn turnout body its width. */
@@ -1844,4 +2022,4 @@ declare function poseOverridesFromDoc(doc: ModuleSchematicDoc): Record<string, {
     heading: number;
 }>;
 
-export { ATLAS_CODE55_N, BUILT_IN_TRACK_PARTS, type BenchworkPoint, type BranchConnector, CODE55_RAIL_HEIGHT_INCHES, type DimensionSource, type DrawCrossing, type DrawCrossover, type DrawIndustry, type DrawSignal, type DrawTrack, type DrawTurnout, ENDPLATE_FASCIA_CLEAR_INCHES, ENDPLATE_LEAD_INCHES, type EditorBranch, type EditorControlPoint, type EditorCpSignal, type EditorCrossing, type EditorIndustry, type EditorState, type EditorTrack, type EditorTurnout, type EndplateBConfig, type EndplatePose, type EndplateTrackIssue, type EndplateWidthIssue, FREEMO_ENDPLATE_TRACK_FASCIA_CLEARANCE_INCHES, FREEMO_ENDPLATE_WIDTH_MIN_INCHES, FREEMO_ENDPLATE_WIDTH_RECOMMENDED_INCHES, FREEMO_TRACK_SPACING_INCHES, type FrogCasting, type GeometryType, type ImportedPart, type IndustryLabelMode, type IndustrySpot, 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 OutlineFace, type PartAngle, type PartDimension, type PartEnd, type PartExtent, 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 SectionFootprint, type SectionRelativePos, type SignalFacing, type SignalSide, type StoredTrackPart, TIE_HALF_LENGTH_INCHES, TURNOUT_LEAD_INCHES_PER_FROG, type TrackConfig, type TrackPart, type TrackRole, type TurnoutClosure, type TurnoutKind, WHOLE_MODULE_SECTION_ID, asModuleSchematic, benchworkBand, benchworkOutline, buildCrossover, buildPassingSiding, buildTransition, carCapacity, checkEndplateWidth, deriveEndplatePoses, divergeSideForHand, docToState, emptyEditorState, endplateCentreOffsetInches, endplateFaceSegments, endplateLead, endplateTrackOffsetInches, endplateWidthInches, frogCasting, frogNumberFromName, fromSectionRelative, geometryTurnDegrees, hasNoFarEndplate, importedPartToTrackPart, inchesToScaleFeet, isLoopDoc, isTransitionTurnout, leadInchesForSize, mergeImportedParts, mergeStoredParts, moduleCenterline, moduleFeatures, moduleFootprint, moduleLengthFromSections, moduleSections, nextId, parseXtpLibrary, partExtent, partExtentForSize, partOutlineAtFrog, pastFrogInchesForSize, pathLengthInches, poseNeedsManual, poseOverridesFromDoc, remapPos, returnLoop, sampleBenchworkOutline, samplePartSegments, samplePath, scaleFeetToInches, sectionAdjacency, sectionBand, sectionBreaksFromSections, sectionComponents, sectionFootprints, sectionNeighbours, sectionSpans, sectionSpansOrWhole, sectionedCenterline, sectionedEndPose, sliceCenterline, stateToDoc, storedPartToTrackPart, toSectionRelative, trackMeetsEndplateIssues, trackPart, trackPath, turnoutClosure, turnoutPartForSize };
+export { ATLAS_CODE55_N, BUILT_IN_TRACK_PARTS, type BenchworkPoint, type BranchConnector, CODE55_RAIL_HEIGHT_INCHES, DEFAULT_FLEX_PART_ID, type DimensionSource, type DrawCrossing, type DrawCrossover, type DrawIndustry, type DrawSignal, type DrawTrack, type DrawTurnout, ENDPLATE_FASCIA_CLEAR_INCHES, ENDPLATE_LEAD_INCHES, type EditorBranch, type EditorControlPoint, type EditorCpSignal, type EditorCrossing, type EditorIndustry, type EditorState, type EditorTrack, type EditorTurnout, type EndplateBConfig, type EndplatePose, type EndplateTrackIssue, type EndplateWidthIssue, 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, 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, type PartAngle, type PartDimension, type PartEnd, type PartExtent, 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 SectionFootprint, type SectionRelativePos, type SignalFacing, type SignalSide, type StoredTrackPart, TIE_HALF_LENGTH_INCHES, TURNOUT_LEAD_INCHES_PER_FROG, type TrackConfig, type TrackPart, type TrackRole, type TurnoutClosure, type TurnoutKind, WHOLE_MODULE_SECTION_ID, asModuleSchematic, benchworkBand, benchworkOutline, buildCrossover, buildPassingSiding, buildTransition, carCapacity, checkEndplateWidth, deriveEndplatePoses, divergeSideForHand, docToState, emptyEditorState, endplateCentreOffsetInches, endplateFaceSegments, endplateLead, endplateTrackOffsetInches, endplateWidthInches, flexPartFor, flexParts, flexPieces, flexUsage, frogCasting, frogNumberFromName, fromSectionRelative, geometryTurnDegrees, hasNoFarEndplate, importedPartToTrackPart, inchesToScaleFeet, isLoopDoc, isTransitionTurnout, leadInchesForSize, maxFlexPieceInches, mergeImportedParts, mergeStoredParts, moduleCenterline, moduleFeatures, moduleFootprint, moduleLengthFromSections, moduleSections, nextId, parseXtpLibrary, partExtent, partExtentForSize, partOutlineAtFrog, pastFrogInchesForSize, pathLengthInches, poseNeedsManual, poseOverridesFromDoc, remapPos, resizeFlexPiece, returnLoop, sampleBenchworkOutline, samplePartSegments, samplePath, scaleFeetToInches, sectionAdjacency, sectionBand, sectionBreaksFromSections, sectionComponents, sectionFootprints, sectionNeighbours, sectionSpans, sectionSpansOrWhole, sectionedCenterline, sectionedEndPose, sliceCenterline, stateToDoc, storedPartToTrackPart, toSectionRelative, trackMeetsEndplateIssues, trackPart, trackPath, turnoutClosure, turnoutFacing, turnoutOccupiedSpan, turnoutPartForSize };