@willcgage/module-schematic 0.74.0 → 0.76.0

package/dist/index.d.cts

@@ -131,6 +131,10 @@ interface SchematicTrack {
      * 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;
+    /** The owner's MEASURED usable length, real inches (#20) — for what the
+     * drawing can't know: a bumper post short of the drawn end, a structure
+     * fouling the track. Absent = derive it from the clearance points (#19). */
+    measuredUsableInches?: number | null;
 }
 interface SchematicTurnout {
     id: string;
@@ -362,6 +366,35 @@ interface SchematicSection {
     geometryDegrees?: number | null;
     /** Lateral jog, for offset sections. */
     geometryOffsetInches?: number | null;
+    /** This board's WEST end (the A side) — see {@link SectionEnd}. */
+    endA?: SectionEnd | null;
+    /** This board's EAST end (the B side). */
+    endB?: SectionEnd | null;
+}
+/**
+ * One end of a board (#130).
+ *
+ * Owner's question was *"how would I update my section joints to be endplates
+ * from within MR?"* — and until now nothing could say it: a section had a
+ * length, a shape and an outline, but nothing about its ends.
+ *
+ * ⚠️ **There is deliberately no "this is an endplate" flag.** An owner could
+ * tick it wrongly and the registry would then tell Free-Dispatcher that two
+ * boards will physically mate when they won't. The geometry decides — describe
+ * the end and {@link assessSectionEnd} works out whether it conforms.
+ *
+ * Absent means **not described**, which is an ordinary internal joint, not a
+ * failing endplate: the standard exempts internal boundaries from the
+ * end-interface rules (#96).
+ */
+interface SectionEnd {
+    /** What this end presents. `"none"` = a closed end (a bumper). */
+    config?: TrackConfig | "none" | null;
+    /** Face width, inches. Absent = the recommended default. */
+    widthInches?: number | null;
+    /** Main 1's signed distance from the face centre — the standard's own
+     * framing, same as an endplate's (see {@link endplateTrackOffsetInches}). */
+    trackOffsetInches?: number | null;
 }
 /** The authored benchwork outline, or null when a module hasn't drawn one
  * (renderers then fall back to a band derived from the endplate widths). A
@@ -771,6 +804,130 @@ declare function scaleFeetToInches(feet: number, ratio?: number): number;
  * ~3.0″; ~3.3″ over the couplers — the real spacing a cut of cars takes. The
  * single constant every repo reads so a track's car count matches everywhere. */
 declare const N_CAR_LENGTH_INCHES = 3.3;
+/**
+ * How far the two routes must separate before a car on one clears equipment on
+ * the other — the CLEARANCE POINT's defining distance (#19).
+ *
+ * ⭐ Deliberately the **Free-moN track spacing**, not a second number. §2.0 uses
+ * 1.125″ as the distance at which two parallel tracks coexist, so "a car here
+ * clears a car there" is the same statement the standard already makes. It's
+ * 15 scale feet centre to centre, inside the prototype's usual 13–15 ft range.
+ *
+ * The alternative — a separate prototype constant — would leave the app holding
+ * two spacings that disagree about what "clear" means.
+ */
+declare const CLEARANCE_SPACING_INCHES = 1.125;
+/**
+ * How far past the FROG a turnout's diverging route reaches the clearance point
+ * (#19) — the point from which usable capacity is measured.
+ *
+ * Not a measurement and not a guess: it's solved from the closure the drawing
+ * already uses, by asking where `offsetAt` first reaches
+ * {@link CLEARANCE_SPACING_INCHES}. So it follows the part's real lead, and a
+ * better-measured part moves it automatically.
+ *
+ * Returns the distance PAST THE FROG because `pos` means the frog (#132) — add
+ * it to the turnout's position, in the direction the turnout faces.
+ */
+declare function clearancePointPastFrogInches(size: number, library?: TrackPart[], clearanceInches?: number): number;
+/** A track's usable capacity, measured to the clearance-point standard (#19). */
+interface UsableCapacity {
+    /** The stretch a car can actually stand on, inches along the run. */
+    fromPos: number;
+    toPos: number;
+    /** Its length — what capacity is computed from. */
+    usableInches: number;
+    /** The run's full drawn length, for comparison. */
+    drawnInches: number;
+    /** How much each end gives up to its governing turnout's clearance point. */
+    givenUpInches: number;
+    /** Cars that fit in the usable length. */
+    cars: number;
+    /** Usable length as scale feet. */
+    scaleFeet: number;
+}
+/**
+ * A track's USABLE capacity — measured from the governing turnout's clearance
+ * point, not from the rail ends (#19/#20).
+ *
+ * A spur runs clearance point → end of track; a siding, clearance point →
+ * clearance point. The difference is not small: FMN-0040's 70″ passing siding
+ * has two #7s on it, and loses 5.4″ at each end — 21 cars drawn, 17 usable.
+ *
+ * `measuredUsableInches` is the owner's override for what the drawing can't
+ * know — a bumper post short of the drawn end, a structure fouling the track.
+ * Given, it wins outright and the clearance points aren't applied to it: they
+ * measured the usable length itself.
+ */
+declare function usableCapacity(input: {
+    fromPos: number;
+    toPos: number;
+    /** Turnouts that DIVERGE ONTO this track — the ones that govern its ends. */
+    governing?: {
+        pos: number;
+        size?: number | null;
+    }[] | null;
+    /** The owner's measured usable length, inches. Wins when present. */
+    measuredUsableInches?: number | null;
+    library?: TrackPart[];
+    carLengthInches?: number;
+}): UsableCapacity;
+/** What a board's end is, once the geometry has been asked (#130). */
+interface SectionEndAssessment {
+    /** Has the owner described this end at all? Undescribed is an ordinary
+     * internal joint — exempt from the end-interface rules (#96) — not a failure. */
+    described: boolean;
+    /** Does it meet the standard's end-interface rules? Only a described end can. */
+    conforming: boolean;
+    /** Why it doesn't, when it doesn't. Empty for a conforming or undescribed end. */
+    issues: EndplateWidthIssue[];
+    /** The resolved values the assessment was made against. */
+    config: TrackConfig | "none";
+    widthInches: number;
+    trackOffsetInches: number;
+}
+/**
+ * Is this end of a board a standard endplate? (#130)
+ *
+ * ⭐ **Derived, never declared.** The issue is emphatic and the reason is good:
+ * a checkbox could be ticked wrongly, and the registry would then promise
+ * Free-Dispatcher a mating surface that doesn't exist. So the answer comes from
+ * the same rules {@link checkEndplateWidth} already applies to a module's own
+ * plates — §1.1's 12″ minimum, and §2.0's 4″ fascia clearance and 1.125″ pair.
+ *
+ * Two of the standard's conditions aren't checked because they can't be false
+ * here: track crosses the face **perpendicular** and a double end's two tracks
+ * sit **1.125″ apart** are both true by construction in this model. Inventing
+ * fields for them would be inventing ways to be wrong.
+ *
+ * An end with no config is **undescribed**, which is the ordinary case — most
+ * joints inside a module are just joints.
+ */
+declare function assessSectionEnd(end: SectionEnd | null | undefined, opts?: {
+    main2Below?: boolean;
+}): SectionEndAssessment;
+/** Two board ends meeting at a joint, and whether that joint is a standard
+ * interface (#130). */
+interface SectionJointAssessment {
+    west: SectionEndAssessment;
+    east: SectionEndAssessment;
+    /** Both ends conform AND present the same number of tracks — so these two
+     * boards could be separated and each used against any other module. */
+    standardInterface: boolean;
+    /** Plain-language reason it isn't one, or null when it is. */
+    reason: string | null;
+}
+/**
+ * Assess a joint — the two board ends that meet there (#130).
+ *
+ * ⚠️ Track COUNT is the only compatibility rule. Two conforming ends of
+ * differing face WIDTH still mate: the standard lets plates differ in width and
+ * be offset, so long as the track lines up. That's a deliberate non-check — see
+ * the note on endplate width authoring.
+ */
+declare function assessSectionJoint(west: SectionEnd | null | undefined, east: SectionEnd | null | undefined, opts?: {
+    main2Below?: boolean;
+}): SectionJointAssessment;
 /** How much of a car-spot span has no rail under it (#194). */
 interface SpanOverhang {
     /** Inches the span runs past the track's near end (0 = it starts on track). */
@@ -822,6 +979,8 @@ interface EditorTrack {
     /** Authored 2-D path (module-local inches) — a bent/rotated spur's real
      * shape. Absent = derive from the main + lane (#2d-track). */
     path?: BenchworkPoint[];
+    /** Measured usable length, real inches (#20). Absent = derived (#19). */
+    measuredUsableInches?: number;
 }
 /** A module_tracks row as loaded for the editor. */
 interface ModuleTrackRow {
@@ -2051,4 +2210,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, 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 SpanOverhang, 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, spanOverhang, stateToDoc, storedPartToTrackPart, toSectionRelative, trackMeetsEndplateIssues, trackPart, trackPath, turnoutClosure, turnoutFacing, turnoutOccupiedSpan, turnoutPartForSize };
+export { ATLAS_CODE55_N, BUILT_IN_TRACK_PARTS, type BenchworkPoint, type BranchConnector, CLEARANCE_SPACING_INCHES, CODE55_RAIL_HEIGHT_INCHES, DEFAULT_FLEX_PART_ID, type DimensionSource, type DrawCrossing, type DrawCrossover, type DrawIndustry, type DrawSignal, type DrawTrack, type DrawTurnout, ENDPLATE_FASCIA_CLEAR_INCHES, ENDPLATE_LEAD_INCHES, type EditorBranch, type EditorControlPoint, type EditorCpSignal, type EditorCrossing, type EditorIndustry, type EditorState, type EditorTrack, type EditorTurnout, type EndplateBConfig, type EndplatePose, type EndplateTrackIssue, type EndplateWidthIssue, 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 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, 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, spanOverhang, stateToDoc, storedPartToTrackPart, toSectionRelative, trackMeetsEndplateIssues, trackPart, trackPath, turnoutClosure, turnoutFacing, turnoutOccupiedSpan, turnoutPartForSize, usableCapacity };

package/dist/index.d.ts

@@ -131,6 +131,10 @@ interface SchematicTrack {
      * 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;
+    /** The owner's MEASURED usable length, real inches (#20) — for what the
+     * drawing can't know: a bumper post short of the drawn end, a structure
+     * fouling the track. Absent = derive it from the clearance points (#19). */
+    measuredUsableInches?: number | null;
 }
 interface SchematicTurnout {
     id: string;
@@ -362,6 +366,35 @@ interface SchematicSection {
     geometryDegrees?: number | null;
     /** Lateral jog, for offset sections. */
     geometryOffsetInches?: number | null;
+    /** This board's WEST end (the A side) — see {@link SectionEnd}. */
+    endA?: SectionEnd | null;
+    /** This board's EAST end (the B side). */
+    endB?: SectionEnd | null;
+}
+/**
+ * One end of a board (#130).
+ *
+ * Owner's question was *"how would I update my section joints to be endplates
+ * from within MR?"* — and until now nothing could say it: a section had a
+ * length, a shape and an outline, but nothing about its ends.
+ *
+ * ⚠️ **There is deliberately no "this is an endplate" flag.** An owner could
+ * tick it wrongly and the registry would then tell Free-Dispatcher that two
+ * boards will physically mate when they won't. The geometry decides — describe
+ * the end and {@link assessSectionEnd} works out whether it conforms.
+ *
+ * Absent means **not described**, which is an ordinary internal joint, not a
+ * failing endplate: the standard exempts internal boundaries from the
+ * end-interface rules (#96).
+ */
+interface SectionEnd {
+    /** What this end presents. `"none"` = a closed end (a bumper). */
+    config?: TrackConfig | "none" | null;
+    /** Face width, inches. Absent = the recommended default. */
+    widthInches?: number | null;
+    /** Main 1's signed distance from the face centre — the standard's own
+     * framing, same as an endplate's (see {@link endplateTrackOffsetInches}). */
+    trackOffsetInches?: number | null;
 }
 /** The authored benchwork outline, or null when a module hasn't drawn one
  * (renderers then fall back to a band derived from the endplate widths). A
@@ -771,6 +804,130 @@ declare function scaleFeetToInches(feet: number, ratio?: number): number;
  * ~3.0″; ~3.3″ over the couplers — the real spacing a cut of cars takes. The
  * single constant every repo reads so a track's car count matches everywhere. */
 declare const N_CAR_LENGTH_INCHES = 3.3;
+/**
+ * How far the two routes must separate before a car on one clears equipment on
+ * the other — the CLEARANCE POINT's defining distance (#19).
+ *
+ * ⭐ Deliberately the **Free-moN track spacing**, not a second number. §2.0 uses
+ * 1.125″ as the distance at which two parallel tracks coexist, so "a car here
+ * clears a car there" is the same statement the standard already makes. It's
+ * 15 scale feet centre to centre, inside the prototype's usual 13–15 ft range.
+ *
+ * The alternative — a separate prototype constant — would leave the app holding
+ * two spacings that disagree about what "clear" means.
+ */
+declare const CLEARANCE_SPACING_INCHES = 1.125;
+/**
+ * How far past the FROG a turnout's diverging route reaches the clearance point
+ * (#19) — the point from which usable capacity is measured.
+ *
+ * Not a measurement and not a guess: it's solved from the closure the drawing
+ * already uses, by asking where `offsetAt` first reaches
+ * {@link CLEARANCE_SPACING_INCHES}. So it follows the part's real lead, and a
+ * better-measured part moves it automatically.
+ *
+ * Returns the distance PAST THE FROG because `pos` means the frog (#132) — add
+ * it to the turnout's position, in the direction the turnout faces.
+ */
+declare function clearancePointPastFrogInches(size: number, library?: TrackPart[], clearanceInches?: number): number;
+/** A track's usable capacity, measured to the clearance-point standard (#19). */
+interface UsableCapacity {
+    /** The stretch a car can actually stand on, inches along the run. */
+    fromPos: number;
+    toPos: number;
+    /** Its length — what capacity is computed from. */
+    usableInches: number;
+    /** The run's full drawn length, for comparison. */
+    drawnInches: number;
+    /** How much each end gives up to its governing turnout's clearance point. */
+    givenUpInches: number;
+    /** Cars that fit in the usable length. */
+    cars: number;
+    /** Usable length as scale feet. */
+    scaleFeet: number;
+}
+/**
+ * A track's USABLE capacity — measured from the governing turnout's clearance
+ * point, not from the rail ends (#19/#20).
+ *
+ * A spur runs clearance point → end of track; a siding, clearance point →
+ * clearance point. The difference is not small: FMN-0040's 70″ passing siding
+ * has two #7s on it, and loses 5.4″ at each end — 21 cars drawn, 17 usable.
+ *
+ * `measuredUsableInches` is the owner's override for what the drawing can't
+ * know — a bumper post short of the drawn end, a structure fouling the track.
+ * Given, it wins outright and the clearance points aren't applied to it: they
+ * measured the usable length itself.
+ */
+declare function usableCapacity(input: {
+    fromPos: number;
+    toPos: number;
+    /** Turnouts that DIVERGE ONTO this track — the ones that govern its ends. */
+    governing?: {
+        pos: number;
+        size?: number | null;
+    }[] | null;
+    /** The owner's measured usable length, inches. Wins when present. */
+    measuredUsableInches?: number | null;
+    library?: TrackPart[];
+    carLengthInches?: number;
+}): UsableCapacity;
+/** What a board's end is, once the geometry has been asked (#130). */
+interface SectionEndAssessment {
+    /** Has the owner described this end at all? Undescribed is an ordinary
+     * internal joint — exempt from the end-interface rules (#96) — not a failure. */
+    described: boolean;
+    /** Does it meet the standard's end-interface rules? Only a described end can. */
+    conforming: boolean;
+    /** Why it doesn't, when it doesn't. Empty for a conforming or undescribed end. */
+    issues: EndplateWidthIssue[];
+    /** The resolved values the assessment was made against. */
+    config: TrackConfig | "none";
+    widthInches: number;
+    trackOffsetInches: number;
+}
+/**
+ * Is this end of a board a standard endplate? (#130)
+ *
+ * ⭐ **Derived, never declared.** The issue is emphatic and the reason is good:
+ * a checkbox could be ticked wrongly, and the registry would then promise
+ * Free-Dispatcher a mating surface that doesn't exist. So the answer comes from
+ * the same rules {@link checkEndplateWidth} already applies to a module's own
+ * plates — §1.1's 12″ minimum, and §2.0's 4″ fascia clearance and 1.125″ pair.
+ *
+ * Two of the standard's conditions aren't checked because they can't be false
+ * here: track crosses the face **perpendicular** and a double end's two tracks
+ * sit **1.125″ apart** are both true by construction in this model. Inventing
+ * fields for them would be inventing ways to be wrong.
+ *
+ * An end with no config is **undescribed**, which is the ordinary case — most
+ * joints inside a module are just joints.
+ */
+declare function assessSectionEnd(end: SectionEnd | null | undefined, opts?: {
+    main2Below?: boolean;
+}): SectionEndAssessment;
+/** Two board ends meeting at a joint, and whether that joint is a standard
+ * interface (#130). */
+interface SectionJointAssessment {
+    west: SectionEndAssessment;
+    east: SectionEndAssessment;
+    /** Both ends conform AND present the same number of tracks — so these two
+     * boards could be separated and each used against any other module. */
+    standardInterface: boolean;
+    /** Plain-language reason it isn't one, or null when it is. */
+    reason: string | null;
+}
+/**
+ * Assess a joint — the two board ends that meet there (#130).
+ *
+ * ⚠️ Track COUNT is the only compatibility rule. Two conforming ends of
+ * differing face WIDTH still mate: the standard lets plates differ in width and
+ * be offset, so long as the track lines up. That's a deliberate non-check — see
+ * the note on endplate width authoring.
+ */
+declare function assessSectionJoint(west: SectionEnd | null | undefined, east: SectionEnd | null | undefined, opts?: {
+    main2Below?: boolean;
+}): SectionJointAssessment;
 /** How much of a car-spot span has no rail under it (#194). */
 interface SpanOverhang {
     /** Inches the span runs past the track's near end (0 = it starts on track). */
@@ -822,6 +979,8 @@ interface EditorTrack {
     /** Authored 2-D path (module-local inches) — a bent/rotated spur's real
      * shape. Absent = derive from the main + lane (#2d-track). */
     path?: BenchworkPoint[];
+    /** Measured usable length, real inches (#20). Absent = derived (#19). */
+    measuredUsableInches?: number;
 }
 /** A module_tracks row as loaded for the editor. */
 interface ModuleTrackRow {
@@ -2051,4 +2210,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, 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 SpanOverhang, 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, spanOverhang, stateToDoc, storedPartToTrackPart, toSectionRelative, trackMeetsEndplateIssues, trackPart, trackPath, turnoutClosure, turnoutFacing, turnoutOccupiedSpan, turnoutPartForSize };
+export { ATLAS_CODE55_N, BUILT_IN_TRACK_PARTS, type BenchworkPoint, type BranchConnector, CLEARANCE_SPACING_INCHES, CODE55_RAIL_HEIGHT_INCHES, DEFAULT_FLEX_PART_ID, type DimensionSource, type DrawCrossing, type DrawCrossover, type DrawIndustry, type DrawSignal, type DrawTrack, type DrawTurnout, ENDPLATE_FASCIA_CLEAR_INCHES, ENDPLATE_LEAD_INCHES, type EditorBranch, type EditorControlPoint, type EditorCpSignal, type EditorCrossing, type EditorIndustry, type EditorState, type EditorTrack, type EditorTurnout, type EndplateBConfig, type EndplatePose, type EndplateTrackIssue, type EndplateWidthIssue, 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 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, 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, spanOverhang, stateToDoc, storedPartToTrackPart, toSectionRelative, trackMeetsEndplateIssues, trackPart, trackPath, turnoutClosure, turnoutFacing, turnoutOccupiedSpan, turnoutPartForSize, usableCapacity };

package/dist/index.js

@@ -29,10 +29,28 @@ function moduleSections(doc) {
       ...typeof len === "number" && Number.isFinite(len) && len > 0 ? { lengthInches: len } : {},
       ...sec.geometryType ? { geometryType: sec.geometryType } : {},
       ...typeof deg === "number" && Number.isFinite(deg) ? { geometryDegrees: deg } : {},
-      ...typeof off === "number" && Number.isFinite(off) ? { geometryOffsetInches: off } : {}
+      ...typeof off === "number" && Number.isFinite(off) ? { geometryOffsetInches: off } : {},
+      // The board's two ends (#130). Written only when actually described —
+      // an absent end is an ordinary internal joint, and an empty object
+      // would claim the owner had said something about it.
+      ...sectionEnd(sec.endA) ? { endA: sectionEnd(sec.endA) } : {},
+      ...sectionEnd(sec.endB) ? { endB: sectionEnd(sec.endB) } : {}
     };
   });
 }
+function sectionEnd(end) {
+  if (!end) return null;
+  const config = end.config === "single" || end.config === "double" || end.config === "none" ? end.config : null;
+  const w = end.widthInches;
+  const o = end.trackOffsetInches;
+  const out = {
+    ...config ? { config } : {},
+    ...typeof w === "number" && Number.isFinite(w) && w > 0 ? { widthInches: w } : {},
+    // Signed, and 0 is meaningful ("explicitly centred", #93) — keep any finite.
+    ...typeof o === "number" && Number.isFinite(o) ? { trackOffsetInches: o } : {}
+  };
+  return Object.keys(out).length ? out : null;
+}
 function sectionFootprints(doc, derive) {
   const spans = derive ? sectionSpans(doc) : [];
   const spanOf = new Map(spans.map((sp) => [sp.id, sp]));
@@ -575,6 +593,92 @@ function scaleFeetToInches(feet, ratio = N_SCALE_RATIO) {
   return feet * 12 / ratio;
 }
 var N_CAR_LENGTH_INCHES = 3.3;
+var CLEARANCE_SPACING_INCHES = FREEMO_TRACK_SPACING_INCHES;
+function clearancePointPastFrogInches(size, library = BUILT_IN_TRACK_PARTS, clearanceInches = CLEARANCE_SPACING_INCHES) {
+  const N = size > 0 ? size : 6;
+  const lead = leadInchesForSize(N, library);
+  const cl = turnoutClosure(N, { leadInches: lead });
+  let lo = 0;
+  let hi = Math.max(4 * lead, 4 * clearanceInches * N);
+  if (cl.offsetAt(hi) < clearanceInches) return hi - lead;
+  for (let i = 0; i < 60; i++) {
+    const mid = (lo + hi) / 2;
+    if (cl.offsetAt(mid) < clearanceInches) lo = mid;
+    else hi = mid;
+  }
+  return Math.max(0, hi - lead);
+}
+function usableCapacity(input) {
+  const lo = Math.min(input.fromPos, input.toPos);
+  const hi = Math.max(input.fromPos, input.toPos);
+  const drawn = hi - lo;
+  const carLen = input.carLengthInches ?? N_CAR_LENGTH_INCHES;
+  if (typeof input.measuredUsableInches === "number" && input.measuredUsableInches >= 0) {
+    const m = input.measuredUsableInches;
+    return {
+      fromPos: lo,
+      toPos: lo + m,
+      usableInches: m,
+      drawnInches: drawn,
+      givenUpInches: Math.max(0, drawn - m),
+      cars: carCapacity(0, m, carLen),
+      scaleFeet: Math.round(inchesToScaleFeet(m))
+    };
+  }
+  let a = lo;
+  let b = hi;
+  for (const sw of input.governing ?? []) {
+    const c = clearancePointPastFrogInches(sw.size ?? 6, input.library);
+    if (Math.abs(sw.pos - lo) <= Math.abs(sw.pos - hi)) a = Math.max(a, lo + c);
+    else b = Math.min(b, hi - c);
+  }
+  const usable = Math.max(0, b - a);
+  return {
+    fromPos: a,
+    toPos: Math.max(a, b),
+    usableInches: usable,
+    drawnInches: drawn,
+    givenUpInches: Math.max(0, drawn - usable),
+    cars: carCapacity(0, usable, carLen),
+    scaleFeet: Math.round(inchesToScaleFeet(usable))
+  };
+}
+function assessSectionEnd(end, opts = {}) {
+  const config = end?.config ?? "none";
+  const widthInches = endplateWidthInches({ widthInches: end?.widthInches });
+  const trackOffsetInches = endplateTrackOffsetInches(
+    end?.trackOffsetInches,
+    config,
+    opts.main2Below
+  );
+  const described = config === "single" || config === "double";
+  if (!described) {
+    return { described: false, conforming: false, issues: [], config, widthInches, trackOffsetInches };
+  }
+  const issues = checkEndplateWidth({
+    widthInches: end?.widthInches,
+    config,
+    trackOffsetInches: end?.trackOffsetInches,
+    main2Below: opts.main2Below
+  });
+  return { described: true, conforming: issues.length === 0, issues, config, widthInches, trackOffsetInches };
+}
+function assessSectionJoint(west, east, opts = {}) {
+  const w = assessSectionEnd(west, opts);
+  const e = assessSectionEnd(east, opts);
+  let reason = null;
+  if (!w.described || !e.described) {
+    reason = "an internal joint \u2014 neither end has been described as an interface";
+    if (w.described !== e.described)
+      reason = `only the ${w.described ? "west" : "east"} side is described as an endplate`;
+  } else if (!w.conforming || !e.conforming) {
+    const bad = !w.conforming ? w : e;
+    reason = bad.issues[0]?.message ?? "an end doesn't meet the standard";
+  } else if (w.config !== e.config) {
+    reason = `${w.config} meets ${e.config} \u2014 the track counts differ`;
+  }
+  return { west: w, east: e, standardInterface: reason === null, reason };
+}
 function spanOverhang(input) {
   const lo = Math.min(input.fromPos, input.toPos);
   const hi = Math.max(input.fromPos, input.toPos);
@@ -825,7 +929,17 @@ function stateToDoc(state, recordNumber) {
         toPos: t.toPos,
         moduleTrackId: t.moduleTrackId,
         trackName: t.trackName || void 0,
-        capacityFeet: Math.round(inchesToScaleFeet(Math.abs(t.toPos - t.fromPos))),
+        // ⚠️ USABLE capacity, measured from the governing turnouts' CLEARANCE
+        // POINTS (#19) — not the drawn rail-to-rail length, which counts track
+        // a car can't stand on without fouling the route it diverged from.
+        // FMN-0040's 70″ siding is 21 cars drawn and 17 usable.
+        capacityFeet: usableCapacity({
+          fromPos: t.fromPos,
+          toPos: t.toPos,
+          governing: state.turnouts.filter((sw) => sw.divergeTrack === t.id),
+          measuredUsableInches: t.measuredUsableInches
+        }).scaleFeet,
+        ...typeof t.measuredUsableInches === "number" && t.measuredUsableInches >= 0 ? { measuredUsableInches: t.measuredUsableInches } : {},
         ...state.loop && t.inLoop ? { inLoop: true } : {},
         ...t.path && t.path.length >= 2 ? { path: t.path } : {}
       }))
@@ -924,7 +1038,10 @@ function docToState(doc, fallbackLength, moduleTracks = []) {
         trackName: t.trackName ?? nameOf(moduleTrackId),
         ...t.inLoop ? { inLoop: true } : {},
         // Authored path kept as-drawn (a physical shape, not rescaled with length).
-        ...trackPath(t.path) ? { path: trackPath(t.path) } : {}
+        ...trackPath(t.path) ? { path: trackPath(t.path) } : {},
+        // A MEASURED length is a real-world fact about the physical track, so it
+        // rescales with the module exactly as its positions do (#20).
+        ...typeof t.measuredUsableInches === "number" && Number.isFinite(t.measuredUsableInches) ? { measuredUsableInches: sc(t.measuredUsableInches) } : {}
       });
     }
   }
