@@ -0,0 +1,86 @@
+---
+description: Re-run this project's patch/build/test pipeline against a new sharp/sharp-libvips release, with judgment at each step rather than blind reapplication.
+argument-hint: <sharp-version> <sharp-libvips-version>
+---
+
+# Rebuild for a new `sharp`/`sharp-libvips` version
+
+Arguments: `$ARGUMENTS` — expected as `<sharp-version> <sharp-libvips-version>`, e.g. `0.36.0 1.4.0`. If either is missing, ask for it before doing anything else.
+
+This is **not** a script to run to completion unattended — it's a guided process with real judgment calls at several points. Read all of this before starting, and stop to report back (rather than guessing and continuing) at any point marked **STOP**. The design rationale for why this is a command and not a shell script is in `README.md`'s "Updating to a new `sharp` release" section — read that first if this is the first time running this command.
+
+## Step 0: Orient
+
+- Read `patches/wrapper-symbols.json` — the current source of truth for which symbols are wrapped and why.
+- Read `README.md`'s "Engineering notes" section (especially "How the fix works" and "The wrapper symbol set") for the full context of what was done for the *current* target version and why.
+- Confirm the new target versions are real releases: check `https://github.com/lovell/sharp/releases` and `https://github.com/lovell/sharp-libvips/releases` (or the npm registry) for the tags given in `$ARGUMENTS`.
+
+## Step 1: Check whether the bug still reproduces at all — before assuming any patches are needed
+
+Do not skip this by assuming "same bug, same fix." Upstream could have partially or fully fixed this independently since the current target version.
+
+1. Update the submodule pins: `git -C vendor/sharp-libvips fetch --tags && git -C vendor/sharp-libvips checkout v<sharp-libvips-version>`, same for `vendor/sharp`.
+2. Build **unpatched** — do *not* run `scripts/apply-patches.sh` yet. Just run `sharp-libvips`'s own `build.sh linux-x64` and `sharp`'s own default build (against the npm `@img/sharp-libvips-linux-x64` package, not `SHARP_FORCE_GLOBAL_LIBVIPS`) to get a genuinely stock addon.
+3. Run `test/electron-crash-repro.js` (with `SHARP_MODULE_PATH` pointed at this stock, unpatched `vendor/sharp`) via `ELECTRON_RUN_AS_NODE=1 electron ...`.
+4. **STOP and report** if it does *not* crash. Investigate why before proceeding — check `sharp-libvips`'s `build/posix.sh` for whether they broadened their own `vips.map` fix, check the [Electron tracking issue](https://github.com/electron/electron/issues/46323) for whether it's been closed, check whether `libvips`'s `VImage8.h` still has the same inline-header pattern. The patches in this repo might need to shrink, change shape entirely, or (best case) not be needed at all for this version. Do not proceed with the rest of this process on autopilot if this happens — the right next step depends entirely on *why* it's fixed.
+
+If it still crashes (expected, most likely outcome): continue to Step 2.
+
+## Step 2: Attempt to apply the existing patches
+
+1. Run `scripts/apply-patches.sh`.
+2. **Clean apply**: proceed to Step 3.
+3. **Apply failure**: diagnose *why*, don't just retry blindly.
+   - Pull up the specific hunk that failed. Diff the relevant upstream file between the *old* target tag (still readable via `git log`/`git show` in the submodule, or by checking out the previous tag in a scratch clone) and the *new* tag, focused on just the lines the patch touches.
+   - Judge: is this a trivial context-line drift (safe to regenerate the patch mechanically — e.g. `git apply --recount` or a manual small edit to the patch file, then re-verify with `git apply --check`) or a structural change (e.g. `VImage8.h`'s `VObject` class reshaped, `build/posix.sh`'s libvips-build block reorganized, `cplusplus/meson.build`'s `library('vips-cpp', ...)` sources list restructured)?
+   - For structural changes: **STOP and report** what changed and what you think the patch needs to become, before actually rewriting it. This is exactly the kind of judgment call that shouldn't happen silently.
+
+## Step 3: Re-check the wrapper symbol scope
+
+Do not assume the symbol set in `patches/wrapper-symbols.json` is still complete or still necessary.
+
+1. Re-run the exhaustive grep for bare `glib`/`gobject` calls across *every* file in the new `vendor/sharp/src/` (not just the files that had them last time):
+   ```bash
+   for f in $(git -C vendor/sharp ls-tree -r --name-only HEAD -- src/ | grep -E '\.(cc|h)$'); do
+     git -C vendor/sharp show HEAD:"$f" | grep -noE '\bg_[a-z0-9_]+\s*\(' | while read -r m; do echo "$f: $m"; done
+   done | sort -u
+   ```
+2. Also re-check whether `libvips`'s other public C++ headers (`VError8.h`, `VInterpolate8.h`, `VRegion8.h`, `VConnection8.h` — see `patches/wrapper-symbols.json`'s `headersChecked` for what was clean last time) have picked up the same inline-header pattern `VImage8.h` has.
+3. Diff both results against `patches/wrapper-symbols.json`. Report: any symbols now called that aren't wrapped (add them — see `extra/glib_wrapper.c`/`.h` in `vendor/sharp-libvips`, following the existing pattern, remembering the `__attribute__((visibility("default")))` requirement), and any wrapped symbols no longer called anywhere (safe to leave as-is; removing them is low priority and not required).
+4. Update `patches/wrapper-symbols.json` and the patch files to match — including the manifest's `targetVersions` field, which must always name the exact versions the manifest was verified against — then re-verify `git apply --check` on both.
+
+## Step 4: Rebuild both phases
+
+```bash
+npm run build:libvips
+npm run build:sharp
+```
+
+## Step 5: Run both gates
+
+```bash
+npm run test:gates
+```
+
+**If either gate fails**, follow the same loop this project's own development actually used — this is expected to happen at least once, not a sign something is broken:
+
+1. Identify the specific symbol from the failure. Gate 1 (sharp's test suite) failures that mention `undefined symbol: <name>` name it directly, as does gate 2's failure mode if it manifests the same way; a genuine segfault in gate 2 means a wrapped symbol still isn't taking effect somewhere (re-check `objdump -T` on the rebuilt `libvips-cpp.so` for that symbol in both directions before assuming it's a *new* symbol).
+2. Add it to the wrapper set (`extra/glib_wrapper.c`/`.h`, `patches/wrapper-symbols.json`, and the relevant call-site patch), regenerate both patch files, rebuild, re-run gates.
+3. **Bound this to 3 automatic iterations.** If gates still aren't green after 3 rounds, **STOP and report** a clear summary of what's still failing, rather than continuing to loop. Something more fundamental is likely different about this version.
+
+## Step 6: Re-verify
+
+1. `objdump -T` on the rebuilt `libvips-cpp.so`, checking **every** symbol in `patches/wrapper-symbols.json` in both directions (bare name absent, `vips_<name>` present as defined + global).
+2. `readelf -d` on the rebuilt `sharp.node` addon — confirm `DT_RPATH` (not `DT_RUNPATH`) once repackaged (see Step 7).
+3. `npm run package`.
+
+## Step 7: Prepare (but do not execute) the release
+
+```bash
+npm run release <new-version>-electron.0
+```
+
+This runs the full pipeline again, bumps `package/package.json`'s version, and prints the remaining manual steps. **Do not run `npm publish` yourself, and do not push/tag without explicit confirmation.** Instead:
+
+1. Write a `CHANGELOG.md` entry summarizing: the new upstream version, any patch adjustments made and why (link back to what Step 2 found), any wrapper-symbol changes (link back to what Step 3 found), and confirmation that both gates pass.
+2. **STOP and report** a summary to the user: what changed, what (if anything) needed judgment calls along the way, and that this is ready for their review before they decide to commit/tag/publish. Publishing is always an explicit, separate, human-confirmed action — never something this command does on its own, no matter how cleanly everything above went.
@@ -0,0 +1,80 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  # Runs the full Linux pipeline (patches -> Phase A -> Phase B -> both test
+  # gates -> local packaging) on every push/PR. This is what actually keeps
+  # README.md's claims honest going forward, rather than relying on
+  # occasional manual runs.
+  linux-build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          submodules: recursive
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+
+      - run: npm install
+
+      - name: Full build + both test gates + local packaging
+        run: npm run build
+
+      - uses: actions/upload-artifact@v7
+        if: always()
+        with:
+          name: package-linux-x64
+          path: package/linux-x64
+          if-no-files-found: ignore
+          retention-days: 7
+
+  # Validates the non-Linux fallback (re-exporting real `sharp` unmodified)
+  # for real, on real macOS/Windows runners — this path is otherwise
+  # unverifiable on the maintainer's Linux-only dev machine. Deliberately
+  # independent of the linux-build job above: doesn't need the Phase A/B
+  # binaries at all, since the fallback branch never touches them.
+  cross-platform-fallback:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [macos-13, macos-14, windows-2022]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+
+      # Installs package/package.json's own "sharp" dependency (the real,
+      # official npm package) — this is the one npm quirk documented in
+      # README.md: an out-of-tree file: dependency doesn't get its
+      # own dependencies installed automatically, so this has to happen
+      # explicitly rather than relying on some outer npm install to do it.
+      - name: Install package/'s own dependencies (real sharp, for the fallback)
+        working-directory: package
+        run: npm install --omit=dev
+
+      - name: Confirm the non-Linux fallback resolves to real sharp and works
+        shell: bash
+        run: |
+          node -e "
+            const sharp = require('./package/index.js');
+            (async () => {
+              console.log('platform:', process.platform, process.arch);
+              console.log('sharp version:', sharp.versions.sharp);
+              const raw = Buffer.alloc(64 * 64 * 3, 128);
+              const jpeg = await sharp(raw, { raw: { width: 64, height: 64, channels: 3 } }).jpeg().toBuffer();
+              console.log('encode ok:', jpeg.length, 'bytes');
+              const meta = await sharp(jpeg).metadata();
+              console.log('metadata ok:', meta.width, 'x', meta.height);
+              const resized = await sharp(jpeg).resize(32, 32).toBuffer();
+              console.log('resize ok:', resized.length, 'bytes');
+              console.log('PASS');
+            })().catch((err) => { console.error('FAIL', err); process.exit(1); });
+          "
@@ -0,0 +1,5 @@
+node_modules/
+dist/
+package/linux-x64/
+# generated at package time from the root README.md (npm shows the package's own README)
+package/README.md
@@ -0,0 +1,6 @@
+[submodule "vendor/sharp-libvips"]
+	path = vendor/sharp-libvips
+	url = https://github.com/lovell/sharp-libvips.git
+[submodule "vendor/sharp"]
+	path = vendor/sharp
+	url = https://github.com/lovell/sharp.git
@@ -0,0 +1,15 @@
+# Changelog
+
+## Unreleased
+
+First release, targeting `sharp` `0.35.3` / `sharp-libvips` `1.3.2`.
+
+- Rebuilds `libvips-cpp.so` with the full `glib`/`gobject` symbol surface hidden (upstream hides only `g_param_spec_types`), re-exporting the seven symbols `sharp`'s native addon actually needs under renamed `vips_g_*` wrappers — see `patches/wrapper-symbols.json` for the full list and per-symbol reasoning.
+- Rebuilds `sharp`'s native addon (and, transitively, `libvips`'s inline `VImage8.h` header) to call those wrappers instead of the now-hidden bare `glib` functions. This eliminates the symbol collision with Electron's own `glib` that segfaults image decoding on Linux ([electron/electron#46323](https://github.com/electron/electron/issues/46323)).
+- The compiled addon resolves its co-located `libvips-cpp.so` via old-style `DT_RPATH` (`$ORIGIN`), so it deterministically wins over any other copy reachable through the consumer's `LD_LIBRARY_PATH` or `node_modules`.
+- Cross-platform dispatch: `linux-x64` uses the patched build; any other Linux architecture throws a clear error at load time rather than silently using an unpatched build; macOS/Windows re-export the real, unmodified `sharp`.
+- Verified against `sharp`'s own upstream test suite (1804/1811 passing; the one failure is a pre-existing, unrelated Node ESM/CJS interop quirk that fails identically against stock `sharp`) and a dedicated Electron crash-regression test, plus end-to-end in a real consuming Electron application.
+- The full build pipeline is scripted and Docker-only (`npm run build`), with CI covering both the Linux pipeline and the macOS/Windows fallback path.
+- Ships TypeScript types (`package/index.d.ts`, forwarding to `sharp`'s own declarations) so the `overrides` install keeps full type information on both the patched and fallback paths.
+
+Known gaps: CI has not yet produced a green run on real macOS/Windows runners, and `linux-arm64` has no patched build (it fails loudly rather than silently).