sync: merge master into main (deploys workflow self-counting fix)

Mirrors the main-sync step that auto-publish-stable.yml normally
runs after a successful PyPI publish, but done manually here
because the publish step failed earlier (PYPI_API_TOKEN secret
unset). Bringing main forward now so:

  - The workflow self-counting fix (02b902a) is registered as the
    active version on the default branch, unblocking future
    dev → testing → review → master cycles.
  - The 0.1.21 version bump (03dcc56, c20a854) is reflected on
    main for parity with the publish-failed master state.

When PyPI_API_TOKEN is configured and the failed run is re-tried,
auto-publish-stable's main-sync will be a no-op (idempotent).

Conflict strategy = -X theirs (master wins on every conflict).

Author: github-actions[bot]

.github/workflows/auto-promote-review-to-stable.yml

@@ -43,6 +43,11 @@ on:
         description: "The SHA on review being approved (40-char)"
         required: true
         type: string
+      force:
+        description: "Bypass the CI-green gate (use only when the gate itself is broken — e.g. self-counting wedge)"
+        required: false
+        default: "false"
+        type: string
 
 permissions:
   contents: write
@@ -195,15 +200,28 @@ jobs:
         env:
           GH_TOKEN: ${{ github.token }}
           SHA: ${{ steps.sha.outputs.sha }}
+          FORCE: ${{ github.event.inputs.force }}
+          SELF_RUN_ID: ${{ github.run_id }}
         run: |
           set -euo pipefail
+
+          if [[ "$FORCE" == "true" ]]; then
+            echo "::warning::Force-promote requested — bypassing CI gate. Use only when the gate itself is wedged."
+            exit 0
+          fi
+
           runs_json=$(gh run list \
             --commit "$SHA" \
-            --json conclusion,status,name,workflowName,url \
+            --json conclusion,status,name,workflowName,databaseId,url \
             --limit 200)
 
-          inflight=$(echo "$runs_json" | jq '[.[] | select(.status != "completed")] | length')
-          failed_runs=$(echo "$runs_json" | jq '[.[] | select(.status == "completed" and .conclusion != "success" and .conclusion != "skipped")]')
+          # Exclude this workflow's own run from the in-flight count: when
+          # triggered by pull_request_review / workflow_dispatch / push,
+          # the current run shows up in the list keyed by the same SHA
+          # with status=in_progress, which would otherwise gate against
+          # itself forever.
+          inflight=$(echo "$runs_json" | jq --argjson self "$SELF_RUN_ID" '[.[] | select(.status != "completed" and .databaseId != $self)] | length')
+          failed_runs=$(echo "$runs_json" | jq --argjson self "$SELF_RUN_ID" '[.[] | select(.status == "completed" and .conclusion != "success" and .conclusion != "skipped" and .databaseId != $self)]')
           failed_count=$(echo "$failed_runs" | jq 'length')
 
           if (( inflight > 0 )); then

.github/workflows/auto-promote-testing-to-review.yml

@@ -132,6 +132,7 @@ jobs:
           GH_TOKEN: ${{ github.token }}
           SHA: ${{ steps.sha.outputs.sha }}
           FORCE: ${{ github.event.inputs.force }}
+          SELF_RUN_ID: ${{ github.run_id }}
         run: |
           set -euo pipefail
 
@@ -146,8 +147,13 @@ jobs:
           #   - completed + success/skipped  → green
           #   - completed + anything else    → red
           #   - !completed                   → in-flight (silent retry)
-          inflight=$(echo "$runs_json" | jq '[.[] | select(.status != "completed")] | length')
-          failed_runs=$(echo "$runs_json" | jq '[.[] | select(.status == "completed" and .conclusion != "success" and .conclusion != "skipped")]')
+          # Exclude this workflow's own run from the in-flight count: when
+          # triggered by workflow_dispatch / pull_request_review / push,
+          # the current run shows up in the list keyed by the same SHA
+          # with status=in_progress, which would otherwise gate against
+          # itself forever.
+          inflight=$(echo "$runs_json" | jq --argjson self "$SELF_RUN_ID" '[.[] | select(.status != "completed" and .databaseId != $self)] | length')
+          failed_runs=$(echo "$runs_json" | jq --argjson self "$SELF_RUN_ID" '[.[] | select(.status == "completed" and .conclusion != "success" and .conclusion != "skipped" and .databaseId != $self)]')
           failed_count=$(echo "$failed_runs" | jq 'length')
 
           echo "in-flight runs: $inflight"

.github/workflows/auto-publish-stable.yml

@@ -178,6 +178,14 @@ jobs:
       - name: Sync project (build + dev deps)
         run: uv sync --all-extras --dev
 
