@willcgage/module-schematic 0.18.0 → 0.19.0

package/dist/index.d.cts

@@ -78,6 +78,11 @@ interface SchematicTrack {
      * endplate A (past the throat = in the loop), lane is the ladder/arc index —
      * one record drives both the unrolled fan and a geometric render. */
     inLoop?: boolean;
+    /** Authored 2-D path for this track (module-local inches, open path with
+     * arcs) — the PHYSICAL shape a bent/rotated spur draws. Absent = derive from
+     * the main centre-line + lane, as before. Physical view only; the operations
+     * view stays positional (#2d-track). */
+    path?: BenchworkPoint[] | null;
 }
 interface SchematicTurnout {
     id: string;
@@ -195,6 +200,10 @@ interface ModuleSchematicDoc {
     outline?: BenchworkPoint[];
     /** @deprecated pre-grouping flat signals; read for back-compat. */
     signals?: SchematicSignal[];
+    /** Authored mainline centre-line (module-local inches, open path with arcs).
+     * Present = the owner drew the real shape; absent = derive from geometry.
+     * Physical view only — the operations view stays derived (#2d-track). */
+    mainPath?: BenchworkPoint[] | null;
 }
 /** A benchwork-outline vertex, module-local inches. The edge from this vertex
  * to the NEXT one is a straight line, unless `bulge` is set — then it's a
@@ -222,6 +231,19 @@ declare function sampleBenchworkOutline(pts: BenchworkPoint[], segsPerArc?: numb
     x: number;
     y: number;
 }[];
+/**
+ * Expand an OPEN track path (whose edges may be arcs) into a dense polyline —
+ * the open-ended sibling of sampleBenchworkOutline (which closes the ring).
+ * Used for authored track centre-lines (a drawn mainline or spur). The final
+ * vertex is always emitted so the path reaches its end.
+ */
+declare function samplePath(pts: BenchworkPoint[], segsPerArc?: number): {
+    x: number;
+    y: number;
+}[];
+/** Normalise an authored track path from a doc, or null if it isn't a real path
+ * (needs ≥ 2 valid points). Keeps per-vertex bulge. */
+declare function trackPath(path: BenchworkPoint[] | null | undefined): BenchworkPoint[] | null;
 interface ModuleFootprintInput {
     /** Mainline length (falls back to footprint length), inches. */
     lengthInches: number;
@@ -232,6 +254,10 @@ interface ModuleFootprintInput {
     endplateWidths?: Record<string, number>;
     /** Authored benchwork outline (module-local inches), or absent for the band. */
     outline?: BenchworkPoint[] | 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). */
+    mainPath?: BenchworkPoint[] | null;
 }
 interface OutlineFace {
     /** The endplate face's two corners + midpoint (the track point). */
@@ -249,7 +275,9 @@ interface ModuleFootprint {
     /** Authored outline (arc-sampled closed ring) or null → render the band. */
     outline: BenchworkPoint[] | null;
 }
-/** Module-local main track centre-line (A→B), sampling arcs for curves/corners. */
+/** 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
+ * centre-line is derived from the geometry fields (length + type/degrees/offset). */
 declare function moduleCenterline(input: ModuleFootprintInput): BenchworkPoint[];
 /** Benchwork band: the centre-line offset ±half-width, tapering widthA→widthB. */
 declare function benchworkBand(center: BenchworkPoint[], widthA?: number, widthB?: number): BenchworkPoint[];
@@ -295,6 +323,9 @@ interface EditorTrack {
     trackName: string;
     /** Inside the balloon of a loop module (#165). */
     inLoop?: boolean;
+    /** Authored 2-D path (module-local inches) — a bent/rotated spur's real
+     * shape. Absent = derive from the main + lane (#2d-track). */
+    path?: BenchworkPoint[];
 }
 /** A module_tracks row as loaded for the editor. */
 interface ModuleTrackRow {
@@ -393,6 +424,9 @@ interface EditorState {
     controlPoints: EditorControlPoint[];
     /** Rail-served industries — car-spot spans on a track (#industries). */
     industries: EditorIndustry[];
+    /** Authored mainline centre-line (module-local inches) — empty = derive from
+     * geometry. The owner-drawn real shape (#2d-track, physical view only). */
+    mainPath: BenchworkPoint[];
 }
 /** Build the empty editor state for a module of the given length. */
 declare function emptyEditorState(lengthInches: number): EditorState;
@@ -671,4 +705,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, FREEMO_ENDPLATE_WIDTH_MIN_INCHES, FREEMO_ENDPLATE_WIDTH_RECOMMENDED_INCHES, type GeometryType, type IndustryLabelMode, 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, deriveEndplatePoses, divergeSideForHand, docToState, emptyEditorState, endplateFaceSegments, endplateWidthInches, geometryTurnDegrees, inchesToScaleFeet, isLoopDoc, isTransitionTurnout, moduleCenterline, moduleFeatures, moduleFootprint, nextId, poseNeedsManual, poseOverridesFromDoc, sampleBenchworkOutline, scaleFeetToInches, stateToDoc };
+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, FREEMO_ENDPLATE_WIDTH_MIN_INCHES, FREEMO_ENDPLATE_WIDTH_RECOMMENDED_INCHES, type GeometryType, type IndustryLabelMode, 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, deriveEndplatePoses, divergeSideForHand, docToState, emptyEditorState, endplateFaceSegments, endplateWidthInches, geometryTurnDegrees, inchesToScaleFeet, isLoopDoc, isTransitionTurnout, moduleCenterline, moduleFeatures, moduleFootprint, nextId, poseNeedsManual, poseOverridesFromDoc, sampleBenchworkOutline, samplePath, scaleFeetToInches, stateToDoc, trackPath };

package/dist/index.d.ts

@@ -78,6 +78,11 @@ interface SchematicTrack {
      * endplate A (past the throat = in the loop), lane is the ladder/arc index —
      * one record drives both the unrolled fan and a geometric render. */
     inLoop?: boolean;
+    /** Authored 2-D path for this track (module-local inches, open path with
+     * arcs) — the PHYSICAL shape a bent/rotated spur draws. Absent = derive from
+     * the main centre-line + lane, as before. Physical view only; the operations
+     * view stays positional (#2d-track). */
+    path?: BenchworkPoint[] | null;
 }
 interface SchematicTurnout {
     id: string;
@@ -195,6 +200,10 @@ interface ModuleSchematicDoc {
     outline?: BenchworkPoint[];
     /** @deprecated pre-grouping flat signals; read for back-compat. */
     signals?: SchematicSignal[];
+    /** Authored mainline centre-line (module-local inches, open path with arcs).
+     * Present = the owner drew the real shape; absent = derive from geometry.
+     * Physical view only — the operations view stays derived (#2d-track). */
+    mainPath?: BenchworkPoint[] | null;
 }
 /** A benchwork-outline vertex, module-local inches. The edge from this vertex
  * to the NEXT one is a straight line, unless `bulge` is set — then it's a
@@ -222,6 +231,19 @@ declare function sampleBenchworkOutline(pts: BenchworkPoint[], segsPerArc?: numb
     x: number;
     y: number;
 }[];
+/**
+ * Expand an OPEN track path (whose edges may be arcs) into a dense polyline —
+ * the open-ended sibling of sampleBenchworkOutline (which closes the ring).
+ * Used for authored track centre-lines (a drawn mainline or spur). The final
+ * vertex is always emitted so the path reaches its end.
+ */
+declare function samplePath(pts: BenchworkPoint[], segsPerArc?: number): {
+    x: number;
+    y: number;
+}[];
+/** Normalise an authored track path from a doc, or null if it isn't a real path
+ * (needs ≥ 2 valid points). Keeps per-vertex bulge. */
+declare function trackPath(path: BenchworkPoint[] | null | undefined): BenchworkPoint[] | null;
 interface ModuleFootprintInput {
     /** Mainline length (falls back to footprint length), inches. */
     lengthInches: number;
@@ -232,6 +254,10 @@ interface ModuleFootprintInput {
     endplateWidths?: Record<string, number>;
     /** Authored benchwork outline (module-local inches), or absent for the band. */
     outline?: BenchworkPoint[] | 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). */
+    mainPath?: BenchworkPoint[] | null;
 }
 interface OutlineFace {
     /** The endplate face's two corners + midpoint (the track point). */
@@ -249,7 +275,9 @@ interface ModuleFootprint {
     /** Authored outline (arc-sampled closed ring) or null → render the band. */
     outline: BenchworkPoint[] | null;
 }
-/** Module-local main track centre-line (A→B), sampling arcs for curves/corners. */
+/** 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
+ * centre-line is derived from the geometry fields (length + type/degrees/offset). */
 declare function moduleCenterline(input: ModuleFootprintInput): BenchworkPoint[];
 /** Benchwork band: the centre-line offset ±half-width, tapering widthA→widthB. */
 declare function benchworkBand(center: BenchworkPoint[], widthA?: number, widthB?: number): BenchworkPoint[];
@@ -295,6 +323,9 @@ interface EditorTrack {
     trackName: string;
     /** Inside the balloon of a loop module (#165). */
     inLoop?: boolean;
+    /** Authored 2-D path (module-local inches) — a bent/rotated spur's real
+     * shape. Absent = derive from the main + lane (#2d-track). */
+    path?: BenchworkPoint[];
 }
 /** A module_tracks row as loaded for the editor. */
 interface ModuleTrackRow {
@@ -393,6 +424,9 @@ interface EditorState {
     controlPoints: EditorControlPoint[];
     /** Rail-served industries — car-spot spans on a track (#industries). */
     industries: EditorIndustry[];
+    /** Authored mainline centre-line (module-local inches) — empty = derive from
+     * geometry. The owner-drawn real shape (#2d-track, physical view only). */
+    mainPath: BenchworkPoint[];
 }
 /** Build the empty editor state for a module of the given length. */
 declare function emptyEditorState(lengthInches: number): EditorState;
@@ -671,4 +705,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, FREEMO_ENDPLATE_WIDTH_MIN_INCHES, FREEMO_ENDPLATE_WIDTH_RECOMMENDED_INCHES, type GeometryType, type IndustryLabelMode, 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, deriveEndplatePoses, divergeSideForHand, docToState, emptyEditorState, endplateFaceSegments, endplateWidthInches, geometryTurnDegrees, inchesToScaleFeet, isLoopDoc, isTransitionTurnout, moduleCenterline, moduleFeatures, moduleFootprint, nextId, poseNeedsManual, poseOverridesFromDoc, sampleBenchworkOutline, scaleFeetToInches, stateToDoc };
+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, FREEMO_ENDPLATE_WIDTH_MIN_INCHES, FREEMO_ENDPLATE_WIDTH_RECOMMENDED_INCHES, type GeometryType, type IndustryLabelMode, 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, deriveEndplatePoses, divergeSideForHand, docToState, emptyEditorState, endplateFaceSegments, endplateWidthInches, geometryTurnDegrees, inchesToScaleFeet, isLoopDoc, isTransitionTurnout, moduleCenterline, moduleFeatures, moduleFootprint, nextId, poseNeedsManual, poseOverridesFromDoc, sampleBenchworkOutline, samplePath, scaleFeetToInches, stateToDoc, trackPath };

package/dist/index.js

@@ -43,6 +43,45 @@ function sampleBenchworkOutline(pts, segsPerArc = 20) {
   }
   return out;
 }
+function samplePath(pts, segsPerArc = 20) {
+  const n = pts.length;
+  if (n < 2) return pts.map((p) => ({ x: p.x, y: p.y }));
+  const out = [];
+  for (let i = 0; i < n - 1; i++) {
+    const p0 = pts[i];
+    const p1 = pts[i + 1];
+    out.push({ x: p0.x, y: p0.y });
+    const bulge = p0.bulge ?? 0;
+    if (!bulge) continue;
+    const dx = p1.x - p0.x;
+    const dy = p1.y - p0.y;
+    const c = Math.hypot(dx, dy);
+    if (c < 1e-6) continue;
+    const nx = -dy / c;
+    const ny = dx / c;
+    const mid = { x: (p0.x + p1.x) / 2 + nx * bulge, y: (p0.y + p1.y) / 2 + ny * bulge };
+    const circ = circleThrough(p0, mid, p1);
+    if (!circ) continue;
+    const a0 = Math.atan2(p0.y - circ.cy, p0.x - circ.cx);
+    const am = Math.atan2(mid.y - circ.cy, mid.x - circ.cx);
+    const a1 = Math.atan2(p1.y - circ.cy, p1.x - circ.cx);
+    const sweep = arcSweep(a0, a1, am);
+    for (let s = 1; s < segsPerArc; s++) {
+      const a = a0 + sweep * s / segsPerArc;
+      out.push({ x: circ.cx + circ.r * Math.cos(a), y: circ.cy + circ.r * Math.sin(a) });
+    }
+  }
+  out.push({ x: pts[n - 1].x, y: pts[n - 1].y });
+  return out;
+}
+function trackPath(path) {
+  const pts = (path ?? []).filter((p) => p && Number.isFinite(p.x) && Number.isFinite(p.y)).map((p) => ({
+    x: p.x,
+    y: p.y,
+    ...Number.isFinite(p.bulge) && p.bulge ? { bulge: p.bulge } : {}
+  }));
+  return pts.length >= 2 ? pts : null;
+}
 function circleThrough(a, b, c) {
   const d = 2 * (a.x * (b.y - c.y) + b.x * (c.y - a.y) + c.x * (a.y - b.y));
   if (Math.abs(d) < 1e-9) return null;
@@ -65,6 +104,8 @@ function arcSweep(a0, a1, am) {
 }
 var DEG_FP = Math.PI / 180;
 function moduleCenterline(input) {
+  const drawn = trackPath(input.mainPath);
+  if (drawn) return samplePath(drawn);
   const L = input.lengthInches > 0 ? input.lengthInches : 24;
   const gt = input.geometryType;
   if (gt === "dead_end") return [{ x: 0, y: 0 }];
@@ -174,7 +215,8 @@ function emptyEditorState(lengthInches) {
     endplateWidths: {},
     outline: [],
     controlPoints: [],
-    industries: []
+    industries: [],
+    mainPath: []
   };
 }
 function isTransitionTurnout(t) {
@@ -311,7 +353,8 @@ function stateToDoc(state, recordNumber) {
         moduleTrackId: t.moduleTrackId,
         trackName: t.trackName || void 0,
         capacityFeet: Math.round(inchesToScaleFeet(Math.abs(t.toPos - t.fromPos))),
-        ...state.loop && t.inLoop ? { inLoop: true } : {}
+        ...state.loop && t.inLoop ? { inLoop: true } : {},
+        ...t.path && t.path.length >= 2 ? { path: t.path } : {}
       }))
     ],
     turnouts: state.turnouts.map((t) => ({
@@ -361,7 +404,9 @@ function stateToDoc(state, recordNumber) {
     } : {},
     // Benchwork footprint outline (module-local inches); only when it's a real
     // ring (≥ 3 vertices).
-    ...state.outline.length >= 3 ? { outline: state.outline } : {}
+    ...state.outline.length >= 3 ? { outline: state.outline } : {},
+    // Authored mainline path (module-local inches); only when it's a real path.
+    ...state.mainPath.length >= 2 ? { mainPath: state.mainPath } : {}
   };
 }
 function docToState(doc, fallbackLength, moduleTracks = []) {
@@ -391,7 +436,9 @@ function docToState(doc, fallbackLength, moduleTracks = []) {
         toPos: t.toPos != null ? sc(t.toPos) : len,
         moduleTrackId,
         trackName: t.trackName ?? nameOf(moduleTrackId),
-        ...t.inLoop ? { inLoop: true } : {}
+        ...t.inLoop ? { inLoop: true } : {},
+        // Authored path kept as-drawn (a physical shape, not rescaled with length).
+        ...trackPath(t.path) ? { path: trackPath(t.path) } : {}
       });
     }
   }
