Release 4.3.0

.github/workflows/ci-sync.yml

@@ -160,8 +160,22 @@ jobs:
               echo "::endgroup::"
               exit 0
             else
-              DIFF_COUNT=$(echo "$RESULT" | python3 -c "import json,sys; print(json.load(sys.stdin)['total_diffs'])")
-              echo "Still $DIFF_COUNT difference(s) with PR #$PR_NUMBER"
+              # Name the files, not just a count.
+              #
+              # A bare "Still 8 difference(s)" is undiagnosable: it gives no
+              # way to tell a genuine divergence from a PR head this run
+              # fetched before the other repo's push had propagated, which is
+              # a real race when both PRs are pushed within seconds of each
+              # other. The target-branch comparison already lists its files;
+              # this one now does too.
+              echo "$RESULT" | python3 -c "
+          import json, sys
+          data = json.load(sys.stdin)
+          print(f\"Still {data['total_diffs']} difference(s) with this PR:\")
+          for surface, info in data['surfaces'].items():
+              for d in info.get('diffs', []):
+                  print(f\"    {d['reason']}: src/{d['file']}\")
+          "
             fi
 
             echo "::endgroup::"

.github/workflows/ci-unit-tests.yml

@@ -2,11 +2,14 @@ name: CI - Unit Tests
 
 on:
   workflow_dispatch:
+  # Called from `ci.yml` on every pull request.
+  workflow_call:
 
 jobs:
   unit-tests:
     name: Unit Tests + Coverage
     runs-on: ubuntu-latest
+    # Required check on `development` — a red suite blocks the merge.
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4

.github/workflows/ci.yml

@@ -16,6 +16,9 @@ jobs:
   lint:
     uses: ./.github/workflows/ci-lint.yml
 
+  unit-tests:
+    uses: ./.github/workflows/ci-unit-tests.yml
+
   format:
     needs: [architecture, build-check, lint]
     uses: ./.github/workflows/ci-format.yml
@@ -27,4 +30,8 @@ jobs:
 
   complete-build:
     needs: [sync]
+    # Full 3-OS packaging is release work: the tag-triggered release
+    # workflow builds it for real, so PRs into development skip it and
+    # only the promotion PRs into main still prove the app packages.
+    if: github.base_ref == 'main'
     uses: ./.github/workflows/build.yml

.gitignore

@@ -52,9 +52,30 @@ resources/st-compiler/**.spec
 # External tool binaries (downloaded by scripts/download-binaries.ts)
 # arduino-cli stays committed since we don't own its releases
 resources/strucpp/
+resources/bin/**
+# Git will not re-include a file whose ancestor directory is excluded, and `bin/**` excludes
+# the platform/arch directories too — so the two exceptions below only bite once these are
+# re-included. Without them a NEWLY downloaded arduino-cli is invisible to git, and the six
+# committed ones survive only because they were already tracked when the rule landed.
+!resources/bin/
+!resources/bin/*/
+!resources/bin/*/*/
+!resources/bin/*/*/arduino-cli
+!resources/bin/*/*/arduino-cli.exe
+# A local build leaves xml2st, iec2c/iec2iec and .binary-metadata.json here, plus
+# timestamped .xml2st-backup-* copies. They are downloaded artefacts, not sources —
+# 123 MB of them were swept into a PR by a `git add -A` before this rule existed.
+resources/sources/MatIEC/
 
 # Playwright
 /test-results/
 playwright-report
 /blob-report/
 /playwright/.cache/
+
+# Claude Code session state (a running session's id and pid — never a project artefact)
+.claude/scheduled_tasks.lock
+
+# Development build of the headless CLI (see webpack.config.cli.dev.ts)
+openplc-cli.dev.js
+openplc-cli.dev.js.map

CLAUDE.md

@@ -160,6 +160,7 @@ const createPou = useOpenPLCStore((s) => s.projectActions.createPou)
 | `console` | Log output |
 | `library` | System + user function block libraries |
 | `file` | File save states (dirty tracking) |
+| `print` | Print/export-to-PDF selection, render mode, page policy, page setup |
 | `ai`, `history`, `modal`, `readme`, `search`, `shared`, `version-control`, `webrtc` | Supporting features |
 
 **Conventions:**
@@ -217,6 +218,37 @@ Structured Text is generated in-process by the TS transpiler
 legacy `xml2st` binary path has been retired. `XmlGenerator` is kept only for
 the "Export Project as XML" feature.
 
+**The Modbus block of `defines.h` has two sources**, split along the ownership
+boundary (`src/backend/shared/compile/steps/modbus-defines.ts`):
+
+- the project's Modbus `PLCServer` says **what is served** — the transports,
+  the slave id, the TCP port, and the speed of a UART of its own. On every
+  target, baremetal included.
+- the board's VPP screens say **what it is served over** — the default UART's
+  speed, the RS-485 pin, the network. `serial` and `network` sections.
+
+The default UART's speed is the one thing on that line the server does not own,
+because it is the editor's own link and a UART has one speed. `resolveServerBaud`
+in `middleware/shared/utils/modbus-server-profile/baud.ts` decides between the
+two, and the SCREEN calls it as well — a hook cannot import `backend/shared`, and
+two copies of that chain is how a screen ends up disagreeing with the firmware.
+
+A firmware build serves exactly one slave (`modbus.slaveid` is a single global),
+so `selectModbusServer` refuses a build with more than one enabled server and
+names them. The editor still allows several, because a project moves between
+targets.
+
+The editor's own link is deliberately NOT derived from the server. `DEBUG_BAUD`
+comes from `screens.serial.baud_rate` — that UART's speed is the package's to
+state — and `DEBUG_SLAVE` is the constant 1, so a project with no Modbus server
+still debugs and changing a server's slave id is not an access event.
+
+On the default UART the firmware answers **both** ids and routes by function
+code: `0x41`-`0x4B` on the editor's, everything on the server's. So a server
+sharing that port keeps whatever id the user picked, and `MBSERIAL_SLAVE` is the
+server's on every port. A board flashed before 4.3.0 may answer the editor on
+another id; Connect tries 1 first and the project's legacy id after.
+
 Platform-specific binaries in `/resources/bin/[platform]/[arch]/`. Board configs in `src/backend/shared/firmware/hals.json`.
 
 ### Debugging
@@ -231,14 +263,23 @@ Platform-specific binaries in `/resources/bin/[platform]/[arch]/`. Board configs
 - **Framework:** Jest + jsdom
 - **Test files:** `*.test.ts(x)`, `*.spec.ts(x)`, or `__tests__/` directories
 - **E2E:** Playwright (`/e2e`), Chromium only
-- **Coverage thresholds** (100% functions/lines/statements required):
-  - `src/frontend/store/slices/`
-  - `src/frontend/utils/`
-  - `src/backend/shared/`
-  - `src/middleware/adapters/editor/`
+- **Coverage thresholds** — per-directory and aggregate, enforced by
+  `jest.config.json`. Branch coverage is not gated anywhere (`branches: 0`);
+  read the config for the current numbers rather than trusting this table:
+
+  | Directory | statements | lines | functions |
+  |---|---|---|---|
+  | `src/frontend/store/slices/` | 97 | 98 | 98 |
+  | `src/frontend/utils/` | 95 | 95 | 97 |
+  | `src/backend/shared/` | 75 | 77 | 76 |
+  | `src/middleware/adapters/editor/` | 85 | 85 | 87 |
+
+  They are floors for the directory as a whole, not a per-file rule, so a new
+  file is not obliged to reach 100% on its own — but it must not drag the
+  directory below the floor.
 - **Mocks:** `configs/mocks/` for file stubs; `identity-obj-proxy` for CSS modules
 
-When adding new code to covered directories, you must add corresponding tests to maintain 100% coverage.
+When adding new code to a covered directory, add tests with it: the directory has to stay above its floor, and an untested file is what pushes it under.
 
 ## Code Style
 
@@ -278,6 +319,7 @@ When adding new code to covered directories, you must add corresponding tests to
 - **Socket.io** for real-time communication
 - **Winston** for structured logging (main process)
 - **serialport** for serial communication
+- **pdf-lib** + **@pdf-lib/fontkit** for PDF export (print/export-to-PDF)
 
 ## Important Patterns
 
@@ -290,11 +332,26 @@ The About modal renders it directly; the web build writes it into `version.json`
 **Bump `APP_VERSION` — never `package.json` alone.** Make the identical one-line
 edit in BOTH repos, and set `package.json.version` to the same value in both so
 they can't drift. Roles: `APP_VERSION` is what the user sees in the About dialog;
-`package.json.version` is what electron-builder stamps on the desktop binary and
-what the release tag `vX.Y.Z` must match. Bumping only `package.json` leaves the
-About dialog stuck on the old version — **this mistake shipped 4.2.7 and 4.2.8
-with About still showing 4.2.6.** If the two ever disagree, `APP_VERSION` is
-authoritative; fix it to match.
+`package.json.version` is what a local build stamps. Bumping only `package.json`
+leaves the About dialog stuck on the old version — **this mistake shipped 4.2.7
+and 4.2.8 with About still showing 4.2.6.** If those two disagree, `APP_VERSION`
+is authoritative; fix `package.json` to match.
+
+**The release tag must equal `APP_VERSION` too.** `release.yml` stamps the binary
+from the tag while About renders `APP_VERSION`, so tagging `v4.3.0` while
+`APP_VERSION` is 4.2.12 ships an installer named 4.3.0 whose About dialog says
+4.2.12 — the same failure in a different disguise. Check before tagging: a pushed
+tag cannot be "fixed to match".
+
+In the editor, electron-builder reads **`release/app/package.json`**, not the root
+one — `electron-builder.json` sets `directories.app` to `release/app`. The release
+workflow runs `npm version <tag>` at the root AND in `release/app`, so a
+*tag-triggered* release is always correct. Two cases are not: a LOCAL package
+build takes whatever `release/app/package.json` says, and a `workflow_dispatch`
+run with an empty `version` input falls back to root `package.json`
+(`release.yml`, version resolution). Use `npm version <v> --no-git-tag-version
+--allow-same-version` in both places rather than editing by hand: it updates each
+lockfile too, which hand edits miss (see DOPE-601).
 
 Release order: bump `APP_VERSION` + `package.json` (both repos, same value) → PR
 to `development` → merge → promote `development`→`main` on both → tag `vX.Y.Z` on
@@ -313,7 +370,7 @@ on its `main` push. (Ideally `package.json.version` should be derived from
 1. Create `types.ts`, `slice.ts`, `index.ts` in `src/frontend/store/slices/<name>/`
 2. Add the slice type to `RootState` union in `src/frontend/store/index.ts`
 3. Spread the slice creator in `createOpenPLCStore()`
-4. Add tests to maintain 100% coverage
+4. Add tests with it, so the directory stays above its coverage floor
 
 ### When adding a new POU language or type:
 1. Update project parser (`src/backend/shared/utils/parse-project-files.ts`)

binary-versions.json

@@ -1,6 +1,6 @@
 {
   "strucpp": {
-    "version": "v0.6.2",
+    "version": "v0.6.8",
     "repository": "Autonomy-Logic/STruCpp"
   }
 }

configs/mocks/monaco-editor-mock.js

@@ -0,0 +1,7 @@
+// monaco-editor ships no CommonJS entry point (package.json has no "main",
+// only an ESM "module" field), so plain `require.resolve('monaco-editor')`
+// fails under Jest — this mapping gives it a real, resolvable path so
+// `jest.mock('monaco-editor', factory)` in individual test files can
+// register their own factory instead of hitting a MODULE_NOT_FOUND error.
+// Tests that don't provide their own factory get this harmless stub.
+export const editor = { tokenize: () => [] }

configs/webpack/webpack.config.cli.dev.ts

@@ -0,0 +1,64 @@
+/**
+ * Development build of the headless CLI.
+ *
+ * Two things make this a config of its own rather than another entry on the dev
+ * main build, and both are path resolution rather than bundling:
+ *
+ *   - `NODE_ENV=development`, because `CompilerModule` chooses between
+ *     `process.cwd()/resources` and `process.resourcesPath` from it, and that
+ *     choice is baked in at build time. A production-built CLI run from a dev
+ *     checkout looks for arduino-cli inside Electron.app and fails with ENOENT.
+ *   - Output at the REPO ROOT, because Electron sets `app.getAppPath()` to the
+ *     directory of the script it is handed, and the compiler resolves the
+ *     STruC++ runtime headers as `getAppPath()/node_modules/strucpp/...`. The
+ *     dev GUI is launched as `electron .` from the root, so the root is what
+ *     the GUI resolves — and matching it is the whole point of the CLI.
+ *
+ * The packaged CLI has neither problem: `app.isPackaged` sends every one of
+ * these lookups to `process.resourcesPath`.
+ */
+
+import webpack from 'webpack'
+import { merge } from 'webpack-merge'
+
+import devMainConfig from './webpack.config.main.dev'
+import webpackPaths from './webpack.paths'
+
+const configuration: webpack.Configuration = {
+  output: {
+    path: webpackPaths.rootPath,
+    filename: '[name].js',
+    library: { type: 'umd' },
+  },
+
+  // One file, no chunks. Both matter because the output directory is the repo
+  // ROOT: merging would keep the dev main build's `main`/`preload` entries and
+  // emit them here too, and code splitting would scatter vendor chunks
+  // alongside them — which is exactly the litter this replaced.
+  optimization: { splitChunks: false, runtimeChunk: false },
+
+  // `entry.ts` reaches both roles through dynamic imports, which webpack would
+  // split into sibling chunk files next to this bundle in the repo root. Folded
+  // back into the one file instead — the point of this config is a single
+  // artifact you can hand to `electron`.
+  plugins: [new webpack.optimize.LimitChunkCountPlugin({ maxChunks: 1 })],
+}
+
+const merged = merge(devMainConfig, configuration)
+
+export default {
+  ...merged,
+  // Assigned after the merge: webpack-merge UNIONS `entry` objects, so the dev
+  // main build's entries would survive an override expressed inside the merge.
+  // `entry.ts`, NOT `cli/main.ts` — the same entry the packaged binary runs.
+  //
+  // Entering at `cli/main.ts` skipped the argv dispatcher, and with it two
+  // things that only exist there: the Linux re-exec that supplies the headless
+  // Chromium switches, and the handler that turns a failure to LOAD the CLI
+  // into an exit instead of a modal error dialog nobody can click. Both were
+  // therefore untestable with the bundle used to test everything else — a dev
+  // build that starts differently from the shipped one is a dev build that can
+  // pass while the product hangs. Costs `--cli` on every dev invocation, which
+  // is what the packaged binary needs anyway.
+  entry: { 'openplc-cli.dev': `${webpackPaths.srcPath}/main/entry.ts` },
+}

configs/webpack/webpack.config.main.prod.ts

@@ -25,7 +25,11 @@ const configuration: webpack.Configuration = {
   target: 'electron-main',
 
   entry: {
-    main: join(webpackPaths.srcMainPath, 'main.ts'),
+    // `entry.ts`, not `main.ts`: a packaged Electron app always runs
+    // `package.json.main`, so the GUI and the headless CLI (DOPE-567) have to
+    // ship in one binary with argv deciding which starts. It imports the GUI
+    // only when this is not a `--cli` run.
+    main: join(webpackPaths.srcMainPath, 'entry.ts'),
     preload: join(webpackPaths.srcMainPath, 'modules/preload/preload.ts'),
   },
 

configs/webpack/webpack.config.renderer.dev.dll.ts

@@ -41,7 +41,18 @@ const configuration: webpack.Configuration = {
     // source code only consumes them via subpath imports (e.g.
     // `browser-basedpyright` ships only the worker bundle under
     // `dist/` and is loaded through `?url`).
-    renderer: Object.keys(dependencies || {}).filter((name) => name !== 'browser-basedpyright'),
+    //
+    // `pdfjs-dist` DOES resolve (it has `main`), but must be excluded for a
+    // different reason: we `import('pdfjs-dist')` for its main-thread API
+    // *and* load `pdf.worker.min.mjs` separately via `?url` as an
+    // independent Worker. Pre-bundling the main API into the DLL creates a
+    // second, separate module instantiation of pdf.js alongside the one in
+    // the renderer bundle, which breaks the API/Worker handshake pdf.js
+    // relies on internally — surfaces as cryptic runtime errors deep in the
+    // worker (e.g. a hash helper missing a method during fingerprint
+    // computation), not a load failure. Same class of problem as the
+    // browser-basedpyright exclusion above, different root cause.
+    renderer: Object.keys(dependencies || {}).filter((name) => name !== 'browser-basedpyright' && name !== 'pdfjs-dist'),
   },
 
   output: {