@bobfrankston/wallplater 1.0.5 → 1.0.7

package/README.md

@@ -1,19 +1,24 @@
 # @bobfrankston/wallplater
 
-JSON-driven wall-plate generator (Decora / duplex / blank gangs). Reads a small
-JSON config and emits a multi-object 3MF (plate + labels as separate,
-individually colourable objects) or per-part STLs.
+JSON-driven wall-plate generator (Decora / duplex / blank / button gangs). Reads
+a small JSON (JSON5) config and emits a multi-object 3MF (plate + labels as
+separate, individually colourable objects) or per-part STLs.
 
 ## Engines
 
 | Engine | Flag | Needs OpenSCAD? | Speed | Notes |
 |---|---|---|---|---|
 | **manifold** (default) | — | no | ~1 s | Direct geometry via [manifold-3d](https://github.com/elalish/manifold) (Clipper2 + robust CSG). Text via [opentype.js](https://github.com/opentypejs/opentype.js). |
-| **scad** (legacy) | `-scad` or `"engine":"scad"` | yes | ~30 s | Writes a `.scad` and shells out to OpenSCAD. Reference / fallback. Does **not** render rocker/header labels. |
+| **scad** (legacy) | `-scad` or `"engine":"scad"` | yes | ~30 s | Writes a `.scad` and shells out to OpenSCAD. Reference / fallback. Renders all hole geometry (incl. button pips) but **not** rocker/header/per-button labels. |
 
 The manifold engine has no system dependency beyond Node and is the path
 forward; `-scad` is kept for parity/verification.
 
+If the `-scad` engine can't find OpenSCAD (neither the `openscad` config path nor
+`openscad` on `PATH`), it offers to install it for you — `winget` on Windows,
+`brew --cask` on macOS, `apt-get` on Linux — then re-checks. Decline (or a
+non-interactive stdin) exits with a hint to install manually or drop `-scad`.
+
 ## Build / install
 
 TypeScript compiled to co-located `.js` / `.d.ts` / `.map` (no `src`/`dist`
@@ -49,6 +54,13 @@ without manual assignment — provided the project has ≥2 filaments. The label
 objects sit flush in the plate's front-face pockets (printed front-face-down), so
 they look hidden in the viewport until coloured.
 
+The 3MF also embeds a **preview thumbnail** (`Metadata/thumbnail.png`, wired via
+the OPC thumbnail relationship) so Windows Explorer and slicers show an image of
+the plate. It's a pure-JS orthographic render of the front face in the configured
+`plateColor` / `accentColor` — no extra dependency, no STL/mesh rendering by the
+shell. (Without it, the file previews blank: the shell never renders the geometry
+itself, it only displays this embedded PNG.)
+
 ## Config
 
 Each specific config is **deep-merged over `defaults.json`** (in this
@@ -56,8 +68,21 @@ directory), so a specific file carries only what differs — often just `name`,
 `gangs`, and a `breaker.switch`. Every default lives in `defaults.json`, not in
 code.
 
-Lengths are written **CSS-style with a unit suffix**: `"0.375in"`, `"5mm"`,
-`"-42mm"`. A bare number is treated as millimetres. Angles are plain numbers.
+Configs are parsed with **JSON5** (the most lenient reader), so comments
+(`//`, `/* */`), trailing commas, and unquoted keys are all allowed — plain JSON
+still works unchanged.
+
+Lengths are written **CSS-style with a unit suffix**. Supported units:
+
+| Suffix | Meaning | mm |
+|---|---|---|
+| `in` | inch | 25.4 |
+| `ft` | foot | 304.8 |
+| `cm` | centimetre | 10 |
+| `mm` | millimetre | 1 |
+
+e.g. `"0.375in"`, `"5mm"`, `"2cm"`, `"0.5ft"`, `"-42mm"`. A bare number (no
+suffix) is treated as millimetres. Angles (e.g. `cskAngle`) are plain numbers.
 
 ```jsonc
 // KitchenBack.json — only what differs from defaults.json
@@ -72,8 +97,11 @@ Lengths are written **CSS-style with a unit suffix**: `"0.375in"`, `"5mm"`,
 }
 ```
 
-- `gangs[].type`: `"decora"` | `"duplex"` | `"blank"`.
+- `gangs[].type`: `"decora"` | `"duplex"` | `"blank"` | `"button"`.
 - `gangs[].screws`: `false` to omit that gang's screw holes (default true).
+- `gangs[].filler`: on a **blank** gang, marks it as backed by a filler/insert
+  plate, so its cover screws sit on the Decora line (wider spacing) instead of
+  the box-ear line.
 - `gangs[].legend`: single label centred above the gang's opening (positioned
   clear of the screw holes; `legendY` / `legendSize`).
 - `gangs[].breaker`: per-gang breaker/circuit label, lower-right of the opening
@@ -112,10 +140,65 @@ overflow. See `../triple_demo.json` for a worked single-gang example.
 > Rocker/header labels are rendered by the **manifold engine only**. The
 > `-scad` engine ignores them (it warns).
 