@@ -440,6 +487,7 @@ function docToState(doc, fallbackLength, moduleTracks = []) {
     y: p.y,
     ...Number.isFinite(p.bulge) && p.bulge ? { bulge: p.bulge } : {}
   }));
+  const mainPath = trackPath(d.mainPath) ?? [];
   return {
     lengthInches: len,
     loop,
@@ -456,6 +504,7 @@ function docToState(doc, fallbackLength, moduleTracks = []) {
     poseOverrides,
     endplateWidths,
     outline,
+    mainPath,
     crossings: (d.crossings ?? []).map((x) => ({
       id: x.id,
       name: x.name ?? "",
@@ -942,6 +991,6 @@ function poseOverridesFromDoc(doc) {
   return out;
 }
 
-export { FREEMO_ENDPLATE_WIDTH_MIN_INCHES, FREEMO_ENDPLATE_WIDTH_RECOMMENDED_INCHES, MAIN2_TRACK_ID, MAIN_TRACK_ID, N_CAR_LENGTH_INCHES, N_SCALE_RATIO, asModuleSchematic, benchworkBand, benchworkOutline, buildCrossover, buildPassingSiding, buildTransition, carCapacity, deriveEndplatePoses, divergeSideForHand, docToState, emptyEditorState, endplateFaceSegments, endplateWidthInches, geometryTurnDegrees, inchesToScaleFeet, isLoopDoc, isTransitionTurnout, moduleCenterline, moduleFeatures, moduleFootprint, nextId, poseNeedsManual, poseOverridesFromDoc, sampleBenchworkOutline, scaleFeetToInches, stateToDoc };
+export { FREEMO_ENDPLATE_WIDTH_MIN_INCHES, FREEMO_ENDPLATE_WIDTH_RECOMMENDED_INCHES, MAIN2_TRACK_ID, MAIN_TRACK_ID, N_CAR_LENGTH_INCHES, N_SCALE_RATIO, asModuleSchematic, benchworkBand, benchworkOutline, buildCrossover, buildPassingSiding, buildTransition, carCapacity, deriveEndplatePoses, divergeSideForHand, docToState, emptyEditorState, endplateFaceSegments, endplateWidthInches, geometryTurnDegrees, inchesToScaleFeet, isLoopDoc, isTransitionTurnout, moduleCenterline, moduleFeatures, moduleFootprint, nextId, poseNeedsManual, poseOverridesFromDoc, sampleBenchworkOutline, samplePath, scaleFeetToInches, stateToDoc, trackPath };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map