+      - name: Add venv bin to PATH so release.sh's `git cliff` resolves
+        # release.sh invokes `git cliff` to regenerate CHANGELOG.md.
+        # `git cliff` works as a git subcommand only if the
+        # `git-cliff` binary is on PATH. `uv sync --dev` puts it
+        # under .venv/bin/, so we prepend that to PATH for the rest
+        # of the job.
+        run: echo "${{ github.workspace }}/.venv/bin" >> "$GITHUB_PATH"
+
       - name: Run release.sh --stable master --from-ci
         env:
           # Standard token for gh CLI (creates GitHub release, uploads).

CHANGELOG.md

@@ -5,6 +5,142 @@ All notable changes to svg2fbf will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.21] - 2026-04-29
+
+### Added
+
+- HARD pre-publish gate — never release without Docker install verification
+- Add byte-exact E2E regression test for svg2fbf output
+- Add --skip-date and --auto-repair-viewbox CLI flags + E2E install path test
+- Scripts/release_all.sh — single-command release orchestrator
+- Pre-flight checks docker daemon is reachable, shows context
+- **justfile:** CI-green + approval gates on promote recipes
+- **justfile:** CI-green + approval gates on promote recipes
+- Fully automated promotion pipeline (TRDD-bbd4b1f0)
+- **ci:** Cross-platform wheel-install gate before PyPI publish
+
+### Fixed
+
+- Promote svg-text2path from optional to required runtime dependency
+- Release_all.sh pre-flight ignores gitignored runtime state
+- Docker tests must always match host CPU arch via --platform
+- Hard memory limits + watchdog to prevent host swap blow-up
+- Address security + correctness audit findings in src/
+- Harden release + validation scripts per audit findings
+- **auto-install:** Six Windows-specific bugs + Windows CI workflow
+- **auto-install,ci:** Windows UTF-8 stdout + tolerant uninstall step
+- **ci-windows:** Pre-extract shutil.which('node') to avoid pwsh escape mangle
+- **ci:** Install system chromium on amd64 for Puppeteer 22+
+- **auto-install:** Six Windows-specific bugs + Windows CI workflow
+- **auto-install,ci:** Windows UTF-8 stdout + tolerant uninstall step
+- **ci-windows:** Pre-extract shutil.which('node') to avoid pwsh escape mangle
+- **ci:** Install system chromium on amd64 for Puppeteer 22+
+- **review:** Restore testing's pyproject.toml + uv.lock, keep rc1 version
+- **cli:** Reconfigure stdout/stderr to UTF-8 on entry to cli()
+- **tests:** Force UTF-8 decoding in test_text2path_integration subprocess calls
+- **tests:** Force UTF-8 in Path.read_text() for windows compat
+- **master:** Forward svg-text2path-required pyproject + lock from review (keep 0.1.20)
+- **ci:** Add .venv/bin to PATH so release.sh can find git-cliff
+- **workflows:** Exclude self from in-flight CI count + add force input
+
+### Other
+
+- Merge dev into testing - feature complete, ready for testing
+- Merge dev into testing - feature complete, ready for testing
+- Zip-slip defense + stale docstring + workflow policy note
+- Opt-in Node 24 runtime + bounded portable-Node download + reconcile TRDD
+- Add pyright to dev deps for in-CI release-dry-run
+- Zip-slip defense + stale docstring + workflow policy note
+- Opt-in Node 24 runtime + bounded portable-Node download + reconcile TRDD
+- Merge dev into testing - feature complete, ready for testing
+
+Resolves conflict in .github/workflows/windows-autoinstall.yml by
+taking testing's version (excludes dev from CI triggers, per TRDD
+"no CI on dev" policy). The dev side carried an older comment block
+arguing for Windows-only CI on dev pushes; that argument was
+superseded by the broader CI-on-dev-is-noise policy that landed on
+testing in commit ca33aa5 (2026-04-29). Net behavior: windows-autoinstall
+fires on testing/review/master/main as expected, never on dev.
+- Merge testing into review - bugs fixed, ready for RC
+
+Forwards all of testing's recent work (auto-promotion pipeline,
+CODEOWNERS, Windows/Linux/macOS auto-install, Docker E2E suite,
+text→path tests, etc.) into review.
+
+Conflicts resolved by keeping review's version artifacts:
+- pyproject.toml: keep version=0.1.20rc1 (review's rc > testing's b3)
+- CHANGELOG.md: keep review's rc1 changelog entries
+- uv.lock: keep review's lockfile (matches rc1's pinned deps)
+
+This preserves the version progression rule: a single version can
+only exist in ONE stage at a time, and stage on review must be ≥
+stage on testing. The next bump (review → master = stable) will
+take this rc1 to 0.1.20 stable.
+- Merge dev into testing - feature complete, ready for testing
+- Merge dev into testing - feature complete, ready for testing
+- Merge testing into review - bugs fixed, ready for release candidate
+- Merge dev into testing - feature complete, ready for testing
+- Merge testing into review - bugs fixed, ready for release candidate
+- Merge dev into testing - feature complete, ready for testing
+- Merge testing into review - bugs fixed, ready for release candidate
+- Review → master (bootstrap of TRDD-bbd4b1f0 auto-promotion pipeline; approved by Emasoft)
+- Merge dev into testing - feature complete, ready for testing
+- Merge dev into testing - feature complete, ready for testing
+- Testing → review (all CI green at 2f44f7c858fd5683a2fdcbb3bb4193a0b7e50394)
+- **npm:** Bump puppeteer in /tests in the npm-all group ([#10](https://github.com/Emasoft/svg2fbf/issues/10))
+- Merge dev into testing - feature complete, ready for testing
+- Testing → review (all CI green at aeb8f2eda476650134dd0b7d362c280c0734ce3b)
+- Review → master (bootstrap; one-off manual merge to deploy workflow self-counting fix)
+
+### Testing
+
+- Wire T13 text→path Docker E2E harness + fixtures (TRDD-c2a3199d)
+- Add pin_fbf_frame_to_png calibration utility (TRDD-c2a3199d)
+- Regen e2e goldens for testing branch (v0.1.20b3 version pin)
+- Restore docker-flavored text_frames golden, only patch version (TRDD-c2a3199d)
+- Version-strip byte-exact tests + add Docker-bound regen for text golden (TRDD-c2a3199d)
+- Regen text_frames golden (CI amd64 environment) + HOST_ARCH override
+- Convert T12 from byte-exact to per-frame visual diff (<3%)
+
+### Documentation
+
+- Add TRDD-eb937ddf — adapt release.sh to PR-based promotion flow
+- Add TRDD-c2a3199d — text→path Docker E2E test plan
+- Annotate T13 + text→path E2E tooling across guides (TRDD-c2a3199d)
+- Add TRDD-ad386cb7 — CI/release pipeline review proposal
+- Add TRDD-bbd4b1f0 — fully-automated promotion pipeline
+- Add TRDD-bbd4b1f0 — fully-automated promotion pipeline
+- Cross-platform gate documentation + workflow fixes
+
+### Miscellaneous
+
+- Gitignore /reports/ and /reports_dev/ per agent-reports rule
+- Add CODEOWNERS — make Emasoft the code owner of everything
+
+### CI/CD
+
+- Add Linux + macOS auto-install workflows + release dry-run gate
+
+## [0.1.20b3] - 2026-04-27
+
+### Other
+
+- Release beta 0.1.20b3
+
+### Miscellaneous
+
+- Update uv.lock for beta 0.1.20b3
+
+## [0.1.20rc1] - 2026-04-27
+
+### Other
+
+- Release rc 0.1.20rc1
+
+### Miscellaneous
+
+- Update uv.lock for rc 0.1.20rc1
+
 ## [0.1.20] - 2026-04-27
 
 ### Fixed
@@ -16,6 +152,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Forward tomli-w dev dep to testing
 - Forward tomli-w dev dep to review
 - Forward tomli-w dev dep to master
+- Release stable 0.1.20
+
+### Miscellaneous
+
+- Update uv.lock for stable 0.1.20
 
 ## [0.1.20b2] - 2026-04-27
 

CONTRIBUTING.md

@@ -148,13 +148,21 @@ fonts and exercises every release-blocking path:
 ```
 
 It runs T1–T10 (Node/Puppeteer auto-install), T_setup/T11 (svg-bbox
-harness + `--text2path` end-to-end), T12 (byte-exact FBF compare against
-the golden) and T13 (per-frame visual diff of the FBF against the input
-fixtures, budget < 3 % `diffPercentage`).
+harness + `--text2path` end-to-end), T12 (per-frame visual diff of the
+freshly-produced FBF against the committed golden FBF, budget < 3 %
+`diffPercentage` per frame) and T13 (per-frame visual diff of the FBF
+against the input fixture SVGs, budget < 3 % `diffPercentage`).
+
+T12 used to be a byte-exact compare, but the system DejaVu glyph table
+drifts by sub-pixel amounts across fresh `apt-get install fonts-dejavu`
+runs even on the same architecture, making byte-exact comparison
+non-deterministic. A pixel-level visual invariant ("the FBF still
+LOOKS like the golden") is the right invariant for this lane.
 
 Relevant scripts and fixtures:
 
 - `tests/fixtures/e2e/text_frames/` — 5 deterministic text fixture SVGs (DejaVu Sans/Serif + Liberation Mono only) and the golden `expected.fbf.svg`. The `*.fbf.svg` ignore rule has an explicit exception for this golden in `tests/.gitignore`; if you regenerate the golden, the exception is what keeps it tracked.
+- `scripts/visual_diff_fbf_vs_golden.py` — T12 harness (extracts each frame from BOTH the produced FBF and the golden FBF, then runs `sbb-compare --json` per pair).
 - `scripts/visual_diff_text_frames.py` — T13 harness (cwd-stages inputs and runs `sbb-compare --json`).
 - `scripts/extract_fbf_frame.py` — XML-level extraction of one frame from an FBF.
 - `scripts/pin_fbf_frame_to_png.py` — calibration utility: pins PROSKENION to frame N and renders the full FBF wrapper to PNG via `sbb-svg2png`. Useful when calibrating the T13 thresholds.

docs/FBF_FRAME_COMPARATOR.md

@@ -257,9 +257,10 @@ The comparator shares infrastructure with `test_frame_rendering.py`:
 - **testrunner.py** - Session-based testing for svg2fbf
 - **scripts/extract_fbf_frame.py** - XML-level lift of `<g id="FRAME0000N">` + `<g id="SHARED_DEFINITIONS">` from an FBF.SVG into a fresh standalone SVG. Used by the T13 Docker E2E harness for per-frame comparison without playing back the animation timeline. Loses ancestor inheritance from `ANIMATION_BACKDROP > ANIMATION_STAGE > ANIMATED_GROUP > PROSKENION` and any `STAGE_FOREGROUND` / `OVERLAY_LAYER` content (empty by default).
 - **scripts/pin_fbf_frame_to_png.py** - Calibration utility. Mutates a copy of an FBF.SVG (pin PROSKENION's `xlink:href`, drop the `<animate>` child) and renders to PNG via `sbb-svg2png`. Preserves the full FBF wrapper — ancestor inheritance, foreground/overlay layers, root SVG attrs — so the rendered PNG matches what a viewer truly sees at frame N. First-class FBF→PNG frame export is tracked upstream as [Emasoft/SVG-BBOX#3](https://github.com/Emasoft/SVG-BBOX/issues/3); when that lands, the pin-and-render workaround in this script becomes obsolete.
+- **scripts/visual_diff_fbf_vs_golden.py** - T12 harness in the Docker E2E suite. Extracts each frame from BOTH the produced FBF and the committed golden FBF (via `extract_fbf_frame.py`), then runs `sbb-compare --json` per pair with the same defaults as T13. Pass requires every frame at or below the image-wide budget (default 3 %).
 - **scripts/visual_diff_text_frames.py** - T13 harness in the Docker E2E suite. Stages input fixtures into `--workdir` and runs `sbb-compare --json` with `cwd=workdir` (sbb tools v1.0.14 sandbox file paths to `process.cwd()` and have no `--allow-paths` flag). Defaults: per-pixel-channel threshold 32/256, image-wide diffPercentage budget 3 %.
 - **scripts/regen_e2e_reference.sh** - Regenerate the non-text byte-exact golden (`tests/fixtures/e2e/expected/animation.fbf.svg`) on the host. Use only when input frames or the CLI invocation in `tests/fixtures/e2e/expected/COMMAND.txt` change intentionally — version bumps are absorbed by the version-strip in the byte-exact test, so they don't require a regen.
-- **scripts/regen_text_frames_golden.sh** - Regenerate the text→path byte-exact golden (`tests/fixtures/e2e/text_frames/expected.fbf.svg`) **inside Docker**. The text→path golden is platform-dependent (Linux vs macOS DejaVu Sans have different glyph metric tables), so this script always builds the same `python:3.12-slim` + `fonts-dejavu` + `fonts-liberation` image as `test_release_clean.sh` and runs `svg2fbf --text2path` inside it, ensuring byte-identical glyph paths to what T12 compares against. Never regenerate this golden on the host directly.
+- **scripts/regen_text_frames_golden.sh** - Regenerate the text→path golden (`tests/fixtures/e2e/text_frames/expected.fbf.svg`) **inside Docker**. T12 is now visual-diff (not byte-exact), but the golden is still platform-pinned: a Linux-generated golden keeps the calibrated baseline near 0 % rather than the ~1-2 % cross-platform AA drift floor. The script always builds the same `python:3.12-slim` + `fonts-dejavu` + `fonts-liberation` image as `test_release_clean.sh` and runs `svg2fbf --text2path` inside it. Never regenerate this golden on the host directly.
 
 ## License