@willcgage/module-schematic 0.14.0 → 0.16.0

package/dist/index.d.cts

@@ -156,9 +156,41 @@ interface ModuleSchematicDoc {
     /** Grade crossings / diamonds (#170). */
     crossings?: SchematicCrossing[];
     controlPoints?: SchematicControlPoint[];
+    /** Benchwork FOOTPRINT outline — the module's physical board shape as a
+     * polygon in module-local inches, in the same frame as the endplate poses
+     * (endplate A's track point at the origin, the mainline along +x, perpendicular
+     * +y up). Stored as an open ring; renderers close it. Absent = derive an
+     * approximate band from the endplate widths. */
+    outline?: BenchworkPoint[];
     /** @deprecated pre-grouping flat signals; read for back-compat. */
     signals?: SchematicSignal[];
 }
+/** 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
+ * circular arc whose midpoint is offset `bulge` inches (signed: + bows to the
+ * left of the P→next direction) perpendicular from the chord. */
+interface BenchworkPoint {
+    x: number;
+    y: number;
+    bulge?: number;
+}
+/** 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;
+/**
+ * Expand a benchwork outline (whose edges may be arcs) into a dense closed
+ * polyline for rendering — the SAME sampling both the Repository preview and
+ * Free-Dispatcher use, so a curve looks identical in both. Straight edges emit
+ * just their start vertex; a bulged edge emits `segsPerArc` points along the
+ * circular arc through the two endpoints and the bulged midpoint.
+ */
+declare function sampleBenchworkOutline(pts: BenchworkPoint[], segsPerArc?: number): {
+    x: number;
+    y: number;
+}[];
 /** Whether a doc is a single-endplate turnback (explicit flag or one endplate). */
 declare function isLoopDoc(doc: ModuleSchematicDoc): boolean;
 declare const MAIN_TRACK_ID = "main";
@@ -263,6 +295,10 @@ interface EditorState {
     /** Authored endplate face widths by endplate id, inches (Free-moN 12″ min,
      * 24″ recommended). Absent id = the recommended default. */
     endplateWidths: Record<string, number>;
+    /** Benchwork footprint outline — polygon vertices in module-local inches
+     * (endplate A's track point at the origin, mainline +x, perpendicular +y up).
+     * Empty = no authored outline (fall back to the endplate-width band). */
+    outline: BenchworkPoint[];
     controlPoints: EditorControlPoint[];
 }
 /** Build the empty editor state for a module of the given length. */
@@ -523,4 +559,4 @@ declare function poseOverridesFromDoc(doc: ModuleSchematicDoc): Record<string, {
     heading: number;
 }>;
 
-export { type BranchConnector, type DrawCrossing, type DrawCrossover, type DrawSignal, type DrawTrack, type DrawTurnout, type EditorBranch, type EditorControlPoint, type EditorCpSignal, type EditorCrossing, type EditorState, type EditorTrack, type EditorTurnout, type EndplateBConfig, type EndplatePose, FREEMO_ENDPLATE_WIDTH_MIN_INCHES, FREEMO_ENDPLATE_WIDTH_RECOMMENDED_INCHES, type GeometryType, MAIN2_TRACK_ID, MAIN_TRACK_ID, type ModuleFeatures, type ModuleGeometryInput, type ModuleSchematicDoc, type ModuleTrackRow, N_SCALE_RATIO, type SchematicBlock, type SchematicControlPoint, type SchematicCrossing, type SchematicEndplate, type SchematicEndplateTrack, type SchematicSignal, type SchematicTrack, type SchematicTurnout, type SignalFacing, type SignalSide, type TrackConfig, type TrackRole, type TurnoutKind, asModuleSchematic, buildCrossover, buildPassingSiding, buildTransition, deriveEndplatePoses, divergeSideForHand, docToState, emptyEditorState, endplateWidthInches, geometryTurnDegrees, inchesToScaleFeet, isLoopDoc, isTransitionTurnout, moduleFeatures, nextId, poseNeedsManual, poseOverridesFromDoc, scaleFeetToInches, stateToDoc };
+export { type BenchworkPoint, type BranchConnector, type DrawCrossing, type DrawCrossover, type DrawSignal, type DrawTrack, type DrawTurnout, type EditorBranch, type EditorControlPoint, type EditorCpSignal, type EditorCrossing, type EditorState, type EditorTrack, type EditorTurnout, type EndplateBConfig, type EndplatePose, FREEMO_ENDPLATE_WIDTH_MIN_INCHES, FREEMO_ENDPLATE_WIDTH_RECOMMENDED_INCHES, type GeometryType, MAIN2_TRACK_ID, MAIN_TRACK_ID, type ModuleFeatures, type ModuleGeometryInput, type ModuleSchematicDoc, type ModuleTrackRow, N_SCALE_RATIO, type SchematicBlock, type SchematicControlPoint, type SchematicCrossing, type SchematicEndplate, type SchematicEndplateTrack, type SchematicSignal, type SchematicTrack, type SchematicTurnout, type SignalFacing, type SignalSide, type TrackConfig, type TrackRole, type TurnoutKind, asModuleSchematic, benchworkOutline, buildCrossover, buildPassingSiding, buildTransition, deriveEndplatePoses, divergeSideForHand, docToState, emptyEditorState, endplateWidthInches, geometryTurnDegrees, inchesToScaleFeet, isLoopDoc, isTransitionTurnout, moduleFeatures, nextId, poseNeedsManual, poseOverridesFromDoc, sampleBenchworkOutline, scaleFeetToInches, stateToDoc };