@@ -2360,6 +2477,6 @@ function poseOverridesFromDoc(doc) {
   return out;
 }
 
-export { ATLAS_CODE55_N, BUILT_IN_TRACK_PARTS, CODE55_RAIL_HEIGHT_INCHES, DEFAULT_FLEX_PART_ID, ENDPLATE_FASCIA_CLEAR_INCHES, ENDPLATE_LEAD_INCHES, FLEX_TRACK_PARTS, FREEMO_ENDPLATE_TRACK_FASCIA_CLEARANCE_INCHES, FREEMO_ENDPLATE_WIDTH_MIN_INCHES, FREEMO_ENDPLATE_WIDTH_RECOMMENDED_INCHES, FREEMO_TRACK_SPACING_INCHES, MAIN2_TRACK_ID, MAIN_TRACK_ID, N_CAR_LENGTH_INCHES, N_SCALE_RATIO, RAIL_GAUGE_INCHES, TIE_HALF_LENGTH_INCHES, TURNOUT_LEAD_INCHES_PER_FROG, 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, spanOverhang, stateToDoc, storedPartToTrackPart, toSectionRelative, trackMeetsEndplateIssues, trackPart, trackPath, turnoutClosure, turnoutFacing, turnoutOccupiedSpan, turnoutPartForSize };
+export { ATLAS_CODE55_N, BUILT_IN_TRACK_PARTS, CLEARANCE_SPACING_INCHES, CODE55_RAIL_HEIGHT_INCHES, DEFAULT_FLEX_PART_ID, ENDPLATE_FASCIA_CLEAR_INCHES, ENDPLATE_LEAD_INCHES, FLEX_TRACK_PARTS, FREEMO_ENDPLATE_TRACK_FASCIA_CLEARANCE_INCHES, FREEMO_ENDPLATE_WIDTH_MIN_INCHES, FREEMO_ENDPLATE_WIDTH_RECOMMENDED_INCHES, FREEMO_TRACK_SPACING_INCHES, MAIN2_TRACK_ID, MAIN_TRACK_ID, N_CAR_LENGTH_INCHES, N_SCALE_RATIO, RAIL_GAUGE_INCHES, TIE_HALF_LENGTH_INCHES, TURNOUT_LEAD_INCHES_PER_FROG, WHOLE_MODULE_SECTION_ID, asModuleSchematic, assessSectionEnd, assessSectionJoint, benchworkBand, benchworkOutline, buildCrossover, buildPassingSiding, buildTransition, carCapacity, checkEndplateWidth, clearancePointPastFrogInches, 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, spanOverhang, stateToDoc, storedPartToTrackPart, toSectionRelative, trackMeetsEndplateIssues, trackPart, trackPath, turnoutClosure, turnoutFacing, turnoutOccupiedSpan, turnoutPartForSize, usableCapacity };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map