← back to pin list

Windows installable version — preliminary challenge inventory

kerfmaster pin list · Big capabilities

intentWhat we want to build. Never claimed the present, so it cannot be stale — and must never be read as a description of the code.

Content last changed 2026-09-13 — computed from the item itself, not typed.

Status: PRELIMINARY (Aristide, 2026-09-13). This pin is the inventory of what a Windows installable version takes. It commissions nothing.

The good news first

The stack is unusually portable: the engine is stdlib-only Python (zero pip dependencies) and the client is vanilla JS — no framework or dependency hell. The one-source-three-lenses ruling anticipated this: the PC shell is a RENDERER over the same engine, never a rewrite.

1. Architecture & packaging challenges

  1. Shop-wide state is the big one. Today ONE server holds the program-number sequence (progseq.json), customer registry, shop profile and tables. Two independent per-PC installs would fork O-numbers, split customers, drift tables. STRATEGIC DECISION NEEDED: (a) one shop PC acts as the server, other stations connect to it (closest to today, least new code), vs (b) true per-PC installs with a sync story (much harder, easy to corrupt the sequence).
  2. UI shell = WebView2 (the Edge engine, preinstalled on Win 10/11): a normal Windows program — own icon, own window, Start menu, installer; inside the window the SAME app.js/canvas code renders. The user never touches a browser; we reuse the browser's rendering engine as the drawing layer (the Slack/Teams/VS Code model). Mac later = the same concept via WKWebView. A native WinForms/WPF rewrite would violate one-source-three-lenses — rejected at design time.
  3. Packaging Python: bundle an embedded Python runtime + engine into an installer (MSI/Inno Setup). Clean because zero pip dependencies; expect antivirus false-positive whack-a-mole on bundled interpreters.
  4. Code signing: unsigned installers trigger SmartScreen 'unknown publisher'. An EV certificate costs a few hundred/year and needs a legal entity to issue to.
  5. Updates: today a deploy is a git pull; installed software needs an updater (check, download, apply, roll back), tamper-proof channel (HTTPS + signed packages), and a version-support policy — customers WILL run old versions.
  6. Services & paths: systemd becomes a Windows service or app-managed process; jobs/data move to AppData or a chosen shop folder; per-station settings (theme, layouts, colors — browser localStorage today) need a home per Windows user.
  7. Testing: everything is verified on Linux today; a real Windows machine/VM joins the loop before every release — Playwright runs there, but the suite must actually run on it.

2. Security

  1. The big win: everything stays in the shop. Engine, jobs, customer files, G-code all on the shop's own disk, no cloud, fully-offline capable — a genuine selling point for ITAR/CMMC shops ('your CAD files never leave the building').
  2. Network exposure: single-PC install listens on localhost only — invisible to the network. The shop-server model exposes the LAN and REQUIRES real login before we ship that mode.
  3. Operator accounts become mandatory — login, roles (sales vs operator), who-did-what on every record. The biggest genuinely new build on this list (and already the standing 'awaits operator accounts' item across the app).
  4. Webview locked down: loads only our local files, never browses the internet — external navigation disabled outright; the usual browser attack surface doesn't exist.
  5. Untrusted input = customer files: DXF/STEP/AI parsers are pure Python — no C-style buffer overflows; worst case a crash or a loud refusal. Deliberate fuzzing before release is cheap insurance.
  6. No secrets in the install — no API keys, no cloud credentials; a license key (if we sell that way) would be the only sensitive item.

3. Memory (all-shift, every-shift runtime)

  1. Python is GC'd — no classic C leaks; the risk is unbounded caches. Known example: the heal cache (_job_prims) keeps each opened job's geometry for instant lens clicks — needs an LRU cap (keep last N jobs) for a PC running weeks. Every cache must be bounded deliberately.
  2. THE KEYSTONE — worker-process model: after a huge file Python doesn't always hand freed memory back to Windows (arena fragmentation). Run each heavy pipeline job (heal, nest, post) in a short-lived worker process that exits when done — Windows reclaims everything, guaranteed; makes most leak classes structurally impossible. The one architectural change for the desktop version.
  3. JS side: a desktop app never gets the browser-refresh reset — per-job canvas caches (Path2D etc.) must release when a job closes.
  4. WebView2 is Chromium: memory-hungry baseline (a few hundred MB), not leaky in practice — feeds the minimum-PC-spec statement.
  5. Peaks vs leaks: the biggest memory events are SPIKES on giant files (a fidelity measure with >1M sample points), not leaks — matters on an 8GB shop PC. Before release: a soak test (scripted week of operator work run overnight, memory watched throughout — the Playwright machinery for it exists).

What must be decided before building

(1) shop-server vs per-PC architecture (item 1.1); (2) licensing/updates commercial model (items 1.4/1.5). Everything else is mechanical engineering, not strategy.