From 85227cfe399df8d1c9bbfc62823d7d814772af98 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 13 Aug 2026 02:38:25 +0000
Subject: [PATCH 1/6] Install global hooks only once per page; refresh stale
 docs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Host may re-execute screen.js on plugin reload, which re-runs this
IIFE. Module state resetting is harmless — it gets rebuilt — but five
hooks installed on shared globals are not module state and accumulated:
window.playSong got wrapped a second time around the already-wrapped
version, so every song load ran the wrapper twice, and the resize,
beforeunload and document pointerdown listeners each fired twice per
event.

Gate all five on a window.__feedBackSplitscreenHooksInstalled flag. It
lives on window precisely because it has to outlive the re-execution
that resets everything else; a second run leaves the first run's hooks,
which are still bound to live closures, in place. Same shape as
sectionmap's __slopsmithSectionMapHooksInstalled guard.

The two wrappers guard the assignment rather than the definition, so the
83-line playSong body stays at its current indentation and the diff
shows the actual change.

Declare plugin-runtime-idempotent.v1 in the manifest now that the plugin
satisfies it. Add a regression test that loads screen.js twice against
one shared window: it counts 2/2/2 listener registrations before this
change and 1/1/1 after.

Docs: the README clone URL and CLAUDE.md's PR conventions both pointed at
a personal fork rather than get-flashbacks. CLAUDE.md also documented the
renderer lookup as the pre-rename slopsmithViz_<id> global; the code has
resolved feedBackViz_ first for a while via vizFactory().

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B4NYejYW2dW7dNtYh7srDy
---
 CLAUDE.md            | 20 +++++++++------
 README.md            |  2 +-
 plugin.json          |  3 ++-
 screen.js            | 61 ++++++++++++++++++++++++++++++++++++--------
 tests/screen.test.js | 51 ++++++++++++++++++++++++++++++++++++
 5 files changed, 116 insertions(+), 21 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 50cbd83..dee122a 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -50,7 +50,7 @@ screen.js
 | `wrap` | element\|null | The `#splitscreen-wrap` div, or null when inactive |
 | `currentFilename` | string\|null | The filename passed to the last `playSong` call |
 | `arrangements` | array | Arrangement list from the last `song_info` WebSocket message |
-| `vizPlugins` | array | `{id, name, …}` entries from `/api/plugins` where `type==='visualization'`. Populated once on page load via `fetchVizPlugins()`. Factory availability (`slopsmithViz_<id>`) is checked lazily in `populateSelect()`, not at fetch time. |
+| `vizPlugins` | array | `{id, name, …}` entries from `/api/plugins` where `type==='visualization'`. Populated once on page load via `fetchVizPlugins()`. Factory availability (`feedBackViz_<id>`, legacy `slopsmithViz_<id>`) is checked lazily in `populateSelect()`, not at fetch time. |
 | `syncInterval` | id\|null | The `setInterval` handle for the time sync loop |
 | `layoutBtn` | element\|null | The layout `<select>` injected into `#player-controls` |
 | `hideBtn` | element\|null | The `▾ Bar` button injected into `#player-controls` |
@@ -182,7 +182,11 @@ Each panel is always in exactly one of these modes. Flags are mutually exclusive
 
 ### Viz renderer (`vizMode = pluginId string`)
 - Highway NOT stopped — it stays alive with its WebSocket and rAF loop
-- `panel.hw.setRenderer(window['slopsmithViz_' + pluginId]())` installs the renderer
+- `panel.hw.setRenderer(vizFactory(pluginId)())` installs the renderer. The factory global
+  was renamed `slopsmithViz_<id>` -> `feedBackViz_<id>` in the feedBack rename, so
+  `vizFactory(id)` walks `VIZ_FACTORY_PREFIXES = ['feedBackViz_', 'slopsmithViz_']` in that
+  order and returns the first hit — current and legacy viz plugins both resolve.
+  `hasVizFactory(id)` is the boolean form used for capability checks.
 - `canvas` stays visible (renderer draws to it)
 - Tab button hidden. A **"3D ⚙"** button (`vizSettingsBtn`) is shown if the viz plugin has per-panel controls (see "Per-panel viz controls" below); it opens `vizPopover` with those controls scoped to this panel. Other viz config still lives in the plugin's global settings UI.
 - To exit: `recreatePanelHighway(panel)` discards the viz highway and installs a fresh 2D highway; `_hideVizControls(panel)` hides the button/popover
@@ -198,10 +202,10 @@ Each panel is always in exactly one of these modes. Flags are mutually exclusive
 
 When a panel is in viz mode, splitscreen shows a `vizSettingsBtn` ("3D ⚙") that opens `vizPopover` — a small popover with controls that override that viz plugin's settings **for this panel only**. The controls are generated from a descriptor, so adding a new per-panel option doesn't require touching the popover code.
 