package/dist/index.d.ts

@@ -156,9 +156,41 @@ interface ModuleSchematicDoc {
     /** Grade crossings / diamonds (#170). */
     crossings?: SchematicCrossing[];
     controlPoints?: SchematicControlPoint[];
+    /** Benchwork FOOTPRINT outline — the module's physical board shape as a
+     * polygon in module-local inches, in the same frame as the endplate poses
+     * (endplate A's track point at the origin, the mainline along +x, perpendicular
+     * +y up). Stored as an open ring; renderers close it. Absent = derive an
+     * approximate band from the endplate widths. */
+    outline?: BenchworkPoint[];
     /** @deprecated pre-grouping flat signals; read for back-compat. */
     signals?: SchematicSignal[];
 }
+/** 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
+ * circular arc whose midpoint is offset `bulge` inches (signed: + bows to the
+ * left of the P→next direction) perpendicular from the chord. */
+interface BenchworkPoint {
+    x: number;
+    y: number;
+    bulge?: number;
+}
+/** 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;
+/**
+ * Expand a benchwork outline (whose edges may be arcs) into a dense closed
+ * polyline for rendering — the SAME sampling both the Repository preview and
+ * Free-Dispatcher use, so a curve looks identical in both. Straight edges emit
+ * just their start vertex; a bulged edge emits `segsPerArc` points along the
+ * circular arc through the two endpoints and the bulged midpoint.
+ */
+declare function sampleBenchworkOutline(pts: BenchworkPoint[], segsPerArc?: number): {
+    x: number;
+    y: number;
+}[];
 /** Whether a doc is a single-endplate turnback (explicit flag or one endplate). */
 declare function isLoopDoc(doc: ModuleSchematicDoc): boolean;
 declare const MAIN_TRACK_ID = "main";
@@ -263,6 +295,10 @@ interface EditorState {
     /** Authored endplate face widths by endplate id, inches (Free-moN 12″ min,
      * 24″ recommended). Absent id = the recommended default. */
     endplateWidths: Record<string, number>;
+    /** Benchwork footprint outline — polygon vertices in module-local inches
+     * (endplate A's track point at the origin, mainline +x, perpendicular +y up).
+     * Empty = no authored outline (fall back to the endplate-width band). */
+    outline: BenchworkPoint[];
     controlPoints: EditorControlPoint[];
 }
 /** Build the empty editor state for a module of the given length. */
@@ -523,4 +559,4 @@ declare function poseOverridesFromDoc(doc: ModuleSchematicDoc): Record<string, {
     heading: number;
 }>;
 
-export { type BranchConnector, type DrawCrossing, type DrawCrossover, type DrawSignal, type DrawTrack, type DrawTurnout, type EditorBranch, type EditorControlPoint, type EditorCpSignal, type EditorCrossing, type EditorState, type EditorTrack, type EditorTurnout, type EndplateBConfig, type EndplatePose, FREEMO_ENDPLATE_WIDTH_MIN_INCHES, FREEMO_ENDPLATE_WIDTH_RECOMMENDED_INCHES, type GeometryType, MAIN2_TRACK_ID, MAIN_TRACK_ID, type ModuleFeatures, type ModuleGeometryInput, type ModuleSchematicDoc, type ModuleTrackRow, N_SCALE_RATIO, type SchematicBlock, type SchematicControlPoint, type SchematicCrossing, type SchematicEndplate, type SchematicEndplateTrack, type SchematicSignal, type SchematicTrack, type SchematicTurnout, type SignalFacing, type SignalSide, type TrackConfig, type TrackRole, type TurnoutKind, asModuleSchematic, buildCrossover, buildPassingSiding, buildTransition, deriveEndplatePoses, divergeSideForHand, docToState, emptyEditorState, endplateWidthInches, geometryTurnDegrees, inchesToScaleFeet, isLoopDoc, isTransitionTurnout, moduleFeatures, nextId, poseNeedsManual, poseOverridesFromDoc, scaleFeetToInches, stateToDoc };
+export { type BenchworkPoint, type BranchConnector, type DrawCrossing, type DrawCrossover, type DrawSignal, type DrawTrack, type DrawTurnout, type EditorBranch, type EditorControlPoint, type EditorCpSignal, type EditorCrossing, type EditorState, type EditorTrack, type EditorTurnout, type EndplateBConfig, type EndplatePose, FREEMO_ENDPLATE_WIDTH_MIN_INCHES, FREEMO_ENDPLATE_WIDTH_RECOMMENDED_INCHES, type GeometryType, MAIN2_TRACK_ID, MAIN_TRACK_ID, type ModuleFeatures, type ModuleGeometryInput, type ModuleSchematicDoc, type ModuleTrackRow, N_SCALE_RATIO, type SchematicBlock, type SchematicControlPoint, type SchematicCrossing, type SchematicEndplate, type SchematicEndplateTrack, type SchematicSignal, type SchematicTrack, type SchematicTurnout, type SignalFacing, type SignalSide, type TrackConfig, type TrackRole, type TurnoutKind, asModuleSchematic, benchworkOutline, buildCrossover, buildPassingSiding, buildTransition, deriveEndplatePoses, divergeSideForHand, docToState, emptyEditorState, endplateWidthInches, geometryTurnDegrees, inchesToScaleFeet, isLoopDoc, isTransitionTurnout, moduleFeatures, nextId, poseNeedsManual, poseOverridesFromDoc, sampleBenchworkOutline, scaleFeetToInches, stateToDoc };