+### Button gangs (round holes in a pip layout)
+
+A `"button"` gang punches a set of round button holes (default **0.5 in**
+diameter) arranged symmetrically like the pips on a die / playing card — odd
+counts put a single button in the centre. Set the count with `buttons` (1–9):
+
+```jsonc
+{
+  "type": "button",
+  "legend": "FAN",                       // the legend "on top" (above the buttons)
+  "buttons": 3,                          // 1-9; pip layout, single = centre
+  "buttonD": "0.5in",                    // optional per-gang diameter (default dims.buttonD)
+  "buttonLegends": ["HI", "MED", "LO"]   // optional small per-button labels
+}
+```
+
+- `buttons`: number of holes (1–9). Setting it implies `type:"button"`. The pip
+  pattern is the standard die/domino layout, read **top → bottom, left → right**:
+  `1`=centre, `2`/`3`=diagonal, `4`/`5`=corners (+centre for 5), `6`/`7`=two
+  columns (+centre for 7), `8`/`9`=full ring/grid. Counts above 9 are an error.
+- `buttonD`: per-gang hole diameter; defaults to `dims.buttonD` (`0.5in`).
+- `buttonLegends`: small labels, one per button in pip reading order (`""` or a
+  short array skips some). They are **in addition to** the gang `legend` on top,
+  and print in the accent colour. Sizing/placement: `buttonLegendSize` (3 mm),
+  `buttonLegendGap` (1 mm, below each hole).
+- Pip spacing is `dims.buttonPitch` (`0.85in` centre-to-centre). A button gang
+  mounts like a device — it gets a screw pair on the Decora line unless
+  `"screws": false`.
+
+See `../buttons_demo.json` for a worked Decora-plus-buttons example.
+
+> Per-button legends are rendered by the **manifold engine only** (the `-scad`
+> engine emits the button holes but skips the small labels, and warns).
+
 See `../decora_wallplate_spec.md` for the dimensional reference and print notes
 (print front-face-down; PETG/ASA recommended for heat near devices; keep plate
 and labels the same material family — see the chat note on ABS+PLA).
 
+### Appearance, output & engine
+
+Top-level keys (all have defaults in `defaults.json`):
+
+| Key | Default | Meaning |
+|---|---|---|
+| `output` | `"3mf"` | `"3mf"` (multi-object + thumbnail), `"stl"` (one binary STL per part), or `"scad"` (write the `.scad` only, no render — implies the scad engine). |
+| `engine` | `"manifold"` | `"manifold"` (direct) or `"scad"` (OpenSCAD). `-scad` on the CLI forces scad. |
+| `plateColor` | `"#35589f"` | Plate (filament 1) colour — used for the embedded preview and the scad-engine preview. |
+| `accentColor` | `"#101010"` | Label (filament 2) colour, same uses. |
+| `printReady` | `true` | Flip the model front-face-down (rotate 180° about X) for printing. The preview camera follows the flip, so labels stay upright either way. |
+| `fontFile` | Arial Bold | Path to a `.ttf`/`.otf` for the **manifold** engine's text. |
+| `font` | Liberation Sans Bold | OpenSCAD fontconfig name for the **scad** engine's text. |
+| `openscad` | Program Files path | OpenSCAD executable; only used by the scad engine (auto-install offered if missing). |
+| `bevel` | `1.2mm` | Front-edge chamfer width. |
+| `labelDepth` | `0.6mm` | Recess depth of the label pockets / height of the label solids. |
+
+Plate geometry, opening sizes, screw spacing, etc. live under the `dims` object
+(see `defaults.json` for the full list, all unit-suffixed lengths). Override any
+single dim by deep-merge, e.g. `"dims": { "depth": "5mm" }`.
+
 ## Files
 
 - `index.ts` — CLI entry / engine dispatch / arg validation

package/config.d.ts

@@ -1,9 +1,9 @@
 export declare const IN = 25.4;
-export type GangType = "blank" | "decora" | "duplex";
+export type GangType = "blank" | "decora" | "duplex" | "button";
 export type Engine = "manifold" | "scad";
-/** A length: CSS-style unit string ("0.375in" / "5mm") or a bare number (mm). */
+/** A length: CSS-style unit string ("0.375in" / "5mm" / "2cm" / "0.5ft") or a bare number (mm). */
 export type Len = string | number;