-- **Descriptor lookup** — `getPanelControlsFor(pluginId)` returns `null` for any plugin other than `highway_3d` (v1 — `_vizPanelGet`/`_vizPanelSet` are hard-wired to highway_3d's storage scheme + `window.h3dBgSet*` setters); for `highway_3d` it returns `window.slopsmithViz_highway_3d.panelControls` if exposed, else the built-in `VIZ_PANEL_CONTROLS.highway_3d` (`palette`, `cameraSmoothing`, `cameraLockLow`, `cameraLockZoom`). The viz-plugin-published list wins, so the plugin can keep the *list of controls* current without splitscreen edits — generalizing to other plugins later means extending the descriptor with per-plugin storage/setter info (or read/write fns) and dropping the gate. Each descriptor entry: `{ key, label, type:'toggle'|'range'|'select', default, min?, max?, step?, options? }` where `options` for `select` is `[{id,label}]`; for `range`, `min`/`max` default to `0`/`1` and `step` to `0.05` when omitted (`_ctlRange`). A plugin-published **empty array** is a valid override — it opts out of per-panel controls (`_showVizControls` hides the button on an empty list).
+- **Descriptor lookup** — `getPanelControlsFor(pluginId)` returns `null` for any plugin other than `highway_3d` (v1 — `_vizPanelGet`/`_vizPanelSet` are hard-wired to highway_3d's storage scheme + `window.h3dBgSet*` setters); for `highway_3d` it returns `vizFactory('highway_3d').panelControls` if exposed, else the built-in `VIZ_PANEL_CONTROLS.highway_3d` (`palette`, `cameraSmoothing`, `cameraLockLow`, `cameraLockZoom`). The viz-plugin-published list wins, so the plugin can keep the *list of controls* current without splitscreen edits — generalizing to other plugins later means extending the descriptor with per-plugin storage/setter info (or read/write fns) and dropping the gate. Each descriptor entry: `{ key, label, type:'toggle'|'range'|'select', default, min?, max?, step?, options? }` where `options` for `select` is `[{id,label}]`; for `range`, `min`/`max` default to `0`/`1` and `step` to `0.05` when omitted (`_ctlRange`). A plugin-published **empty array** is a valid override — it opts out of per-panel controls (`_showVizControls` hides the button on an empty list).
 - **Storage** — per-panel values are written to the viz plugin's own per-panel keys, **not** `splitscreenPanelPrefs`. For `highway_3d`: `localStorage['h3d_bg_panel<N>_<key>']` (read by the plugin's `_bgReadSetting`, falling back to the global `h3d_bg_<key>`). `_vizPanelGet` / `_vizPanelSet` implement this; `_vizPanelSet` also re-fires `window.h3dBgSet<Key>(<currentGlobal>)` so the plugin's change event runs (instant rebuild for settings like `palette`; the 3D renderer also re-reads everything per frame, so even without the re-fire the panel key takes effect next frame). On reload, `enterVizMode` → `_showVizControls` → `buildVizPopover` re-reads the keys, so the popover reflects the saved per-panel state. Stale `h3d_bg_panel<N>_*` keys from a panel that later stopped running 3D are inert (the plugin only reads `panel<N>` keys for a live panel N) — they're left in place, same as the original palette behavior.
 - **Lifecycle** — `_showVizControls(panel, pluginId)` (builds the popover + shows the button) is called at the end of `enterVizMode` and the in-place viz-switch branch of `panel.select.onchange`. `_hideVizControls(panel)` (hides + empties) is called from `exitVizMode`, `enterLyricsMode`, `enterJumpingTabMode`. `togglePanelBar` closes the popover when hiding the bar (it's anchored to the bar height). A document-level capture `pointerdown` listener (`_closeAllVizPopovers`) closes any open popover on a click outside `.ss-viz-popover` / `[data-ss-viz-btn]`. The `vizSettingsBtn` click handler **rebuilds the popover from current localStorage every time it opens** — `_closeAllVizPopovers` / the outside-click handler only hide (don't empty), so the rebuild-on-open is the single point that guarantees the controls reflect any `h3d_bg_*` changes (e.g. via the plugin's own settings UI) made while the popover was closed.
-- **Note for new viz plugins** that want per-panel controls: expose `window.slopsmithViz_<id>.panelControls = [...]` and use the `*_panel<N>_*` localStorage convention the plugin already reads (or, if it uses a different scheme, the descriptor would need to carry `read`/`write` fns — not implemented in v1; only `highway_3d` is wired).
+- **Note for new viz plugins** that want per-panel controls: expose `window.feedBackViz_<id>.panelControls = [...]` and use the `*_panel<N>_*` localStorage convention the plugin already reads (or, if it uses a different scheme, the descriptor would need to carry `read`/`write` fns — not implemented in v1; only `highway_3d` is wired).
 
 ## `sizeCanvases()` — call it whenever layout space changes
 
@@ -323,7 +327,7 @@ The plugin capability-checks all external factories at runtime and gracefully di
 | Factory | Checked via | Used in |
 |---|---|---|
 | `window.createJumpingTabPane` | `typeof === 'function'` | `populateSelect()`, `enterJumpingTabMode()` |
-| `window['slopsmithViz_' + id]` | resolved via `fetchVizPlugins()` | `populateSelect()`, `enterVizMode()` — auto-discovered for any `type=visualization` plugin |
+| `window['feedBackViz_' + id]` (legacy `slopsmithViz_` fallback) | resolved via `fetchVizPlugins()` | `populateSelect()`, `enterVizMode()` — auto-discovered for any `type=visualization` plugin |
 | `window.createTabView` | `typeof === 'function'` | `initPanel()` (wires tabBtn) |
 | `window.createNoteDetector` | `typeof === 'function'` | `initPanel()` (wires detectBtn/channelBtn) |
 
@@ -355,7 +359,7 @@ Follow the lyrics/jumping-tab pattern:
 
 ## Git and PR conventions
 
-- All work goes on feature branches off `main` in this repo (`carochacs/feedBack-plugin-splitscreen`)
-- PRs target `carochacs/feedBack-plugin-splitscreen`
-- Use `gh pr create --repo carochacs/feedBack-plugin-splitscreen --base main --head carochacs:<branch>` from inside the plugin directory
+- All work goes on feature branches off `main` in this repo (`get-flashbacks/feedBack-plugin-splitscreen`)
+- PRs target `get-flashbacks/feedBack-plugin-splitscreen`
+- Use `gh pr create --repo get-flashbacks/feedBack-plugin-splitscreen --base main --head <branch>` from inside the plugin directory
 - Always branch from `origin/main` — there is no separate upstream remote
diff --git a/README.md b/README.md
index 8f9a91a..789fc7b 100644
--- a/README.md
+++ b/README.md
@@ -23,7 +23,7 @@ A plugin for [feedBack](https://github.com/got-feedback/feedBack) that shows 2
 
 ```bash
 cd /path/to/feedBack/plugins
-git clone https://github.com/carochacs/feedBack-plugin-splitscreen.git splitscreen
+git clone https://github.com/get-flashbacks/feedBack-plugin-splitscreen.git splitscreen
 docker compose restart
 ```
 
diff --git a/plugin.json b/plugin.json
index c626059..e67a97c 100644
--- a/plugin.json
+++ b/plugin.json
@@ -1,8 +1,9 @@
 {
   "id": "splitscreen",
   "name": "Split Screen",
-  "version": "1.14.1",
+  "version": "1.14.2",
   "private": false,
+  "standards": ["plugin-runtime-idempotent.v1"],
   "settings": {
     "html": "settings.html",
     "category": "graphics"
diff --git a/screen.js b/screen.js
index 4a805b9..0d1452d 100644
--- a/screen.js
+++ b/screen.js
@@ -19,6 +19,29 @@ try {
      *  <audio> element.
      * ====================================================================== */
 
+    // ── Reload idempotency (plugin-runtime-idempotent.v1) ─────────────────
+    // The Host may re-execute screen.js on plugin reload, which re-runs this
+    // whole IIFE. Module state resetting is harmless — it gets rebuilt — but
+    // the hooks we install on shared globals are not module state and would
+    // accumulate: window.playSong would be wrapped a second time around the
+    // already-wrapped version (so every song load runs our wrapper twice),
+    // and the resize / beforeunload / pointerdown listeners would each fire
+    // twice per event.
+    //
+    // The flag lives on `window` precisely because it has to outlive the
+    // re-execution that resets everything else. On a second run we skip
+    // installing hooks and leave the first run's — which are still bound to
+    // a fully live set of closures — in place. Same shape as sectionmap's
+    // __slopsmithSectionMapHooksInstalled guard.
+    //
+    // Node test env: tests/screen.test.js builds a fresh `global.window` per
+    // case, so the flag is always absent there and hooks install every time,
+    // exactly as before.
+    const HOOK_KEY = '__feedBackSplitscreenHooksInstalled';
+    const _hooksAlreadyInstalled =
+        typeof window !== 'undefined' && window[HOOK_KEY] === true;
+    if (typeof window !== 'undefined') window[HOOK_KEY] = true;
+
     const LAYOUTS = {
         'top-bottom':  { panels: 2, style: 'flex-col' },
         'left-right':  { panels: 2, style: 'flex-row' },
@@ -1796,11 +1819,15 @@ try {
         for (const p of panels) if (p.vizPopover) p.vizPopover.style.display = 'none';
     }
     // Close any open viz popover when clicking outside it / its trigger button.
-    document.addEventListener('pointerdown', (e) => {
-        const t = e.target;
-        if (t && typeof t.closest === 'function' && (t.closest('.ss-viz-popover') || t.closest('[data-ss-viz-btn]'))) return;
-        _closeAllVizPopovers();
-    }, true);
+    // Guarded: a reload would otherwise leave two capture listeners closing
+    // popovers on every pointerdown (see HOOK_KEY at the top of the IIFE).
+    if (!_hooksAlreadyInstalled) {
+        document.addEventListener('pointerdown', (e) => {
+            const t = e.target;
+            if (t && typeof t.closest === 'function' && (t.closest('.ss-viz-popover') || t.closest('[data-ss-viz-btn]'))) return;
+            _closeAllVizPopovers();
+        }, true);
+    }
 
     /**
      * ── Mastery slider helpers ──
@@ -4482,15 +4509,17 @@ try {
     // reservation, sliding the wrap (and every panel's bar) under the
     // follower toolbar. Follower mode has its own resize handler in
     // bootFollowerMode that resizes panels without touching the wrap.
-    window.addEventListener('resize', () => {
-        if (active && !FOLLOWER) sizeCanvases();
-    });
+    if (!_hooksAlreadyInstalled) {
+        window.addEventListener('resize', () => {
+            if (active && !FOLLOWER) sizeCanvases();
+        });
+    }
 
     // Tell any popped-out panels the main window is going away so they stop
     // syncing (and stop their highway rAF loops) and show a notice instead of
     // freezing silently. Best-effort — beforeunload BroadcastChannel posts
     // aren't guaranteed to flush; the popup's own state stays the floor.
-    if (!FOLLOWER) {
+    if (!FOLLOWER && !_hooksAlreadyInstalled) {
         window.addEventListener('beforeunload', () => {
             try {
                 const c = _ssChannel();
@@ -4504,8 +4533,13 @@ try {
     }
 
     // ── Hook into playSong ──
+    // The wrapper is always built, but only installed on a first run — see
+    // HOOK_KEY at the top of the IIFE. Guarding the assignment rather than
+    // the definition keeps this readable: a second evaluation would
+    // otherwise wrap the already-wrapped playSong, running everything below
+    // twice per song load.
     const _play = window.playSong;
-    window.playSong = async function (f, a) {
+    const _ssPlaySong = async function (f, a) {
         // Mount the Split button (and its siblings) BEFORE awaiting the
         // upstream chain. Any upstream playSong wrapper that throws (e.g.
         // capo failing in its v3 insertBefore — seen in the wild on the
@@ -4593,11 +4627,16 @@ try {
     // away from the player, but if something tries we don't tear down split
     // (the follower panel IS the player).
     const _show = window.showScreen;
-    window.showScreen = function (id) {
+    const _ssShowScreen = function (id) {
         if (!FOLLOWER && id !== 'player' && active) stopSplitScreen();
         _show(id);
     };
 
+    if (!_hooksAlreadyInstalled) {
+        window.playSong = _ssPlaySong;
+        window.showScreen = _ssShowScreen;
+    }
+
     // ══════════════════════════════════════════════════════════════════════
     //  Follower-mode bootstrap (popup window only)
     //  The actual `if (FOLLOWER) bootFollowerMode();` invocation is at the
diff --git a/tests/screen.test.js b/tests/screen.test.js
index c8725d5..738af99 100644
--- a/tests/screen.test.js
+++ b/tests/screen.test.js
@@ -355,3 +355,54 @@ test('_bestFitLayout picks the smallest layout with room, and caps at six', () =
     assert.equal(_bestFitLayout(6), 'six');
     assert.equal(_bestFitLayout(7), 'six'); // nothing bigger — caller must truncate
 });
+
+// ── Reload idempotency (plugin-runtime-idempotent.v1) ─────────────────────
+// The Host may re-execute screen.js on plugin reload. Module state resetting
+// is fine, but hooks installed on shared globals must not accumulate: before
+// the HOOK_KEY guard, a second evaluation wrapped the already-wrapped
+// playSong and added a second copy of every listener, so each song load ran
+// the wrapper twice and each resize/pointerdown fired twice.
+test('re-evaluating screen.js installs its global hooks exactly once', () => {
+    const counts = { resize: 0, beforeunload: 0, pointerdown: 0 };
+    const location = { search: '', host: 'localhost:8420', protocol: 'http:' };
+
+    // One shared window across both loads — that is what a reload looks like.
+    global.window = {
+        location,
+        addEventListener: (ev) => {
+            if (ev in counts) counts[ev]++;
+        },
+    };
+    global.document = {
+        getElementById: () => null,
+        addEventListener: (ev) => { if (ev in counts) counts[ev]++; },
+        body: { appendChild: () => {} },
+        createElement: () => ({
+            style: {}, classList: { add() {}, remove() {} },
+            addEventListener() {}, appendChild() {}, setAttribute() {},
+        }),
+        readyState: 'loading',
+    };
+    global.localStorage = makeLocalStorage();
+    global.location = location;
+
+    const originalPlaySong = async function original() {};
+    window.playSong = originalPlaySong;
+    window.showScreen = function original() {};
+
+    const file = path.join(__dirname, '..', 'screen.js');
+    const load = () => {
+        delete require.cache[require.resolve(file)];
+        require(file);
+    };
+
+    load();
+    assert.notEqual(window.playSong, originalPlaySong, 'first load should wrap playSong');
+    const afterFirst = { ...counts };
+    const wrappedOnce = window.playSong;
+
+    load();
+
+    assert.deepEqual(counts, afterFirst, 'second evaluation must not re-add listeners');
+    assert.equal(window.playSong, wrappedOnce, 'second evaluation must not re-wrap playSong');
+});

From 83604926d87ab075166018e65f7d8b2d1caab925 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 13 Aug 2026 02:51:15 +0000
Subject: [PATCH 2/6] Add targeted plugin-spec compliance checks
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This repo's ci.yml calls the shared reusable-ci.yml, which runs the test
suites and nothing else. The org's original-repo plugins run their own
custom-checks.yml instead, so enforcement was split down the middle:
forks got tests but no spec checks, originals got spec checks but not
always tests. A cross-repo audit found defects on both sides of that line.

Three targeted jobs rather than the originals' full sixteen —
version-bumped-on-change, changelog-updated, and
idempotent-top-level-guard. These are the ones that map to defects
actually found in these repos: versions and changelogs going stale while
functional source shipped, and screen.js re-executing on reload without a
guard. Jobs self-skip where they do not apply.

The right home for these is got-feedback/.github's reusable-ci.yml, so
every repo picks them up from one reference instead of four copies. The
file says so, and says to delete it when that lands.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B4NYejYW2dW7dNtYh7srDy
---
 .github/workflows/compliance.yml | 140 +++++++++++++++++++++++++++++++
 1 file changed, 140 insertions(+)
 create mode 100644 .github/workflows/compliance.yml

diff --git a/.github/workflows/compliance.yml b/.github/workflows/compliance.yml
new file mode 100644
index 0000000..4ee33e2
--- /dev/null
+++ b/.github/workflows/compliance.yml
@@ -0,0 +1,140 @@
+name: compliance
+
+# A targeted subset of the plugin-spec checks that the org's original-repo
+# plugins run via their own custom-checks.yml. This repo's ci.yml calls the
+# shared reusable-ci.yml, which runs the test suites and nothing else — so
+# before this file, fork-derived plugins got tests but no spec enforcement
+# while the originals got enforcement but (in one case) no tests.
+#
+# Deliberately not the full 16-job set. These three are the ones that map to
+# defects a cross-repo audit actually found in these repos: versions and
+# changelogs going stale while functional source shipped, and screen.js
+# re-executing on plugin reload without a guard. Jobs self-skip when they
+# don't apply (no CHANGELOG.md, no screen.js).
+#
+# The right long-term home for these is got-feedback/.github's
+# reusable-ci.yml, so every repo picks them up from one reference. Delete
+# this file when that lands.
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+env:
+  PLUGIN_DIR: "."
+
+jobs:
+  version-bumped-on-change:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: plugin.json version must bump when functional source changes
+        run: |
+          set -eu
+          BASE="${{ github.event.pull_request.base.sha }}"
+          if [ -z "$BASE" ]; then
+            BASE="${{ github.event.before }}"
+          fi
+          if [ -z "$BASE" ] || ! git cat-file -e "$BASE" 2>/dev/null; then
+            echo "No usable base commit to diff against — skipping"
+            exit 0
+          fi
+          DIR="$PLUGIN_DIR"
+          CHANGED=$(git diff --name-only "$BASE" HEAD -- "$DIR" || true)
+          FUNCTIONAL=$(echo "$CHANGED" | grep -E '\.(py|js|html)$' | grep -vE '(^|/)tests?/' | grep -v 'plugin\.json$' || true)
+          if [ -z "$FUNCTIONAL" ]; then
+            echo "No functional source changed — skipping"
+            exit 0
+          fi
+          MANIFEST_CHANGED=$(git diff --name-only "$BASE" HEAD -- "$DIR/plugin.json" || true)
+          if [ -z "$MANIFEST_CHANGED" ]; then
+            echo "::error file=$DIR/plugin.json::functional source changed ($FUNCTIONAL) but plugin.json was not — bump the version"
+            exit 1
+          fi
+          OLD_VERSION=$(git show "$BASE:$DIR/plugin.json" 2>/dev/null | python3 -c "import json,sys; print(json.load(sys.stdin).get('version',''))" || echo "")
+          NEW_VERSION=$(python3 -c "import json; print(json.load(open('$DIR/plugin.json')).get('version',''))")
+          if [ "$OLD_VERSION" = "$NEW_VERSION" ]; then
+            echo "::error file=$DIR/plugin.json::plugin.json changed but version is still $NEW_VERSION — bump it"
+            exit 1
+          fi
+          echo "OK: version bumped $OLD_VERSION -> $NEW_VERSION"
+
+  idempotent-top-level-guard:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Top-level listeners/timers must be inside a reload guard
+        run: |
+          python3 - <<'PY'
+          import os, re, sys
+
+          plugin_dir = os.environ["PLUGIN_DIR"]
+          js_path = os.path.join(plugin_dir, "screen.js")
+          if not os.path.isfile(js_path):
+              print("No screen.js — skipping")
+              raise SystemExit(0)
+
+          src = open(js_path, encoding="utf-8").read()
+          has_hotpath = bool(re.search(r'(window\.addEventListener|document\.addEventListener|setInterval)\s*\(', src))
+          # Guard naming varies across the org (__xInstalled, __xHooksInstalled,
+          # __feedBackDynamicDifficulty, __ddCardBadgeRegistered, ...) — no
+          # single suffix covers them, so just require *some* window-level __
+          # flag rather than pattern-matching a specific naming style.
+          #
+          # Both access forms count. section_map, the org's reference guard,
+          # hoists the name into a const and uses window[HOOK_KEY]; matching
+          # only the dotted form flags it as unguarded when it is not.
+          dotted = re.search(r'window\.__\w+', src)
+          bracket_literal = re.search(r'window\s*\[\s*[\'"]__\w+[\'"]\s*\]', src)
+          bracket_const = (
+              re.search(r'window\s*\[\s*[A-Za-z_$][\w$]*\s*\]', src)
+              and re.search(r'[\'"]__\w+[\'"]', src)
+          )
+          has_guard = bool(dotted or bracket_literal or bracket_const)
+
+          if has_hotpath and not has_guard:
+              print(f"::error file={js_path}::found addEventListener/setInterval but no window.__*Installed-style reload guard — screen.js can re-execute on plugin reload")
+              sys.exit(1)
+          print("OK: no unguarded top-level listeners detected (or none present)")
+          PY
+
+  changelog-updated:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: CHANGELOG.md Unreleased section must be updated for functional changes
+        run: |
+          set -eu
+          if [ ! -f CHANGELOG.md ]; then
+            echo "No CHANGELOG.md in this repo — skipping"
+            exit 0
+          fi
+          BASE="${{ github.event.pull_request.base.sha }}"
+          if [ -z "$BASE" ]; then
+            BASE="${{ github.event.before }}"
+          fi
+          if [ -z "$BASE" ] || ! git cat-file -e "$BASE" 2>/dev/null; then
+            echo "No usable base commit to diff against — skipping"
+            exit 0
+          fi
+          FUNCTIONAL=$(git diff --name-only "$BASE" HEAD -- "$PLUGIN_DIR" | grep -E '\.(py|js|html)$' | grep -vE '(^|/)tests?/' || true)
+          if [ -z "$FUNCTIONAL" ]; then
+            echo "No functional source changed — skipping"
+            exit 0
+          fi
+          CHANGELOG_DIFF=$(git diff --name-only "$BASE" HEAD -- CHANGELOG.md || true)
+          if [ -z "$CHANGELOG_DIFF" ]; then
+            echo "::error file=CHANGELOG.md::functional source changed but CHANGELOG.md was not updated"
+            exit 1
+          fi
+          echo "OK: CHANGELOG.md was updated"
+

From a510defa64a8b858183fecc8573f04559916e524 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 13 Aug 2026 02:58:54 +0000
Subject: [PATCH 3/6] Share the DOM stubs between tests; widen a re-indented
 variable name
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Review feedback from PR #29 (DeepSource, blocking).

The reload test duplicated ~25 lines of freshPlugin's window/document
setup, which is what produced a fresh crop of empty-function findings —
the same stubs already existed a few hundred lines up. Extract
makeDocumentStub() and loadPlugin() and use them from both, with the
no-op bodies collapsed onto one documented `noop` instead of six
anonymous empty methods. The test keeps building its own window because
that is the point of it: a reload is one window surviving two
evaluations, where freshPlugin builds a new one per call.

Rename `t` -> `target` in the pointerdown handler. Pre-existing code, but
guarding the listener re-indented the line, so it now reads as changed.

33/33, and the double-load harness still reports hooks installed once.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B4NYejYW2dW7dNtYh7srDy
---
 screen.js            |  5 +--
 tests/screen.test.js | 76 ++++++++++++++++++++++----------------------
 2 files changed, 41 insertions(+), 40 deletions(-)

diff --git a/screen.js b/screen.js
index 0d1452d..a1f97d7 100644
--- a/screen.js
+++ b/screen.js
@@ -1823,8 +1823,9 @@ try {
     // popovers on every pointerdown (see HOOK_KEY at the top of the IIFE).
     if (!_hooksAlreadyInstalled) {
         document.addEventListener('pointerdown', (e) => {
-            const t = e.target;
-            if (t && typeof t.closest === 'function' && (t.closest('.ss-viz-popover') || t.closest('[data-ss-viz-btn]'))) return;
+            const target = e.target;
+            if (target && typeof target.closest === 'function'
+                && (target.closest('.ss-viz-popover') || target.closest('[data-ss-viz-btn]'))) return;
             _closeAllVizPopovers();
         }, true);
     }
diff --git a/tests/screen.test.js b/tests/screen.test.js
index 738af99..32136b2 100644
--- a/tests/screen.test.js
+++ b/tests/screen.test.js
@@ -15,24 +15,41 @@ function makeLocalStorage() {
     };
 }
 
-function freshPlugin({ search = '', protocol = 'http:' } = {}) {
-    const location = { search, host: 'localhost:8420', protocol };
-    global.window = { location, addEventListener: () => {} };
-    global.document = {
+// screen.js only needs these DOM entry points to exist while its IIFE
+// evaluates — no test asserts on rendering, so the bodies are deliberately
+// inert. One shared no-op keeps that intent in a single place.
+const noop = () => { /* inert DOM stub — see comment above */ };
+
+function makeDocumentStub(onAddEventListener = noop) {
+    return {
         getElementById: () => null,
-        addEventListener: () => {},
-        body: { appendChild: () => {} },
+        addEventListener: onAddEventListener,
+        body: { appendChild: noop },
         createElement: () => ({
-            style: {}, classList: { add() {}, remove() {} },
-            addEventListener() {}, appendChild() {}, setAttribute() {},
+            style: {},
+            classList: { add: noop, remove: noop },
+            addEventListener: noop,
+            appendChild: noop,
+            setAttribute: noop,
         }),
         readyState: 'loading',
     };
+}
+
+const PLUGIN_PATH = path.join(__dirname, '..', 'screen.js');
+
+function loadPlugin() {
+    delete require.cache[require.resolve(PLUGIN_PATH)];
+    return require(PLUGIN_PATH);
+}
+
+function freshPlugin({ search = '', protocol = 'http:' } = {}) {
+    const location = { search, host: 'localhost:8420', protocol };
+    global.window = { location, addEventListener: noop };
+    global.document = makeDocumentStub();
     global.localStorage = makeLocalStorage();
     global.location = location;
-    const file = path.join(__dirname, '..', 'screen.js');
-    delete require.cache[require.resolve(file)];
-    return require(file);
+    return loadPlugin();
 }
 
 test('getWsUrl decodes percent-encoded filenames and builds a ws:// URL', () => {
@@ -364,44 +381,27 @@ test('_bestFitLayout picks the smallest layout with room, and caps at six', () =
 // the wrapper twice and each resize/pointerdown fired twice.
 test('re-evaluating screen.js installs its global hooks exactly once', () => {
     const counts = { resize: 0, beforeunload: 0, pointerdown: 0 };
+    const tally = (ev) => { if (ev in counts) counts[ev] += 1; };
     const location = { search: '', host: 'localhost:8420', protocol: 'http:' };
 
-    // One shared window across both loads — that is what a reload looks like.
-    global.window = {
-        location,
-        addEventListener: (ev) => {
-            if (ev in counts) counts[ev]++;
-        },
-    };
-    global.document = {
-        getElementById: () => null,
-        addEventListener: (ev) => { if (ev in counts) counts[ev]++; },
-        body: { appendChild: () => {} },
-        createElement: () => ({
-            style: {}, classList: { add() {}, remove() {} },
-            addEventListener() {}, appendChild() {}, setAttribute() {},
-        }),
-        readyState: 'loading',
-    };
+    // Deliberately NOT freshPlugin(): it builds a new window per call, and a
+    // reload is precisely the case where one window survives two evaluations.
+    global.window = { location, addEventListener: tally };
+    global.document = makeDocumentStub(tally);
     global.localStorage = makeLocalStorage();
     global.location = location;
 
-    const originalPlaySong = async function original() {};
+    // Sentinels — only their identity matters, so the bodies stay empty.
+    const originalPlaySong = async function originalPlaySong() { /* sentinel */ };
     window.playSong = originalPlaySong;
-    window.showScreen = function original() {};
-
-    const file = path.join(__dirname, '..', 'screen.js');
-    const load = () => {
-        delete require.cache[require.resolve(file)];
-        require(file);
-    };
+    window.showScreen = function originalShowScreen() { /* sentinel */ };
 
-    load();
+    loadPlugin();
     assert.notEqual(window.playSong, originalPlaySong, 'first load should wrap playSong');
     const afterFirst = { ...counts };
     const wrappedOnce = window.playSong;
 
-    load();
+    loadPlugin();
 
     assert.deepEqual(counts, afterFirst, 'second evaluation must not re-add listeners');
     assert.equal(window.playSong, wrappedOnce, 'second evaluation must not re-wrap playSong');

From d991f5e07db242658f8f6a085ca334c612c3c77f Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 13 Aug 2026 03:03:48 +0000
Subject: [PATCH 4/6] fix(reload): gate the whole IIFE body, not just the hook
 sites
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Review feedback from PR #29 — the per-site guard was too narrow.

Skipping hook installation is exactly what makes run #1's closures the
live state, so anything run #2 builds is unreachable, and three top-level
blocks were still executing on a second evaluation:

- The settings-sync wiring re-bound its change handlers. Those mutate run
  #2's `layout` / `alwaysSplit`, which run #1's live playSong wrapper
  never reads — so toggling "Always Split" after a reload silently did
  nothing.
- _maybeResumeLanShare() couldn't see run #1's `_lanShare`, so it opened a
  second relay socket and broadcaster for the same room. Worse,
  _ensureMainBroadcasterAndListener() reassigns `ch.onmessage` on the
  shared BroadcastChannel, clobbering run #1's handler — the one that
  processes popup `docked`/`closed`, so a popped-out panel could no
  longer be re-docked.
- bootFollowerMode() / bootRemoteJoin() rebuilt a second layout in a
  follower or ?ss= viewer window.

Return out of the IIFE when the flag is already set. That subsumes all
five per-site guards, which are removed. A fresh page load has no flag,
so crash-recovery share resume and follower boot still run.

The test now also counts settings-control wirings, which is what catches
this class: it fails against the previous per-site version.

Also finishes the doc sweep — six screen.js comments still named
slopsmithViz_* as the primary factory global.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B4NYejYW2dW7dNtYh7srDy
---
 screen.js            | 95 +++++++++++++++++++++-----------------------
 tests/screen.test.js | 24 ++++++++---
 2 files changed, 65 insertions(+), 54 deletions(-)

diff --git a/screen.js b/screen.js
index a1f97d7..6b2ebe9 100644
--- a/screen.js
+++ b/screen.js
@@ -21,26 +21,39 @@ try {
 
     // ── Reload idempotency (plugin-runtime-idempotent.v1) ─────────────────
     // The Host may re-execute screen.js on plugin reload, which re-runs this
-    // whole IIFE. Module state resetting is harmless — it gets rebuilt — but
-    // the hooks we install on shared globals are not module state and would
-    // accumulate: window.playSong would be wrapped a second time around the
-    // already-wrapped version (so every song load runs our wrapper twice),
-    // and the resize / beforeunload / pointerdown listeners would each fire
-    // twice per event.
+    // whole IIFE. A second run must not execute ANY top-level statement with
+    // observable side effects, so bail out of the entire body rather than
+    // guarding individual hook sites.
+    //
+    // Guarding only the shared-global hooks isn't enough, because skipping
+    // hook installation is exactly what makes run #1's closures the live
+    // state — anything run #2 builds is then unreachable, and some of it
+    // actively fights run #1:
+    //   • the settings-sync wiring below re-binds the change handlers, which
+    //     would mutate run #2's `layout` / `alwaysSplit` — values run #1's
+    //     live playSong wrapper never reads, so the settings silently no-op;
+    //   • _maybeResumeLanShare() can't see run #1's `_lanShare`, so it opens
+    //     a SECOND relay socket and broadcaster for the same room, and
+    //     _ensureMainBroadcasterAndListener() reassigns `ch.onmessage` on the
+    //     shared BroadcastChannel — clobbering run #1's handler, which is
+    //     what processes popup `docked`/`closed`, so a popped-out panel can
+    //     no longer be re-docked;
+    //   • bootFollowerMode() / bootRemoteJoin() would build a second layout
+    //     in a follower or ?ss= viewer window.
     //
     // The flag lives on `window` precisely because it has to outlive the
-    // re-execution that resets everything else. On a second run we skip
-    // installing hooks and leave the first run's — which are still bound to
-    // a fully live set of closures — in place. Same shape as sectionmap's
-    // __slopsmithSectionMapHooksInstalled guard.
+    // re-execution that resets everything else. Same shape as sectionmap's
+    // __slopsmithSectionMapHooksInstalled guard, applied at body level.
     //
     // Node test env: tests/screen.test.js builds a fresh `global.window` per
-    // case, so the flag is always absent there and hooks install every time,
-    // exactly as before.
+    // case, so the flag is absent there and the body runs in full — including
+    // the module.exports block at the bottom, which the early return would
+    // otherwise skip.
     const HOOK_KEY = '__feedBackSplitscreenHooksInstalled';
-    const _hooksAlreadyInstalled =
-        typeof window !== 'undefined' && window[HOOK_KEY] === true;
-    if (typeof window !== 'undefined') window[HOOK_KEY] = true;
+    if (typeof window !== 'undefined') {
+        if (window[HOOK_KEY]) return;
+        window[HOOK_KEY] = true;
+    }
 
     const LAYOUTS = {
         'top-bottom':  { panels: 2, style: 'flex-col' },
@@ -320,12 +333,12 @@ try {
             const resp = await fetch('/api/plugins');
             const all  = await resp.json();
             // Store metadata for all viz plugins; factory presence is checked at
-            // populateSelect() time (not at fetch time), so the window['slopsmithViz_*']
+            // populateSelect() time (not at fetch time), so the window['feedBackViz_*']
             // globals are evaluated when the dropdown is first built.
             vizPlugins = (all || []).filter(p => p?.type === 'visualization');
         } catch (_) {
             // /api/plugins unavailable — fall back to scanning window for any
-            // slopsmithViz_* factories that are already loaded so viz options
+            // feedBackViz_* factories that are already loaded so viz options
             // remain available even when the plugin registry can't be fetched.
             // Mark fetch as failed so populateSelect re-scans on every build,
             // preserving the "deferred plugin scripts are reflected" property
@@ -355,7 +368,7 @@ try {
 
     // Bounded poll for viz factories that register AFTER the picker is
     // first built. /api/plugins returns metadata for every type:visualization
-    // plugin immediately, but each plugin's window.slopsmithViz_<id> factory
+    // plugin immediately, but each plugin's window.feedBackViz_<id> factory
     // only exists after the host has loaded and executed that plugin's
     // screen.js. The host loads plugin scripts sequentially in loadPlugins()
     // (alphabetical by directory). Two cases leave the picker missing
@@ -684,7 +697,7 @@ try {
     // `key` is the localStorage suffix the viz plugin reads per-panel. For
     // highway_3d that's h3d_bg_panel<N>_<key>, falling back to the global
     // h3d_bg_<key> (see the plugin's _bgReadSetting). A viz plugin can override
-    // this list at runtime by exposing `window.slopsmithViz_highway_3d.panelControls`
+    // this list at runtime by exposing `window.feedBackViz_highway_3d.panelControls`
     // (same shape) — that takes precedence so the plugin owns the up-to-date
     // list without splitscreen needing edits when it adds options.
     // For `range`: min/max default to 0..1 and step to 0.05 when omitted.
@@ -716,7 +729,7 @@ try {
         // setters. The popover stays hidden for other viz plugins until the
         // descriptor carries per-plugin storage/setter info (or read/write fns).
         // A plugin can still customize *which* controls show via
-        // window.slopsmithViz_highway_3d.panelControls.
+        // window.feedBackViz_highway_3d.panelControls.
         if (pluginId !== 'highway_3d') return null;
         const fac = vizFactory(pluginId);
         // An array (even empty) is an intentional override — empty = opt out of
@@ -1819,16 +1832,12 @@ try {
         for (const p of panels) if (p.vizPopover) p.vizPopover.style.display = 'none';
     }
     // Close any open viz popover when clicking outside it / its trigger button.
-    // Guarded: a reload would otherwise leave two capture listeners closing
-    // popovers on every pointerdown (see HOOK_KEY at the top of the IIFE).
-    if (!_hooksAlreadyInstalled) {
-        document.addEventListener('pointerdown', (e) => {
-            const target = e.target;
-            if (target && typeof target.closest === 'function'
-                && (target.closest('.ss-viz-popover') || target.closest('[data-ss-viz-btn]'))) return;
-            _closeAllVizPopovers();
-        }, true);
-    }
+    document.addEventListener('pointerdown', (e) => {
+        const target = e.target;
+        if (target && typeof target.closest === 'function'
+            && (target.closest('.ss-viz-popover') || target.closest('[data-ss-viz-btn]'))) return;
+        _closeAllVizPopovers();
+    }, true);
 
     /**
      * ── Mastery slider helpers ──
@@ -1895,7 +1904,7 @@ try {
 
         // Any registered viz plugin whose factory hasn't loaded yet? Kick
         // off the bounded poll so the picker auto-repopulates once their
-        // script registers window.slopsmithViz_<id>. Single-flight — cheap
+        // script registers window.feedBackViz_<id>. Single-flight — cheap
         // to call on every populateSelect.
         if (vizPlugins.some(vp => !hasVizFactory(vp.id))) {
             _startVizFactoryWatch();
@@ -4510,17 +4519,15 @@ try {
     // reservation, sliding the wrap (and every panel's bar) under the
     // follower toolbar. Follower mode has its own resize handler in
     // bootFollowerMode that resizes panels without touching the wrap.
-    if (!_hooksAlreadyInstalled) {
-        window.addEventListener('resize', () => {
-            if (active && !FOLLOWER) sizeCanvases();
-        });
-    }
+    window.addEventListener('resize', () => {
+        if (active && !FOLLOWER) sizeCanvases();
+    });
 
     // Tell any popped-out panels the main window is going away so they stop
     // syncing (and stop their highway rAF loops) and show a notice instead of
     // freezing silently. Best-effort — beforeunload BroadcastChannel posts
     // aren't guaranteed to flush; the popup's own state stays the floor.
-    if (!FOLLOWER && !_hooksAlreadyInstalled) {
+    if (!FOLLOWER) {
         window.addEventListener('beforeunload', () => {
             try {
                 const c = _ssChannel();
@@ -4534,13 +4541,8 @@ try {
     }
 
     // ── Hook into playSong ──
-    // The wrapper is always built, but only installed on a first run — see
-    // HOOK_KEY at the top of the IIFE. Guarding the assignment rather than
-    // the definition keeps this readable: a second evaluation would
-    // otherwise wrap the already-wrapped playSong, running everything below
-    // twice per song load.
     const _play = window.playSong;
-    const _ssPlaySong = async function (f, a) {
+    window.playSong = async function (f, a) {
         // Mount the Split button (and its siblings) BEFORE awaiting the
         // upstream chain. Any upstream playSong wrapper that throws (e.g.
         // capo failing in its v3 insertBefore — seen in the wild on the
@@ -4628,16 +4630,11 @@ try {
     // away from the player, but if something tries we don't tear down split
     // (the follower panel IS the player).
     const _show = window.showScreen;
-    const _ssShowScreen = function (id) {
+    window.showScreen = function (id) {
         if (!FOLLOWER && id !== 'player' && active) stopSplitScreen();
         _show(id);
     };
 
-    if (!_hooksAlreadyInstalled) {
-        window.playSong = _ssPlaySong;
-        window.showScreen = _ssShowScreen;
-    }
-
     // ══════════════════════════════════════════════════════════════════════
     //  Follower-mode bootstrap (popup window only)
     //  The actual `if (FOLLOWER) bootFollowerMode();` invocation is at the
diff --git a/tests/screen.test.js b/tests/screen.test.js
index 32136b2..d6448c5 100644
--- a/tests/screen.test.js
+++ b/tests/screen.test.js
@@ -374,11 +374,12 @@ test('_bestFitLayout picks the smallest layout with room, and caps at six', () =
 });
 
 // ── Reload idempotency (plugin-runtime-idempotent.v1) ─────────────────────
-// The Host may re-execute screen.js on plugin reload. Module state resetting
-// is fine, but hooks installed on shared globals must not accumulate: before
-// the HOOK_KEY guard, a second evaluation wrapped the already-wrapped
-// playSong and added a second copy of every listener, so each song load ran
-// the wrapper twice and each resize/pointerdown fired twice.
+// The Host may re-execute screen.js on plugin reload. A second evaluation
+// must not run ANY top-level statement with observable side effects: not
+// just the shared-global hooks (before the guard, playSong got wrapped
+// around the already-wrapped version and every listener was added twice),
+// but also the settings-sync wiring, the LAN-share resume, and the
+// follower boot — all of which would build state no live hook reads.
 test('re-evaluating screen.js installs its global hooks exactly once', () => {
     const counts = { resize: 0, beforeunload: 0, pointerdown: 0 };
     const tally = (ev) => { if (ev in counts) counts[ev] += 1; };
@@ -391,6 +392,17 @@ test('re-evaluating screen.js installs its global hooks exactly once', () => {
     global.localStorage = makeLocalStorage();
     global.location = location;
 
+    // The settings-sync block wires a change handler onto this control. A
+    // second evaluation re-wiring it is the subtler half of the bug: the new
+    // handler mutates state that run #1's live playSong wrapper never reads,
+    // so "Always Split" would silently stop working after a reload.
+    let settingsWirings = 0;
+    global.document.getElementById = (id) => (
+        id === 'splitscreen-default-layout'
+            ? { value: '', addEventListener: () => { settingsWirings += 1; } }
+            : null
+    );
+
     // Sentinels — only their identity matters, so the bodies stay empty.
     const originalPlaySong = async function originalPlaySong() { /* sentinel */ };
     window.playSong = originalPlaySong;
@@ -398,6 +410,7 @@ test('re-evaluating screen.js installs its global hooks exactly once', () => {
 
     loadPlugin();
     assert.notEqual(window.playSong, originalPlaySong, 'first load should wrap playSong');
+    assert.equal(settingsWirings, 1, 'first load should wire the settings control once');
     const afterFirst = { ...counts };
     const wrappedOnce = window.playSong;
 
@@ -405,4 +418,5 @@ test('re-evaluating screen.js installs its global hooks exactly once', () => {
 
     assert.deepEqual(counts, afterFirst, 'second evaluation must not re-add listeners');
     assert.equal(window.playSong, wrappedOnce, 'second evaluation must not re-wrap playSong');
+    assert.equal(settingsWirings, 1, 'second evaluation must not re-wire settings handlers');
 });

From 55bfd6fb190eb96a7f9a794a224b29d026ef1c55 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 13 Aug 2026 03:05:04 +0000
Subject: [PATCH 5/6] ci(compliance): diff against the merge base, and check
 [Unreleased] itself
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Review feedback on the compliance workflow.

The jobs diffed `$BASE..HEAD` where BASE is `pull_request.base.sha` — the
live tip of main, not the merge base. Any commit landing on main after a
branch forks then shows up in the diff, so a stale branch gets failed for
a version bump it does not owe. Use `git merge-base` first.

`changelog-updated` only asserted CHANGELOG.md appeared in the diff, so
editing an already-released section while [Unreleased] stayed put passed
— the exact slip these checks exist to catch. Compare the [Unreleased]
section itself; a release cut that empties it still counts as a change.

Treat .css as functional source too: the Host cache-busts plugin assets
by version, so a stylesheet-only change needs a bump.

Record the guard job's known limitation in the file: it proves a guard
exists somewhere, not that every hotpath sits inside one.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B4NYejYW2dW7dNtYh7srDy
---
 .github/workflows/compliance.yml | 32 ++++++++++++++++++++++++++------
 1 file changed, 26 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/compliance.yml b/.github/workflows/compliance.yml
index 4ee33e2..e989d39 100644
--- a/.github/workflows/compliance.yml
+++ b/.github/workflows/compliance.yml
@@ -46,9 +46,14 @@ jobs:
             echo "No usable base commit to diff against — skipping"
             exit 0
           fi
+          # Diff against the MERGE BASE, not the base tip. On pull_request,
+          # github.event.pull_request.base.sha is main's live tip, so a
+          # two-dot diff also reports commits that landed on main after this
+          # branch forked — failing the PR for a bump it does not owe.
+          BASE=$(git merge-base "$BASE" HEAD || echo "$BASE")
           DIR="$PLUGIN_DIR"
           CHANGED=$(git diff --name-only "$BASE" HEAD -- "$DIR" || true)
-          FUNCTIONAL=$(echo "$CHANGED" | grep -E '\.(py|js|html)$' | grep -vE '(^|/)tests?/' | grep -v 'plugin\.json$' || true)
+          FUNCTIONAL=$(echo "$CHANGED" | grep -E '\.(py|js|html|css)$' | grep -vE '(^|/)tests?/' | grep -v 'plugin\.json$' || true)
           if [ -z "$FUNCTIONAL" ]; then
             echo "No functional source changed — skipping"
             exit 0
@@ -99,6 +104,10 @@ jobs:
           )
           has_guard = bool(dotted or bracket_literal or bracket_const)
 
+          # Known limitation: this proves a guard EXISTS somewhere in the
+          # file, not that every hotpath sits inside one. A new unguarded
+          # listener added alongside an existing guard still passes. It is a
+          # cross-repo floor, not proof of idempotency.
           if has_hotpath and not has_guard:
               print(f"::error file={js_path}::found addEventListener/setInterval but no window.__*Installed-style reload guard — screen.js can re-execute on plugin reload")
               sys.exit(1)
@@ -126,15 +135,26 @@ jobs:
             echo "No usable base commit to diff against — skipping"
             exit 0
           fi
-          FUNCTIONAL=$(git diff --name-only "$BASE" HEAD -- "$PLUGIN_DIR" | grep -E '\.(py|js|html)$' | grep -vE '(^|/)tests?/' || true)
+          # Diff against the MERGE BASE, not the base tip. On pull_request,
+          # github.event.pull_request.base.sha is main's live tip, so a
+          # two-dot diff also reports commits that landed on main after this
+          # branch forked — failing the PR for a bump it does not owe.
+          BASE=$(git merge-base "$BASE" HEAD || echo "$BASE")
+          FUNCTIONAL=$(git diff --name-only "$BASE" HEAD -- "$PLUGIN_DIR" | grep -E '\.(py|js|html|css)$' | grep -vE '(^|/)tests?/' || true)
           if [ -z "$FUNCTIONAL" ]; then
             echo "No functional source changed — skipping"
             exit 0
           fi
-          CHANGELOG_DIFF=$(git diff --name-only "$BASE" HEAD -- CHANGELOG.md || true)
-          if [ -z "$CHANGELOG_DIFF" ]; then
-            echo "::error file=CHANGELOG.md::functional source changed but CHANGELOG.md was not updated"
+          # Touching the file is not enough — editing an already-released
+          # section while [Unreleased] stays put is the exact slip this is
+          # meant to catch. Compare the [Unreleased] section itself.
+          unreleased() {
+            git show "$1:CHANGELOG.md" 2>/dev/null \
+              | awk '/^## \[Unreleased\]/{f=1;next} /^## \[/{f=0} f'
+          }
+          if [ "$(unreleased "$BASE")" = "$(unreleased HEAD)" ]; then
+            echo "::error file=CHANGELOG.md::functional source changed but CHANGELOG.md's [Unreleased] section did not (a release cut that empties it also counts as a change)"
             exit 1
           fi
-          echo "OK: CHANGELOG.md was updated"
+          echo "OK: CHANGELOG.md [Unreleased] changed"
 

From f2622f9dae4bcc45d8f52843db0608b726c40b92 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 13 Aug 2026 03:09:35 +0000
Subject: [PATCH 6/6] docs: install from the canonical repo; state the fork
 relationship
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The README cloned a personal fork (carochacs/…), and my first pass moved
it to get-flashbacks — still a fork. Either way the plugin becomes
fork-specific: anyone following the README tracks a fork rather than
got-feedBack/feedBack-plugin-splitscreen, which is where the plugin
actually lives, and it stops being useful to the repo it came from.
Install now points upstream.

CLAUDE.md gets the same correction plus the reasoning, since agents read
it verbatim: canonical repo named explicitly, user-facing links kept on
got-feedBack, day-to-day PRs still targeting this fork, and a note that
non-fork-specific fixes are worth opening upstream too — core's "upstream
PRs retire debt" rule applied to plugins.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B4NYejYW2dW7dNtYh7srDy
---
 CLAUDE.md | 18 ++++++++++++++----
 README.md |  2 +-
 2 files changed, 15 insertions(+), 5 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index dee122a..5d0acc7 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -359,7 +359,17 @@ Follow the lyrics/jumping-tab pattern:
 
 ## Git and PR conventions
 
-- All work goes on feature branches off `main` in this repo (`get-flashbacks/feedBack-plugin-splitscreen`)
-- PRs target `get-flashbacks/feedBack-plugin-splitscreen`
-- Use `gh pr create --repo get-flashbacks/feedBack-plugin-splitscreen --base main --head <branch>` from inside the plugin directory
-- Always branch from `origin/main` — there is no separate upstream remote
+- **`got-feedBack/feedBack-plugin-splitscreen` is the canonical plugin repo.** This
+  checkout (`get-flashbacks/feedBack-plugin-splitscreen`) is a fork of it. Keep changes
+  portable: anything a user or the upstream project would read — the README's install
+  instructions, links to feedBack or sibling plugins — points at `got-feedBack`, not at
+  this fork. Redirecting those to the fork is what stops the plugin being useful to the
+  repo it came from.
+- Day-to-day work goes on feature branches off `main` in this fork, and PRs target this
+  fork: `gh pr create --repo get-flashbacks/feedBack-plugin-splitscreen --base main --head <branch>`
+  from inside the plugin directory.
+- A fix that isn't fork-specific is worth opening upstream against
+  `got-feedBack/feedBack-plugin-splitscreen` too — same idea as core's
+  "upstream PRs retire debt" rule.
+- Always branch from `origin/main`; there is no `upstream` remote configured here, so add
+  one explicitly if you're preparing an upstream PR.
diff --git a/README.md b/README.md
index 789fc7b..a21752d 100644
--- a/README.md
+++ b/README.md
@@ -23,7 +23,7 @@ A plugin for [feedBack](https://github.com/got-feedback/feedBack) that shows 2
 
 ```bash
 cd /path/to/feedBack/plugins
-git clone https://github.com/get-flashbacks/feedBack-plugin-splitscreen.git splitscreen
+git clone https://github.com/got-feedBack/feedBack-plugin-splitscreen.git splitscreen
 docker compose restart
 ```