ginext-core 0.8.1__tar.gz

ginext_core-0.8.1/.clang-format

@@ -0,0 +1,70 @@
+# clang-format does not have a native version-pinning mechanism.
+# This config was written for clang-format 21. Run `clang-format --version`
+# and verify it reports 21.x before reformatting; older versions may produce
+# different output for some options used here.
+---
+Language:        Cpp
+BasedOnStyle:    GNU
+
+# Indentation: 2 spaces, no tabs (GLib/GTK standard)
+IndentWidth:     2
+TabWidth:        2
+UseTab:          Never
+IndentCaseLabels: false
+ContinuationIndentWidth: 4
+
+# Line length
+ColumnLimit:     100
+
+# Braces: GNU style — function body brace on new line (no indent),
+# control-flow braces on their own line indented to body level.
+BreakBeforeBraces: GNU
+
+# Return type on its own line for all function definitions:
+#   static void
+#   my_func (void)
+#   {
+BreakAfterReturnType: All
+
+# Pointers stay with the variable name: `type *var`
+PointerAlignment: Right
+
+# Space before ALL opening parens — the most distinctive GLib/GTK trait:
+#   g_free (ptr);    if (x)    sizeof (int)
+SpaceBeforeParens: Always
+
+# Don't bin-pack: keep all parameters on one line or each on its own
+BinPackParameters: false
+BinPackArguments:  false
+
+# Align continuation parameters to the opening paren:
+#   foo (long_arg1,
+#        long_arg2);
+AlignAfterOpenBracket:                    Align
+AllowAllArgumentsOnNextLine:              false
+AllowAllParametersOfDeclarationOnNextLine: false
+
+# Don't merge short constructs onto one line
+AllowShortFunctionsOnASingleLine: None
+AllowShortIfStatementsOnASingleLine: Never
+AllowShortLoopsOnASingleLine: false
+AllowShortCaseLabelsOnASingleLine: false
+
+# Keep #include order as written
+SortIncludes: Never
+
+# Don't reflow existing comments
+ReflowComments: false
+
+# Trailing comments: don't force-align across lines
+AlignTrailingComments:
+  Kind:           Never
+
+# Miscellaneous GLib/GTK conventions
+AlignOperands:             true
+BreakBeforeTernaryOperators: true
+SpaceAfterCStyleCast:      false
+SpacesInParentheses:       false
+SpacesInSquareBrackets:    false
+MaxEmptyLinesToKeep:       2
+KeepEmptyLinesAtTheStartOfBlocks: false

ginext_core-0.8.1/.github/workflows/ci-windows.yml

