Add standalone native binaries for Windows/macOS/Linux

.github/workflows/binaries.yml

@@ -0,0 +1,93 @@
+name: binaries
+
+on:
+  push:
+    branches: [master]
+    paths:
+      - "bin/cli.js"
+      - "src/pptxdiff/**"
+      - "src/packages/binaries/**"
+      - ".github/workflows/binaries.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  # linux + win (x64 AND arm64) are genuinely cross-compiled by
+  # @yao-pkg/pkg from one host — confirmed directly (real ELF aarch64 /
+  # PE32+ Aarch64 executables built on an x64 dev sandbox) — no
+  # codesigning concern for either OS, so all four build together in one
+  # job. Cross-ARCH builds need --fallback-to-source (see build.mjs) since
+  # V8 bytecode generation for a foreign arch fails without QEMU emulation
+  # — harmless, this is already-open-source code with nothing to protect
+  # by shipping bytecode instead of plain source.
+  build-linux-win:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v5
+        with:
+          node-version: "22"
+      - run: npm install
+        working-directory: src/packages/binaries
+      - run: npm test
+        working-directory: src/packages/binaries
+      - run: npm run test:e2e
+        working-directory: src/packages/binaries
+      - run: npm run build -- linux linux-arm64 win win-arm64
+        working-directory: src/packages/binaries
+      - uses: actions/upload-artifact@v4
+        with:
+          name: pptxdiff-linux
+          path: src/packages/binaries/pptxdiff-linux/pptxdiff-linux
+          if-no-files-found: error
+      - uses: actions/upload-artifact@v4
+        with:
+          name: pptxdiff-linux-arm64
+          path: src/packages/binaries/pptxdiff-linux/pptxdiff-linux-arm64
+          if-no-files-found: error
+      - uses: actions/upload-artifact@v4
+        with:
+          name: pptxdiff-win
+          path: src/packages/binaries/pptxdiff-win/pptxdiff-win.exe
+          if-no-files-found: error
+      - uses: actions/upload-artifact@v4
+        with:
+          name: pptxdiff-win-arm64
+          path: src/packages/binaries/pptxdiff-win/pptxdiff-win-arm64.exe
+          if-no-files-found: error
+
+  # mac (both Intel x64 and Apple Silicon arm64) builds on a REAL macOS
+  # runner specifically so both can be ad-hoc codesigned (codesign only
+  # exists on macOS) — an unsigned mac binary is a real functional problem
+  # on Apple Silicon, not just a warning, so neither is cross-compiled from
+  # the linux job above. See build.mjs's header comment and
+  # docs/.scrolls/GAP_CONTEXT.md. GitHub's macos-latest runners are
+  # themselves Apple Silicon as of 2024, so the arm64 build here is a
+  # genuinely native build+sign, not a translated one.
+  build-mac:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v5
+        with:
+          node-version: "22"
+      - run: npm install
+        working-directory: src/packages/binaries
+      - run: npm test
+        working-directory: src/packages/binaries
+      - run: npm run test:e2e
+        working-directory: src/packages/binaries
+      - run: npm run build -- mac mac-arm64
+        working-directory: src/packages/binaries
+      - uses: actions/upload-artifact@v4
+        with:
+          name: pptxdiff-mac
+          path: src/packages/binaries/pptxdiff-mac/pptxdiff-mac
+          if-no-files-found: error
+      - uses: actions/upload-artifact@v4
+        with:
+          name: pptxdiff-mac-arm64
+          path: src/packages/binaries/pptxdiff-mac/pptxdiff-mac-arm64
+          if-no-files-found: error

.gitignore

