diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
new file mode 100644
index 0000000..4c813e5
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -0,0 +1,70 @@
+name: Bug report
+description: Report something broken or unexpectedly behaving in this FeedBack repo.
+title: "[Bug]: "
+labels: ["bug", "needs triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this for reproducible failures. Include the smallest chart, plugin state, or workflow that shows the issue.
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: What is happening?
+      placeholder: Describe the problem in one or two sentences.
+    validations:
+      required: true
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - screen.js / runtime behavior
+        - settings.html / settings persistence
+        - plugin reload or idempotency
+        - FeedBack core integration
+        - performance during playback
+        - documentation or packaging
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      description: What should someone do to see the issue?
+      placeholder: |
+        1. Open FeedBack...
+        2. Enable/open...
+        3. Play/import/change...
+        4. See...
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+    validations:
+      required: true
+  - type: textarea
+    id: validation
+    attributes:
+      label: Useful validation
+      description: What should be checked when this is fixed?
+      placeholder: Reload the plugin, open it from FeedBack, test during playback, and check console errors.
+  - type: input
+    id: environment
+    attributes:
+      label: Environment
+      placeholder: Browser/OS, FeedBack version or commit, plugin version, Docker image, etc.
+  - type: textarea
+    id: notes
+    attributes:
+      label: Additional notes
+      description: Logs, screenshots, chart files, console output, or related PRs/issues.
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 0000000..a12153d
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Roadmap or planning question
+    url: https://github.com/get-flashbacks/feedBack-plugin-splitscreen/issues
+    about: Use the relevant GitHub Project board for roadmap-level planning when available.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
new file mode 100644
index 0000000..8fb62a7
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -0,0 +1,53 @@
+name: Feature request
+description: Suggest a new capability or workflow improvement.
+title: "[Feature]: "
+labels: ["enhancement", "needs triage"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: User problem or opportunity
+      description: What workflow gap does this solve?
+      placeholder: When practicing or authoring in FeedBack, I want...
+    validations:
+      required: true
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - screen.js / runtime behavior
+        - settings.html / settings persistence
+        - plugin reload or idempotency
+        - FeedBack core integration
+        - performance during playback
+        - documentation or packaging
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed behavior
+      description: What should change from the user's perspective?
+    validations:
+      required: true
+  - type: textarea
+    id: implementation_notes
+    attributes:
+      label: Implementation notes
+      description: Mention relevant files, plugin lifecycle concerns, API/data format changes, or performance risks.
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: Acceptance criteria
+      description: What must be true for this to be considered done?
+      placeholder: |
+        - [ ] The user can...
+        - [ ] The change survives reload/reopen...
+        - [ ] No console/server errors appear...
+    validations:
+      required: true
+  - type: textarea
+    id: references
+    attributes:
+      label: References or mockups
diff --git a/.github/ISSUE_TEMPLATE/task.yml b/.github/ISSUE_TEMPLATE/task.yml
new file mode 100644
index 0000000..57e7e0e
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/task.yml
@@ -0,0 +1,55 @@
+name: Task or improvement
+description: Track cleanup, refactors, documentation, research, or non-bug work.
+title: "[Task]: "
+labels: ["task", "needs triage"]
+body:
+  - type: textarea
+    id: goal
+    attributes:
+      label: Goal
+      description: What should be accomplished?
+    validations:
+      required: true
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - screen.js / runtime behavior
+        - settings.html / settings persistence
+        - plugin reload or idempotency
+        - FeedBack core integration
+        - performance during playback
+        - documentation or packaging
+    validations:
+      required: true
+  - type: textarea
+    id: scope
+    attributes:
+      label: Scope
+      description: What is included, and what is intentionally out of scope?
+  - type: textarea
+    id: checklist
+    attributes:
+      label: Checklist
+      description: Break the work into concrete steps.
+      placeholder: |
+        - [ ] ...
+        - [ ] ...
+    validations:
+      required: true
+  - type: dropdown
+    id: priority
+    attributes:
+      label: Priority
+      options:
+        - low
+        - medium
+        - high
+    validations:
+      required: true
+  - type: textarea
+    id: validation
+    attributes:
+      label: Validation
+      placeholder: Reload the plugin, open it from FeedBack, test during playback, and check console errors.
diff --git a/.github/workflows/pullfrog.yml b/.github/workflows/pullfrog.yml
new file mode 100644
index 0000000..b34af7e
--- /dev/null
+++ b/.github/workflows/pullfrog.yml
@@ -0,0 +1,67 @@
+# PULLFROG ACTION — DO NOT EDIT EXCEPT WHERE INDICATED
+name: Pullfrog
+run-name: ${{ inputs.name || github.workflow }}
+on:
+  workflow_dispatch:
+    inputs:
+      prompt:
+        type: string
+        description: Agent prompt
+      name:
+        type: string
+        description: Run name
+
+permissions:
+  contents: read
+
+jobs:
+  pullfrog:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 1
+      - name: Run agent
+        uses: pullfrog/pullfrog@v0
+        with:
+          prompt: ${{ inputs.prompt }}
+        env:
+          # add at least one provider API key
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          GOOGLE_GENERATIVE_AI_API_KEY:
+            ${{ secrets.GOOGLE_GENERATIVE_AI_API_KEY }}
+          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
+          XAI_API_KEY: ${{ secrets.XAI_API_KEY }}
+          DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}
+          MOONSHOT_API_KEY: ${{ secrets.MOONSHOT_API_KEY }}
+          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
+          OPENCODE_API_KEY: ${{ secrets.OPENCODE_API_KEY }}
+          
+          # for Amazon Bedrock (https://docs.pullfrog.com/bedrock)
+          # AWS_BEARER_TOKEN_BEDROCK: ${{ secrets.AWS_BEARER_TOKEN_BEDROCK }}
+          # AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          # AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          # AWS_REGION: us-east-1
+          # BEDROCK_MODEL_ID: <bedrock-model-id>
+          
+          # for Google Vertex AI (https://docs.pullfrog.com/vertex)
+          # VERTEX_SERVICE_ACCOUNT_JSON: >-
+          #   ${{ secrets.VERTEX_SERVICE_ACCOUNT_JSON }}
+          # GOOGLE_CLOUD_PROJECT: my-project
+          # VERTEX_LOCATION: global
+          # VERTEX_MODEL_ID: <vertex-model-id>
+
+          # for any OpenAI-compatible endpoint — LiteLLM, Cloudflare AI Gateway,
+          # self-hosted vLLM (https://docs.pullfrog.com/openai-compatible)
+          # OPENAI_COMPATIBLE_BASE_URL: https://litellm.example.com/v1
+          # OPENAI_COMPATIBLE_API_KEY: ${{ secrets.OPENAI_COMPATIBLE_API_KEY }}
+          # OPENAI_COMPATIBLE_MODEL: <model-id>
+          # both limits are required — set them to the real limits of that model
+          # OPENAI_COMPATIBLE_CONTEXT: "128000"
+          # OPENAI_COMPATIBLE_MAX_OUTPUT: "16384"
diff --git a/CLAUDE.md b/CLAUDE.md
index 877c7eb..50cbd83 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,6 +1,6 @@
 # Split Screen Plugin — AI Agent Guide
 
-All logic lives in a single IIFE in `screen.js`. There is no build step, no bundler, no imports. The plugin is loaded as a plain `<script>` tag by slopsmith core, which means every global it needs (`highway`, `createHighway`, `window.playSong`, `window.showScreen`) must already be on `window` when the script executes.
+All logic lives in a single IIFE in `screen.js`. There is no build step, no bundler, no imports. The plugin is loaded as a plain `<script>` tag by feedBack core, which means every global it needs (`highway`, `createHighway`, `window.playSong`, `window.showScreen`) must already be on `window` when the script executes.
 
 ## Module structure
 
@@ -355,7 +355,7 @@ Follow the lyrics/jumping-tab pattern:
 
 ## Git and PR conventions
 
-- All work goes on feature branches off `main` in this repo (`topkoa/slopsmith-plugin-splitscreen`)
-- PRs target `topkoa/slopsmith-plugin-splitscreen` — NOT `got-feedback/feedBack-plugin-splitscreen` (the upstream)
-- Use `gh pr create --repo topkoa/slopsmith-plugin-splitscreen --base main --head topkoa:<branch>` from inside the plugin directory
-- Do not base feature branches on `upstream/main` — the fork and upstream can diverge; always branch from `origin/main`
+- 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
+- Always branch from `origin/main` — there is no separate upstream remote
diff --git a/README.md b/README.md
index 5a0a8b8..8f9a91a 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
-# Slopsmith Plugin: Split Screen
+# feedBack Plugin: Split Screen
 
-A plugin for [Slopsmith](https://github.com/got-feedback/feedBack) that shows 2–4 highway panels side-by-side during playback, each rendering a different arrangement of the same song. Practice lead and rhythm at once, watch bass against lead, or run a quad view of every arrangement a song has.
+A plugin for [feedBack](https://github.com/got-feedback/feedBack) that shows 2–4 highway panels side-by-side during playback, each rendering a different arrangement of the same song. Practice lead and rhythm at once, watch bass against lead, or run a quad view of every arrangement a song has.
 
 ## Features
 
@@ -22,12 +22,12 @@ A plugin for [Slopsmith](https://github.com/got-feedback/feedBack) that shows 2
 ## Installation
 
 ```bash
-cd /path/to/slopsmith/plugins
-git clone https://github.com/topkoa/slopsmith-plugin-splitscreen.git splitscreen
+cd /path/to/feedBack/plugins
+git clone https://github.com/carochacs/feedBack-plugin-splitscreen.git splitscreen
 docker compose restart
 ```
 
-**Compatibility** — splitscreen runs on any Slopsmith core. On cores with the `highway:visibility` plugin API (~0.2.7.1+), a visualization plugin that mounts a sibling overlay — e.g. the 3D Highway's WebGL overlay — hides itself cleanly while splitscreen is active. On older cores that overlay may bleed through the panels; update the core (and the 3D Highway plugin) to fix it.
+**Compatibility** — splitscreen runs on any feedBack core. On cores with the `highway:visibility` plugin API (~0.2.7.1+), a visualization plugin that mounts a sibling overlay — e.g. the 3D Highway's WebGL overlay — hides itself cleanly while splitscreen is active. On older cores that overlay may bleed through the panels; update the core (and the 3D Highway plugin) to fix it.
 
 ## Usage
 
@@ -305,7 +305,7 @@ Messages arrive in the order listed above. Do not start rendering until you rece
 
 ## Requirements
 
-- Slopsmith with the highway factory (`createHighway()`) and `setRenderer` support exposed on `window` — available in all recent builds (slopsmith#36)
+- feedBack with the highway factory (`createHighway()`) and `setRenderer` support exposed on `window` — available in all recent builds (slopsmith#36)
 - A song with ≥2 arrangements to see any benefit; 1-arrangement songs simply render the same view in every panel
 
 ## Other Plugins
diff --git a/plugin.json b/plugin.json
index 9c2bcfa..8ef39c3 100644
--- a/plugin.json
+++ b/plugin.json
@@ -1,7 +1,7 @@
 {
   "id": "splitscreen",
   "name": "Split Screen",
-  "version": "1.11.0",
+  "version": "1.14.0",
   "private": false,
   "settings": {
     "html": "settings.html",
diff --git a/screen.js b/screen.js
index a71067f..e9377dd 100644
--- a/screen.js
+++ b/screen.js
@@ -22,19 +22,31 @@ try {
     const LAYOUTS = {
         'top-bottom':  { panels: 2, style: 'flex-col' },
         'left-right':  { panels: 2, style: 'flex-row' },
-        'tri-top':     { panels: 3, style: 'grid-tri' },
-        'tri-bottom':  { panels: 3, style: 'grid-tri' },
-        'quad':        { panels: 4, style: 'grid-2x2' },
+        // tri-top/tri-bottom/quad/five/six use CSS grid (cols x rows), not flex —
+        // see applyLayoutStyle for why: flex-wrap:wrap + %-height items inside a
+        // container whose height comes from position insets (not an explicit
+        // height) left wrapped rows non-interactive in some browsers.
+        'tri-top':     { panels: 3, cols: 2, rows: 2, style: 'grid' },
+        'tri-bottom':  { panels: 3, cols: 2, rows: 2, style: 'grid' },
+        'quad':        { panels: 4, cols: 2, rows: 2, style: 'grid' },
+        // 'five' uses a 6-column grid so top-row panels can span 3/6 (half) and
+        // bottom-row panels span 2/6 (a third) — the LCM of 2 and 3 columns.
+        'five':        { panels: 5, cols: 6, rows: 2, style: 'grid' },
+        'six':         { panels: 6, cols: 3, rows: 2, style: 'grid' },
     };
 
     const OFF_CLASS = 'px-3 py-1.5 bg-dark-600 hover:bg-dark-500 rounded-lg text-xs text-gray-300 transition';
     const ON_CLASS  = 'px-3 py-1.5 bg-blue-900/50 hover:bg-blue-900/60 rounded-lg text-xs text-blue-300 transition';
 
-    // v3 host exposes a stable plugin-control slot (the Plugins rail popover).
+    /**
+     * v3 host exposes a stable plugin-control slot (the Plugins rail popover).
+     */
     function _ssIsV3() {
         return !!(window.slopsmith && window.slopsmith.uiVersion === 'v3');
     }
-    // Returns the slot element in v3, or null (classic UI / unavailable).
+    /**
+     * Returns the slot element in v3, or null (classic UI / unavailable).
+     */
     function _ssPlayerControlSlot() {
         if (!(_ssIsV3() && window.slopsmith.ui && typeof window.slopsmith.ui.playerControlSlot === 'function')) return null;
         try { const s = window.slopsmith.ui.playerControlSlot(); return s instanceof Element ? s : null; }
@@ -88,8 +100,10 @@ try {
     // unbind-all ran before this late bind) from a rebuild (the binding is preserved
     // + likely reused by the new panel, so leave it).
     let _ssRealStopGen = 0;
-    // Allocate the lowest free deviceKey (reusing keys freed by unbind), so
-    // switching devices doesn't leak keys until the pool is exhausted.
+    /**
+     * Allocate the lowest free deviceKey (reusing keys freed by unbind), so
+     * switching devices doesn't leak keys until the pool is exhausted.
+     */
     function _ssResolveDeviceKey(name) {
         if (_ssDeviceKeyByName.has(name)) return _ssDeviceKeyByName.get(name);
         const used = new Set(_ssDeviceKeyByName.values());
@@ -100,19 +114,23 @@ try {
     const _ssAudio = () =>
         (typeof window !== 'undefined' && window.feedBackDesktop && window.feedBackDesktop.audio) || null;
 
-    // Suppress / restore the note_detect default singleton (so it doesn't render a
-    // duplicate HUD over panel 1 in split mode). Prefer the plugin's own setter so the
-    // mechanism stays owned by note_detect; fall back to the shared flag on an older build.
+    /**
+     * Suppress / restore the note_detect default singleton (so it doesn't render a
+     * duplicate HUD over panel 1 in split mode). Prefer the plugin's own setter so the
+     * mechanism stays owned by note_detect; fall back to the shared flag on an older build.
+     */
     function _ssSetDefaultSuppressed(v) {
         const cnd = (typeof window !== 'undefined') ? window.createNoteDetector : null;
         if (cnd && typeof cnd.setDefaultSuppressed === 'function') cnd.setDefaultSuppressed(v);
         else if (typeof window !== 'undefined') window.__ndSuppressDefault = !!v;
     }
 
-    // Unbind an extra device once NO panel is using it, freeing its engine slot +
-    // deviceKey. Called when a panel switches away from a device (or is torn down),
-    // so re-picking devices can't accumulate stale binds (which crossed sources +
-    // duplicated scores). No-op for "" (Main) or a device another panel still uses.
+    /**
+     * Unbind an extra device once NO panel is using it, freeing its engine slot +
+     * deviceKey. Called when a panel switches away from a device (or is torn down),
+     * so re-picking devices can't accumulate stale binds (which crossed sources +
+     * duplicated scores). No-op for "" (Main) or a device another panel still uses.
+     */
     async function _ssMaybeUnbindDevice(name) {
         if (!name) return;
         // Still in use if a panel currently has it OR is mid-bind to it (an in-flight
@@ -199,21 +217,34 @@ try {
     // Defaults to panel 0; clicking another panel transfers focus.
     let focusedPanelIdx = 0;
     const focusListeners = new Set();
+    /**
+     * Focused Panel.
+     */
     function _focusedPanel() {
         if (!active || !panels.length) return null;
         if (focusedPanelIdx >= panels.length) focusedPanelIdx = 0;
         return panels[focusedPanelIdx];
     }
+    /**
+     * Emit Focus Change.
+     */
     function _emitFocusChange() {
         for (const fn of focusListeners) {
             try { fn(); } catch (_) { /* listener errors must not break peers */ }
         }
     }
+    /**
+     * Apply Focus Border.
+     */
     function _applyFocusBorder() {
         for (let i = 0; i < panels.length; i++) {
             panels[i].panelDiv.style.borderColor = i === focusedPanelIdx ? '#4080e0' : '#333';
         }
     }
+    /**
+     * Set Focused Panel.
+     * @param {*} idx
+     */
     function _setFocusedPanel(idx) {
         if (idx < 0 || idx >= panels.length) return;
         if (idx === focusedPanelIdx) return;
@@ -221,6 +252,10 @@ try {
         _applyFocusBorder();
         _emitFocusChange();
     }
+    /**
+     * Find Panel Idx By Canvas.
+     * @param {*} canvas
+     */
     function _findPanelIdxByCanvas(canvas) {
         if (!canvas) return -1;
         for (let i = 0; i < panels.length; i++) {
@@ -236,6 +271,10 @@ try {
     // a viz whether it registered under the new or the legacy global — otherwise a
     // migrated viz (e.g. highway_3d) never shows up here.
     const VIZ_FACTORY_PREFIXES = ['feedBackViz_', 'slopsmithViz_'];
+    /**
+     * Viz Factory.
+     * @param {*} id
+     */
     function vizFactory(id) {
         for (let i = 0; i < VIZ_FACTORY_PREFIXES.length; i++) {
             const f = window[VIZ_FACTORY_PREFIXES[i] + id];
@@ -243,9 +282,16 @@ try {
         }
         return undefined;
     }
+    /**
+     * Has Viz Factory.
+     * @param {*} id
+     */
     function hasVizFactory(id) { return typeof vizFactory(id) === 'function'; }
 
     let _vizPluginsFetchFailed = false;
+    /**
+     * Fetch Viz Plugins.
+     */
     async function fetchVizPlugins() {
         try {
             const resp = await fetch('/api/plugins');
@@ -265,6 +311,9 @@ try {
             _rescanVizPluginsFromWindow();
         }
     }
+    /**
+     * Rescan Viz Plugins From Window.
+     */
     function _rescanVizPluginsFromWindow() {
         const seen = new Set();
         const found = [];
@@ -299,6 +348,9 @@ try {
     // way to surface the missing viz options.
     const _seenVizFactoryIds = new Set();
     let _vizFactoryWatchTimer = null;
+    /**
+     * Start Viz Factory Watch.
+     */
     function _startVizFactoryWatch() {
         if (_vizFactoryWatchTimer) return;
         // Seed with factories already present so the first tick only fires
@@ -343,11 +395,13 @@ try {
     // interaction.
     const _vizPluginsReady = fetchVizPlugins();
 
-    // ── LAN share helpers (splitscreen#21) ──
-    // Declared ABOVE the FOLLOWER/REMOTE_JOIN parse and the settings-sync
-    // block, both of which call into these during IIFE evaluation (the
-    // ROOM_KEY_* consts would otherwise be in their temporal dead zone).
-    // WS URL for the core session-sync relay endpoint (feedBack#1030).
+    /**
+     * ── LAN share helpers (splitscreen#21) ──
+     * Declared ABOVE the FOLLOWER/REMOTE_JOIN parse and the settings-sync
+     * block, both of which call into these during IIFE evaluation (the
+     * ROOM_KEY_* consts would otherwise be in their temporal dead zone).
+     * WS URL for the core session-sync relay endpoint (feedBack#1030).
+     */
     function getSyncUrl(key) {
         const proto = location.protocol === 'https:' ? 'wss:' : 'ws:';
         return `${proto}//${location.host}/ws/sync/${key}`;
@@ -359,6 +413,9 @@ try {
     // lands in an empty relay room, and the relay rate-caps scanning.
     const ROOM_KEY_ALPHABET = 'ABCDEFGHJKMNPQRSTVWXYZ23456789';
     const ROOM_KEY_LENGTH = 6;
+    /**
+     * Generate Room Key.
+     */
     function generateRoomKey() {
         let out = '';
         try {
@@ -371,10 +428,12 @@ try {
         return out;
     }
 
-    // Case-insensitive entry: trim + uppercase, then validate against the
-    // alphabet. The filtered alphabet is what makes lookalike tolerance work —
-    // a generated key can never contain 0/O/1/I/L/U, so there is nothing to
-    // mis-map. Returns the canonical uppercase key, or null.
+    /**
+     * Case-insensitive entry: trim + uppercase, then validate against the
+     * alphabet. The filtered alphabet is what makes lookalike tolerance work —
+     * a generated key can never contain 0/O/1/I/L/U, so there is nothing to
+     * mis-map. Returns the canonical uppercase key, or null.
+     */
     function normalizeRoomKey(raw) {
         if (typeof raw !== 'string') return null;
         const key = raw.trim().toUpperCase();
@@ -385,9 +444,11 @@ try {
         return key;
     }
 
-    // The persistent per-install room key (splitscreen#21: saved and reused so
-    // viewer bookmarks keep working across sessions; rotate via the settings
-    // page's Regenerate button).
+    /**
+     * The persistent per-install room key (splitscreen#21: saved and reused so
+     * viewer bookmarks keep working across sessions; rotate via the settings
+     * page's Regenerate button).
+     */
     function ensureRoomKey() {
         let key = null;
         try { key = normalizeRoomKey(localStorage.getItem('splitscreenRoomKey')); } catch (_) {}
@@ -398,15 +459,22 @@ try {
         return key;
     }
 
+    /**
+     * Build Share Url.
+     * @param {*} origin
+     * @param {*} key
+     */
     function buildShareUrl(origin, key) {
         return String(origin).replace(/\/+$/, '') + '/?ss=' + key;
     }
 
-    // Build the FOLLOWER config for a remote viewer from a relay `config`
-    // message. Mirrors the URL-param parse shape, with two deliberate
-    // differences: `remote: true` (gates dock/close semantics) and the
-    // note-detect fields stripped — viewers are passive mirrors and must
-    // never inherit the host's mic/device bindings.
+    /**
+     * Build the FOLLOWER config for a remote viewer from a relay `config`
+     * message. Mirrors the URL-param parse shape, with two deliberate
+     * differences: `remote: true` (gates dock/close semantics) and the
+     * note-detect fields stripped — viewers are passive mirrors and must
+     * never inherit the host's mic/device bindings.
+     */
     function makeRemoteFollowerCfg(msg, popupId) {
         const cfg = (msg && msg.cfg) || {};
         return {
@@ -493,6 +561,9 @@ try {
     })();
     const SS_CHANNEL_NAME = 'slopsmith-ss';
     let ssChannel = null;       // shared BroadcastChannel (lazily opened)
+    /**
+     * Ss Channel.
+     */
     function _ssChannel() {
         if (!ssChannel && typeof BroadcastChannel === 'function') {
             ssChannel = new BroadcastChannel(SS_CHANNEL_NAME);
@@ -602,7 +673,9 @@ try {
             { key: 'cameraLockZoom',  label: 'Locked zoom (In ↔ Out)',   type: 'range',  default: 0.5, min: 0, max: 1, step: 0.05 },
         ],
     };
-    // Range-control bounds with defaults (min/max/step are optional in the descriptor).
+    /**
+     * Range-control bounds with defaults (min/max/step are optional in the descriptor).
+     */
     function _ctlRange(ctl) {
         return {
             lo: Number.isFinite(ctl.min) ? ctl.min : 0,
@@ -610,6 +683,10 @@ try {
             st: Number.isFinite(ctl.step) ? ctl.step : 0.05,
         };
     }
+    /**
+     * Get Panel Controls For.
+     * @param {*} pluginId
+     */
     function getPanelControlsFor(pluginId) {
         // v1: only highway_3d is wired — _vizPanelGet/_vizPanelSet use its
         // localStorage scheme (h3d_bg_panel<N>_<key>) and its window.h3dBgSet*
@@ -666,14 +743,16 @@ try {
         }
     }
 
-    // ── Panel preference persistence ──
-    // Snapshot a live panel into the splitscreenPanelPrefs entry shape. Mode is
-    // encoded into arrName (LYRICS_VALUE / JUMPING_TAB_VALUE:<arr> /
-    // VIZ_PREFIX:<id>:<arr> / plain arrangement name). Single source of truth
-    // for the encoding — used by savePanelPrefs (persist to localStorage),
-    // captureCurrentPrefs (in-memory, for rebuildLayout / _redockPanel) and
-    // popOutPanel (snapshot of the panels left behind). Keep all three on this
-    // helper so a new per-panel field is added once, not three times.
+    /**
+     * ── Panel preference persistence ──
+     * Snapshot a live panel into the splitscreenPanelPrefs entry shape. Mode is
+     * encoded into arrName (LYRICS_VALUE / JUMPING_TAB_VALUE:<arr> /
+     * VIZ_PREFIX:<id>:<arr> / plain arrangement name). Single source of truth
+     * for the encoding — used by savePanelPrefs (persist to localStorage),
+     * captureCurrentPrefs (in-memory, for rebuildLayout / _redockPanel) and
+     * popOutPanel (snapshot of the panels left behind). Keep all three on this
+     * helper so a new per-panel field is added once, not three times.
+     */
     function panelToPrefs(p) {
         return {
             arrName: p.jumpingTabMode
@@ -682,6 +761,7 @@ try {
                 ? VIZ_PREFIX + ':' + p.vizMode + ':' + (arrangements[p.arrIndex]?.name || '')
                 : p.lyricsMode ? LYRICS_VALUE : (arrangements[p.arrIndex]?.name || ''),
             lyrics: !!p.lyricsOverlayOn,
+            chords: !!p.chordsOverlayOn,
             inverted: p.hw.getInverted(),
             lefty: p.hw.getLefty(),
             detectChannel: p.detectChannel || 'mono',
@@ -692,17 +772,24 @@ try {
             name: p.name || '',
         };
     }
+    /**
+     * Save Panel Prefs.
+     */
     function savePanelPrefs() {
         localStorage.setItem(STORAGE_KEY, JSON.stringify(panels.map(panelToPrefs)));
     }
 
-    // Notify cross-plugin consumers (e.g. Camera Director's panel selector) that
-    // the panel set or a panel name changed, via the window.feedBack event bus.
+    /**
+     * Notify cross-plugin consumers (e.g. Camera Director's panel selector) that
+     * the panel set or a panel name changed, via the window.feedBack event bus.
+     */
     function _emitPanelsChanged() {
         try { if (window.feedBack && typeof window.feedBack.emit === 'function') window.feedBack.emit('splitscreen:panels-changed'); } catch (_) { /* ignore */ }
     }
-    // Commit an edited panel name (from the bar input): sanitize, store on the
-    // panel, persist, and notify. Empty falls back to the positional default.
+    /**
+     * Commit an edited panel name (from the bar input): sanitize, store on the
+     * panel, persist, and notify. Empty falls back to the positional default.
+     */
     function _commitPanelName(panelDiv, raw) {
         const i = panels.findIndex((p) => p.panelDiv === panelDiv);
         if (i === -1) return;
@@ -714,6 +801,9 @@ try {
         _emitPanelsChanged();
     }
 
+    /**
+     * Load Panel Prefs.
+     */
     function loadPanelPrefs() {
         try {
             return JSON.parse(localStorage.getItem(STORAGE_KEY)) || null;
@@ -729,6 +819,10 @@ try {
     const PREFS_MIGRATION_KEY = 'splitscreenPrefsMigrationV';
     const PREFS_CURRENT_V = 2;
 
+    /**
+     * Migrate Panel Prefs.
+     * @param {*} prefs
+     */
     function migratePanelPrefs(prefs) {
         if (!Array.isArray(prefs)) return prefs;
         let v = 0;
@@ -756,6 +850,10 @@ try {
         return out;
     }
 
+    /**
+     * Resolve Arr Index.
+     * @param {*} arrName
+     */
     function resolveArrIndex(arrName) {
         if (!arrName || arrName === LYRICS_VALUE || arrName.startsWith(JUMPING_TAB_VALUE) || arrName.startsWith(VIZ_PREFIX + ':')) return -1;
         const lower = arrName.toLowerCase();
@@ -765,10 +863,21 @@ try {
         return -1;
     }
 
-    // ── Helpers ──
+    /**
+     * ── Helpers ──
+     */
     function getWsUrl(filename, arrangement) {
         const proto = location.protocol === 'https:' ? 'wss:' : 'ws:';
-        const arrParam = arrangement !== undefined ? `?arrangement=${arrangement}` : '';
+        // `arrangement` here is a position in the local `arrangements` array
+        // (server-sorted smart-name order). The server's `?arrangement=`
+        // query param indexes into song.arrangements in its *original,
+        // unsorted* storage order — each entry's `.index` field carries that
+        // true index. Translate position -> true index so callers can keep
+        // working in local-array-position terms (dropdown option values, etc).
+        const serverIndex = arrangement !== undefined
+            ? (arrangements[arrangement]?.index ?? arrangement)
+            : undefined;
+        const arrParam = serverIndex !== undefined ? `?arrangement=${serverIndex}` : '';
         // Match core highway.js (`decodeURIComponent(filename)` before
         // building the WS URL — static/highway.js:3575). v3's songs.js
         // calls `playSong(encodeURIComponent(localFilename))`, so
@@ -791,6 +900,10 @@ try {
         return `${proto}//${location.host}/ws/highway/${decoded}${arrParam}`;
     }
 
+    /**
+     * Get Default Arrangements.
+     * @param {*} count
+     */
     function getDefaultArrangements(count) {
         // Assign arrangements intelligently: lead, rhythm, bass, then wrap
         const defaults = [];
@@ -816,6 +929,11 @@ try {
     //  Lyrics-only pane renderer
     // ══════════════════════════════════════════════════════════════════════
 
+    /**
+     * Create Lyrics Pane.
+     * @param {*} container
+     * @param {*} opts
+     */
     function createLyricsPane(container, opts) {
         const overlay = !!(opts && opts.overlay);
         const el = document.createElement('div');
@@ -842,6 +960,10 @@ try {
         let ws = null;
         let raf = null;
 
+        /**
+         * Parse Lyrics.
+         * @param {*} data
+         */
         function parseLyrics(data) {
             lyrics = data;
             lines = null;
@@ -884,11 +1006,20 @@ try {
             lines = result;
         }
 
+        /**
+         * Syllable Text.
+         * @param {*} s
+         */
         function syllableText(s) {
             const t = s.w || '';
             return (t.endsWith('+') || t.endsWith('-')) ? t.slice(0, -1) : t;
         }
 
+        /**
+         * Render Line.
+         * @param {*} lineData
+         * @param {*} currentTime
+         */
         function renderLine(lineData, currentTime) {
             const frag = document.createDocumentFragment();
             for (const word of lineData.words) {
@@ -914,6 +1045,9 @@ try {
             return frag;
         }
 
+        /**
+         * Render.
+         */
         function render() {
             raf = requestAnimationFrame(render);
             if (!lines || !lines.length) {
@@ -969,6 +1103,11 @@ try {
             }
         }
 
+        /**
+         * Connect.
+         * @param {*} filename
+         * @param {*} arrangement
+         */
         function connect(filename, arrangement) {
             destroy();
             ws = new WebSocket(getWsUrl(filename, arrangement));
@@ -981,6 +1120,9 @@ try {
             raf = requestAnimationFrame(render);
         }
 
+        /**
+         * Destroy.
+         */
         function destroy() {
             if (raf) { cancelAnimationFrame(raf); raf = null; }
             if (ws) { ws.close(); ws = null; }
@@ -994,12 +1136,17 @@ try {
 
     // ══════════════════════════════════════════════════════════════════════
 
-    // ── Layout ──
+    /**
+     * ── Layout ──
+     */
     function createWrap() {
         if (wrap) wrap.remove();
         const player = document.getElementById('player');
         wrap = document.createElement('div');
         wrap.id = 'splitscreen-wrap';
+        // Start transparent so startSplitScreen() can fade it in once panels
+        // are ready/sized — avoids a jarring hard cut into split mode.
+        wrap.style.opacity = '0';
         // The wrap is position:absolute relative to #player, so it must be a
         // direct child of #player. Anchor it before the bottom chrome. Core
         // (slopsmith#719) wraps #player-controls in a #player-footer div, so
@@ -1015,37 +1162,74 @@ try {
         return wrap;
     }
 
+    /**
+     * Apply Layout Style.
+     * @param {*} container
+     * @param {*} layoutKey
+     */
     function applyLayoutStyle(container, layoutKey) {
         // Note: bottom is set dynamically by sizeCanvases() to leave room for global controls
-        container.style.cssText =
-            'position:absolute;top:0;left:0;right:0;z-index:3;display:flex;';
-        if (layoutKey === 'top-bottom') {
-            container.style.flexDirection = 'column';
-        } else if (layoutKey === 'left-right') {
-            container.style.flexDirection = 'row';
+        const cfg = LAYOUTS[layoutKey];
+        if (cfg && cfg.style === 'grid') {
+            // CSS grid avoids the flex `height:50%` resolution ambiguity that left
+            // wrapped rows non-interactive: the wrap's height comes from position
+            // insets (top/bottom set by sizeCanvases()), not an explicit height
+            // property, and some browsers treat that as indefinite for % height
+            // resolution inside a flex-wrap container — collapsing or
+            // mis-positioning bottom-row panels so they can't be clicked/focused.
+            // grid-template-columns/rows size cells from the container's
+            // available space directly, bypassing % height resolution entirely.
+            container.style.cssText =
+                'position:absolute;top:0;left:0;right:0;z-index:3;display:grid;opacity:0;' +
+                'grid-template-columns:repeat(' + cfg.cols + ',1fr);' +
+                'grid-template-rows:repeat(' + cfg.rows + ',1fr);';
         } else {
-            container.style.flexDirection = 'row';
-            container.style.flexWrap = 'wrap';
+            container.style.cssText =
+                'position:absolute;top:0;left:0;right:0;z-index:3;display:flex;opacity:0;';
+            if (layoutKey === 'top-bottom') {
+                container.style.flexDirection = 'column';
+            } else if (layoutKey === 'left-right') {
+                container.style.flexDirection = 'row';
+            } else {
+                container.style.flexDirection = 'row';
+                container.style.flexWrap = 'wrap';
+            }
         }
     }
 
+    /**
+     * Create Panel.
+     * @param {*} index
+     * @param {*} container
+     * @param {*} layoutKey
+     */
     function createPanel(index, container, layoutKey) {
         const panelDiv = document.createElement('div');
         panelDiv.className = 'splitscreen-panel';
         panelDiv.style.cssText = 'position:relative;overflow:hidden;box-sizing:border-box;border:1px solid #333;';
 
-        if (layoutKey === 'quad') {
-            panelDiv.style.width = '50%';
-            panelDiv.style.height = '50%';
+        const _cfg = LAYOUTS[layoutKey];
+        if (_cfg && _cfg.style === 'grid') {
+            // CSS grid sizes the cells — no explicit width/height needed on the
+            // item. min-width/min-height:0 stops the canvas from overflowing its
+            // cell (grid items otherwise refuse to shrink below their content size).
+            panelDiv.style.minWidth = '0';
+            panelDiv.style.minHeight = '0';
+            if (layoutKey === 'tri-top' && index === 0) {
+                // Panel 0 spans the full top row; panels 1-2 auto-flow onto row 2.
+                panelDiv.style.gridColumn = '1 / span 2';
+            } else if (layoutKey === 'tri-bottom' && index === 2) {
+                // Panels 0-1 auto-flow across row 1; panel 2 spans the full bottom row.
+                panelDiv.style.gridColumn = '1 / span 2';
+            } else if (layoutKey === 'five') {
+                // Top row: 2 wide panels (half the 6-col grid each); bottom row:
+                // 3 narrow panels (a third each). Auto-flow places them in order.
+                panelDiv.style.gridColumn = index < 2 ? 'span 3' : 'span 2';
+            }
+            // quad / six: uniform cells, no explicit span needed.
         } else if (layoutKey === 'left-right') {
             panelDiv.style.width = '50%';
             panelDiv.style.height = '100%';
-        } else if (layoutKey === 'tri-top') {
-            panelDiv.style.width = index === 0 ? '100%' : '50%';
-            panelDiv.style.height = '50%';
-        } else if (layoutKey === 'tri-bottom') {
-            panelDiv.style.width = index === 2 ? '100%' : '50%';
-            panelDiv.style.height = '50%';
         } else if (layoutKey === 'follower') {
             panelDiv.style.width = '100%';
             panelDiv.style.height = '100%';
@@ -1135,6 +1319,14 @@ try {
         const updateLyricsStyle = (on) => styleToggle(lyricsBtn, on, '#065f46');
         bar.appendChild(lyricsBtn);
 
+        // Hidden unless window.createFretboardOverlay is available (the
+        // fretboard plugin's per-panel factory export) — same
+        // capability-check pattern as the jumping-tab / viz buttons.
+        const chordsBtn = makeToggleBtn('Chords');
+        const updateChordsStyle = (on) => styleToggle(chordsBtn, on, '#7c2d12');
+        chordsBtn.style.display = 'none';
+        bar.appendChild(chordsBtn);
+
         const tabBtn = makeToggleBtn('Tab');
         const updateTabStyle = (on) => styleToggle(tabBtn, on, '#1e40af');
         updateTabStyle(false);
@@ -1307,6 +1499,7 @@ try {
             invertBtn, updateInvertStyle,
             leftyBtn, updateLeftyStyle,
             lyricsBtn, updateLyricsStyle,
+            chordsBtn, updateChordsStyle,
             tabBtn, updateTabStyle,
             detectBtn, updateDetectStyle,
             channelBtn, deviceSelect, latWrap, latVal, latDown, latUp,
@@ -1316,8 +1509,34 @@ try {
         };
     }
 
+    // sizeCanvases() reads #section-map's height every time it runs, but is
+    // only ever called from window resize / activation / layout-change /
+    // controls-toggle — not when the Section Map bar (an independent plugin)
+    // changes its OWN height/visibility on its own schedule. Lazily attach a
+    // ResizeObserver to it (retried on every sizeCanvases() call until the
+    // element exists, since that plugin may not have built its bar yet the
+    // first time this runs) so panels reflow whenever it does, not just on
+    // the next window resize.
+    let _sectionMapObserver = null;
+    /**
+     * Watch Section Map.
+     */
+    function _watchSectionMap() {
+        if (_sectionMapObserver || typeof ResizeObserver !== 'function') return;
+        const sm = document.getElementById('section-map');
+        if (!sm) return;
+        _sectionMapObserver = new ResizeObserver(() => {
+            if (active && !FOLLOWER) sizeCanvases();
+        });
+        _sectionMapObserver.observe(sm);
+    }
+
+    /**
+     * Size Canvases.
+     */
     function sizeCanvases() {
         if (!wrap || !panels.length) return;
+        _watchSectionMap();
         // Bottom chrome is #player-footer (wraps #player-controls + the Section
         // Practice bar) on current cores; fall back to #player-controls alone on
         // older cores that have no footer wrapper.
@@ -1336,21 +1555,23 @@ try {
             } else if (!p.lyricsMode) {
                 p.hw.resize();
             }
+            if (p.chordsOverlay) p.chordsOverlay.resize();
         }
     }
 
-    // ── Highway re-creation (fixes issue #22: charts mix on mid-song arrangement switch) ──
-    // hw.reconnect() / hw.connect() in core close+reopen the WS, but the OLD WS's
-    // onmessage handler is bound with a closure that still references the same
-    // outer-scope `notes`/`chords` arrays. Pending messages from the old socket
-    // can fire after the arrays are cleared, leaking the previous chart's data
-    // into the new arrangement. Replacing the highway instance entirely orphans
-    // the old closure so late messages can't pollute the new chart.
+    /**
+     * ── Highway re-creation (fixes issue #22: charts mix on mid-song arrangement switch) ──
+     * hw.reconnect() / hw.connect() in core close+reopen the WS, but the OLD WS's
+     * onmessage handler is bound with a closure that still references the same
+     * outer-scope `notes`/`chords` arrays. Pending messages from the old socket
+     * can fire after the arrays are cleared, leaking the previous chart's data
+     * into the new arrangement. Replacing the highway instance entirely orphans
+     * the old closure so late messages can't pollute the new chart.
+     */
     function recreatePanelHighway(panel, opts) {
         const old = panel.hw;
         const inverted = old.getInverted();
         const lefty = old.getLefty();
-        const lyricsVisible = typeof old.getLyricsVisible === 'function' ? old.getLyricsVisible() : true;
         const mastery = old.getMastery();
         old.stop();
 
@@ -1390,19 +1611,45 @@ try {
         hw.init(panel.canvas);
         hw.setInverted(inverted);
         hw.setLefty(lefty);
-        if (typeof hw.setLyricsVisible === 'function') hw.setLyricsVisible(lyricsVisible);
+        // Always false: the panel's own DOM lyrics overlay (createLyricsPane)
+        // is the single lyrics display for splitscreen panels, working
+        // uniformly across every renderer. Leaving the highway's built-in
+        // flag on double-renders full lyric text — the default 2D renderer's
+        // drawLyrics() draws its own copy, and viz plugins that read
+        // bundle.lyricsVisible (e.g. 3D Highway) draw a third.
+        if (typeof hw.setLyricsVisible === 'function') hw.setLyricsVisible(false);
         hw.setMastery(mastery);
         hw.resize();
         panel.hw = hw;
+
+        // toggleDetect() captures `highway: panel.hw` by value when the detector
+        // is created — leaving it bound to the just-discarded `old` highway
+        // here would orphan it on a stopped instance that never tracks the
+        // new chart. Rebuild it against the fresh `hw` if it was live.
+        if (panel.detector) {
+            toggleDetect(panel);
+            toggleDetect(panel);
+        }
+
+        // panel.canvas was just replaced with a fresh element (context-type
+        // lock workaround above). External consumers of the documented
+        // window.slopsmithSplitscreen API (panelIndexFor/panelChromeFor/
+        // settingsAnchorFor/isCanvasFocused) that cached the old canvas from
+        // getPanels() would silently stop resolving this panel — notify so
+        // they can refresh their reference. Fires on every arrangement
+        // switch and viz mode enter/exit, both of which call this function.
+        _emitPanelsChanged();
     }
 
-    // ── Per-panel viz controls ("3D ⚙" popover) ──
-    // Per-panel values live in the viz plugin's own per-panel localStorage keys
-    // (highway_3d: h3d_bg_panel<N>_<key>, fallback global h3d_bg_<key>) — NOT in
-    // splitscreenPanelPrefs. Writing the per-panel key is enough for the 3D
-    // renderer (it re-reads all settings each frame); for instant-rebuild
-    // settings (palette) we also re-fire the plugin's global setter with its
-    // existing value so _bgEmitChange runs. No global state changes hands.
+    /**
+     * ── Per-panel viz controls ("3D ⚙" popover) ──
+     * Per-panel values live in the viz plugin's own per-panel localStorage keys
+     * (highway_3d: h3d_bg_panel<N>_<key>, fallback global h3d_bg_<key>) — NOT in
+     * splitscreenPanelPrefs. Writing the per-panel key is enough for the 3D
+     * renderer (it re-reads all settings each frame); for instant-rebuild
+     * settings (palette) we also re-fire the plugin's global setter with its
+     * existing value so _bgEmitChange runs. No global state changes hands.
+     */
     function _vizPanelGet(pluginId, panelIdx, ctl) {
         let v = null;
         try {
@@ -1419,6 +1666,13 @@ try {
         }
         return v;
     }
+    /**
+     * Viz Panel Set.
+     * @param {*} pluginId
+     * @param {*} panelIdx
+     * @param {*} ctl
+     * @param {*} value
+     */
     function _vizPanelSet(pluginId, panelIdx, ctl, value) {
         try { localStorage.setItem('h3d_bg_panel' + panelIdx + '_' + ctl.key, String(value)); } catch (_) {}
         // Re-fire the plugin's global setter with the global's *current* value
@@ -1448,6 +1702,11 @@ try {
         try { setter(v); } catch (_) {}
     }
 
+    /**
+     * Build Viz Popover.
+     * @param {*} panel
+     * @param {*} pluginId
+     */
     function buildVizPopover(panel, pluginId) {
         const pop = panel.vizPopover;
         if (!pop) return;
@@ -1510,6 +1769,11 @@ try {
         }
     }
 
+    /**
+     * Show Viz Controls.
+     * @param {*} panel
+     * @param {*} pluginId
+     */
     function _showVizControls(panel, pluginId) {
         if (!panel.vizSettingsBtn) return;
         const ctrls = getPanelControlsFor(pluginId);
@@ -1517,10 +1781,17 @@ try {
         buildVizPopover(panel, pluginId);
         panel.vizSettingsBtn.style.display = '';
     }
+    /**
+     * Hide Viz Controls.
+     * @param {*} panel
+     */
     function _hideVizControls(panel) {
         if (panel.vizSettingsBtn) panel.vizSettingsBtn.style.display = 'none';
         if (panel.vizPopover) { panel.vizPopover.style.display = 'none'; panel.vizPopover.innerHTML = ''; }
     }
+    /**
+     * Close All Viz Popovers.
+     */
     function _closeAllVizPopovers() {
         for (const p of panels) if (p.vizPopover) p.vizPopover.style.display = 'none';
     }
@@ -1531,7 +1802,9 @@ try {
         _closeAllVizPopovers();
     }, true);
 
-    // ── Mastery slider helpers ──
+    /**
+     * ── Mastery slider helpers ──
+     */
     function hookPanelReady(panel) {
         panel.masterySlider.disabled = true;
         panel.masterySlider.style.opacity = '0.4';
@@ -1548,7 +1821,9 @@ try {
         };
     }
 
-    // ── Panel lifecycle ──
+    /**
+     * ── Panel lifecycle ──
+     */
     function populateSelect(panel, arrIndex) {
         // If /api/plugins fetch failed earlier, re-scan window for viz
         // factories every time the dropdown is built — covers viz plugin
@@ -1599,23 +1874,57 @@ try {
         }
     }
 
+    /**
+     * Enter Lyrics Mode.
+     * @param {*} panel
+     */
     function enterLyricsMode(panel) {
         if (panel.lyricsMode) return;
 
         if (panel.vizMode) exitVizMode(panel, panel.arrIndex);
         if (panel.jumpingTabMode) exitJumpingTabMode(panel, panel.arrIndex);
         if (panel.tabActive) togglePanelTab(panel);
+        // Detect on/off isn't persisted in prefs (only channel/device/offset
+        // are) — it's a purely in-session toggle. With detectBtn about to be
+        // hidden the user would have no way to stop a live detector while in
+        // this mode, so turn it off (before the highway stops and the button
+        // hides) rather than leave it scoring against an already-stopped
+        // highway with an inaccessible control.
+        if (panel.detector) toggleDetect(panel);
         panel.hw.stop();
         panel.canvas.style.display = 'none';
 
-        // Hide highway-specific buttons and mastery slider
+        // Hide highway-specific buttons and mastery slider. Lyrics/Detect/Channel
+        // are meaningless once the highway is stopped and the canvas is hidden —
+        // leaving lyricsBtn live lets the per-panel lyrics overlay spawn on top
+        // of the full lyrics pane, duplicating the text.
         panel.invertBtn.style.display = 'none';
         panel.leftyBtn.style.display = 'none';
         panel.tabBtn.style.display = 'none';
+        panel.lyricsBtn.style.display = 'none';
+        panel.chordsBtn.style.display = 'none';
+        if (panel.detectBtn) panel.detectBtn.style.display = 'none';
+        if (panel.channelBtn) panel.channelBtn.style.display = 'none';
         panel.masteryHeading.style.display = 'none';
         panel.masterySlider.style.display = 'none';
         panel.masteryLabel.style.display = 'none';
         _hideVizControls(panel);
+        // Destroy the per-panel lyrics overlay so it doesn't stack visibly on
+        // top of the full lyrics pane, duplicating the text. lyricsOverlayOn
+        // is left untouched so the overlay comes back on exit if it was on.
+        if (panel.lyricsOverlay) {
+            panel.lyricsOverlay.destroy();
+            panel.lyricsOverlay.el.remove();
+            panel.lyricsOverlay = null;
+        }
+        // Same for the chords overlay — the highway is about to stop, so its
+        // getNotes()/getChords()/getTime() would just freeze rather than
+        // update, leaving a stale fretboard sitting on top of the lyrics
+        // pane. chordsOverlayOn is left untouched so it comes back on exit.
+        if (panel.chordsOverlay) {
+            panel.chordsOverlay.destroy();
+            panel.chordsOverlay = null;
+        }
 
         panel.lyricsPane = createLyricsPane(panel.panelDiv);
         panel.lyricsPane.el.style.bottom = (panel.bar.offsetHeight || 28) + 'px';
@@ -1626,6 +1935,11 @@ try {
         savePanelPrefs();
     }
 
+    /**
+     * Exit Lyrics Mode.
+     * @param {*} panel
+     * @param {*} arrIndex
+     */
     function exitLyricsMode(panel, arrIndex) {
         if (!panel.lyricsMode) return;
 
@@ -1639,36 +1953,85 @@ try {
         panel.invertBtn.style.display = '';
         panel.leftyBtn.style.display = '';
         panel.tabBtn.style.display = '';
+        panel.lyricsBtn.style.display = '';
+        panel.chordsBtn.style.display = (typeof window.createFretboardOverlay === 'function') ? '' : 'none';
+        if (panel.detectBtn) panel.detectBtn.style.display = '';
+        if (panel.channelBtn) panel.channelBtn.style.display = '';
         panel.masteryHeading.style.display = '';
         panel.masterySlider.style.display = '';
         panel.masteryLabel.style.display = '';
         panel.lyricsMode = false;
 
         panel.hw.init(panel.canvas);
+        // Force false after every init(), same as recreatePanelHighway —
+        // init() may reset the highway's internal renderer state (including
+        // this flag) back to its true default even on a reused instance.
+        if (typeof panel.hw.setLyricsVisible === 'function') panel.hw.setLyricsVisible(false);
         panel.hw.resize();
         panel.arrIndex = arrIndex;
         panel.arrName.textContent = arrangements[arrIndex]?.name || '';
         hookPanelReady(panel);
         panel.hw.connect(getWsUrl(currentFilename, arrIndex), { onSongInfo: () => {} });
+        // Restore the per-panel lyrics overlay if it was on before entering
+        // lyrics mode. Never enable the highway's built-in lyrics flag here
+        // — the overlay is the only lyrics display splitscreen panels use;
+        // see recreatePanelHighway for why.
+        if (panel.lyricsOverlayOn) {
+            panel.lyricsOverlay = createLyricsPane(panel.panelDiv, { overlay: true });
+            panel.lyricsOverlay.connect(currentFilename, 0);
+        }
+        // Restore the per-panel chords overlay if it was on before entering
+        // lyrics mode.
+        if (panel.chordsOverlayOn && typeof window.createFretboardOverlay === 'function') {
+            panel.chordsOverlay = window.createFretboardOverlay({
+                container: panel.panelDiv,
+                getHighway: () => panel.hw,
+                bottomOffset: () => panel.bar.offsetHeight,
+            });
+        }
         savePanelPrefs();
     }
 
+    /**
+     * Enter Jumping Tab Mode.
+     * @param {*} panel
+     */
     function enterJumpingTabMode(panel) {
         if (panel.jumpingTabMode) return;
 
         if (panel.vizMode) exitVizMode(panel, panel.arrIndex);
         if (panel.lyricsMode) exitLyricsMode(panel, panel.arrIndex);
         if (panel.tabActive) togglePanelTab(panel);
+        // Detect on/off isn't persisted in prefs (only channel/device/offset
+        // are) — it's a purely in-session toggle. With detectBtn about to be
+        // hidden the user would have no way to stop a live detector while in
+        // this mode, so turn it off (before the highway stops and the button
+        // hides) rather than leave it scoring against an already-stopped
+        // highway with an inaccessible control.
+        if (panel.detector) toggleDetect(panel);
         panel.hw.stop();
         panel.canvas.style.display = 'none';
 
         panel.invertBtn.style.display = 'none';
         panel.leftyBtn.style.display = 'none';
         panel.tabBtn.style.display = 'none';
+        panel.lyricsBtn.style.display = 'none';
+        panel.chordsBtn.style.display = 'none';
+        if (panel.detectBtn) panel.detectBtn.style.display = 'none';
+        if (panel.channelBtn) panel.channelBtn.style.display = 'none';
         panel.masteryHeading.style.display = 'none';
         panel.masterySlider.style.display = 'none';
         panel.masteryLabel.style.display = 'none';
         _hideVizControls(panel);
+        if (panel.lyricsOverlay) {
+            panel.lyricsOverlay.destroy();
+            panel.lyricsOverlay.el.remove();
+            panel.lyricsOverlay = null;
+        }
+        if (panel.chordsOverlay) {
+            panel.chordsOverlay.destroy();
+            panel.chordsOverlay = null;
+        }
 
         const jtContainer = document.createElement('div');
         jtContainer.style.cssText =
@@ -1691,6 +2054,11 @@ try {
         savePanelPrefs();
     }
 
+    /**
+     * Exit Jumping Tab Mode.
+     * @param {*} panel
+     * @param {*} arrIndex
+     */
     function exitJumpingTabMode(panel, arrIndex) {
         if (!panel.jumpingTabMode) return;
 
@@ -1707,20 +2075,48 @@ try {
         panel.invertBtn.style.display = '';
         panel.leftyBtn.style.display = '';
         panel.tabBtn.style.display = '';
+        panel.lyricsBtn.style.display = '';
+        panel.chordsBtn.style.display = (typeof window.createFretboardOverlay === 'function') ? '' : 'none';
+        if (panel.detectBtn) panel.detectBtn.style.display = '';
+        if (panel.channelBtn) panel.channelBtn.style.display = '';
         panel.masteryHeading.style.display = '';
         panel.masterySlider.style.display = '';
         panel.masteryLabel.style.display = '';
         panel.jumpingTabMode = false;
 
         panel.hw.init(panel.canvas);
+        // Force false after every init(), same as recreatePanelHighway —
+        // init() may reset the highway's internal renderer state (including
+        // this flag) back to its true default even on a reused instance.
+        if (typeof panel.hw.setLyricsVisible === 'function') panel.hw.setLyricsVisible(false);
         panel.hw.resize();
         panel.arrIndex = arrIndex;
         panel.arrName.textContent = arrangements[arrIndex]?.name || '';
         hookPanelReady(panel);
         panel.hw.connect(getWsUrl(currentFilename, arrIndex), { onSongInfo: () => {} });
+        // Never enable the highway's built-in lyrics flag here — the overlay
+        // is the only lyrics display splitscreen panels use; see
+        // recreatePanelHighway for why.
+        if (panel.lyricsOverlayOn) {
+            panel.lyricsOverlay = createLyricsPane(panel.panelDiv, { overlay: true });
+            panel.lyricsOverlay.connect(currentFilename, 0);
+        }
+        if (panel.chordsOverlayOn && typeof window.createFretboardOverlay === 'function') {
+            panel.chordsOverlay = window.createFretboardOverlay({
+                container: panel.panelDiv,
+                getHighway: () => panel.hw,
+                bottomOffset: () => panel.bar.offsetHeight,
+            });
+        }
         savePanelPrefs();
     }
 
+    /**
+     * Enter Viz Mode.
+     * @param {*} panel
+     * @param {*} pluginId
+     * @param {*} rendererPreInstalled
+     */
     function enterVizMode(panel, pluginId, rendererPreInstalled) {
         if (panel.vizMode) return;
 
@@ -1779,6 +2175,11 @@ try {
         savePanelPrefs();
     }
 
+    /**
+     * Exit Viz Mode.
+     * @param {*} panel
+     * @param {*} arrIndex
+     */
     function exitVizMode(panel, arrIndex) {
         if (!panel.vizMode) return;
 
@@ -1815,6 +2216,12 @@ try {
         savePanelPrefs();
     }
 
+    /**
+     * Init Panel.
+     * @param {*} panel
+     * @param {*} arrIndex
+     * @param {*} prefs
+     */
     function initPanel(panel, arrIndex, prefs) {
         const isLyricsMode = prefs?.arrName === LYRICS_VALUE;
         const isJumpingTabMode = prefs?.arrName?.startsWith(JUMPING_TAB_VALUE) || false;
@@ -1837,6 +2244,8 @@ try {
         panel.lyricsPane = null;
         panel.lyricsOverlay = null;
         panel.lyricsOverlayOn = false;
+        panel.chordsOverlay = null;
+        panel.chordsOverlayOn = false;
         panel.jumpingTabMode = false;
         panel.jumpingTabPane = null;
         panel.jumpingTabContainer = null;
@@ -1865,13 +2274,13 @@ try {
 
         panel.hw.init(panel.canvas);
 
-        // Apply saved preferences
+        // Apply saved preferences. Lyrics are handled below by
+        // _toggleLyricsOverlay, which is the sole source of truth for
+        // splitscreen's lyrics display — never set the highway's built-in
+        // lyrics flag from prefs here.
         if (prefs && !isLyricsMode && !isJumpingTabMode) {
             if (prefs.inverted !== undefined) panel.hw.setInverted(prefs.inverted);
             if (prefs.lefty !== undefined) panel.hw.setLefty(prefs.lefty);
-            if (prefs.lyrics !== undefined && typeof panel.hw.setLyricsVisible === 'function') {
-                panel.hw.setLyricsVisible(prefs.lyrics);
-            }
         }
 
         const savedMastery = (prefs?.mastery !== undefined) ? prefs.mastery : 1;
@@ -2025,8 +2434,16 @@ try {
         // so it works regardless of which renderer (2D, piano, drums, 3D
         // Highway, future viz) owns the canvas. Future-proof: any new viz
         // plugin gets lyric support for free without modification.
-        // Also keeps the highway's built-in setLyricsVisible (in-canvas
-        // underline cue) in sync — complementary to the overlay text.
+        //
+        // The highway's built-in setLyricsVisible is ALWAYS kept false here,
+        // never synced to `on`. It defaults to true on a fresh highway, and
+        // every renderer that respects it draws its own full lyric text —
+        // the default 2D renderer's drawLyrics(), and viz plugins that read
+        // bundle.lyricsVisible (e.g. 3D Highway). Passing `on` through used
+        // to turn overlay-on into a double lyrics render (DOM overlay text +
+        // the renderer's own copy) on top of whichever renderer is active.
+        // Forcing it false unconditionally still suppresses that default-true
+        // for panels with the overlay off, without ever re-enabling it.
         panel.lyricsOverlayOn = prefs?.lyrics === true;
         const _toggleLyricsOverlay = (on) => {
             if (on) {
@@ -2043,15 +2460,14 @@ try {
                 panel.lyricsOverlay = null;
             }
             if (typeof panel.hw.setLyricsVisible === 'function') {
-                panel.hw.setLyricsVisible(on);
+                panel.hw.setLyricsVisible(false);
             }
             panel.updateLyricsStyle(on);
         };
-        // Always invoke _toggleLyricsOverlay so the highway's built-in
-        // lyricsVisible flag (which feeds bundle.lyricsVisible consumed by
-        // viz renderers like 3D highway) is synced to the saved toggle
-        // state. Without this, viz panels with overlay off would still
-        // render lyrics because the built-in flag defaults to true.
+        // Always invoke _toggleLyricsOverlay (even off) so the highway's
+        // built-in lyricsVisible flag is forced false on init — it defaults
+        // to true on a fresh highway, and the overlay is the only lyrics
+        // display splitscreen panels should ever show.
         _toggleLyricsOverlay(panel.lyricsOverlayOn);
         panel.lyricsBtn.onclick = () => {
             panel.lyricsOverlayOn = !panel.lyricsOverlayOn;
@@ -2059,6 +2475,40 @@ try {
             savePanelPrefs();
         };
 
+        // Per-panel chord diagrams (fretboard overlay), mirroring the lyrics
+        // overlay above. window.createFretboardOverlay is the fretboard
+        // plugin's multi-instance factory export (feedBack-plugin-fretboard's
+        // own single global toggle is untouched by this — each panel here
+        // gets its own independent instance bound to that panel's own `hw`,
+        // so it reflects that panel's chart even though the main highway is
+        // hidden while splitscreen is active). Hidden entirely when the
+        // fretboard plugin isn't loaded.
+        const hasFretboardFactory = typeof window.createFretboardOverlay === 'function';
+        panel.chordsBtn.style.display = hasFretboardFactory ? '' : 'none';
+        panel.chordsOverlayOn = hasFretboardFactory && prefs?.chords === true;
+        const _toggleChordsOverlay = (on) => {
+            if (panel.chordsOverlay) {
+                panel.chordsOverlay.destroy();
+                panel.chordsOverlay = null;
+            }
+            if (on && hasFretboardFactory) {
+                panel.chordsOverlay = window.createFretboardOverlay({
+                    container: panel.panelDiv,
+                    getHighway: () => panel.hw,
+                    bottomOffset: () => panel.bar.offsetHeight,
+                });
+            }
+            panel.updateChordsStyle(on);
+        };
+        if (hasFretboardFactory) {
+            _toggleChordsOverlay(panel.chordsOverlayOn);
+            panel.chordsBtn.onclick = () => {
+                panel.chordsOverlayOn = !panel.chordsOverlayOn;
+                _toggleChordsOverlay(panel.chordsOverlayOn);
+                savePanelPrefs();
+            };
+        }
+
         // Per-panel Highway/Tab mode toggle (uses tabview factory)
         const hasTabFactory = typeof window.createTabView === 'function';
         if (hasTabFactory) {
@@ -2124,6 +2574,10 @@ try {
         }
     }
 
+    /**
+     * Toggle Panel Tab.
+     * @param {*} panel
+     */
     async function togglePanelTab(panel) {
         if (panel.tabActive) {
             // Back to highway
@@ -2146,9 +2600,10 @@ try {
         panel.tabBtn.disabled = true;
         try {
             const decoded = decodeURIComponent(currentFilename);
+            const serverIndex = arrangements[panel.arrIndex]?.index ?? panel.arrIndex;
             const url = '/api/plugins/tabview/gp5/' +
                 encodeURIComponent(decoded) +
-                '?arrangement=' + panel.arrIndex;
+                '?arrangement=' + serverIndex;
             const resp = await fetch(url);
             if (!resp.ok) throw new Error(await resp.text());
             const data = await resp.arrayBuffer();
@@ -2163,7 +2618,7 @@ try {
             const tv = window.createTabView({
                 container: tabContainer,
                 getBeats: () => panel.hw.getBeats(),
-                getCurrentTime: () => document.getElementById('audio').currentTime,
+                getCurrentTime: () => { const a = document.getElementById('audio'); return a ? a.currentTime : 0; },
             });
             await tv.load(data);
             tv.startSync();
@@ -2182,6 +2637,10 @@ try {
         }
     }
 
+    /**
+     * Toggle Detect.
+     * @param {*} panel
+     */
     function toggleDetect(panel) {
         if (panel.detector) {
             panel.detector.destroy();
@@ -2210,6 +2669,10 @@ try {
         panel.updateDetectStyle(true);
     }
 
+    /**
+     * Cycle Detect Channel.
+     * @param {*} panel
+     */
     function cycleDetectChannel(panel) {
         // mono / left / right only — multi-channel selection (ch3+) is deferred (see
         // DETECT_CHANNEL_CYCLE). Each panel binds its OWN device via the picker, so a
@@ -2223,9 +2686,11 @@ try {
         savePanelPrefs();
     }
 
-    // Nudge a panel's detection-timing offset (ms) and apply it live to its bound
-    // source. Lets the user dial in an extra device's capture latency by watching
-    // the score peak. Clamped to ±250 ms.
+    /**
+     * Nudge a panel's detection-timing offset (ms) and apply it live to its bound
+     * source. Lets the user dial in an extra device's capture latency by watching
+     * the score peak. Clamped to ±250 ms.
+     */
     function _ssNudgeOffset(panel, delta) {
         const next = Math.max(-250, Math.min(250, (panel.detectVerifierOffsetMs || 0) + delta));
         panel.detectVerifierOffsetMs = next;
@@ -2240,8 +2705,10 @@ try {
         savePanelPrefs();
     }
 
-    // Populate + wire the per-panel input DEVICE picker. No-op (and the dropdown
-    // stays hidden) unless the desktop bridge exposes the Phase 2 multi-device API.
+    /**
+     * Populate + wire the per-panel input DEVICE picker. No-op (and the dropdown
+     * stays hidden) unless the desktop bridge exposes the Phase 2 multi-device API.
+     */
     async function setupDevicePicker(panel) {
         const sel = panel.deviceSelect;
         if (!sel) return;
@@ -2299,11 +2766,13 @@ try {
         sel.onchange = () => { _ssApplyDevice(panel, sel.value); };
     }
 
-    // Resolve + bind the chosen device, set the panel's deviceKey, and rebind a live
-    // detector. SERIALIZED per panel: each device change runs after the previous one
-    // fully completes (bind + old-device unbind), so overlapping picks (A then B
-    // before A's bind resolves) can't apply out of order and leave the panel on the
-    // wrong device. Returns the chain tail so callers can await the actual apply.
+    /**
+     * Resolve + bind the chosen device, set the panel's deviceKey, and rebind a live
+     * detector. SERIALIZED per panel: each device change runs after the previous one
+     * fully completes (bind + old-device unbind), so overlapping picks (A then B
+     * before A's bind resolves) can't apply out of order and leave the panel on the
+     * wrong device. Returns the chain tail so callers can await the actual apply.
+     */
     function _ssApplyDevice(panel, name) {
         panel._ssDeviceChain = (panel._ssDeviceChain || Promise.resolve())
             .catch(() => {})
@@ -2311,8 +2780,10 @@ try {
         return panel._ssDeviceChain;
     }
 
-    // "" = primary input. (A source's device is fixed at allocation, so a live
-    // detector is torn down + rebuilt to move it.)
+    /**
+     * "" = primary input. (A source's device is fixed at allocation, so a live
+     * detector is torn down + rebuilt to move it.)
+     */
     async function _ssApplyDeviceImpl(panel, name) {
         // Record the device THIS panel is (about to be) bound to for the whole async
         // operation, BEFORE detectDeviceName is updated — so a concurrent
@@ -2326,6 +2797,11 @@ try {
         }
     }
 
+    /**
+     * Ss Apply Device Body.
+     * @param {*} panel
+     * @param {*} name
+     */
     async function _ssApplyDeviceBody(panel, name) {
         const audio = _ssAudio();
         const startStopGen = _ssRealStopGen;  // detect a REAL stop racing this bind
@@ -2404,6 +2880,11 @@ try {
         savePanelPrefs();
     }
 
+    /**
+     * Switch Panel Arrangement.
+     * @param {*} panel
+     * @param {*} arrIndex
+     */
     function switchPanelArrangement(panel, arrIndex) {
         panel.arrIndex = arrIndex;
         panel.arrName.textContent = arrangements[arrIndex]?.name || '';
@@ -2413,6 +2894,9 @@ try {
         panel.hw.connect(getWsUrl(currentFilename, arrIndex), { onSongInfo: () => {} });
     }
 
+    /**
+     * Teardown Panels.
+     */
     function teardownPanels() {
         // Flip active + notify focus listeners up-front. All callers
         // (stopSplitScreen, rebuildLayout, popOutPanel, _redockPanel) need
@@ -2474,6 +2958,10 @@ try {
                 p.lyricsOverlay.el.remove();
                 p.lyricsOverlay = null;
             }
+            if (p.chordsOverlay) {
+                p.chordsOverlay.destroy();
+                p.chordsOverlay = null;
+            }
             if (p.jumpingTabPane) {
                 p.jumpingTabPane.destroy();
                 p.jumpingTabPane = null;
@@ -2499,6 +2987,10 @@ try {
     //  Pop-out / dock helpers
     // ══════════════════════════════════════════════════════════════════════
 
+    /**
+     * Capture Mode.
+     * @param {*} panel
+     */
     function _captureMode(panel) {
         if (panel.lyricsMode) return 'lyrics';
         if (panel.jumpingTabMode) return 'jt';
@@ -2506,14 +2998,16 @@ try {
         return '2d';
     }
 
-    // Decode a captured panel mode into the saved-prefs `arrName` form.
-    // Shared by _redockPanel and _followerCfgToPrefs so the popup-and-back
-    // round-trip produces the same prefs the main-window flow would.
-    //
-    // Legacy: pre-PR-36 popups encoded 3D Highway as cfg.mode === '3d'
-    // rather than 'viz:highway_3d'. Map it explicitly so a popup that was
-    // opened on an older build and is now docking back lands on the
-    // correct renderer instead of silently falling back to 2D.
+    /**
+     * Decode a captured panel mode into the saved-prefs `arrName` form.
+     * Shared by _redockPanel and _followerCfgToPrefs so the popup-and-back
+     * round-trip produces the same prefs the main-window flow would.
+     *
+     * Legacy: pre-PR-36 popups encoded 3D Highway as cfg.mode === '3d'
+     * rather than 'viz:highway_3d'. Map it explicitly so a popup that was
+     * opened on an older build and is now docking back lands on the
+     * correct renderer instead of silently falling back to 2D.
+     */
     function _modeToArrName(mode, arrNameStr) {
         if (mode === 'lyrics') return LYRICS_VALUE;
         if (mode === 'jt') return JUMPING_TAB_VALUE + ':' + arrNameStr;
@@ -2522,6 +3016,10 @@ try {
         return arrNameStr;
     }
 
+    /**
+     * Capture Follower Config.
+     * @param {*} panel
+     */
     function _captureFollowerConfig(panel) {
         return {
             arrangement: panel.arrIndex || 0,
@@ -2544,6 +3042,9 @@ try {
         };
     }
 
+    /**
+     * New Popup Id.
+     */
     function _newPopupId() {
         try {
             return crypto.randomUUID();
@@ -2556,6 +3057,10 @@ try {
     // for pop-out failures). Top-centre pill, fades in next frame, auto-removes
     // after ~3.5 s; a new call replaces any in-flight one.
     let _mainToastEl = null;
+    /**
+     * Show Main Toast.
+     * @param {*} msg
+     */
     function _showMainToast(msg) {
         try {
             if (_mainToastEl) { _mainToastEl.remove(); _mainToastEl = null; }
@@ -2583,11 +3088,22 @@ try {
         } catch (_) { /* DOM not ready / detached — silently drop */ }
     }
 
-    // Open a popup window pre-configured to show this panel as a follower.
-    // The panel is removed from the main layout once the popup is opened
-    // (slot collapses; rebuildLayout reflows remaining panels).
+    /**
+     * Open a popup window pre-configured to show this panel as a follower.
+     * The panel is removed from the main layout once the popup is opened
+     * (slot collapses; rebuildLayout reflows remaining panels).
+     */
     function popOutPanel(panel) {
         if (!currentFilename) return;
+        // A start is in flight (e.g. this is the very first pop-out of the
+        // session and startSplitScreen is still awaiting _vizPluginsReady).
+        // teardownPanels() below would rip out that half-built layout out
+        // from under it — bail instead of racing it, same hazard rebuildLayout()
+        // and _redockPanel() already guard against via `_starting`.
+        if (_starting) {
+            _showMainToast('Split screen is still starting — try popping out again in a moment.');
+            return;
+        }
         const idx = panels.indexOf(panel);
         if (idx === -1) return;
         if (typeof BroadcastChannel !== 'function') {
@@ -2694,11 +3210,20 @@ try {
         }
     }
 
-    // Called from the popup when the user clicks Dock. Posts the panel's
-    // current state back to the main window, then closes. Sets _followerDocking
-    // so the beforeunload handler skips the redundant `closed` post — `docked`
-    // already tells the main to re-instate the panel, and a trailing `closed`
-    // could race ahead of a deferred _redockPanel and drop the popups entry.
+    /**
+     * Called from the popup when the user clicks Dock. Posts state back to the
+     * main window, then closes. Sets _followerDocking so the beforeunload
+     * handler skips the redundant `closed` post — `docked` already tells the
+     * main to re-instate the panel(s), and a trailing `closed` could race
+     * ahead of a deferred _redockPanel and drop the popups entry.
+     *
+     * The popup can itself be split into up to 4 sub-panels (rebuildFollowerLayout).
+     * `popups` on the main side tracks one entry per popup WINDOW, not per
+     * sub-panel, so we capture EVERY current sub-panel here (`finalStates`,
+     * plural) rather than just the one whose Dock button was clicked —
+     * otherwise closing the window on a single sub-panel's dock silently
+     * discards the other 1-3 sub-panels' state.
+     */
     function dockFollowerPanel(panel) {
         if (!FOLLOWER) return;
         if (FOLLOWER.remote) return;   // LAN viewers have nothing to dock into
@@ -2709,14 +3234,37 @@ try {
                 ch.postMessage({
                     type: 'docked',
                     popupId: FOLLOWER.popupId,
+                    // Keep `finalState` (singular) for the common 1-panel-popup
+                    // case / older main builds; add `finalStates` (all of this
+                    // popup's current sub-panels, in on-screen order) for the
+                    // multi-panel case.
                     finalState: _captureFollowerConfig(panel),
+                    finalStates: panels.map(p => _captureFollowerConfig(p)),
                 });
             }
         } catch (_) {}
         try { window.close(); } catch (_) {}
     }
 
-    // ── Main toggle ──
+    /**
+     * Dock every currently popped-out panel back into this window at once.
+     * Broadcasts a `dock-all` request rather than reaching into each popup's
+     * state directly — every live popup reacts via its own dockFollowerPanel
+     * (the SAME per-panel path its own Dock button uses), so each redock
+     * carries the popup's actual live sub-panel state and closes itself, and
+     * `_redockPanel`'s existing `_starting` single-flight queue (main side)
+     * already serialises concurrent `docked` replies safely — no extra guard
+     * needed here for the bulk case.
+     */
+    function dockAllPanels() {
+        if (popups.size === 0) return;
+        const ch = _ssChannel();
+        if (ch) ch.postMessage({ type: 'dock-all' });
+    }
+
+    /**
+     * ── Main toggle ──
+     */
     function rebuildLayout() {
         // A start is in flight (e.g. user changed the layout select while the
         // initial start was awaiting _vizPluginsReady). Tearing down now would
@@ -2736,10 +3284,18 @@ try {
         if (wasActive) startSplitScreen(null, savedPrefs);
     }
 
+    /**
+     * Capture Current Prefs.
+     */
     function captureCurrentPrefs() {
         return panels.map(panelToPrefs);
     }
 
+    /**
+     * Start Split Screen.
+     * @param {*} existingArrangements
+     * @param {*} savedPrefs
+     */
     async function startSplitScreen(existingArrangements, savedPrefs) {
         // Re-entrancy guard: prevent concurrent starts from double-clicks,
         // layout rebuilds, or auto-reactivate firing while a start is in flight.
@@ -2903,6 +3459,14 @@ try {
 
         // Hook into the time sync loop
         startTimeSync();
+
+        // Fade the wrap in now that all panels are built and sized — matches
+        // the fade pattern used elsewhere in this codebase (_showMainToast,
+        // player HUD) so entering split isn't a jarring hard cut.
+        if (wrap) {
+            wrap.style.transition = 'opacity 0.15s ease-in';
+            wrap.style.opacity = '1';
+        }
         } catch (err) {
             // Rollback any partial state so the UI doesn't get stuck with
             // active=true, default highway hidden, and no panels — that's
@@ -2941,7 +3505,7 @@ try {
             // reflows the final panel set including the redocked one.
             while (_pendingRedocks.length && !_starting) {
                 const r = _pendingRedocks.shift();
-                _redockPanel(r.popupId, r.finalState);
+                _redockPanel(r.popupId, r.finalState, r.finalStates);
             }
             // Drain a queued rebuild from rebuildLayout. Only fire if the
             // session is still active — a failed start above already did
@@ -2953,7 +3517,11 @@ try {
         }
     }
 
+    /**
+     * Stop Split Screen.
+     */
     function stopSplitScreen() {
+        if (_stopFadeTimer) { clearTimeout(_stopFadeTimer); _stopFadeTimer = null; }
         savePanelPrefs();
         teardownPanels();  // flips active=false + emits focus change
         // Defensive clear at full-session-end. Well-behaved plugins
@@ -2986,13 +3554,43 @@ try {
         stopTimeSync();
     }
 
+    let _stopFadeTimer = null;
+
+    /**
+     * Fade the wrap out, then run the real stop once the transition has had
+     * time to play. Only used for the user-initiated Stop (toggle()) — the
+     * navigation-driven auto-stop paths (song change, leaving the player)
+     * call stopSplitScreen() directly and synchronously, since those rely on
+     * `active` flipping immediately (e.g. before a new song's _play() runs).
+     *
+     * A stop is already in flight until stopSplitScreen() actually runs and
+     * flips `active`, so repeated toggle() calls while fading out would each
+     * re-enter here — guard against scheduling more than one stop.
+     */
+    function _fadeOutWrapThenStop() {
+        if (_stopFadeTimer) return;
+        if (wrap) {
+            wrap.style.transition = 'opacity 0.12s ease-out';
+            wrap.style.opacity = '0';
+            _stopFadeTimer = setTimeout(() => {
+                _stopFadeTimer = null;
+                stopSplitScreen();
+            }, 130);
+            return;
+        }
+        stopSplitScreen();
+    }
+
+    /**
+     * Toggle.
+     */
     function toggle() {
         if (_starting) return; // treat in-flight start as already active
         if (active) {
             // User-intent off — persist so navigation-driven stops (song
             // switch, leaving player) don't erase the user's on-state.
             try { localStorage.setItem('splitscreenActive', 'false'); } catch (_) {}
-            stopSplitScreen();
+            _fadeOutWrapThenStop();
         } else {
             startSplitScreen();
         }
@@ -3001,6 +3599,9 @@ try {
     // ── Time sync ──
     let syncInterval = null;
 
+    /**
+     * Start Time Sync.
+     */
     function startTimeSync() {
         stopTimeSync();
         const audio = document.getElementById('audio');
@@ -3013,6 +3614,9 @@ try {
         }, 1000 / 60);
     }
 
+    /**
+     * Stop Time Sync.
+     */
     function stopTimeSync() {
         if (syncInterval) {
             clearInterval(syncInterval);
@@ -3033,6 +3637,9 @@ try {
     // when a new popup registers and when the broadcaster stops — see
     // popOutPanel / _stopPopupBroadcaster.
     let _lastBroadcastTime = null;
+    /**
+     * Start Popup Broadcaster.
+     */
     function _startPopupBroadcaster() {
         if (_popupBroadcastInterval) return;
         const audio = document.getElementById('audio');
@@ -3045,9 +3652,11 @@ try {
             // forced close / OS kill): otherwise their slot lingers and we'd
             // keep broadcasting to nobody at 60 Hz indefinitely. popup.closed
             // is a cheap same-origin boolean.
+            let _reaped = false;
             for (const [id, e] of popups) {
-                if (e.popup && e.popup.closed) popups.delete(id);
+                if (e.popup && e.popup.closed) { popups.delete(id); _reaped = true; }
             }
+            if (_reaped) updateBtn(); // keep Dock all's visibility in sync promptly
             if (popups.size === 0 && !_lanShare) { _stopPopupBroadcaster(); return; }
             // Only broadcast when the playhead actually moved — skips ~60
             // redundant structured-clone messages/sec (and the follower's
@@ -3067,6 +3676,9 @@ try {
             }
         }, 1000 / 60);
     }
+    /**
+     * Stop Popup Broadcaster.
+     */
     function _stopPopupBroadcaster() {
         if (_popupBroadcastInterval) {
             clearInterval(_popupBroadcastInterval);
@@ -3101,6 +3713,10 @@ try {
     // indistinguishable while cutting relay traffic to a third.
     const LAN_TIME_MIN_INTERVAL_MS = 50;
 
+    /**
+     * Lan Send.
+     * @param {*} msg
+     */
     function _lanSend(msg) {
         const ws = _lanShare && _lanShare.ws;
         if (!ws || ws.readyState !== 1) return;
@@ -3112,8 +3728,10 @@ try {
         try { ws.send(JSON.stringify(msg)); } catch (_) {}
     }
 
-    // Answer a viewer's `hello`. No song loaded yet → answer nothing; the
-    // viewer hello-polls until a config with a filename can be produced.
+    /**
+     * Answer a viewer's `hello`. No song loaded yet → answer nothing; the
+     * viewer hello-polls until a config with a filename can be produced.
+     */
     function _lanHelloResponse(popupId) {
         if (!_lanShare || !currentFilename) return null;
         const audio = document.getElementById('audio');
@@ -3127,6 +3745,9 @@ try {
         };
     }
 
+    /**
+     * Lan Connect.
+     */
     function _lanConnect() {
         if (!_lanShare || _lanShare.ws) return;
         let ws;
@@ -3150,6 +3771,9 @@ try {
         ws.onerror = () => { try { ws.close(); } catch (_) {} };
     }
 
+    /**
+     * Lan Schedule Reconnect.
+     */
     function _lanScheduleReconnect() {
         if (!_lanShare || _lanShare.retryTimer) return;
         const delay = _lanShare.backoffMs || 1000;
@@ -3161,14 +3785,20 @@ try {
         }, delay);
     }
 
-    // Capture `panel` as the shared config — with the note-detect fields
-    // stripped (viewers are passive mirrors; never forward mic bindings).
+    /**
+     * Capture `panel` as the shared config — with the note-detect fields
+     * stripped (viewers are passive mirrors; never forward mic bindings).
+     */
     function _lanCaptureCfg(panel) {
         return Object.assign(_captureFollowerConfig(panel), {
             detectChannel: 'mono', detectDeviceName: '', detectVerifierOffsetMs: 0,
         });
     }
 
+    /**
+     * Start Lan Share.
+     * @param {*} panel
+     */
     function startLanShare(panel) {
         if (typeof WebSocket !== 'function') {
             _showMainToast('LAN sharing requires WebSocket support.');
@@ -3187,6 +3817,9 @@ try {
         return true;
     }
 
+    /**
+     * Stop Lan Share.
+     */
     function stopLanShare() {
         if (!_lanShare) return;
         _lanSend({ type: 'share-ended' });   // terminal for viewers — before teardown
@@ -3200,9 +3833,11 @@ try {
         } catch (_) {}
     }
 
-    // Re-arm a share that was active when this window last unloaded (crash,
-    // reload, app relaunch) so viewers left open on other devices recover
-    // without any interaction — the crash-recovery contract (splitscreen#21).
+    /**
+     * Re-arm a share that was active when this window last unloaded (crash,
+     * reload, app relaunch) so viewers left open on other devices recover
+     * without any interaction — the crash-recovery contract (splitscreen#21).
+     */
     function _maybeResumeLanShare() {
         if (FOLLOWER || REMOTE_JOIN || _lanShare) return;
         if (typeof WebSocket !== 'function') return;
@@ -3217,10 +3852,12 @@ try {
         } catch (_) {}
     }
 
-    // Copy with a non-secure-context fallback. LAN hosts are frequently plain
-    // http (e.g. a Docker session at http://192.168.x.x), where
-    // navigator.clipboard does not exist — fall back to the classic
-    // hidden-textarea + execCommand('copy') path. Resolves true on success.
+    /**
+     * Copy with a non-secure-context fallback. LAN hosts are frequently plain
+     * http (e.g. a Docker session at http://192.168.x.x), where
+     * navigator.clipboard does not exist — fall back to the classic
+     * hidden-textarea + execCommand('copy') path. Resolves true on success.
+     */
     function _copyTextToClipboard(text) {
         return new Promise((resolve) => {
             try {
@@ -3234,6 +3871,10 @@ try {
             resolve(_copyViaExecCommand(text));
         });
     }
+    /**
+     * Copy Via Exec Command.
+     * @param {*} text
+     */
     function _copyViaExecCommand(text) {
         try {
             const ta = document.createElement('textarea');
@@ -3257,9 +3898,15 @@ try {
     // Docker session, location.origin is already the address the viewer needs.
     let _lanShareModalEl = null;
     let _lanShareModalSeq = 0;   // invocation nonce — see the await note below
+    /**
+     * Close Lan Share Modal.
+     */
     function _closeLanShareModal() {
         if (_lanShareModalEl) { try { _lanShareModalEl.remove(); } catch (_) {} _lanShareModalEl = null; }
     }
+    /**
+     * Show Lan Share Modal.
+     */
     async function _showLanShareModal() {
         // The getLanAccess() await below yields: a second invocation entering
         // meanwhile would otherwise stack a second overlay on top of this
@@ -3376,11 +4023,13 @@ try {
     // ══════════════════════════════════════════════════════════════════════
     let _mainChannelListenerAttached = false;
     let _mainAudioListenersEl = null;   // the <audio> the play/pause listeners are bound to
-    // Broadcast the current play/pause state to any popups so they can pause
-    // their time extrapolation precisely (instead of relying solely on the
-    // "audio time stopped advancing" heuristic + backstop). Best-effort: in
-    // JUCE mode the <audio> element's play/pause events may not fire — the
-    // follower's heuristic still covers that case.
+    /**
+     * Broadcast the current play/pause state to any popups so they can pause
+     * their time extrapolation precisely (instead of relying solely on the
+     * "audio time stopped advancing" heuristic + backstop). Best-effort: in
+     * JUCE mode the <audio> element's play/pause events may not fire — the
+     * follower's heuristic still covers that case.
+     */
     function _broadcastMainPlayState() {
         try {
             const ch = _ssChannel();
@@ -3391,6 +4040,9 @@ try {
             _lanSend(msg);
         } catch (_) {}
     }
+    /**
+     * Ensure Main Broadcaster And Listener.
+     */
     function _ensureMainBroadcasterAndListener() {
         if (FOLLOWER) return;            // never run in popup
         // Two independently-guarded halves. The channel handler is once-ever;
@@ -3408,7 +4060,7 @@ try {
             if (ch) ch.onmessage = (ev) => {
                 const msg = ev.data || {};
                 if (msg.type === 'docked' && msg.popupId && popups.has(msg.popupId)) {
-                    _redockPanel(msg.popupId, msg.finalState || null);
+                    _redockPanel(msg.popupId, msg.finalState || null, msg.finalStates || null);
                 } else if (msg.type === 'closed' && msg.popupId && popups.has(msg.popupId)) {
                     // Popup was closed without an explicit Dock click. Treat
                     // the panel as removed; don't re-add. Just drop the entry —
@@ -3430,46 +4082,97 @@ try {
         }
     }
 
-    // Re-instate a panel that was popped out, using the original config
-    // we captured at pop-out time, overlaid with anything the popup told
-    // us via `finalState`.
-    function _redockPanel(popupId, finalState) {
+    /**
+     * Re-instate a panel that was popped out, using the original config
+     * we captured at pop-out time, overlaid with anything the popup told
+     * us via `finalState`.
+     * Smallest LAYOUTS entry with room for `n` panels; falls back to the
+     * largest available layout if nothing fits (caller must then truncate).
+     */
+    function _bestFitLayout(n) {
+        let best = null;
+        for (const k of Object.keys(LAYOUTS)) {
+            if (LAYOUTS[k].panels >= n && (!best || LAYOUTS[k].panels < LAYOUTS[best].panels)) best = k;
+        }
+        if (best) return best;
+        return Object.keys(LAYOUTS).reduce((a, b) => (LAYOUTS[b].panels > LAYOUTS[a].panels ? b : a));
+    }
+
+    /**
+     * Redock Panel.
+     * @param {*} popupId
+     * @param {*} finalState
+     * @param {*} finalStates
+     */
+    function _redockPanel(popupId, finalState, finalStates) {
         // A start (e.g. the rebuild that follows a pop-out) is in flight —
         // tearing down now would race the in-flight panel build. Queue it;
         // startSplitScreen's finally drains _pendingRedocks. Don't delete
         // the popups entry yet — the deferred call needs it.
-        if (_starting) { _pendingRedocks.push({ popupId, finalState }); return; }
+        if (_starting) { _pendingRedocks.push({ popupId, finalState, finalStates }); return; }
         const entry = popups.get(popupId);
         if (!entry) return;
         popups.delete(popupId);
-        if (!currentFilename) return;
+        if (!currentFilename) {
+            _showMainToast('Could not dock panel — no song is currently loaded.');
+            return;
+        }
 
-        // Decide where to slot the redocked panel back. If split is currently
-        // active, capture the running prefs and append; otherwise start split
-        // fresh with just this one panel.
-        const merged = Object.assign({}, entry.originalConfig, finalState || {});
-        const arrName = _modeToArrName(merged.mode, arrangements[merged.arrangement]?.name || '');
-        const newPrefs = {
-            arrName,
-            // Restore the per-panel toggles captured at pop-out time (and
-            // optionally overlaid with whatever the popup last reported via
-            // finalState) instead of forcing fresh defaults.
-            lyrics: !!merged.lyrics,
-            inverted: !!merged.inverted,
-            lefty: !!merged.lefty,
-            detectChannel: merged.detectChannel || 'mono',
-            detectDeviceName: merged.detectDeviceName || '',
-            detectVerifierOffsetMs: Number.isFinite(merged.detectVerifierOffsetMs) ? merged.detectVerifierOffsetMs : 0,
-            barHidden: !!merged.barHidden,
-            mastery: Number.isFinite(merged.mastery) ? merged.mastery : 1,
-        };
+        // A popup that split itself into multiple sub-panels sends `finalStates`
+        // (one capture per sub-panel, in on-screen order); fall back to the
+        // single `finalState` for older/1-panel popups. Only the FIRST state
+        // is merged against `entry.originalConfig` (the panel that was
+        // originally popped out) — the rest were created fresh inside the
+        // popup's own layout and have no corresponding pre-pop-out config to
+        // merge against; their captures are already self-sufficient (see
+        // _captureFollowerConfig).
+        const states = (Array.isArray(finalStates) && finalStates.length > 0)
+            ? finalStates
+            : [finalState || {}];
+
+        const newPrefsList = states.map((state, i) => {
+            const merged = i === 0 ? Object.assign({}, entry.originalConfig, state || {}) : (state || {});
+            const arrName = _modeToArrName(merged.mode, arrangements[merged.arrangement]?.name || '');
+            return {
+                arrName,
+                // Restore the per-panel toggles captured at pop-out time (and
+                // optionally overlaid with whatever the popup last reported)
+                // instead of forcing fresh defaults.
+                lyrics: !!merged.lyrics,
+                inverted: !!merged.inverted,
+                lefty: !!merged.lefty,
+                detectChannel: merged.detectChannel || 'mono',
+                detectDeviceName: merged.detectDeviceName || '',
+                detectVerifierOffsetMs: Number.isFinite(merged.detectVerifierOffsetMs) ? merged.detectVerifierOffsetMs : 0,
+                barHidden: !!merged.barHidden,
+                mastery: Number.isFinite(merged.mastery) ? merged.mastery : 1,
+            };
+        });
 
         let savedPrefs;
         if (active) {
             savedPrefs = captureCurrentPrefs();
-            savedPrefs.push(newPrefs);
+            savedPrefs.push(...newPrefsList);
         } else {
-            savedPrefs = [newPrefs];
+            savedPrefs = newPrefsList;
+        }
+
+        // Grow the layout to fit everything being redocked — otherwise
+        // startSplitScreen only builds LAYOUTS[layout].panels slots and the
+        // newly-docked panel(s) at the tail of savedPrefs are silently
+        // dropped when the current layout is already at (or near) capacity.
+        const fit = _bestFitLayout(savedPrefs.length);
+        if (LAYOUTS[fit].panels > (LAYOUTS[layout]?.panels || 0)) {
+            layout = fit;
+            try { localStorage.setItem('splitscreenLayout', layout); } catch (_) {}
+        }
+        if (savedPrefs.length > LAYOUTS[layout].panels) {
+            // Every layout is full (6-panel max) — keep what fits, drop the
+            // rest rather than silently discarding via the modulo in
+            // startSplitScreen with no explanation.
+            const dropped = savedPrefs.length - LAYOUTS[layout].panels;
+            savedPrefs = savedPrefs.slice(0, LAYOUTS[layout].panels);
+            _showMainToast('Only room for ' + LAYOUTS[layout].panels + ' panels — ' + dropped + ' docked panel' + (dropped === 1 ? '' : 's') + ' dropped.');
         }
 
         if (active) {
@@ -3487,6 +4190,9 @@ try {
     // ── Layout cycle button ──
     let layoutBtn = null;
 
+    /**
+     * Create Layout Btn.
+     */
     function createLayoutBtn() {
         if (layoutBtn) return layoutBtn;
         const slot = _ssPlayerControlSlot();
@@ -3505,6 +4211,8 @@ try {
             { value: 'tri-top',     label: '⊤ 1+2' },
             { value: 'tri-bottom',  label: '⊥ 2+1' },
             { value: 'quad',        label: '⊞ Quad' },
+            { value: 'five',        label: '⊟ Five' },
+            { value: 'six',         label: '⊞ Six' },
         ];
         for (const o of options) {
             const opt = document.createElement('option');
@@ -3523,7 +4231,9 @@ try {
         return layoutBtn;
     }
 
-    // ── Player HUD fade (top-left song title fades out once playback begins) ──
+    /**
+     * ── Player HUD fade (top-left song title fades out once playback begins) ──
+     */
     function showHud() {
         const hud = document.getElementById('player-hud');
         if (!hud) return;
@@ -3531,6 +4241,9 @@ try {
         hud.style.opacity = '1';
     }
 
+    /**
+     * Fade Out Hud.
+     */
     function fadeOutHud() {
         const hud = document.getElementById('player-hud');
         if (!hud) return;
@@ -3538,6 +4251,9 @@ try {
         hud.style.opacity = '0';
     }
 
+    /**
+     * Restore Hud.
+     */
     function restoreHud() {
         const hud = document.getElementById('player-hud');
         if (!hud) return;
@@ -3545,6 +4261,9 @@ try {
         hud.style.opacity = '';
     }
 
+    /**
+     * On Audio Play.
+     */
     function onAudioPlay() {
         if (active) fadeOutHud();
     }
@@ -3564,6 +4283,10 @@ try {
         'viz-picker',
     ];
 
+    /**
+     * Set Redundant Controls Hidden.
+     * @param {*} hide
+     */
     function setRedundantControlsHidden(hide) {
         for (const id of REDUNDANT_CONTROL_IDS) {
             const el = document.getElementById(id);
@@ -3574,7 +4297,11 @@ try {
     // ── Hide/show controls bar ──
     let hideBtn = null;
     let floatBtn = null;
+    let dockAllBtn = null;
 
+    /**
+     * Create Hide Btn.
+     */
     function createHideBtn() {
         if (hideBtn) return hideBtn;
         const slot = _ssPlayerControlSlot();
@@ -3601,6 +4328,32 @@ try {
         return hideBtn;
     }
 
+    /**
+     * Create Dock All Btn. A bulk "dock every popped-out panel" control,
+     * visible only while >=1 panel is currently popped out (see updateBtn).
+     */
+    function createDockAllBtn() {
+        if (dockAllBtn) return dockAllBtn;
+        const slot = _ssPlayerControlSlot();
+        const c = slot || document.getElementById('player-controls');
+        if (!c) return null;
+        if (_ssIsV3() && !slot) return null;  // v3 mounts exclusively into the slot
+        dockAllBtn = document.createElement('button');
+        dockAllBtn.id = 'btn-splitscreen-dock-all';
+        dockAllBtn.className = OFF_CLASS;
+        dockAllBtn.textContent = '⇲ Dock all';
+        dockAllBtn.title = 'Dock every popped-out panel back into this window';
+        dockAllBtn.style.display = 'none';
+        dockAllBtn.onclick = dockAllPanels;
+        const closeBtn = c.querySelector('button[onclick*="showScreen"]');
+        if (closeBtn) c.insertBefore(dockAllBtn, closeBtn);
+        else c.appendChild(dockAllBtn);
+        return dockAllBtn;
+    }
+
+    /**
+     * Create Floating Show Btn.
+     */
     function createFloatingShowBtn() {
         if (floatBtn) return floatBtn;
         const player = document.getElementById('player');
@@ -3618,6 +4371,10 @@ try {
         return floatBtn;
     }
 
+    /**
+     * Toggle Panel Bar.
+     * @param {*} panel
+     */
     function togglePanelBar(panel) {
         const hiding = panel.bar.style.display !== 'none';
         panel.bar.style.display = hiding ? 'none' : '';
@@ -3644,9 +4401,13 @@ try {
         } else if (!panel.lyricsMode) {
             panel.hw.resize();
         }
+        if (panel.chordsOverlay) panel.chordsOverlay.resize();
         savePanelPrefs();
     }
 
+    /**
+     * Toggle Controls Visibility.
+     */
     function toggleControlsVisibility() {
         controlsHidden = !controlsHidden;
         localStorage.setItem('splitscreenControlsHidden', controlsHidden);
@@ -3656,7 +4417,9 @@ try {
         updateBtn();
     }
 
-    // ── Toggle button ──
+    /**
+     * ── Toggle button ──
+     */
     function updateBtn() {
         const btn = document.getElementById('btn-splitscreen');
         if (btn) btn.className = active ? ON_CLASS : OFF_CLASS;
@@ -3666,8 +4429,16 @@ try {
             hideBtn.textContent = controlsHidden ? '▴ Bar' : '▾ Bar';
         }
         if (floatBtn) floatBtn.style.display = (active && controlsHidden) ? '' : 'none';
+        // Independent of `active`: popping out every panel can leave split
+        // mode inactive in the main window (popOutPanel's last-panel-popped
+        // path calls stopSplitScreen()) while the popup(s) are still live —
+        // Dock all must stay visible so the user can get them back.
+        if (dockAllBtn) dockAllBtn.style.display = popups.size > 0 ? '' : 'none';
     }
 
+    /**
+     * Inject Btn.
+     */
     function injectBtn() {
         // v3: mount split-screen controls into the host's stable plugin-control
         // slot (Plugins rail popover). In v3 the slot is always present, so the
@@ -3695,6 +4466,7 @@ try {
         createLayoutBtn();
         createHideBtn();
         createFloatingShowBtn();
+        createDockAllBtn();
     }
 
     // ── Resize handler ──
@@ -3852,6 +4624,10 @@ try {
     // backstop in case a `playstate:false` (pause) message is dropped.
     const _FOLLOWER_MAX_EXTRAP_S = 2.0;
 
+    /**
+     * Install Follower Audio Shim.
+     * @param {*} audio
+     */
     function _installFollowerAudioShim(audio) {
         if (!audio) return;
         try {
@@ -3878,9 +4654,11 @@ try {
     // song change — doesn't stack listeners; also covers a hypothetical
     // element swap).
     let _followerPlayGuardEl = null;
-    // Keep the popup's <audio> paused — and re-pause it whenever anything
-    // calls .play() (autoplay, a src swap on song change). Mute alone leaves
-    // it decoding the stream for nothing.
+    /**
+     * Keep the popup's <audio> paused — and re-pause it whenever anything
+     * calls .play() (autoplay, a src swap on song change). Mute alone leaves
+     * it decoding the stream for nothing.
+     */
     function _silenceFollowerAudio(audio) {
         if (!audio) return;
         audio.muted = true;
@@ -3892,9 +4670,11 @@ try {
         }
     }
 
-    // rAF loop that advances _followerCurrentTime between `time` broadcasts
-    // while the main window reports playback. Idempotent; cancelled on
-    // orphan / unload.
+    /**
+     * rAF loop that advances _followerCurrentTime between `time` broadcasts
+     * while the main window reports playback. Idempotent; cancelled on
+     * orphan / unload.
+     */
     function _startFollowerInterp() {
         if (_followerInterpRaf != null) return;
         const tick = () => {
@@ -3910,21 +4690,26 @@ try {
         };
         _followerInterpRaf = requestAnimationFrame(tick);
     }
+    /**
+     * Stop Follower Interp.
+     */
     function _stopFollowerInterp() {
         if (_followerInterpRaf != null) { cancelAnimationFrame(_followerInterpRaf); _followerInterpRaf = null; }
     }
 
-    // Handle a `time` broadcast: derive playback rate vs wall-time, re-anchor,
-    // fan the value out to every panel highway.
-    //
-    // The most reliable "is it playing" signal is observing the broadcast
-    // clock itself advance in real time (dT/dWall ≈ playbackRate) — that works
-    // regardless of whether the main window's <audio>.paused is meaningful
-    // (it isn't, in JUCE mode). The optional `playing` flag on the message is
-    // only used to STOP extrapolating when the clock has also stalled: it lets
-    // us tell "main paused" from "main tab throttled to ~1 Hz" within the gap
-    // between messages, which the clock alone can't. The 2 s extrapolation
-    // backstop covers the case where the flag is absent/unreliable.
+    /**
+     * Handle a `time` broadcast: derive playback rate vs wall-time, re-anchor,
+     * fan the value out to every panel highway.
+     *
+     * The most reliable "is it playing" signal is observing the broadcast
+     * clock itself advance in real time (dT/dWall ≈ playbackRate) — that works
+     * regardless of whether the main window's <audio>.paused is meaningful
+     * (it isn't, in JUCE mode). The optional `playing` flag on the message is
+     * only used to STOP extrapolating when the clock has also stalled: it lets
+     * us tell "main paused" from "main tab throttled to ~1 Hz" within the gap
+     * between messages, which the clock alone can't. The 2 s extrapolation
+     * backstop covers the case where the flag is absent/unreliable.
+     */
     function _onFollowerTimeMessage(t, playing) {
         const nowP = performance.now();
         let advancedInRealtime = false;
@@ -3964,7 +4749,9 @@ try {
         _maybeDismissFollowerToastOnPlay(t);
     }
 
-    // Handle an explicit play/pause notice from the main window.
+    /**
+     * Handle an explicit play/pause notice from the main window.
+     */
     function _onFollowerPlayState(playing) {
         _followerPlaying = playing;
         if (playing) {
@@ -3979,8 +4766,10 @@ try {
         }
     }
 
-    // The main window is closing — stop syncing, tear the panels down, and
-    // tell the user. Idempotent.
+    /**
+     * The main window is closing — stop syncing, tear the panels down, and
+     * tell the user. Idempotent.
+     */
     function _onFollowerOrphaned(title, subText) {
         if (_followerOrphaned) return;
         _followerOrphaned = true;
@@ -4007,7 +4796,7 @@ try {
             'font-family:sans-serif;text-align:center;padding:24px;';
         const h = document.createElement('div');
         h.style.cssText = 'font-size:18px;font-weight:600;color:#e5e7eb;';
-        h.textContent = title || 'Main Slopsmith window closed';
+        h.textContent = title || 'Main feedBack window closed';
         const sub = document.createElement('div');
         sub.style.cssText = 'font-size:13px;';
         sub.textContent = subText || 'This follower window is no longer synced — you can close it.';
@@ -4016,9 +4805,11 @@ try {
         document.body.appendChild(o);
     }
 
-    // Shared message dispatch for both follower transports: the local
-    // BroadcastChannel (popup windows) and the LAN relay WebSocket (remote
-    // viewers). Reads live module state, so it survives layout rebuilds.
+    /**
+     * Shared message dispatch for both follower transports: the local
+     * BroadcastChannel (popup windows) and the LAN relay WebSocket (remote
+     * viewers). Reads live module state, so it survives layout rebuilds.
+     */
     function _followerBusHandler(msg) {
         if (_followerOrphaned || !msg) return;
         const remote = !!(FOLLOWER && FOLLOWER.remote);
@@ -4037,6 +4828,13 @@ try {
             } else {
                 _onFollowerOrphaned();
             }
+        } else if (msg.type === 'dock-all') {
+            // Main window's "Dock all" button asked every live popup to dock
+            // itself. Reuse the exact single-panel dock path (dockFollowerPanel)
+            // so this popup's live state — not a stale pop-out-time snapshot —
+            // is what gets redocked; remote LAN viewers have nothing to dock
+            // into and dockFollowerPanel already no-ops for them.
+            if (!remote && panels.length) dockFollowerPanel(panels[0]);
         } else if (msg.type === 'share-ended') {
             if (remote) {
                 _onFollowerOrphaned('Sharing ended',
@@ -4068,6 +4866,9 @@ try {
     // handler can re-assert mute/pause + re-shim without re-querying.
     let _followerAudio = null;
 
+    /**
+     * Boot Follower Mode.
+     */
     function bootFollowerMode() {
         // Hide non-panel chrome with a single CSS rule so we don't have to
         // chase every element id slopsmith renders. The follower wrap covers
@@ -4161,12 +4962,14 @@ try {
         });
     }
 
-    // Load `filename` in the popup, wait for it to be ready, then build the
-    // follower panels from `cfgs`. Used both on initial bootstrap
-    // (cfgs = [FOLLOWER]) and on song-change (cfgs = current panel states).
-    // The popup's main highway is shared across all panels for time / song
-    // info purposes; per-panel arrangement is set inside each panel's own
-    // WebSocket via initPanel.
+    /**
+     * Load `filename` in the popup, wait for it to be ready, then build the
+     * follower panels from `cfgs`. Used both on initial bootstrap
+     * (cfgs = [FOLLOWER]) and on song-change (cfgs = current panel states).
+     * The popup's main highway is shared across all panels for time / song
+     * info purposes; per-panel arrangement is set inside each panel's own
+     * WebSocket via initPanel.
+     */
     async function loadSongInFollower(filename, cfgs) {
         const firstArr = (cfgs[0] && cfgs[0].arrangement) || 0;
         try {
@@ -4204,6 +5007,9 @@ try {
         _buildFollowerToolbar();
     }
 
+    /**
+     * Wait For Highway Ready.
+     */
     function waitForHighwayReady() {
         return new Promise(resolve => {
             const info = highway.getSongInfo();
@@ -4245,8 +5051,10 @@ try {
     let _followerLayoutKey = 'follower';
     const FOLLOWER_TOOLBAR_H = 32;
 
-    // Convert a captured panel config (cfg) and arrIdx into the prefs
-    // shape that initPanel expects.
+    /**
+     * Convert a captured panel config (cfg) and arrIdx into the prefs
+     * shape that initPanel expects.
+     */
     function _followerCfgToPrefs(cfg, arrIdx) {
         const arrName = _modeToArrName(cfg.mode, arrangements[arrIdx]?.name || '');
         return {
@@ -4266,10 +5074,12 @@ try {
         };
     }
 
-    // Build N panels per `layoutKey` into the wrap div. `cfgs` is an array
-    // of panel configs (one per slot); slots beyond cfgs.length get smart
-    // defaults via getDefaultArrangements. Replaces the older single-panel
-    // buildFollowerPanel so the popup can host any of the standard layouts.
+    /**
+     * Build N panels per `layoutKey` into the wrap div. `cfgs` is an array
+     * of panel configs (one per slot); slots beyond cfgs.length get smart
+     * defaults via getDefaultArrangements. Replaces the older single-panel
+     * buildFollowerPanel so the popup can host any of the standard layouts.
+     */
     function buildFollowerLayout(cfgs, layoutKey) {
         layoutKey = FOLLOWER_LAYOUT_PANELS[layoutKey] ? layoutKey : 'follower';
         _followerLayoutKey = layoutKey;
@@ -4306,9 +5116,14 @@ try {
             followerWrap.style.display = 'flex';
             followerWrap.style.flexDirection = 'row';
         } else if (layoutKey === 'quad') {
-            followerWrap.style.display = 'flex';
-            followerWrap.style.flexDirection = 'row';
-            followerWrap.style.flexWrap = 'wrap';
+            // CSS grid, not flex-wrap — same non-interactive-panel bug as the
+            // main window's wrap (see applyLayoutStyle): followerWrap's height
+            // comes from a position inset (bottom:FOLLOWER_TOOLBAR_H), not an
+            // explicit height, which some browsers resolve as indefinite for
+            // %-height flex items in a wrapped row.
+            followerWrap.style.display = 'grid';
+            followerWrap.style.gridTemplateColumns = 'repeat(2,1fr)';
+            followerWrap.style.gridTemplateRows = 'repeat(2,1fr)';
         }
         // else: single (follower) — leave as block layout (no flex).
         document.body.appendChild(followerWrap);
@@ -4398,6 +5213,9 @@ try {
     // Built once per popup, the layout selector triggers rebuild of the
     // panel grid.
     let _followerToolbar = null;
+    /**
+     * Build Follower Toolbar.
+     */
     function _buildFollowerToolbar() {
         if (_followerToolbar) return _followerToolbar;
         const bar = document.createElement('div');
@@ -4439,9 +5257,11 @@ try {
         return bar;
     }
 
-    // Rebuild the popup's panel grid into a new layout. Captures the
-    // current panels' configs so existing slots survive the change; new
-    // slots fill with smart defaults via getDefaultArrangements.
+    /**
+     * Rebuild the popup's panel grid into a new layout. Captures the
+     * current panels' configs so existing slots survive the change; new
+     * slots fill with smart defaults via getDefaultArrangements.
+     */
     function rebuildFollowerLayout(newLayoutKey) {
         if (!FOLLOWER_LAYOUT_PANELS[newLayoutKey]) return;
         if (_followerRebuildBusy) {
@@ -4463,19 +5283,23 @@ try {
         buildFollowerLayout(cfgs, newLayoutKey);
     }
 
-    // Capture every popup panel's current state into an array of cfgs,
-    // suitable for handing back to loadSongInFollower / buildFollowerLayout.
-    // Reads from the live panels so any user changes since pop-out or
-    // last layout change are honoured.
+    /**
+     * Capture every popup panel's current state into an array of cfgs,
+     * suitable for handing back to loadSongInFollower / buildFollowerLayout.
+     * Reads from the live panels so any user changes since pop-out or
+     * last layout change are honoured.
+     */
     function _captureAllFollowerConfigs() {
         return panels.map(p => _captureFollowerConfig(p));
     }
 
-    // Rebuild the follower panels for a new song while preserving the
-    // user's layout + per-panel mode + arrangement choices. Triggered by
-    // the main window's `song-changed` broadcast. Single-flight: a change
-    // arriving while one is in progress is coalesced — only the latest
-    // pending filename runs after the current rebuild finishes.
+    /**
+     * Rebuild the follower panels for a new song while preserving the
+     * user's layout + per-panel mode + arrangement choices. Triggered by
+     * the main window's `song-changed` broadcast. Single-flight: a change
+     * arriving while one is in progress is coalesced — only the latest
+     * pending filename runs after the current rebuild finishes.
+     */
     async function _handleFollowerSongChange(newFilename) {
         if (_followerOrphaned) return;
         if (_followerRebuildBusy) { _followerPendingFilename = newFilename; return; }
@@ -4521,11 +5345,13 @@ try {
     let _followerToast = null;
     let _followerToastBaselineTime = 0;
 
-    // Common-tuning name resolver. Order-agnostic — works whether the
-    // tuning array is high-to-low or low-to-high (we test both ends for
-    // the drop pattern). Returns null for anything that isn't a flat
-    // uniform offset or a one-string drop variant; the caller falls
-    // back to displaying raw offsets in that case.
+    /**
+     * Common-tuning name resolver. Order-agnostic — works whether the
+     * tuning array is high-to-low or low-to-high (we test both ends for
+     * the drop pattern). Returns null for anything that isn't a flat
+     * uniform offset or a one-string drop variant; the caller falls
+     * back to displaying raw offsets in that case.
+     */
     function _resolveFollowerTuningName(tuning) {
         if (!Array.isArray(tuning) || tuning.length === 0) return null;
         const STANDARD_NAMES = {
@@ -4560,6 +5386,9 @@ try {
         return null;
     }
 
+    /**
+     * Dismiss Follower Toast.
+     */
     function _dismissFollowerToast() {
         if (!_followerToast) return;
         const toast = _followerToast;
@@ -4571,11 +5400,13 @@ try {
         }, FOLLOWER_TOAST_FADE_MS);
     }
 
-    // Called from the time-broadcast handler. Dismisses the toast the
-    // first time the main window's audio.currentTime advances past the
-    // baseline captured at toast-creation — i.e. play has actually
-    // started. While main is paused at the new song's start (t = 0),
-    // every broadcast carries the same t and the toast stays visible.
+    /**
+     * Called from the time-broadcast handler. Dismisses the toast the
+     * first time the main window's audio.currentTime advances past the
+     * baseline captured at toast-creation — i.e. play has actually
+     * started. While main is paused at the new song's start (t = 0),
+     * every broadcast carries the same t and the toast stays visible.
+     */
     function _maybeDismissFollowerToastOnPlay(t) {
         if (!_followerToast) return;
         if (t > _followerToastBaselineTime + FOLLOWER_TOAST_PLAY_THRESHOLD_S) {
@@ -4583,6 +5414,10 @@ try {
         }
     }
 
+    /**
+     * Show Follower Song Toast.
+     * @param {*} info
+     */
     function _showFollowerSongToast(info) {
         if (!info) return;
         // Replace any existing toast (rapid song-change sequence).
@@ -4684,11 +5519,13 @@ try {
     let _remoteWaitingEl = null;
     let _remoteWaitingShown = false;
 
-    // Hello-poll: runs pre-boot (host may not be sharing / have a song yet)
-    // AND while the waiting overlay is up after a host restart — a relaunched
-    // host that sits paused emits nothing on its own, so polling is what
-    // fetches the config that dismisses the overlay and re-syncs the song.
-    // Self-stops once booted and not waiting.
+    /**
+     * Hello-poll: runs pre-boot (host may not be sharing / have a song yet)
+     * AND while the waiting overlay is up after a host restart — a relaunched
+     * host that sits paused emits nothing on its own, so polling is what
+     * fetches the config that dismisses the overlay and re-syncs the song.
+     * Self-stops once booted and not waiting.
+     */
     function _remoteStartHelloPoll() {
         if (_remoteHelloTimer != null) return;
         _remoteHelloTimer = setInterval(() => {
@@ -4696,6 +5533,9 @@ try {
             _remoteSendHello();
         }, 3000);
     }
+    /**
+     * Remote Stop Hello Poll.
+     */
     function _remoteStopHelloPoll() {
         if (_remoteHelloTimer != null) {
             clearInterval(_remoteHelloTimer);
@@ -4703,6 +5543,10 @@ try {
         }
     }
 
+    /**
+     * Show Remote Waiting.
+     * @param {*} text
+     */
     function _showRemoteWaiting(text) {
         if (_followerOrphaned) return;
         _remoteWaitingShown = true;
@@ -4729,17 +5573,26 @@ try {
         if (t) t.textContent = text || 'Connecting…';
         _remoteWaitingEl.style.display = 'flex';
     }
+    /**
+     * Hide Remote Waiting.
+     */
     function _hideRemoteWaiting() {
         _remoteWaitingShown = false;   // hello-poll self-stops on its next tick
         if (_remoteWaitingEl) _remoteWaitingEl.style.display = 'none';
     }
 
+    /**
+     * Remote Send Hello.
+     */
     function _remoteSendHello() {
         if (_remoteWs && _remoteWs.readyState === 1) {
             try { _remoteWs.send(JSON.stringify({ type: 'hello', popupId: _remotePopupId })); } catch (_) {}
         }
     }
 
+    /**
+     * Remote Connect.
+     */
     function _remoteConnect() {
         if (_followerOrphaned) return;
         let ws;
@@ -4783,6 +5636,9 @@ try {
         ws.onerror = () => { try { ws.close(); } catch (_) {} };
     }
 
+    /**
+     * Remote Schedule Reconnect.
+     */
     function _remoteScheduleReconnect() {
         if (_followerOrphaned) return;
         const delay = _remoteBackoffMs;
@@ -4792,6 +5648,9 @@ try {
         }, delay);
     }
 
+    /**
+     * Boot Remote Join.
+     */
     function bootRemoteJoin() {
         _remotePopupId = 'lan-' + _newPopupId();
         _showRemoteWaiting('Connecting to host…');
@@ -4819,6 +5678,7 @@ try {
             panelToPrefs, migratePanelPrefs, _ctlRange,
             getSyncUrl, generateRoomKey, normalizeRoomKey, ensureRoomKey,
             buildShareUrl, makeRemoteFollowerCfg, ROOM_KEY_ALPHABET,
+            LAYOUTS, applyLayoutStyle, _bestFitLayout,
             _setArrangementsForTest(next) { arrangements = next; },
         };
     }
diff --git a/tests/screen.test.js b/tests/screen.test.js
index 014d83f..c8725d5 100644
--- a/tests/screen.test.js
+++ b/tests/screen.test.js
@@ -52,6 +52,31 @@ test('getWsUrl uses wss:// under https', () => {
     assert.match(getWsUrl('a.sloppak', 1), /^wss:\/\//);
 });
 
+test('getWsUrl translates a local dropdown position to the arrangement\'s true server index', () => {
+    const mod = freshPlugin();
+    // Server-sorted order (Lead, Rhythm, Bass) differs from original storage
+    // order: Rhythm is stored at index 2, Bass at index 0.
+    mod._setArrangementsForTest([
+        { name: 'Lead', index: 1 },
+        { name: 'Rhythm', index: 2 },
+        { name: 'Bass', index: 0 },
+    ]);
+    assert.equal(
+        mod.getWsUrl('song.sloppak', 1),
+        'ws://localhost:8420/ws/highway/song.sloppak?arrangement=2');
+    assert.equal(
+        mod.getWsUrl('song.sloppak', 2),
+        'ws://localhost:8420/ws/highway/song.sloppak?arrangement=0');
+});
+
+test('getWsUrl falls back to the supplied position when .index is unavailable', () => {
+    const mod = freshPlugin();
+    mod._setArrangementsForTest([{ name: 'Lead' }, { name: 'Rhythm' }]);
+    assert.equal(
+        mod.getWsUrl('song.sloppak', 1),
+        'ws://localhost:8420/ws/highway/song.sloppak?arrangement=1');
+});
+
 test('resolveArrIndex is case-insensitive and finds by name', () => {
     const mod = freshPlugin();
     mod._setArrangementsForTest([{ name: 'Lead' }, { name: 'Rhythm' }, { name: 'Bass' }]);
@@ -267,3 +292,66 @@ test('loading with ?ss=<key> under the node test harness does not boot or throw'
     const mod = freshPlugin({ search: '?ss=k7tr4m' });
     assert.equal(typeof mod.getSyncUrl, 'function');
 });
+
+// ── LAYOUTS / applyLayoutStyle (splitscreen#1: CSS grid fix for the
+// non-interactive-panel bug) ──────────────────────────────────────────────
+test('multi-panel layouts (tri/quad/five/six) are CSS grid, not flex-wrap', () => {
+    const { LAYOUTS } = freshPlugin();
+    for (const key of ['tri-top', 'tri-bottom', 'quad', 'five', 'six']) {
+        assert.equal(LAYOUTS[key].style, 'grid', `${key} should use grid`);
+        assert.ok(Number.isInteger(LAYOUTS[key].cols) && LAYOUTS[key].cols > 0, `${key}.cols`);
+        assert.ok(Number.isInteger(LAYOUTS[key].rows) && LAYOUTS[key].rows > 0, `${key}.rows`);
+        assert.ok(LAYOUTS[key].cols * LAYOUTS[key].rows >= LAYOUTS[key].panels,
+            `${key} grid (${LAYOUTS[key].cols}x${LAYOUTS[key].rows}) must fit its ${LAYOUTS[key].panels} panels`);
+    }
+    // top-bottom/left-right stay flex (2-panel layouts never hit the
+    // %-height-in-flex-wrap ambiguity since they don't wrap onto a 2nd row).
+    assert.equal(LAYOUTS['top-bottom'].style, 'flex-col');
+    assert.equal(LAYOUTS['left-right'].style, 'flex-row');
+});
+
+test('applyLayoutStyle sets a grid template sized from cols/rows for quad', () => {
+    const { applyLayoutStyle } = freshPlugin();
+    const container = { style: {} };
+    applyLayoutStyle(container, 'quad');
+    assert.match(container.style.cssText, /display:grid/);
+    assert.match(container.style.cssText, /grid-template-columns:repeat\(2,1fr\)/);
+    assert.match(container.style.cssText, /grid-template-rows:repeat\(2,1fr\)/);
+});
+
+test('applyLayoutStyle uses a 6-column grid for five, 3-column for six', () => {
+    const { applyLayoutStyle } = freshPlugin();
+    const five = { style: {} };
+    applyLayoutStyle(five, 'five');
+    assert.match(five.style.cssText, /grid-template-columns:repeat\(6,1fr\)/);
+    assert.match(five.style.cssText, /grid-template-rows:repeat\(2,1fr\)/);
+
+    const six = { style: {} };
+    applyLayoutStyle(six, 'six');
+    assert.match(six.style.cssText, /grid-template-columns:repeat\(3,1fr\)/);
+    assert.match(six.style.cssText, /grid-template-rows:repeat\(2,1fr\)/);
+});
+
+test('applyLayoutStyle still uses flex for the 2-panel layouts', () => {
+    const { applyLayoutStyle } = freshPlugin();
+    const topBottom = { style: {} };
+    applyLayoutStyle(topBottom, 'top-bottom');
+    assert.match(topBottom.style.cssText, /display:flex/);
+    assert.equal(topBottom.style.flexDirection, 'column');
+
+    const leftRight = { style: {} };
+    applyLayoutStyle(leftRight, 'left-right');
+    assert.match(leftRight.style.cssText, /display:flex/);
+    assert.equal(leftRight.style.flexDirection, 'row');
+});
+
+test('_bestFitLayout picks the smallest layout with room, and caps at six', () => {
+    const { _bestFitLayout } = freshPlugin();
+    assert.equal(_bestFitLayout(1), 'top-bottom');
+    assert.equal(_bestFitLayout(2), 'top-bottom');
+    assert.equal(_bestFitLayout(3), 'tri-top');
+    assert.equal(_bestFitLayout(4), 'quad');
+    assert.equal(_bestFitLayout(5), 'five');
+    assert.equal(_bestFitLayout(6), 'six');
+    assert.equal(_bestFitLayout(7), 'six'); // nothing bigger — caller must truncate
+});