@@ -0,0 +1,192 @@
+name: CI (Windows)
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-windows-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  packages: write
+
+env:
+  # Pin vcpkg (the tool + its registry) so builds are reproducible across runs
+  # and runner-image updates. Matches the default-registry baseline in
+  # vcpkg-configuration.json.
+  VCPKG_COMMIT: "059d760472984042e1b4db0d40efd935a1adcbc9"
+  # Pin LLVM to the version validated locally. clang-cl < 21 doesn't accept the
+  # GCC-style `-include Python.h` flag meson emits (warns + treats Python.h as a
+  # missing input); 22.1.7's clang-cl accepts it.
+  LLVM_VERSION: "22.1.7"
+
+jobs:
+  build:
+    name: ${{ matrix.name }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: x64
+            runner: windows-latest
+            triplet: x64-windows
+            llvm_asset: win64
+            py_asset: amd64
+          - name: arm64
+            runner: windows-11-arm
+            triplet: arm64-windows
+            llvm_asset: woa64
+            py_asset: arm64
+    runs-on: ${{ matrix.runner }}
+    env:
+      GINEXT_TRIPLET: ${{ matrix.triplet }}
+      GINEXT_LLVM: C:\LLVM
+      GINEXT_VS: C:\Program Files\Microsoft Visual Studio\2022\Enterprise
+      VCPKG_DEFAULT_TRIPLET: ${{ matrix.triplet }}
+      # Pin the manifest install tree to a known path so build-env.ps1 finds it
+      # (run-vcpkg otherwise installs to a per-run GUID dir).
+      VCPKG_INSTALLED_DIR: ${{ github.workspace }}/vcpkg_installed
+      # Binary cache: a durable GitHub Packages NuGet feed (check before build,
+      # upload after each package) plus x-gha as a secondary. Set in the nuget
+      # step once vcpkg is bootstrapped.
+      NUGET_FEED: https://nuget.pkg.github.com/jdahlin/index.json
+    steps:
+      - uses: actions/checkout@v4
+
+      # Expose the GitHub Actions cache backend to vcpkg's x-gha binary source
+      # (run-vcpkg caches the vcpkg tool itself; x-gha caches the built packages).
+      - name: Export GitHub Actions cache env for vcpkg
+        uses: actions/github-script@v7
+        with:
+          script: |
+            core.exportVariable('ACTIONS_CACHE_URL', process.env.ACTIONS_CACHE_URL || '');
+            core.exportVariable('ACTIONS_RUNTIME_TOKEN', process.env.ACTIONS_RUNTIME_TOKEN || '');
+
+      # Native CPython 3.14 from python.org (NOT actions/setup-python): the
+      # setup-python build makes meson emit a GCC-style `-include Python.h` for
+      # the extension, which clang-cl rejects. The python.org installer matches
+      # the locally validated toolchain and produces a clean build.
+      - name: Install CPython 3.14.5 (python.org)
+        shell: pwsh
+        run: |
+          $url = "https://www.python.org/ftp/python/3.14.5/python-3.14.5-${{ matrix.py_asset }}.exe"
+          $dst = "$env:RUNNER_TEMP\py314"
+          Invoke-WebRequest $url -OutFile "$env:RUNNER_TEMP\py.exe"
+          Start-Process "$env:RUNNER_TEMP\py.exe" -Wait -ArgumentList `
+            '/quiet','InstallAllUsers=0','PrependPath=0','Include_pip=1','Include_dev=1',"TargetDir=$dst"
+          "$dst" | Out-File -FilePath $env:GITHUB_PATH -Append
+          "$dst\Scripts" | Out-File -FilePath $env:GITHUB_PATH -Append
+          "GINEXT_BASE_PYTHON=$dst\python.exe" | Out-File -FilePath $env:GITHUB_ENV -Append
+          & "$dst\python.exe" --version
+          # Python 3.14 ships a PEP 739 build-details.json; meson 1.11 reads it,
+          # takes c_api.pkgconfig_path, and runs pkg-config python-3.14 whose
+          # GCC-style `-include Python.h -Wno-missing-field-initializers` Cflags
+          # break clang-cl. Remove build-details.json (and any python*.pc) so
+          # meson falls back to sysconfig (include dirs only) -- the clean path.
+          $found = $false
+          foreach ($pat in 'build-details.json','python-3.14.pc','python-3.14-embed.pc','python3.pc','python3-embed.pc') {
+            Get-ChildItem -Path $dst -Recurse -Filter $pat -EA SilentlyContinue | ForEach-Object {
+              $found = $true; Write-Host "removing $($_.FullName)"; Remove-Item $_.FullName -Force
+            }
+          }
+          if (-not $found) { Write-Host "WARNING: no build-details.json / python*.pc found under $dst" }
+
+      - uses: astral-sh/setup-uv@v5
+
+      # Pinned LLVM (clang-cl + lld-link). The NSIS installer supports /S silent
+      # install; woa64 asset is the native Windows-on-ARM build.
+      - name: Install LLVM ${{ env.LLVM_VERSION }} (${{ matrix.llvm_asset }})
+        shell: pwsh
+        run: |
+          $url = "https://github.com/llvm/llvm-project/releases/download/llvmorg-$env:LLVM_VERSION/LLVM-$env:LLVM_VERSION-${{ matrix.llvm_asset }}.exe"
+          Write-Host "Downloading $url"
+          Invoke-WebRequest -Uri $url -OutFile "$env:RUNNER_TEMP\llvm.exe"
+          Start-Process -FilePath "$env:RUNNER_TEMP\llvm.exe" -ArgumentList "/S","/D=C:\LLVM" -Wait
+          & "C:\LLVM\bin\clang-cl.exe" --version
+
+      # Locate the VS install on the runner (Enterprise on hosted images).
+      - name: Resolve Visual Studio install
+        shell: pwsh
+        run: |
+          $vswhere = "${env:ProgramFiles(x86)}\Microsoft Visual Studio\Installer\vswhere.exe"
+          $vs = & $vswhere -latest -products * -property installationPath
+          if (-not $vs) { throw "no Visual Studio install found" }
+          "GINEXT_VS=$vs" | Out-File -FilePath $env:GITHUB_ENV -Append
+          Write-Host "VS: $vs"
+
+      # Provision a pinned vcpkg (tool cached via the GH cache) WITHOUT installing
+      # yet, so we can configure the NuGet binary cache first. Sets VCPKG_ROOT.
+      - name: Setup vcpkg
+        uses: lukka/run-vcpkg@v11
+        with:
+          vcpkgGitCommitId: ${{ env.VCPKG_COMMIT }}
+          vcpkgJsonGlob: "vcpkg.json"
+          runVcpkgInstall: false
+
+      # Point vcpkg at the GitHub Packages NuGet feed (readwrite): each package is
+      # looked up before building and uploaded right after it builds, so the feed
+      # self-seeds and timed-out runs still persist completed packages. x-gha kept
+      # as a secondary read/write source.
+      - name: Configure vcpkg binary caches
+        shell: pwsh
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          $nuget = & "$env:VCPKG_ROOT\vcpkg.exe" fetch nuget | Select-Object -Last 1
+          & $nuget sources add -Source "$env:NUGET_FEED" -Name github `
+            -UserName "${{ github.repository_owner }}" -Password $env:GH_TOKEN `
+            -StorePasswordInClearText -NonInteractive
+          & $nuget setapikey $env:GH_TOKEN -Source "$env:NUGET_FEED" -NonInteractive
+          "VCPKG_BINARY_SOURCES=clear;nuget,$env:NUGET_FEED,readwrite;x-gha,readwrite" `
+            | Out-File -FilePath $env:GITHUB_ENV -Append
+
+      - name: vcpkg install (manifest)
+        shell: pwsh
+        timeout-minutes: 180
+        run: |
+          & "$env:VCPKG_ROOT\vcpkg.exe" install --triplet $env:GINEXT_TRIPLET `
+            --x-feature=gtk --x-feature=gstreamer `
+            --x-install-root "$env:VCPKG_INSTALLED_DIR"
+
+      - name: Setup build venv
+        shell: pwsh
+        # GINEXT_BASE_PYTHON is set by the python.org install step.
+        run: '& tools\win\setup.ps1'
+
+      - name: Build ginext (+ gi test typelibs)
+        shell: pwsh
+        # Call directly (not `powershell -File`), so the [switch] binds the
+        # boolean $true instead of the literal string. -WithGiTests builds the
+        # GIMarshallingTests/Regress/Utility/GoiBench typelibs (via a cp312
+        # scanner venv) so the full core suite can run.
+        run: '& tools\win\build.ps1 -WithGiTests:$true'
+
+      - name: Upload meson logs on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: meson-logs-${{ matrix.name }}
+          path: |
+            build/**/meson-logs/meson-log.txt
+            build/**/build.ninja
+            build/**/compile_commands.json
+          if-no-files-found: warn
+
+      # Core suite + the package suites (gio/gtk/gst). The glib-gir overlay
+      # supplies GIRepository-3.0 + the Win32 platform typelibs, the build step
+      # generated the gi test typelibs, the gtk/gstreamer introspection overlays
+      # supply the Gtk/Gdk/Gsk/Gst typelibs, and run_tests sets
+      # GINEXT_OVERLAY_PATH so the sub-package overlays apply. gtk runs in fixed
+      # order (-p no:randomly) per the known cross-platform random-order crash.
+      - name: Run core + gio + gtk + gst suites
+        shell: pwsh
+        run: |
+          . tools\win\build-env.ps1
+          $arch = $env:GINEXT_TRIPLET -replace '-windows$',''
+          & ".venv-win-$arch\Scripts\python.exe" tools\win\run_tests.py `
+            src/ginext/tests/ packages/ginext-gio/tests/gio `
+            packages/ginext-gtk/tests/gtk4 packages/ginext-gst/tests/gst `
+            -q -p no:randomly --continue-on-collection-errors

ginext_core-0.8.1/.github/workflows/ci.yml

@@ -0,0 +1,220 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# Mirror GitLab's `interruptible: true` — cancel superseded runs on the same ref.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+# Default token perms for all jobs: read code + pull the CI image from GHCR.
+# The image job alone elevates to packages: write to push.
+permissions:
+  contents: read
+  packages: read
+
+# Run the JS-based actions (checkout/cache/upload-artifact/login) on Node 24; Node 20
+# is deprecated and removed from runners in Sep 2026.
+env:
+  IMAGE: ghcr.io/jdahlin/ginext-ci
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
+jobs:
+  # Build the CI image from ci/Dockerfile and push it to GHCR — but ONLY when the
+  # Dockerfile actually changes. The image is tagged by a hash of ci/Dockerfile,
+  # so an unchanged Dockerfile resolves to an existing tag and the build is
+  # skipped; the test/typecheck jobs just pull it (mirrors GitLab's prebuilt
+  # CI_IMAGE). Requires the repo's Actions token to have packages: write
+  # (Settings → Actions → General → Workflow permissions → Read and write).
+  image:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    outputs:
+      ref: ${{ steps.tag.outputs.ref }}
+    steps:
+      - uses: actions/checkout@v4
+      - id: tag
+        run: echo "ref=${IMAGE}:$(sha256sum ci/Dockerfile | cut -c1-16)" >> "$GITHUB_OUTPUT"
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Build & push image only if this Dockerfile hash isn't already published
+        run: |
+          if docker manifest inspect "${{ steps.tag.outputs.ref }}" >/dev/null 2>&1; then
+            echo "Image ${{ steps.tag.outputs.ref }} already exists — reusing, no rebuild."
+          else
+            echo "ci/Dockerfile changed — building ${{ steps.tag.outputs.ref }}"
+            docker build -t "${{ steps.tag.outputs.ref }}" -f ci/Dockerfile ci
+            docker push "${{ steps.tag.outputs.ref }}"
+          fi
+
+  # GitLab stages `test` + `extended`: the pytest jobs. Each writes JUnit XML.
+  test:
+    needs: image
+    runs-on: ubuntu-latest
+    container:
+      image: ${{ needs.image.outputs.ref }}
+      credentials:
+        username: ${{ github.actor }}
+        password: ${{ secrets.GITHUB_TOKEN }}
+    strategy:
+      fail-fast: false
+      matrix:
+        target: [test, test-debug, test-asan, test-ubsan]
+    name: ${{ matrix.target }}
+    env:
+      UV_CACHE_DIR: ${{ github.workspace }}/.cache/uv
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/cache@v4
+        with:
+          path: .cache/uv
+          # Per-job key so the parallel jobs don't race to save the same cache
+          # ("another job may be creating this cache"); restore-keys still lets a
+          # cold job seed from any sibling's cache.
+          key: uv-${{ matrix.target }}-${{ hashFiles('uv.lock') }}
+          restore-keys: |
+            uv-${{ matrix.target }}-
+            uv-
+      - name: Configure pytest workers
+        # GitLab pinned PYTEST_WORKERS=8 (its runner misreported CPUs); GitHub
+        # runners report correctly, so derive it from the host.
+        run: echo "PYTEST_WORKERS=$(nproc)" >> "$GITHUB_ENV"
+      - name: make ${{ matrix.target }}
+        run: make ${{ matrix.target }} PYTEST_JUNIT_DIR="reports/junit/${{ matrix.target }}"
+      # Render a pass/fail table on the run summary page from the JUnit XML.
+      - name: Test summary
+        if: always()
+        continue-on-error: true
+        shell: bash
+        env:
+          LABEL: ${{ matrix.target }}
+        run: |
+          python3 - "$LABEL" <<'PY' >> "$GITHUB_STEP_SUMMARY"
+          import sys, glob, xml.etree.ElementTree as ET
+          label = sys.argv[1]
+          t = f = e = s = 0
+          files = glob.glob("reports/junit/**/*.xml", recursive=True)
+          for p in files:
+              try:
+                  root = ET.parse(p).getroot()
+              except ET.ParseError:
+                  continue
+              for ts in root.iter("testsuite"):
+                  t += int(ts.get("tests") or 0)
+                  f += int(ts.get("failures") or 0)
+                  e += int(ts.get("errors") or 0)
+                  s += int(ts.get("skipped") or 0)
+          passed = t - f - e - s
+          mark = "✅" if (files and f == 0 and e == 0) else "❌"
+          if not files:
+              print(f"### {mark} {label}\n\n_no test report — failed before tests ran_\n")
+          else:
+              print(f"### {mark} {label}\n")
+              print("| passed | failed | errors | skipped | total |")
+              print("|---:|---:|---:|---:|---:|")
+              print(f"| **{passed}** | {f} | {e} | {s} | {t} |\n")
+          PY
+      - name: Upload JUnit reports
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: junit-${{ matrix.target }}
+          path: reports/junit/
+          if-no-files-found: ignore
+
+  # GitLab `typecheck` job: separate caches (mypy + generated stubs), no JUnit.
+  typecheck:
+    needs: image
+    runs-on: ubuntu-latest
+    container:
+      image: ${{ needs.image.outputs.ref }}
+      credentials:
+        username: ${{ github.actor }}
+        password: ${{ secrets.GITHUB_TOKEN }}
+    env:
+      UV_CACHE_DIR: ${{ github.workspace }}/.cache/uv
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/cache@v4
+        with:
+          path: .cache/uv
+          key: uv-typecheck-${{ hashFiles('uv.lock') }}
+          restore-keys: |
+            uv-typecheck-
+            uv-
+      # mypy incremental cache (validated by content hash; run-mypy.sh wipes a
+      # poisoned cache and retries, so cross-commit reuse is safe).
+      - uses: actions/cache@v4
+        with:
+          path: |
+            .mypy_cache
+            examples/commander/.mypy_cache
+          key: mypy-${{ github.ref_name }}
+          restore-keys: mypy-
+      # Generated .pyi stubs + content stamp; a valid stamp lets `make stubs`
+      # skip GIR-parsing regeneration.
+      - uses: actions/cache@v4
+        with:
+          path: |
+            packages/ginext-stubs/ginext-stubs
+            packages/ginext-stubs/.stub-generated.stamp
+          key: stubs-${{ github.ref_name }}
+          restore-keys: stubs-
+      - run: make typecheck
+
+  # Aggregate the JUnit artifacts into a "Tests" check run so the pass/fail
+  # counts show in the PR's checks list (no third-party action).
+  test-results:
+    needs: test
+    if: ${{ always() }}
+    runs-on: ubuntu-latest
+    permissions:
+      checks: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: junit-*
+          path: junit
+      - name: Publish Tests check run
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+          SHA: ${{ github.event.pull_request.head.sha || github.sha }}
+        run: |
+          python3 - "$SHA" > body.json <<'PY'
+          import sys, glob, os, json, xml.etree.ElementTree as ET
+          sha = sys.argv[1]
+          rows = []; TP = TF = TS = TT = 0
+          for d in sorted(glob.glob("junit/junit-*")):
+              name = os.path.basename(d).replace("junit-", "")
+              t = f = e = s = 0
+              for p in glob.glob(d + "/**/*.xml", recursive=True):
+                  try:
+                      root = ET.parse(p).getroot()
+                  except ET.ParseError:
+                      continue
+                  for ts in root.iter("testsuite"):
+                      t += int(ts.get("tests") or 0); f += int(ts.get("failures") or 0)
+                      e += int(ts.get("errors") or 0); s += int(ts.get("skipped") or 0)
+              passed = t - f - e - s
+              mark = "✅" if (t and f == 0 and e == 0) else "❌"
+              rows.append(f"| {mark} {name} | {passed} | {f + e} | {s} | {t} |")
+              TP += passed; TF += f + e; TS += s; TT += t
+          title = f"{TP} passed, {TF} failed, {TS} skipped"
+          summary = ("| job | passed | failed | skipped | total |\n"
+                     "|---|---:|---:|---:|---:|\n" + "\n".join(rows))
+          conclusion = "success" if (TT and TF == 0) else ("failure" if TT else "neutral")
+          json.dump({"name": "Tests", "head_sha": sha, "status": "completed",
+                     "conclusion": conclusion,
+                     "output": {"title": title, "summary": summary}}, sys.stdout)
+          PY
+          gh api -X POST "repos/$REPO/check-runs" --input body.json >/dev/null
+          echo "Published Tests check for $SHA"

ginext_core-0.8.1/.github/workflows/commit-policy.yml

@@ -0,0 +1,33 @@
+name: Commit policy
+
+# Pre-merge gate: reject any PR whose commits carry an AI attribution trailer.
+# The repo also has a local pre-commit commit-msg hook for this, but local hooks
+# don't run on squash-merge or in CI, so this is the enforced check.
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
+jobs:
+  no-ai-coauthor:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Forbid AI Co-Authored-By trailer
+        env:
+          BASE: ${{ github.event.pull_request.base.sha }}
+          HEAD: ${{ github.event.pull_request.head.sha }}
+        run: |
+          if git log --format='%B' "$BASE..$HEAD" \
+               | grep -inE '^[[:space:]]*Co-Authored-By:.*(claude|anthropic|gpt|copilot|openai)'; then
+            echo "::error::A commit in this PR has a forbidden AI Co-Authored-By trailer. Remove it (e.g. git rebase) before merging."
+            exit 1
+          fi
+          echo "OK: no AI Co-Authored-By trailers in this PR's commits."

ginext_core-0.8.1/.github/workflows/docs.yml

@@ -0,0 +1,96 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+# Only one Pages deployment at a time; let an in-progress run finish.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+  packages: read
+
+# Run the JS-based actions (checkout/cache/upload-pages-artifact) on Node 24; Node 20
+# is deprecated and removed from runners in Sep 2026.
+env:
+  IMAGE: ghcr.io/jdahlin/ginext-ci
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
+jobs:
+  # Resolve (and build-if-missing) the CI image, which ships the GIR dev
+  # packages + uv the generator needs. Mirrors ci.yml's image job — tagged by a
+  # hash of ci/Dockerfile, so an unchanged Dockerfile just reuses the image.
+  image:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    outputs:
+      ref: ${{ steps.tag.outputs.ref }}
+    steps:
+      - uses: actions/checkout@v4
+      - id: tag
+        run: echo "ref=${IMAGE}:$(sha256sum ci/Dockerfile | cut -c1-16)" >> "$GITHUB_OUTPUT"
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Build & push image only if this Dockerfile hash isn't already published
+        run: |
+          if docker manifest inspect "${{ steps.tag.outputs.ref }}" >/dev/null 2>&1; then
+            echo "Image ${{ steps.tag.outputs.ref }} already exists — reusing."
+          else
+            echo "ci/Dockerfile changed — building ${{ steps.tag.outputs.ref }}"
+            docker build -t "${{ steps.tag.outputs.ref }}" -f ci/Dockerfile ci
+            docker push "${{ steps.tag.outputs.ref }}"
+          fi
+
+  # Generate the API reference from the system GIRs, then build the mkdocs site.
+  build:
+    needs: image
+    runs-on: ubuntu-latest
+    container:
+      image: ${{ needs.image.outputs.ref }}
+      credentials:
+        username: ${{ github.actor }}
+        password: ${{ secrets.GITHUB_TOKEN }}
+    env:
+      UV_CACHE_DIR: ${{ github.workspace }}/.cache/uv
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/cache@v4
+        with:
+          path: .cache/uv
+          key: uv-docs-${{ hashFiles('uv.lock', 'packages/ginext-stubgen/pyproject.toml') }}
+          restore-keys: |
+            uv-docs-
+            uv-
+      - name: Generate API reference (GLib, GObject, Gio, Gdk, Gtk, Pango)
+        run: make api-docs
+      - name: Build mkdocs site
+        run: |
+          uv run --no-project \
+            --with mkdocs-material \
+            --with mkdocs-literate-nav \
+            mkdocs build --strict --site-dir site
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4