@@ -385,3 +385,22 @@ src/pptxdiff/docs-site/site/
 ## Covers pptxdiff-cli, @pptxdiff/server, and any future src/packages/*/lib/.
 !src/packages/*/lib/
 !src/packages/*/lib/**
+
+## Native-binary build output (src/packages/binaries/build.mjs, via
+## @yao-pkg/pkg) — the single packaged executable per OS is generated, not
+## source; keep each OS folder's own README.md and CHANGELOG.md tracked
+## (they document the folder even before a build has ever run there) but
+## ignore the built binary itself. build.mjs also writes a temp pkg config
+## directly at the repo root (see WISDOM.md's pkg-config-colocation trap
+## entry for why) and always removes it in a `finally` — ignored here too
+## as a defensive backstop in case a build is interrupted mid-run.
+src/packages/binaries/pptxdiff-win/*
+src/packages/binaries/pptxdiff-mac/*
+src/packages/binaries/pptxdiff-linux/*
+!src/packages/binaries/pptxdiff-win/README.md
+!src/packages/binaries/pptxdiff-mac/README.md
+!src/packages/binaries/pptxdiff-linux/README.md
+!src/packages/binaries/pptxdiff-win/CHANGELOG.md
+!src/packages/binaries/pptxdiff-mac/CHANGELOG.md
+!src/packages/binaries/pptxdiff-linux/CHANGELOG.md
+/.pkg-binaries-config.*.json

.gitignores/user.gitignore

@@ -29,3 +29,22 @@ src/pptxdiff/docs-site/site/
 ## Covers pptxdiff-cli, @pptxdiff/server, and any future src/packages/*/lib/.
 !src/packages/*/lib/
 !src/packages/*/lib/**
+
+## Native-binary build output (src/packages/binaries/build.mjs, via
+## @yao-pkg/pkg) — the single packaged executable per OS is generated, not
+## source; keep each OS folder's own README.md and CHANGELOG.md tracked
+## (they document the folder even before a build has ever run there) but
+## ignore the built binary itself. build.mjs also writes a temp pkg config
+## directly at the repo root (see WISDOM.md's pkg-config-colocation trap
+## entry for why) and always removes it in a `finally` — ignored here too
+## as a defensive backstop in case a build is interrupted mid-run.
+src/packages/binaries/pptxdiff-win/*
+src/packages/binaries/pptxdiff-mac/*
+src/packages/binaries/pptxdiff-linux/*
+!src/packages/binaries/pptxdiff-win/README.md
+!src/packages/binaries/pptxdiff-mac/README.md
+!src/packages/binaries/pptxdiff-linux/README.md
+!src/packages/binaries/pptxdiff-win/CHANGELOG.md
+!src/packages/binaries/pptxdiff-mac/CHANGELOG.md
+!src/packages/binaries/pptxdiff-linux/CHANGELOG.md
+/.pkg-binaries-config.*.json

CHANGELOG.md

@@ -40,6 +40,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   state to the tap even without a version-pin change, while a scheduled run still only does real work
   on an actual version bump. `test_formula.mjs` now also asserts `LICENSE` stays byte-identical to
   the repo root's copy, catching drift instead of silently shipping a stale license to the tap.
+- New private `@pptxdiff/binaries` package (`src/packages/binaries/`) building standalone native `pptxdiff` executables for Windows, macOS, and Linux (x64 AND arm64 for all three) via `@yao-pkg/pkg` — download one file and run it, no separate Node.js install required.
+- Native arm64 builds for all three OSes (`pptxdiff-mac-arm64`, `pptxdiff-win-arm64.exe`, `pptxdiff-linux-arm64`), each sharing its OS's output folder with the existing x64 build — avoids Apple Silicon Macs having to run the Intel binary via Rosetta 2 translation, and gives Windows-on-ARM/arm64-Linux users a native option too.
+- Per-OS build output folders `src/packages/binaries/pptxdiff-{win,mac,linux}/`, each with its own `README.md` and `CHANGELOG.md`.
+- `.github/workflows/binaries.yml`: `pkg` genuinely cross-compiles, so Windows and Linux (both chip variants) build together in one `ubuntu-latest` job; both macOS targets build in their own `macos-latest` job so they can be properly ad-hoc codesigned.
+- `make pkg.binaries.build` / `npm run build:binary` for local builds (all six targets by default, or a specific subset).
+- Red/Green TDD test suite for the build tooling itself: `npm test` (fast, pure — config/asset-drift/regression checks) and `npm run test:e2e` (slow, real — builds and runs the actual packaged binary over real HTTP) in `src/packages/binaries/`.
 
 ## [0.7.0] - 2026-08-02
 

Makefile

@@ -52,6 +52,9 @@ VSCE_EXT_VERSION := $(shell node -p "require('$(VSCE_PKGJSON_PATH)').version")
 VSCE_EXT_NAME := $(shell node -p "require('$(VSCE_PKGJSON_PATH)').name")
 VSIX_EXT_PATH_LOCAL := dist/$(VSCE_EXT_NAME)-$(VSCE_EXT_VERSION).vsix
 
+BINARIES_PKG_DIR_RELPATH := ./src/packages/binaries
+BINARIES_PKG_DIR := $(abspath $(ROOT_DIR)/$(BINARIES_PKG_DIR_RELPATH))
+
 MKDOCS_YML_PATH := $(abspath $(ROOT_DIR)/$(MKDOCS_YML_RELPATH))
 
 ####################### DETERMINE VSCODE EDITOR TYPE ###########################
@@ -97,6 +100,7 @@ help:
 	# pkg.build         :	Build the extension (creates a.vsix file).
 	# pkg.publish       :	Publish the extension.
 	# pkg.release       :	Build and Publish the extension.
+	# pkg.binaries.build:	Build a standalone native pptxdiff executable for the current OS.
 	#
 	# vsce.open         :	Opens the VS Code Extension Management page for a Publisher.
 	# vsce.token        :	Opens the Azure DevOps Page to Manage the Personal Access Token for VSCE.
@@ -209,7 +213,16 @@ pkg.vsce.install.local:
 	@echo -e "\n✨ Installing VS Code extension locally (from 'dist/' folder)... ⏳\n"
 	@echo -e "\n✨ VS Code Type: $(VSCODE_CMD)"
 	@$(VSCODE_CMD) --install-extension $(VSCE_PKG_DIR)/$(VSIX_EXT_PATH_LOCAL) --force
-
+
+.PHONY: pkg.binaries.build
+pkg.binaries.build:
+	@## npm run build:binary — builds a standalone native pptxdiff executable
+	@## for the CURRENT host OS only (Node SEA has no cross-compile mode); see
+	@## src/packages/binaries/README.md and .github/workflows/binaries.yml for
+	@## how all three (win/mac/linux) get built via a CI matrix.
+	@echo -e "\n✨ Building native pptxdiff binary for the current OS... ⏳\n"
+	@cd $(BINARIES_PKG_DIR) && npm install && npm run build
+
 
 ############################## ..: COMMANDS vsce.*:.. ################################
 

docs/.scrolls/DOCS.md

@@ -286,3 +286,68 @@ PUBLIC-docs-site side of the same rule.
   index), so no FAQ change was needed; `docs/.scrolls/SPEC.md`/`GAP_ANALYSIS.md`/`GAP_CONTEXT.md`
   already fully cover the underlying feature from the sessions that built it — this session's scope
   was specifically the public docs site, per the explicit ask.
+## 16. Content updates + new changelog subpage for standalone native binaries (`@pptxdiff/binaries`, added a later session)
+
+Follow-up to the `@pptxdiff/binaries` feature (SPEC.md §36 — six standalone executables, x64+arm64
+for Windows/macOS/Linux, via `@yao-pkg/pkg`) shipped across several turns of the same session — the
+`.scrolls/` working-memory docs were updated as each piece landed, but the PUBLIC docs-site was not
+touched at all until an explicit follow-up ("verify docs/.scrolls folder is updated and so is the
+docs-site folder"). Confirmed via `git log --oneline master..HEAD -- src/pptxdiff/docs-site/`
+returning zero commits before this entry — a real, not hypothetical, gap.
+
+- **`getting-started.md` gained "Option D — standalone binary (no Node.js at all)"**, between the
+  existing Option C (just the file) and "What happens on first load" — this page's whole job is
+  already "here are the ways to run pptxdiff," so a new install option belongs here, not a new
+  top-level page (see §14's own reasoning for the opposite call on `headless-cli-api.md`, which
+  documents a genuinely different tool with a different purpose — this is the SAME `bin/cli.js`,
+  just packaged differently). New `doc_coverage:` id `native-binaries` (`partial` — the page is
+  accurate, but the underlying feature has known gaps: unsigned/ad-hoc-signed, not on GitHub
+  Releases yet), anchored to the new section.
+- **`cli.md` gained a one-paragraph cross-link** ("No Node.js at all?") pointing at the new Option D
+  — no new `doc_coverage:` id here, since `getting-started.md`'s new id already covers the feature
+  and this is supplementary framing on an already-covered page, not a second independent unit of
+  coverage.
+- **`limitations.md` gained a new row** (`native-binaries-limitations`, `complete` — the limitation
+  itself is fully documented even though the underlying feature has real gaps, same convention §14
+  established for `headless-cli-api-limitations`) and the existing "npm CLI opens a browser tab" row
+  was reworded to note the binaries share that same property (same `bin/cli.js`, not a native-window
+  wrapper) rather than reading as if the binaries somehow escaped it.
+- **`index.md`'s "No install required" card** updated to mention the binaries option — a factual
+  correction (the card previously implied only two options existed), no coverage-registry impact
+  (the card doesn't carry its own `doc_coverage:` entry, `index.md`'s existing ids are unaffected).
+- **New changelog subpage `changelogs/pptxdiff-binaries.md`**, added to nav under "NPM Package(s)"
+  (same category `pptxdiff-cli`/`@pptxdiff/server` already live in, despite also being `private:
+  true` unpublished packages — the nav grouping in this site means "package.json-defined sibling in
+  this repo," not "published to the npm registry") and to `changelog.md`'s index. **Structurally
+  different from every other changelog subpage**: `@pptxdiff/binaries` has no single package-level
+  `CHANGELOG.md` (each OS's binary has its own, since they're independent downloadable artifacts —
+  see `SPEC.md` §36/`GAP_CONTEXT.md`) — so this page transcludes all THREE
+  (`src/packages/binaries/pptxdiff-{win,mac,linux}/CHANGELOG.md`) under their own `## Windows` /
+  `## macOS` / `## Linux` subheadings, rather than one `--8<--` include like every other subpage.
+- **A real `mkdocs build --strict` failure found and fixed, not just described**: the three per-OS
+  `CHANGELOG.md` files each linked back to the root `CHANGELOG.md` via a relative path
+  (`../../../../CHANGELOG.md`) that's correct when the file is read on GitHub (four levels up from
+  `src/packages/binaries/pptxdiff-win/`) but WRONG once transcluded verbatim into
+  `docs-site/docs/changelogs/pptxdiff-binaries.md` — `pymdownx.snippets` is a textual include, it
+  does not rewrite relative links to account for where the content ends up, so the link resolved
+  against the WRONG base and `mkdocs build --strict`'s link checker correctly flagged it (twice — the
+  same relative link appears in the transcluded content of two other, unrelated warnings the build
+  also printed for the same reason). Fixed at the SOURCE (`src/packages/binaries/pptxdiff-{win,mac,
+  linux}/CHANGELOG.md` themselves, since the docs-site page transcludes them verbatim) by swapping
+  the relative link for the same absolute GitHub URL pattern every other subpage's own "Source:"
+  line already uses — the fix had to happen in the package-level files, not the docs-site page, since
+  the page has no content of its own to fix.
+- **`scripts/coverage_registry.yml` gained two new ids** (`native-binaries` under `features:`,
+  `native-binaries-limitations` under `limitations:`), each added in the same change as the
+  page/row that declares them via `doc_coverage:` front matter, per this file's own §8/§14 rule —
+  `sync_doc_coverage.py --write` then `--check` re-run to confirm 36 complete + 4 partial + 0 missing
+  (of 40; was 34 complete + 1 partial before this session's headless-CLI-API work, then presumably
+  higher still after intervening sessions not otherwise noted here).
+- **Verified for real**: `mkdocs build --strict` clean after the link fix (one remaining, expected,
+  harmless warning — `git-revision-date-localized-plugin` complaining the brand-new, not-yet-committed
+  `pptxdiff-binaries.md` has no git history yet; resolves itself once committed, not a structural
+  issue). Directly grepped the built HTML (`getting-started/index.html`, `cli/index.html`,
+  `limitations/index.html`) to confirm the new anchor (`option-e-standalone-binary-no-nodejs-at-all`)
+  matches EXACTLY between the page that defines it and the two pages that link to it, rather than
+  trusting that `--strict` alone would have caught a mismatched anchor (MkDocs's built-in link
+  checker validates that a linked FILE exists, not that a `#fragment` inside it does).