-/** Parse a length to millimetres. */
+/** Parse a length to millimetres. A bare number (no suffix) is millimetres. */
 export declare function mm(v: Len): number;
 export interface RockerCfg {
     left?: string;
@@ -13,6 +13,9 @@ export interface GangCfg {
     type?: GangType;
     opening?: boolean;
     legend?: string;
+    buttons?: number;
+    buttonD?: Len;
+    buttonLegends?: string[];
     filler?: boolean;
     screws?: boolean;
     rockers?: RockerCfg[];
@@ -38,6 +41,8 @@ export interface DimsCfg {
     duplexW?: Len;
     duplexH?: Len;
     duplexSpacing?: Len;
+    buttonD?: Len;
+    buttonPitch?: Len;
     screwSpacing?: Len;
     blankScrewSpacing?: Len;
     screwClearD?: Len;
@@ -56,6 +61,8 @@ export interface Config {
     rockerGap?: Len;
     headerSize?: Len;
     headerGap?: Len;
+    buttonLegendSize?: Len;
+    buttonLegendGap?: Len;
     bevel?: Len;
     labelDepth?: Len;
     blankScrews?: boolean;
@@ -90,6 +97,8 @@ export interface Dims {
     duplexW: number;
     duplexH: number;
     duplexSpacing: number;
+    buttonD: number;
+    buttonPitch: number;
     screwSpacing: number;
     blankScrewSpacing: number;
     screwClearD: number;
@@ -109,6 +118,8 @@ export interface Resolved {
     rockerGap: number;
     headerSize: number;
     headerGap: number;
+    buttonLegendSize: number;
+    buttonLegendGap: number;
     bevel: number;
     labelDepth: number;
     blankScrews: boolean;
@@ -124,4 +135,10 @@ export interface Resolved {
 }
 export declare function loadConfig(path: string): Resolved;
 export declare function gangType(g: GangCfg): GangType;
+/**
+ * Pip layout for a button gang: grid coordinates (gx, gy) each in {-1, 0, 1}
+ * (gy up), die/domino style, in reading order (top -> bottom, left -> right).
+ * Odd counts include the centre (0, 0). Supports 1-9.
+ */
+export declare function pipGrid(n: number): [number, number][];
 //# sourceMappingURL=config.d.ts.map

package/config.js

@@ -5,25 +5,29 @@
  * (in this directory), so a specific file need only carry what differs — often
  * just `name`, `gangs`, and a `breaker.switch`.
  *
- * Lengths are written CSS-style with a unit suffix: "0.375in", "5mm", "-42mm".
- * A bare number is treated as millimetres. Angles are plain numbers (degrees).
+ * Lengths are written CSS-style with a unit suffix: "0.375in", "5mm", "2cm",
+ * "0.5ft", "-42mm". A bare number is treated as millimetres. Angles are plain
+ * numbers (degrees).
  */
 import { readFileSync } from "fs";
 import { join } from "path";
+import JSON5 from "json5";
 export const IN = 25.4;
-/** Parse a length to millimetres. */
+/** Millimetres per supported length unit. */
+const UNIT = { mm: 1, cm: 10, in: IN, ft: 12 * IN };
+/** Parse a length to millimetres. A bare number (no suffix) is millimetres. */
 export function mm(v) {
     if (typeof v === "number")
         return v;
-    const m = /^\s*(-?[\d.]+)\s*(mm|in)?\s*$/i.exec(v);
+    const m = /^\s*(-?[\d.]+)\s*(mm|cm|in|ft)?\s*$/i.exec(v);
     if (!m)
-        throw new Error(`invalid length "${v}" (use e.g. "0.375in" or "5mm")`);
-    const n = parseFloat(m[1]);
-    return m[2] && m[2].toLowerCase() === "in" ? n * IN : n;
+        throw new Error(`invalid length "${v}" (use e.g. "0.375in", "5mm", "2cm", "0.5ft")`);
+    return parseFloat(m[1]) * UNIT[(m[2] ?? "mm").toLowerCase()];
 }
-// JSON.parse returns dynamic shape; merged then validated below.
+// JSON5 (lenient: comments, trailing commas, unquoted keys) returns dynamic
+// shape; merged then validated below.
 function readJson(path) {
-    return JSON.parse(readFileSync(path, "utf8"));
+    return JSON5.parse(readFileSync(path, "utf8"));
 }
 /** Deep-merge plain objects; arrays and scalars from `over` replace `base`. */
 function deepMerge(base, over) {
@@ -50,6 +54,7 @@ export function loadConfig(path) {
         faceT: mm(d.faceT), rimW: mm(d.rimW), cornerR: mm(d.cornerR),
         openW: mm(d.openW), openH: mm(d.openH), openR: mm(d.openR),
         duplexW: mm(d.duplexW), duplexH: mm(d.duplexH), duplexSpacing: mm(d.duplexSpacing),
+        buttonD: mm(d.buttonD), buttonPitch: mm(d.buttonPitch),
         screwSpacing: mm(d.screwSpacing), blankScrewSpacing: mm(d.blankScrewSpacing),
         screwClearD: mm(d.screwClearD), screwHeadD: mm(d.screwHeadD), cskAngle: d.cskAngle,
     };
@@ -62,6 +67,7 @@ export function loadConfig(path) {
         gangBreakerSize: mm(c.gangBreakerSize), gangBreakerY: mm(c.gangBreakerY),
         rockerSize: mm(c.rockerSize), rockerGap: mm(c.rockerGap),
         headerSize: mm(c.headerSize), headerGap: mm(c.headerGap),
+        buttonLegendSize: mm(c.buttonLegendSize), buttonLegendGap: mm(c.buttonLegendGap),
         bevel: mm(c.bevel), labelDepth: mm(c.labelDepth),
         blankScrews: c.blankScrews,
         font: c.font, fontFile: c.fontFile,
@@ -74,8 +80,32 @@ export function loadConfig(path) {
 export function gangType(g) {
     if (g.type)
         return g.type;
+    if (g.buttons && g.buttons > 0)
+        return "button"; // count implies a button gang
     if (g.opening === true)
         return "decora";
     return "blank";
 }
+/**
+ * Pip layout for a button gang: grid coordinates (gx, gy) each in {-1, 0, 1}
+ * (gy up), die/domino style, in reading order (top -> bottom, left -> right).
+ * Odd counts include the centre (0, 0). Supports 1-9.
+ */
+export function pipGrid(n) {
+    const grid = {
+        1: [[0, 0]],
+        2: [[-1, 1], [1, -1]],
+        3: [[-1, 1], [0, 0], [1, -1]],
+        4: [[-1, 1], [1, 1], [-1, -1], [1, -1]],
+        5: [[-1, 1], [1, 1], [0, 0], [-1, -1], [1, -1]],
+        6: [[-1, 1], [1, 1], [-1, 0], [1, 0], [-1, -1], [1, -1]],
+        7: [[-1, 1], [1, 1], [-1, 0], [0, 0], [1, 0], [-1, -1], [1, -1]],
+        8: [[-1, 1], [0, 1], [1, 1], [-1, 0], [1, 0], [-1, -1], [0, -1], [1, -1]],
+        9: [[-1, 1], [0, 1], [1, 1], [-1, 0], [0, 0], [1, 0], [-1, -1], [0, -1], [1, -1]],
+    };
+    const p = grid[n];
+    if (!p)
+        throw new Error(`buttons: count ${n} unsupported (pip layout is 1-9)`);
+    return p;
+}
 //# sourceMappingURL=config.js.map

package/defaults.json

@@ -9,6 +9,8 @@
   "rockerGap": "1.5mm",
   "headerSize": "4mm",
   "headerGap": "5mm",
+  "buttonLegendSize": "3mm",
+  "buttonLegendGap": "1mm",
   "bevel": "1.2mm",
   "labelDepth": "0.6mm",
   "blankScrews": true,
@@ -34,6 +36,8 @@
     "duplexW": "1.34375in",
     "duplexH": "1.125in",
     "duplexSpacing": "1.5in",
+    "buttonD": "0.5in",
+    "buttonPitch": "0.85in",
     "screwSpacing": "3.8125in",
     "blankScrewSpacing": "3.281in",
     "screwClearD": "4mm",

package/geometry.js

@@ -6,7 +6,7 @@
  * print-oriented, ready for build3mf() or writeBinaryStl().
  */
 import Module from "manifold-3d";
-import { gangType } from "./config.js";
+import { gangType, pipGrid, mm } from "./config.js";
 import { loadFont, textToContours } from "./text.js";
 const SEG = 96; // circular segments (matches the SCAD $fn = 96)
 let wasm = null;
@@ -83,6 +83,14 @@ export async function buildMeshes(cfg) {
             if (sc)
                 cutters.push(screw(x, 0)); // single centre screw
         }
+        else if (t === "button") { // round button holes in a pip layout
+            const bd = g.buttonD !== undefined ? mm(g.buttonD) : d.buttonD;
+            for (const [gx, gy] of pipGrid(g.buttons))
+                cutters.push(Manifold.cylinder(DEPTH + 2, bd / 2, bd / 2, SEG)
+                    .translate([x + gx * d.buttonPitch, gy * d.buttonPitch, -1]));
+            if (sc)
+                screwsPair(x, d.screwSpacing); // mounts like a device, on the Decora line
+        }
         else if (cfg.blankScrews && sc) { // blank: box-ear line, or Decora line if a filler plate
             screwsPair(x, g.filler ? d.screwSpacing : d.blankScrewSpacing);
         }
@@ -101,6 +109,18 @@ export async function buildMeshes(cfg) {
             accent.push({ txt: g.breaker, size: cfg.gangBreakerSize, halign: "right", x: gx + openHalf, y: cfg.gangBreakerY });
         if ((g.header ?? "") !== "")
             accent.push({ txt: g.header, size: cfg.headerSize, halign: "center", x: gx, y: openTop + cfg.headerGap });
+        if (gangType(g) === "button") { // per-button legends, small, below each hole
+            const bd = g.buttonD !== undefined ? mm(g.buttonD) : d.buttonD;
+            const bl = g.buttonLegends ?? [];
+            const pips = pipGrid(g.buttons);
+            for (let j = 0; j < pips.length; j++) {
+                if ((bl[j] ?? "") === "")
+                    continue;
+                const [px, py] = pips[j];
+                accent.push({ txt: bl[j], size: cfg.buttonLegendSize, halign: "center",
+                    x: gx + px * d.buttonPitch, y: py * d.buttonPitch - bd / 2 - cfg.buttonLegendGap });
+            }
+        }
         const rk = g.rockers ?? [];
         for (let j = 0; j < rk.length; j++) {
             const yr = openTop - (j + 0.5) * (d.openH / rk.length); // rockers top -> bottom

package/index.js

@@ -15,9 +15,21 @@
 import { writeFileSync, unlinkSync } from "fs";
 import { basename, dirname, join } from "path";
 import { loadConfig } from "./config.js";
-import { generateScad, runOpenscad, readStl } from "./scad.js";
+import { generateScad, runOpenscad, readStl, ensureOpenscad } from "./scad.js";
 import { buildMeshes } from "./geometry.js";
 import { build3mf, writeBinaryStl } from "./threemf.js";
+// Preview-PNG view: both engines flip the model front-face-down when printReady
+// (rotate 180 about X -> front normal -Z, world-up -Y), so aim the thumbnail
+// camera at the readable front either way.
+function thumbView(cfg) {
+    const f = cfg.printReady;
+    return {
+        front: [0, 0, f ? -1 : 1],
+        up: [0, f ? -1 : 1, 0],
+        plateColor: cfg.plateColor,
+        accentColor: cfg.accentColor,
+    };
+}
 // Bambu object-list name: "<config> <part>"; the accent text object reads "labels".
 function partName(cfgName, label) {
     return `${cfgName} ${label === "legend" ? "labels" : label}`;
@@ -35,27 +47,28 @@ function partList(cfg) {
     return parts;
 }
 function runScadEngine(cfg, dir) {
-    if (cfg.gangs.some((g) => (g.rockers?.length ?? 0) > 0 || (g.header ?? "") !== "" || (g.breaker ?? "") !== ""))
-        console.warn("  ! per-gang rocker/header/breaker labels are only rendered by the manifold engine; the -scad engine ignores them.");
+    if (cfg.gangs.some((g) => (g.rockers?.length ?? 0) > 0 || (g.header ?? "") !== "" || (g.breaker ?? "") !== "" || (g.buttonLegends?.length ?? 0) > 0))
+        console.warn("  ! per-gang rocker/header/breaker labels and per-button legends are only rendered by the manifold engine; the -scad engine ignores them (button holes themselves are emitted).");
     const scadPath = join(dir, `${cfg.name}.scad`);
     writeFileSync(scadPath, generateScad(cfg));
     console.log("wrote", basename(scadPath));
     if (cfg.output === "scad")
         return;
+    const exe = ensureOpenscad(cfg.openscad); // verify/install OpenSCAD before any export
     const parts = partList(cfg);
     if (cfg.output === "stl") {
         for (const p of parts)
-            runOpenscad(cfg.openscad, scadPath, join(dir, `${cfg.name}_${p.label}.stl`), p.mode);
+            runOpenscad(exe, scadPath, join(dir, `${cfg.name}_${p.label}.stl`), p.mode);
     }
     else {
         const tmp = [];
         const objects = parts.map((p) => {
             const stl = join(dir, `_${cfg.name}_${p.label}.stl`);
-            runOpenscad(cfg.openscad, scadPath, stl, p.mode);
+            runOpenscad(exe, scadPath, stl, p.mode);
             tmp.push(stl);
             return { name: partName(cfg.name, p.label), mesh: readStl(stl), extruder: partExtruder(p.label) };
         });
-        writeFileSync(join(dir, `${cfg.name}.3mf`), build3mf(objects));
+        writeFileSync(join(dir, `${cfg.name}.3mf`), build3mf(objects, thumbView(cfg)));
         for (const t of tmp)
             unlinkSync(t);
         console.log("  wrote", `${cfg.name}.3mf`, `(${objects.length} objects: ${objects.map((o) => o.name).join(", ")})`);
@@ -75,7 +88,7 @@ async function runManifoldEngine(cfg, dir) {
     }
     else {
         const objects = meshes.map((m) => ({ name: partName(cfg.name, m.label), mesh: m.mesh, extruder: partExtruder(m.label) }));
-        writeFileSync(join(dir, `${cfg.name}.3mf`), build3mf(objects));
+        writeFileSync(join(dir, `${cfg.name}.3mf`), build3mf(objects, thumbView(cfg)));
         console.log("  wrote", `${cfg.name}.3mf`, `(${objects.length} objects: ${objects.map((o) => o.name).join(", ")})`);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/wallplater",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "type": "module",
   "description": "JSON-driven wall-plate generator (Decora / duplex / blank). Direct-to-3MF via manifold-3d, with an optional OpenSCAD engine.",
   "main": "index.js",
@@ -19,6 +19,7 @@
     "release": "npmglobalize"
   },
   "dependencies": {
+    "json5": "^2.2.3",
     "manifold-3d": "^3.0.0",
     "opentype.js": "^1.3.4"
   },

package/scad.d.ts

@@ -1,6 +1,7 @@
 import { type Resolved } from "./config.js";
 import type { Mesh } from "./threemf.js";
 export declare function generateScad(cfg: Resolved): string;
+export declare function ensureOpenscad(exe: string): string;
 export declare function runOpenscad(exe: string, scadPath: string, outPath: string, mode: string): void;
 export declare function readStl(path: string): Mesh;
 //# sourceMappingURL=scad.d.ts.map

package/scad.js

@@ -4,8 +4,8 @@
  * one STL per colour part, and reads STLs back into the common Mesh shape.
  * Note: rocker/header labels are manifold-engine only and are not emitted here.
  */
-import { readFileSync } from "fs";
-import { execFileSync } from "child_process";
+import { readFileSync, existsSync, readSync } from "fs";
+import { execFileSync, spawnSync } from "child_process";
 import { basename } from "path";
 import { gangType } from "./config.js";
 function num(n) {
@@ -17,11 +17,13 @@ export function generateScad(cfg) {
     const legend = "[" + cfg.gangs.map((g) => `"${g.legend ?? ""}"`).join(", ") + "]";
     const filler = "[" + cfg.gangs.map((g) => (g.filler ? "true" : "false")).join(", ") + "]";
     const screws = "[" + cfg.gangs.map((g) => (g.screws === false ? "false" : "true")).join(", ") + "]";
+    const buttons = "[" + cfg.gangs.map((g) => num(g.buttons ?? 0)).join(", ") + "]";
     const params = `// ===== Auto-generated by wallplater from ${cfg.name}.json — do not hand-edit =====
 GANGS         = ${gangs};   // per gang: "blank" | "decora" | "duplex"
 LEGEND        = ${legend};
 FILLER        = ${filler};   // blank gang has a filler/insert plate -> screws on Decora line
 SCREWS        = ${screws};   // per gang: place screw holes? (false = omit)
+BUTTONS       = ${buttons};   // per gang: button-hole count (0 = not a button gang)
 GANG_PITCH    = ${num(d.gangPitch)};
 ONE_GANG_W    = ${num(d.oneGangWidth)};
 PLATE_H       = ${num(d.height)};
@@ -36,6 +38,8 @@ OPEN_R        = ${num(d.openR)};
 DUPLEX_W      = ${num(d.duplexW)};
 DUPLEX_H      = ${num(d.duplexH)};
 DUPLEX_SPACING= ${num(d.duplexSpacing)};
+BUTTON_D      = ${num(d.buttonD)};
+BUTTON_PITCH  = ${num(d.buttonPitch)};
 SCREW_SPACING = ${num(d.screwSpacing)};
 BLANK_SCREW_SPACING = ${num(d.blankScrewSpacing)};
 BLANK_SCREWS  = ${cfg.blankScrews};
@@ -82,6 +86,24 @@ module duplex_opening(x)
         translate([x, s * DUPLEX_SPACING/2, -1]) linear_extrude(DEPTH + 2)
             intersection() { circle(d = DUPLEX_W); square([DUPLEX_W, DUPLEX_H], center = true); }
 
+// pip grid: [gx, gy] in {-1,0,1} (gy up), die/domino style, centre for odd counts (1-9)
+function pip_grid(n) =
+    n == 1 ? [[0,0]] :
+    n == 2 ? [[-1,1],[1,-1]] :
+    n == 3 ? [[-1,1],[0,0],[1,-1]] :
+    n == 4 ? [[-1,1],[1,1],[-1,-1],[1,-1]] :
+    n == 5 ? [[-1,1],[1,1],[0,0],[-1,-1],[1,-1]] :
+    n == 6 ? [[-1,1],[1,1],[-1,0],[1,0],[-1,-1],[1,-1]] :
+    n == 7 ? [[-1,1],[1,1],[-1,0],[0,0],[1,0],[-1,-1],[1,-1]] :
+    n == 8 ? [[-1,1],[0,1],[1,1],[-1,0],[1,0],[-1,-1],[0,-1],[1,-1]] :
+    n == 9 ? [[-1,1],[0,1],[1,1],[-1,0],[0,0],[1,0],[-1,-1],[0,-1],[1,-1]] :
+    [];
+
+module button_holes(x, n)
+    for (p = pip_grid(n))
+        translate([x + p[0]*BUTTON_PITCH, p[1]*BUTTON_PITCH, -1])
+            cylinder(d = BUTTON_D, h = DEPTH + 2);
+
 module outline() rrect(PLATE_W, PLATE_H, CORNER_R);
 
 module plate_body() {
@@ -120,6 +142,7 @@ module plate() {
             sc = (i >= len(SCREWS)) || SCREWS[i];                         // place screws on this gang?
             if (t == "decora")      { decora_opening(x); if (sc) screws_pair(x, SCREW_SPACING); }
             else if (t == "duplex") { duplex_opening(x); if (sc) screw(x, 0); }   // single centre screw
+            else if (t == "button") { button_holes(x, BUTTONS[i]); if (sc) screws_pair(x, SCREW_SPACING); }
             else if (BLANK_SCREWS && sc)                                  // blank: box-ear line, or Decora line if a filler plate
                 screws_pair(x, (i < len(FILLER) && FILLER[i]) ? SCREW_SPACING : BLANK_SCREW_SPACING);
         }
@@ -140,6 +163,68 @@ if (MODE == "preview") {
 else if (MODE == "legend")    oriented() legend_solids(LABEL_DEPTH);
 else if (MODE == "breaker")   oriented() breaker_solid(LABEL_DEPTH);
 `;
+// ----- OpenSCAD discovery + optional install -----
+// Return a runnable OpenSCAD command: the configured path if it exists, else a
+// bare "openscad(.exe)" if that's on PATH, else null.
+function findOpenscad(exe) {
+    if (exe && existsSync(exe))
+        return exe;
+    const probe = process.platform === "win32" ? "openscad.exe" : "openscad";
+    const r = spawnSync(probe, ["--version"], { stdio: "ignore" });
+    if (!r.error && r.status === 0)
+        return probe;
+    return null;
+}
+// Synchronous y/N prompt (CLI is otherwise synchronous). Non-TTY/EOF -> no.
+function promptYesNo(q) {
+    process.stdout.write(q);
+    const buf = Buffer.alloc(64);
+    try {
+        const n = readSync(0, buf, 0, buf.length, null);
+        const ans = buf.toString("utf8", 0, n).trim().toLowerCase();
+        return ans === "y" || ans === "yes";
+    }
+    catch {
+        return false; // stdin not readable (piped/CI) -> decline
+    }
+}
+// Platform install command for OpenSCAD: [exe, args].
+function installCmd() {
+    switch (process.platform) {
+        case "win32": return ["winget", ["install", "--id", "OpenSCAD.OpenSCAD", "-e",
+                "--accept-package-agreements", "--accept-source-agreements"]];
+        case "darwin": return ["brew", ["install", "--cask", "openscad"]];
+        default: return ["sudo", ["apt-get", "install", "-y", "openscad"]];
+    }
+}
+// Ensure OpenSCAD is available; offer to install it if not. Returns the command
+// to invoke, or exits the process if it can't be found/installed.
+export function ensureOpenscad(exe) {
+    const found = findOpenscad(exe);
+    if (found)
+        return found;
+    const [cmd, args] = installCmd();
+    const shown = `${cmd} ${args.join(" ")}`;
+    console.error(`OpenSCAD not found (looked for "${exe}" and "openscad" on PATH).`);
+    if (!promptYesNo(`Install it now with:\n    ${shown}\n? [y/N] `)) {
+        console.error("The -scad engine needs OpenSCAD. Install it, or drop -scad to use the default manifold engine.");
+        process.exit(1);
+    }
+    try {
+        execFileSync(cmd, args, { stdio: "inherit" });
+    }
+    catch {
+        console.error("Install failed. Install OpenSCAD manually: https://openscad.org/downloads.html");
+        process.exit(1);
+    }
+    const after = findOpenscad(exe);
+    if (!after) {
+        console.error('OpenSCAD installed but not yet found — open a new terminal (so PATH refreshes), or set "openscad" in your config to the full exe path.');
+        process.exit(1);
+    }
+    console.log("OpenSCAD installed.");
+    return after;
+}
 export function runOpenscad(exe, scadPath, outPath, mode) {
     const fmt = outPath.endsWith(".3mf") ? "3mf" : outPath.endsWith(".png") ? "png" : "binstl";
     execFileSync(exe, [`-D`, `MODE="${mode}"`, "--export-format", fmt, "-o", outPath, scadPath], { stdio: ["ignore", "ignore", "inherit"] });

package/threemf.d.ts

@@ -7,6 +7,14 @@ export interface Object3mf {
     mesh: Mesh;
     extruder?: number;
 }
-export declare function build3mf(objects: Object3mf[]): Buffer;
+export interface ViewOpts {
+    front?: number[];
+    up?: number[];
+    plateColor?: string;
+    accentColor?: string;
+    size?: number;
+}
+export declare function build3mf(objects: Object3mf[], view?: ViewOpts): Buffer;
+export declare function renderThumbnail(objects: Object3mf[], opts?: ViewOpts): Buffer;
 export declare function writeBinaryStl(mesh: Mesh): Buffer;
 //# sourceMappingURL=threemf.d.ts.map

package/threemf.js

@@ -5,12 +5,12 @@
  *     individually colourable objects), packed into the OPC zip by hand.
  *   - writeBinaryStl(): a single binary STL (used for the manifold STL path).
  */
-import { deflateRawSync } from "zlib";
+import { deflateRawSync, deflateSync } from "zlib";
 function xmlEscape(s) {
     return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 }
 // ---------- multi-object 3MF (core spec, no slicer settings) ----------
-export function build3mf(objects) {
+export function build3mf(objects, view = {}) {
     // separate, named top-level objects (each individually selectable/colourable
     // in Bambu), all at the same transform so the labels stay seated in the
     // plate's pockets.
@@ -43,15 +43,21 @@ ${objects.map((o, i) => `  <object id="${i + 1}">
   </object>`).join("\n")}
 </config>
 `;
+    // Package thumbnail (PNG). Windows Explorer / slicers display this embedded
+    // image as the file's preview; they do NOT render the mesh themselves. It is
+    // wired up via the OPC thumbnail relationship below + the png content type.
+    const thumb = renderThumbnail(objects, view);
     const ct = `<?xml version="1.0" encoding="UTF-8"?>
 <Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">
  <Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>
  <Default Extension="model" ContentType="application/vnd.ms-package.3dmanufacturing-3dmodel+xml"/>
+ <Default Extension="png" ContentType="image/png"/>
 </Types>
 `;
     const rels = `<?xml version="1.0" encoding="UTF-8"?>
 <Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
  <Relationship Target="/3D/3dmodel.model" Id="rel0" Type="http://schemas.microsoft.com/3dmanufacturing/2013/01/3dmodel"/>
+ <Relationship Target="/Metadata/thumbnail.png" Id="rel-thumb" Type="http://schemas.openxmlformats.org/package/2006/relationships/metadata/thumbnail"/>
 </Relationships>
 `;
     return zip([
@@ -59,8 +65,137 @@ ${objects.map((o, i) => `  <object id="${i + 1}">
         { name: "_rels/.rels", data: Buffer.from(rels) },
         { name: "3D/3dmodel.model", data: Buffer.from(model) },
         { name: "Metadata/model_settings.config", data: Buffer.from(settings) },
+        { name: "Metadata/thumbnail.png", data: thumb },
     ]);
 }
+// ---------- preview thumbnail (orthographic, pure-JS, no deps) ----------
+function hexRgb(s, fallback) {
+    const m = /^#?([0-9a-fA-F]{6})$/.exec(s ?? "");
+    if (!m)
+        return fallback;
+    const n = parseInt(m[1], 16);
+    return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+}
+function vcross(a, b) {
+    return [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
+}
+function vdot(a, b) { return a[0] * b[0] + a[1] * b[1] + a[2] * b[2]; }
+function vnorm(a) { const l = Math.hypot(a[0], a[1], a[2]) || 1; return [a[0] / l, a[1] / l, a[2] / l]; }
+// Render a top-down (front-facing) orthographic preview of all objects to a PNG.
+// Plate-extruder parts take plateColor, accent parts accentColor; a fixed light
+// gives the flat face a little form. Background is transparent.
+export function renderThumbnail(objects, opts = {}) {
+    const S = opts.size ?? 320;
+    const front = vnorm(opts.front ?? [0, 0, 1]);
+    const up = vnorm(opts.up ?? [0, 1, 0]);
+    const right = vnorm(vcross(up, front)); // right,up,front right-handed -> non-mirrored
+    const camUp = up;
+    const plateC = hexRgb(opts.plateColor, [120, 140, 200]);
+    const accentC = hexRgb(opts.accentColor, [20, 20, 24]);
+    // light from upper-left-front in screen space, expressed in world coords
+    const light = vnorm([
+        -0.4 * right[0] + 0.5 * camUp[0] + 0.9 * front[0],
+        -0.4 * right[1] + 0.5 * camUp[1] + 0.9 * front[1],
+        -0.4 * right[2] + 0.5 * camUp[2] + 0.9 * front[2],
+    ]);
+    const AMBIENT = 0.45;
+    const tris = [];
+    let uMin = Infinity, uMax = -Infinity, vMin = Infinity, vMax = -Infinity;
+    for (const o of objects) {
+        const col = (o.extruder ?? 1) === 1 ? plateC : accentC;
+        const pv = o.mesh.verts.map((p) => [vdot(p, right), vdot(p, camUp), vdot(p, front)]);
+        for (const p of pv) {
+            if (p[0] < uMin)
+                uMin = p[0];
+            if (p[0] > uMax)
+                uMax = p[0];
+            if (p[1] < vMin)
+                vMin = p[1];
+            if (p[1] > vMax)
+                vMax = p[1];
+        }
+        for (const t of o.mesh.tris) {
+            const a = o.mesh.verts[t[0]], b = o.mesh.verts[t[1]], c = o.mesh.verts[t[2]];
+            const n = vnorm(vcross([b[0] - a[0], b[1] - a[1], b[2] - a[2]], [c[0] - a[0], c[1] - a[1], c[2] - a[2]]));
+            if (vdot(n, front) <= 0)
+                continue; // cull faces pointing away from viewer
+            const inten = AMBIENT + (1 - AMBIENT) * Math.max(0, vdot(n, light));
+            const shade = [
+                Math.min(255, col[0] * inten), Math.min(255, col[1] * inten), Math.min(255, col[2] * inten),
+            ];
+            const A = pv[t[0]], B = pv[t[1]], C = pv[t[2]];
+            tris.push({ x: [A[0], B[0], C[0]], y: [A[1], B[1], C[1]], z: [A[2], B[2], C[2]], col: shade });
+        }
+    }
+    const pad = Math.round(S * 0.08);
+    const span = Math.max(uMax - uMin, vMax - vMin, 1e-6);
+    const scale = (S - 2 * pad) / span;
+    const ox = pad + (S - 2 * pad - (uMax - uMin) * scale) / 2;
+    const oy = pad + (S - 2 * pad - (vMax - vMin) * scale) / 2;
+    const sx = (u) => ox + (u - uMin) * scale;
+    const sy = (v) => S - (oy + (v - vMin) * scale); // flip: image row 0 is top
+    const rgba = Buffer.alloc(S * S * 4); // transparent background
+    const zbuf = new Float32Array(S * S).fill(-Infinity);
+    for (const tr of tris) {
+        const px = [sx(tr.x[0]), sx(tr.x[1]), sx(tr.x[2])];
+        const py = [sy(tr.y[0]), sy(tr.y[1]), sy(tr.y[2])];
+        const area = (px[1] - px[0]) * (py[2] - py[0]) - (px[2] - px[0]) * (py[1] - py[0]);
+        if (Math.abs(area) < 1e-9)
+            continue;
+        const minX = Math.max(0, Math.floor(Math.min(px[0], px[1], px[2])));
+        const maxX = Math.min(S - 1, Math.ceil(Math.max(px[0], px[1], px[2])));
+        const minY = Math.max(0, Math.floor(Math.min(py[0], py[1], py[2])));
+        const maxY = Math.min(S - 1, Math.ceil(Math.max(py[0], py[1], py[2])));
+        for (let yy = minY; yy <= maxY; yy++) {
+            for (let xx = minX; xx <= maxX; xx++) {
+                const cx = xx + 0.5, cy = yy + 0.5;
+                const w0 = ((px[1] - cx) * (py[2] - cy) - (px[2] - cx) * (py[1] - cy)) / area;
+                const w1 = ((px[2] - cx) * (py[0] - cy) - (px[0] - cx) * (py[2] - cy)) / area;
+                const w2 = 1 - w0 - w1;
+                if (w0 < 0 || w1 < 0 || w2 < 0)
+                    continue;
+                const z = w0 * tr.z[0] + w1 * tr.z[1] + w2 * tr.z[2];
+                const idx = yy * S + xx;
+                if (z <= zbuf[idx])
+                    continue;
+                zbuf[idx] = z;
+                const o4 = idx * 4;
+                rgba[o4] = tr.col[0];
+                rgba[o4 + 1] = tr.col[1];
+                rgba[o4 + 2] = tr.col[2];
+                rgba[o4 + 3] = 255;
+            }
+        }
+    }
+    return encodePng(S, S, rgba);
+}
+// minimal 8-bit RGBA PNG (single IDAT, no filtering)
+function encodePng(width, height, rgba) {
+    const chunk = (type, data) => {
+        const t = Buffer.from(type, "latin1");
+        const len = Buffer.alloc(4);
+        len.writeUInt32BE(data.length, 0);
+        const crc = Buffer.alloc(4);
+        crc.writeUInt32BE(crc32(Buffer.concat([t, data])), 0);
+        return Buffer.concat([len, t, data, crc]);
+    };
+    const ihdr = Buffer.alloc(13);
+    ihdr.writeUInt32BE(width, 0);
+    ihdr.writeUInt32BE(height, 4);
+    ihdr[8] = 8;
+    ihdr[9] = 6;
+    ihdr[10] = 0;
+    ihdr[11] = 0;
+    ihdr[12] = 0; // 8-bit, RGBA
+    const row = width * 4;
+    const raw = Buffer.alloc(height * (1 + row));
+    for (let y = 0; y < height; y++) {
+        raw[y * (1 + row)] = 0; // filter: none
+        rgba.copy(raw, y * (1 + row) + 1, y * row, (y + 1) * row);
+    }
+    const sig = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+    return Buffer.concat([sig, chunk("IHDR", ihdr), chunk("IDAT", deflateSync(raw)), chunk("IEND", Buffer.alloc(0))]);
+}
 // ---------- binary STL (single object) ----------
 export function writeBinaryStl(mesh) {
     const buf = Buffer.alloc(84 + mesh.tris.length * 50);