@willcgage/module-schematic 0.28.1 → 0.29.0

package/dist/index.d.cts

@@ -240,8 +240,22 @@ interface ModuleSchematicDoc {
     outline?: BenchworkPoint[];
     /** Internal section joints — inches from endplate A where the module's boards
      * split into sections. Operationally one unit; these mark construction/transport
-     * seams (exempt from the end-interface standards). Empty/absent = one section. */
+     * seams (exempt from the end-interface standards). Empty/absent = one section.
+     * Describes only sections that are full-depth SLICES; a section with a shape
+     * of its own lives in `sections` below. */
     sectionBreaks?: number[];
+    /** The module's sections as real objects — named, each with a bench-work
+     * outline of its own (#96 phase 2). A module is a kit: the same sections can
+     * be set up in different combinations, so its footprint is the UNION of the
+     * sections present rather than an independently authored shape.
+     *
+     * Needed because sections are not slices. Real modules hang a deep section
+     * off the BACK of a shallow main band — a peninsula carrying an industry —
+     * which no single position along the main can describe.
+     *
+     * Absent = the module keeps using its own `outline` exactly as before; this
+     * is purely additive and nothing migrates on read. */
+    sections?: SchematicSection[];
     /** @deprecated pre-grouping flat signals; read for back-compat. */
     signals?: SchematicSignal[];
     /** Authored mainline centre-line (module-local inches, open path with arcs).
@@ -258,12 +272,43 @@ interface BenchworkPoint {
     y: number;
     bulge?: number;
 }
+/** One bench-work section of a module (#96 phase 2). */
+interface SchematicSection {
+    id: string;
+    /** What the owner calls this board — "west transition", "double #3". */
+    name?: string | null;
+    /** This section's own footprint polygon, module-local inches, same frame as
+     * the module outline. Absent = the section has no shape of its own yet (it's
+     * described only by the joints in `sectionBreaks`). */
+    outline?: BenchworkPoint[] | 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
  * valid outline needs at least 3 points. Normalises each vertex to {x, y, bulge?}. */
 declare function benchworkOutline(doc: {
     outline?: BenchworkPoint[] | null;
 } | null | undefined): BenchworkPoint[] | null;
+/** The module's sections, normalised — id required, name trimmed away when
+ * blank, outline kept only when it's a usable polygon (#96 phase 2). */
+declare function moduleSections(doc: {
+    sections?: SchematicSection[] | null;
+} | null | undefined): SchematicSection[];
+/** Every section outline that's actually a shape, arc-sampled for drawing.
+ * Drawing all of them IS the module's footprint — the union of its sections.
+ * No polygon boolean is computed: a renderer painting each ring gives the same
+ * picture, and an approximate union would be worse than none. If something
+ * ever needs a single ring (an export, a collision test), that's the point to
+ * bring in real clipping. */
+declare function sectionFootprints(doc: {
+    sections?: SchematicSection[] | null;
+} | null | undefined): {
+    id: string;
+    name?: string;
+    outline: {
+        x: number;
+        y: number;
+    }[];
+}[];
 /**
  * Expand a benchwork outline (whose edges may be arcs) into a dense closed
  * polyline for rendering — the SAME sampling both the Repository preview and
@@ -305,6 +350,9 @@ interface ModuleFootprintInput {
     endplateTrackOffsets?: Record<string, number>;
     /** Authored benchwork outline (module-local inches), or absent for the band. */
     outline?: BenchworkPoint[] | null;
+    /** The module's sections (#96 phase 2). When any carries an outline, the
+     * module's footprint is the union of those — `outline` is then ignored. */
+    sections?: SchematicSection[] | null;
     /** Authored mainline centre-line (module-local inches, open path with arcs).
      * When present it wins over the geometry-derived centre-line — the owner drew
      * the real shape (#2d-track, physical view only). */
@@ -323,8 +371,20 @@ interface ModuleFootprint {
     band: BenchworkPoint[];
     /** Endplate faces: [A end, B end]. */
     endplateFaces: OutlineFace[];
-    /** Authored outline (arc-sampled closed ring) or null → render the band. */
+    /** Authored outline (arc-sampled closed ring) or null → render the band.
+     * Null too when `sectionOutlines` is non-empty — the sections ARE the shape. */
     outline: BenchworkPoint[] | null;
+    /** Per-section footprints, arc-sampled (#96 phase 2). Draw every one: together
+     * they are the module's footprint. Empty = this module doesn't use sections,
+     * so fall back to `outline ?? band` exactly as before. */
+    sectionOutlines: {
+        id: string;
+        name?: string;
+        outline: {
+            x: number;
+            y: number;
+        }[];
+    }[];
 }
 /** Module-local main track centre-line (A→B), sampling arcs for curves/corners.
  * An authored `mainPath` wins — the owner drew the real shape; otherwise the
@@ -531,6 +591,9 @@ interface EditorState {
     /** Internal section joints — inches from endplate A where the boards split
      * into sections. Empty = a single section (#48). */
     sectionBreaks: number[];
+    /** The module's sections as named objects, each optionally carrying its own
+     * outline (#96 phase 2). Empty = fall back to `outline` + `sectionBreaks`. */
+    sections: SchematicSection[];
     controlPoints: EditorControlPoint[];
     /** Rail-served industries — car-spot spans on a track (#industries). */
     industries: EditorIndustry[];
@@ -815,4 +878,4 @@ declare function poseOverridesFromDoc(doc: ModuleSchematicDoc): Record<string, {
     heading: number;
 }>;
 
-export { type BenchworkPoint, type BranchConnector, type DrawCrossing, type DrawCrossover, type DrawIndustry, type DrawSignal, type DrawTrack, type DrawTurnout, type EditorBranch, type EditorControlPoint, type EditorCpSignal, type EditorCrossing, type EditorIndustry, type EditorState, type EditorTrack, type EditorTurnout, type EndplateBConfig, type EndplatePose, type EndplateWidthIssue, FREEMO_ENDPLATE_TRACK_FASCIA_CLEARANCE_INCHES, FREEMO_ENDPLATE_WIDTH_MIN_INCHES, FREEMO_ENDPLATE_WIDTH_RECOMMENDED_INCHES, FREEMO_TRACK_SPACING_INCHES, type GeometryType, 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 SchematicBlock, type SchematicControlPoint, type SchematicCrossing, type SchematicEndplate, type SchematicEndplateTrack, type SchematicIndustry, type SchematicSignal, type SchematicTrack, type SchematicTurnout, type SignalFacing, type SignalSide, type TrackConfig, type TrackRole, type TurnoutKind, asModuleSchematic, benchworkBand, benchworkOutline, buildCrossover, buildPassingSiding, buildTransition, carCapacity, checkEndplateWidth, deriveEndplatePoses, divergeSideForHand, docToState, emptyEditorState, endplateFaceSegments, endplateTrackOffsetFor, endplateTrackOffsetInches, endplateWidthInches, geometryTurnDegrees, inchesToScaleFeet, isLoopDoc, isTransitionTurnout, moduleCenterline, moduleFeatures, moduleFootprint, nextId, poseNeedsManual, poseOverridesFromDoc, sampleBenchworkOutline, samplePath, scaleFeetToInches, stateToDoc, trackPath };
+export { type BenchworkPoint, type BranchConnector, type DrawCrossing, type DrawCrossover, type DrawIndustry, type DrawSignal, type DrawTrack, type DrawTurnout, type EditorBranch, type EditorControlPoint, type EditorCpSignal, type EditorCrossing, type EditorIndustry, type EditorState, type EditorTrack, type EditorTurnout, type EndplateBConfig, type EndplatePose, type EndplateWidthIssue, FREEMO_ENDPLATE_TRACK_FASCIA_CLEARANCE_INCHES, FREEMO_ENDPLATE_WIDTH_MIN_INCHES, FREEMO_ENDPLATE_WIDTH_RECOMMENDED_INCHES, FREEMO_TRACK_SPACING_INCHES, type GeometryType, 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 SchematicBlock, type SchematicControlPoint, type SchematicCrossing, type SchematicEndplate, type SchematicEndplateTrack, type SchematicIndustry, type SchematicSection, type SchematicSignal, type SchematicTrack, type SchematicTurnout, type SignalFacing, type SignalSide, type TrackConfig, type TrackRole, type TurnoutKind, asModuleSchematic, benchworkBand, benchworkOutline, buildCrossover, buildPassingSiding, buildTransition, carCapacity, checkEndplateWidth, deriveEndplatePoses, divergeSideForHand, docToState, emptyEditorState, endplateFaceSegments, endplateTrackOffsetFor, endplateTrackOffsetInches, endplateWidthInches, geometryTurnDegrees, inchesToScaleFeet, isLoopDoc, isTransitionTurnout, moduleCenterline, moduleFeatures, moduleFootprint, moduleSections, nextId, poseNeedsManual, poseOverridesFromDoc, sampleBenchworkOutline, samplePath, scaleFeetToInches, sectionFootprints, stateToDoc, trackPath };

package/dist/index.d.ts

@@ -240,8 +240,22 @@ interface ModuleSchematicDoc {
     outline?: BenchworkPoint[];
     /** Internal section joints — inches from endplate A where the module's boards
      * split into sections. Operationally one unit; these mark construction/transport
-     * seams (exempt from the end-interface standards). Empty/absent = one section. */
+     * seams (exempt from the end-interface standards). Empty/absent = one section.
+     * Describes only sections that are full-depth SLICES; a section with a shape
+     * of its own lives in `sections` below. */
     sectionBreaks?: number[];
+    /** The module's sections as real objects — named, each with a bench-work
+     * outline of its own (#96 phase 2). A module is a kit: the same sections can
+     * be set up in different combinations, so its footprint is the UNION of the
+     * sections present rather than an independently authored shape.
+     *
+     * Needed because sections are not slices. Real modules hang a deep section
+     * off the BACK of a shallow main band — a peninsula carrying an industry —
+     * which no single position along the main can describe.
+     *
+     * Absent = the module keeps using its own `outline` exactly as before; this
+     * is purely additive and nothing migrates on read. */
+    sections?: SchematicSection[];
     /** @deprecated pre-grouping flat signals; read for back-compat. */
     signals?: SchematicSignal[];
     /** Authored mainline centre-line (module-local inches, open path with arcs).
@@ -258,12 +272,43 @@ interface BenchworkPoint {
     y: number;
     bulge?: number;
 }
+/** One bench-work section of a module (#96 phase 2). */
+interface SchematicSection {
+    id: string;
+    /** What the owner calls this board — "west transition", "double #3". */
+    name?: string | null;
+    /** This section's own footprint polygon, module-local inches, same frame as
+     * the module outline. Absent = the section has no shape of its own yet (it's
+     * described only by the joints in `sectionBreaks`). */
+    outline?: BenchworkPoint[] | 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
  * valid outline needs at least 3 points. Normalises each vertex to {x, y, bulge?}. */
 declare function benchworkOutline(doc: {
     outline?: BenchworkPoint[] | null;
 } | null | undefined): BenchworkPoint[] | null;
+/** The module's sections, normalised — id required, name trimmed away when
+ * blank, outline kept only when it's a usable polygon (#96 phase 2). */
+declare function moduleSections(doc: {
+    sections?: SchematicSection[] | null;
+} | null | undefined): SchematicSection[];
+/** Every section outline that's actually a shape, arc-sampled for drawing.
+ * Drawing all of them IS the module's footprint — the union of its sections.
+ * No polygon boolean is computed: a renderer painting each ring gives the same
+ * picture, and an approximate union would be worse than none. If something
+ * ever needs a single ring (an export, a collision test), that's the point to
+ * bring in real clipping. */
+declare function sectionFootprints(doc: {
+    sections?: SchematicSection[] | null;
+} | null | undefined): {
+    id: string;
+    name?: string;
+    outline: {
+        x: number;
+        y: number;
+    }[];
+}[];
 /**
  * Expand a benchwork outline (whose edges may be arcs) into a dense closed
  * polyline for rendering — the SAME sampling both the Repository preview and
@@ -305,6 +350,9 @@ interface ModuleFootprintInput {
     endplateTrackOffsets?: Record<string, number>;
     /** Authored benchwork outline (module-local inches), or absent for the band. */
     outline?: BenchworkPoint[] | null;
+    /** The module's sections (#96 phase 2). When any carries an outline, the
+     * module's footprint is the union of those — `outline` is then ignored. */
+    sections?: SchematicSection[] | null;
     /** Authored mainline centre-line (module-local inches, open path with arcs).
      * When present it wins over the geometry-derived centre-line — the owner drew
      * the real shape (#2d-track, physical view only). */
@@ -323,8 +371,20 @@ interface ModuleFootprint {
     band: BenchworkPoint[];
     /** Endplate faces: [A end, B end]. */
     endplateFaces: OutlineFace[];
-    /** Authored outline (arc-sampled closed ring) or null → render the band. */
+    /** Authored outline (arc-sampled closed ring) or null → render the band.
+     * Null too when `sectionOutlines` is non-empty — the sections ARE the shape. */
     outline: BenchworkPoint[] | null;
+    /** Per-section footprints, arc-sampled (#96 phase 2). Draw every one: together
+     * they are the module's footprint. Empty = this module doesn't use sections,
+     * so fall back to `outline ?? band` exactly as before. */
+    sectionOutlines: {
+        id: string;
+        name?: string;
+        outline: {
+            x: number;
+            y: number;
+        }[];
+    }[];
 }
 /** Module-local main track centre-line (A→B), sampling arcs for curves/corners.
  * An authored `mainPath` wins — the owner drew the real shape; otherwise the
@@ -531,6 +591,9 @@ interface EditorState {
     /** Internal section joints — inches from endplate A where the boards split
      * into sections. Empty = a single section (#48). */
     sectionBreaks: number[];
+    /** The module's sections as named objects, each optionally carrying its own
+     * outline (#96 phase 2). Empty = fall back to `outline` + `sectionBreaks`. */
+    sections: SchematicSection[];
     controlPoints: EditorControlPoint[];
     /** Rail-served industries — car-spot spans on a track (#industries). */
     industries: EditorIndustry[];
@@ -815,4 +878,4 @@ declare function poseOverridesFromDoc(doc: ModuleSchematicDoc): Record<string, {
     heading: number;
 }>;
 
-export { type BenchworkPoint, type BranchConnector, type DrawCrossing, type DrawCrossover, type DrawIndustry, type DrawSignal, type DrawTrack, type DrawTurnout, type EditorBranch, type EditorControlPoint, type EditorCpSignal, type EditorCrossing, type EditorIndustry, type EditorState, type EditorTrack, type EditorTurnout, type EndplateBConfig, type EndplatePose, type EndplateWidthIssue, FREEMO_ENDPLATE_TRACK_FASCIA_CLEARANCE_INCHES, FREEMO_ENDPLATE_WIDTH_MIN_INCHES, FREEMO_ENDPLATE_WIDTH_RECOMMENDED_INCHES, FREEMO_TRACK_SPACING_INCHES, type GeometryType, 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 SchematicBlock, type SchematicControlPoint, type SchematicCrossing, type SchematicEndplate, type SchematicEndplateTrack, type SchematicIndustry, type SchematicSignal, type SchematicTrack, type SchematicTurnout, type SignalFacing, type SignalSide, type TrackConfig, type TrackRole, type TurnoutKind, asModuleSchematic, benchworkBand, benchworkOutline, buildCrossover, buildPassingSiding, buildTransition, carCapacity, checkEndplateWidth, deriveEndplatePoses, divergeSideForHand, docToState, emptyEditorState, endplateFaceSegments, endplateTrackOffsetFor, endplateTrackOffsetInches, endplateWidthInches, geometryTurnDegrees, inchesToScaleFeet, isLoopDoc, isTransitionTurnout, moduleCenterline, moduleFeatures, moduleFootprint, nextId, poseNeedsManual, poseOverridesFromDoc, sampleBenchworkOutline, samplePath, scaleFeetToInches, stateToDoc, trackPath };
+export { type BenchworkPoint, type BranchConnector, type DrawCrossing, type DrawCrossover, type DrawIndustry, type DrawSignal, type DrawTrack, type DrawTurnout, type EditorBranch, type EditorControlPoint, type EditorCpSignal, type EditorCrossing, type EditorIndustry, type EditorState, type EditorTrack, type EditorTurnout, type EndplateBConfig, type EndplatePose, type EndplateWidthIssue, FREEMO_ENDPLATE_TRACK_FASCIA_CLEARANCE_INCHES, FREEMO_ENDPLATE_WIDTH_MIN_INCHES, FREEMO_ENDPLATE_WIDTH_RECOMMENDED_INCHES, FREEMO_TRACK_SPACING_INCHES, type GeometryType, 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 SchematicBlock, type SchematicControlPoint, type SchematicCrossing, type SchematicEndplate, type SchematicEndplateTrack, type SchematicIndustry, type SchematicSection, type SchematicSignal, type SchematicTrack, type SchematicTurnout, type SignalFacing, type SignalSide, type TrackConfig, type TrackRole, type TurnoutKind, asModuleSchematic, benchworkBand, benchworkOutline, buildCrossover, buildPassingSiding, buildTransition, carCapacity, checkEndplateWidth, deriveEndplatePoses, divergeSideForHand, docToState, emptyEditorState, endplateFaceSegments, endplateTrackOffsetFor, endplateTrackOffsetInches, endplateWidthInches, geometryTurnDegrees, inchesToScaleFeet, isLoopDoc, isTransitionTurnout, moduleCenterline, moduleFeatures, moduleFootprint, moduleSections, nextId, poseNeedsManual, poseOverridesFromDoc, sampleBenchworkOutline, samplePath, scaleFeetToInches, sectionFootprints, stateToDoc, trackPath };

package/dist/index.js

@@ -15,6 +15,24 @@ function benchworkOutline(doc) {
   }));
   return pts.length >= 3 ? pts : null;
 }
+function moduleSections(doc) {
+  return (doc?.sections ?? []).filter((sec) => sec && typeof sec.id === "string" && sec.id !== "").map((sec) => {
+    const outline = benchworkOutline({ outline: sec.outline });
+    const name = typeof sec.name === "string" ? sec.name.trim() : "";
+    return {
+      id: sec.id,
+      ...name ? { name } : {},
+      ...outline ? { outline } : {}
+    };
+  });
+}
+function sectionFootprints(doc) {
+  return moduleSections(doc).filter((sec) => sec.outline).map((sec) => ({
+    id: sec.id,
+    ...sec.name ? { name: sec.name } : {},
+    outline: sampleBenchworkOutline(sec.outline)
+  }));
+}
 function sampleBenchworkOutline(pts, segsPerArc = 20) {
   const n = pts.length;
   if (n < 2) return pts.map((p) => ({ x: p.x, y: p.y }));
@@ -177,11 +195,13 @@ function moduleFootprint(input) {
   const authored = benchworkOutline(input);
   const offA = input.endplateTrackOffsets?.["A"] ?? 0;
   const offB = input.endplateTrackOffsets?.["B"] ?? 0;
+  const sectionOutlines = sectionFootprints(input);
   return {
     centerline,
     band: benchworkBand(centerline, widthA, widthB, offA, offB),
     endplateFaces: endplateFaceSegments(centerline, widthA, widthB, offA, offB),
-    outline: authored ? sampleBenchworkOutline(authored) : null
+    outline: sectionOutlines.length || !authored ? null : sampleBenchworkOutline(authored),
+    sectionOutlines
   };
 }
 function endplateTrackOffsetFor(config, authoredTrackOffset) {
@@ -262,6 +282,7 @@ function emptyEditorState(lengthInches) {
     endplateTrackOffsets: {},
     outline: [],
     sectionBreaks: [],
+    sections: [],
     controlPoints: [],
     industries: [],
     mainPath: []
@@ -485,6 +506,9 @@ function stateToDoc(state, recordNumber) {
     ...state.outline.length >= 3 ? { outline: state.outline } : {},
     // Internal section joints (inches from A), when the module has more than one.
     ...state.sectionBreaks.length ? { sectionBreaks: state.sectionBreaks } : {},
+    // Sections as objects — emitted only once the owner has some, so a module
+    // that never used them keeps exactly the doc it had before (#96 phase 2).
+    ...state.sections.length ? { sections: moduleSections({ sections: state.sections }) } : {},
     // Authored mainline path (module-local inches); only when it's a real path.
     ...state.mainPath.length >= 2 ? { mainPath: state.mainPath } : {}
   };
@@ -590,6 +614,7 @@ function docToState(doc, fallbackLength, moduleTracks = []) {
     endplateTrackOffsets,
     outline,
     sectionBreaks: (d.sectionBreaks ?? []).filter((n) => Number.isFinite(n)).map((n) => sc(n)),
+    sections: moduleSections(d),
     mainPath,
     crossings: (d.crossings ?? []).map((x) => ({
       id: x.id,
@@ -1091,6 +1116,6 @@ function poseOverridesFromDoc(doc) {
   return out;
 }
 
-export { 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, asModuleSchematic, benchworkBand, benchworkOutline, buildCrossover, buildPassingSiding, buildTransition, carCapacity, checkEndplateWidth, deriveEndplatePoses, divergeSideForHand, docToState, emptyEditorState, endplateFaceSegments, endplateTrackOffsetFor, endplateTrackOffsetInches, endplateWidthInches, geometryTurnDegrees, inchesToScaleFeet, isLoopDoc, isTransitionTurnout, moduleCenterline, moduleFeatures, moduleFootprint, nextId, poseNeedsManual, poseOverridesFromDoc, sampleBenchworkOutline, samplePath, scaleFeetToInches, stateToDoc, trackPath };
+export { 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, asModuleSchematic, benchworkBand, benchworkOutline, buildCrossover, buildPassingSiding, buildTransition, carCapacity, checkEndplateWidth, deriveEndplatePoses, divergeSideForHand, docToState, emptyEditorState, endplateFaceSegments, endplateTrackOffsetFor, endplateTrackOffsetInches, endplateWidthInches, geometryTurnDegrees, inchesToScaleFeet, isLoopDoc, isTransitionTurnout, moduleCenterline, moduleFeatures, moduleFootprint, moduleSections, nextId, poseNeedsManual, poseOverridesFromDoc, sampleBenchworkOutline, samplePath, scaleFeetToInches, sectionFootprints, stateToDoc, trackPath };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map