package/dist/index.js

@@ -5,6 +5,64 @@ function endplateWidthInches(ep) {
   const w = ep?.widthInches;
   return typeof w === "number" && w > 0 ? w : FREEMO_ENDPLATE_WIDTH_RECOMMENDED_INCHES;
 }
+function benchworkOutline(doc) {
+  const pts = (doc?.outline ?? []).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 >= 3 ? pts : null;
+}
+function sampleBenchworkOutline(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; i++) {
+    const p0 = pts[i];
+    const p1 = pts[(i + 1) % n];
+    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) });
+    }
+  }
+  return out;
+}
+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;
+  const a2 = a.x * a.x + a.y * a.y;
+  const b2 = b.x * b.x + b.y * b.y;
+  const c2 = c.x * c.x + c.y * c.y;
+  const cx = (a2 * (b.y - c.y) + b2 * (c.y - a.y) + c2 * (a.y - b.y)) / d;
+  const cy = (a2 * (c.x - b.x) + b2 * (a.x - c.x) + c2 * (b.x - a.x)) / d;
+  return { cx, cy, r: Math.hypot(a.x - cx, a.y - cy) };
+}
+function arcSweep(a0, a1, am) {
+  const norm = (x) => {
+    let v = (x - a0) % (2 * Math.PI);
+    if (v < 0) v += 2 * Math.PI;
+    return v;
+  };
+  const m = norm(am);
+  const one = norm(a1);
+  return m <= one ? one : one - 2 * Math.PI;
+}
 function isLoopDoc(doc) {
   return doc.loop === true || doc.endplates.length === 1;
 }
@@ -37,6 +95,7 @@ function emptyEditorState(lengthInches) {
     branches: [],
     poseOverrides: {},
     endplateWidths: {},
+    outline: [],
     controlPoints: []
   };
 }
@@ -206,7 +265,10 @@ function stateToDoc(state, recordNumber) {
         kind: "mast",
         side: s.side
       }))
-    }))
+    })),
+    // Benchwork footprint outline (module-local inches); only when it's a real
+    // ring (≥ 3 vertices).
+    ...state.outline.length >= 3 ? { outline: state.outline } : {}
   };
 }
 function docToState(doc, fallbackLength, moduleTracks = []) {
@@ -280,6 +342,11 @@ function docToState(doc, fallbackLength, moduleTracks = []) {
     if (typeof e.widthInches === "number" && e.widthInches > 0)
       endplateWidths[e.id] = e.widthInches;
   }
+  const outline = (d.outline ?? []).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 {
     lengthInches: len,
     loop,
@@ -295,6 +362,7 @@ function docToState(doc, fallbackLength, moduleTracks = []) {
     })),
     poseOverrides,
     endplateWidths,
+    outline,
     crossings: (d.crossings ?? []).map((x) => ({
       id: x.id,
       name: x.name ?? "",
@@ -752,6 +820,6 @@ function poseOverridesFromDoc(doc) {
   return out;
 }
 
-export { FREEMO_ENDPLATE_WIDTH_MIN_INCHES, FREEMO_ENDPLATE_WIDTH_RECOMMENDED_INCHES, MAIN2_TRACK_ID, MAIN_TRACK_ID, N_SCALE_RATIO, asModuleSchematic, buildCrossover, buildPassingSiding, buildTransition, deriveEndplatePoses, divergeSideForHand, docToState, emptyEditorState, endplateWidthInches, geometryTurnDegrees, inchesToScaleFeet, isLoopDoc, isTransitionTurnout, moduleFeatures, nextId, poseNeedsManual, poseOverridesFromDoc, scaleFeetToInches, stateToDoc };
+export { FREEMO_ENDPLATE_WIDTH_MIN_INCHES, FREEMO_ENDPLATE_WIDTH_RECOMMENDED_INCHES, MAIN2_TRACK_ID, MAIN_TRACK_ID, N_SCALE_RATIO, asModuleSchematic, benchworkOutline, buildCrossover, buildPassingSiding, buildTransition, deriveEndplatePoses, divergeSideForHand, docToState, emptyEditorState, endplateWidthInches, geometryTurnDegrees, inchesToScaleFeet, isLoopDoc, isTransitionTurnout, moduleFeatures, nextId, poseNeedsManual, poseOverridesFromDoc, sampleBenchworkOutline, scaleFeetToInches, stateToDoc };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map