<!-- neur0doku — replayable intro tutorial. Lives at /neur0doku/tutorial/.
     13 panels: Beta's intro -> single-region rule -> Spindle's row/
     column rule -> the Knot/Knell choice -> a 3x3 thought-experiment
     aside -> the real board expands -> the Knot/Knell 4x4 (pick
     either open cell, then find whoever's left) -> Fray reveals
     himself on a 5x5 -> a practice round that teaches the hint tools
     -> a real Shop trip for the 6th character, which is the LAST
     panel — buying the 6th character sends the player straight to
     the real neur0doku home page, no unlock screen of its own.

     DESIGN NOTE — the 3x3 "aside" (panel 4 below) is a SEPARATE,
     small, explicitly-labeled thought-experiment board, not the real
     persisted board. This isn't a shortcut hiding a seam — it's
     mathematically true and worth teaching plainly: with only 4
     columns' worth of adjacency math available, a 3-wide board simply
     CANNOT hold a third non-touching face once two are placed (see
     skeleton.js's own "provably exists for n>=4" comment — this is
     that fact, dramatized). Spindle says as much before it happens
     ("watch what happens if it was just the three of us"), so the
     seam is honest rather than papered over.

     DESIGN NOTE — the real catalog (catalog.js) has Knell gated behind
     OWNING Knot first (requiresAll: ['knot']), which would normally
     block "pick either one first." Rather than special-case that one
     conflict, this tutorial pre-grants ALL FIVE starting characters
     (Beta, Spindle, Knot, Knell, Fray at cycle 0/1 — see the PHASE 7
     block in the module script below for cycle 2+, where Umbrella/
     Builder replace Knot/Knell here too) the instant it loads — see
     getTutorialStartingCharacters(), the one place to edit if that
     list should change. Ownership being true early doesn't mean a
     face is on screen yet; the panels below still reveal each one in
     story order. Only the 6th character (chosen in the Shop panel,
     no chain) goes through a real Shop purchase.

     DESIGN NOTE — the Knot/Knell 4x4 panel and the 5x5 practice round
     both introduce a single-TAP (not double-tap) marker: tapping a
     still-blank cell toggles a black "don't go here" X
     (../images/doku_xmarkb.png). This is intentionally the ONLY marker
     mode wired up so far — the "?" guess-marker toggle and its
     trash-can clear button are a later pass (see the open items list
     at the bottom of tutorial-parts.md).

     DESIGN NOTE — once the player returns from the Shop with a 6th
     character, they land on the real neur0doku home page immediately
     — no "welcome back" panel, no in-tutorial unlock screen. Everything
     the hint tools need to teach (Undo / 4 X's / Reveal a face) is
     already taught during the 5x5 practice round, before the Shop
     trip, so there's nothing left to explain on return, and "unlock
     Story Mode" is something the home page itself handles now, not
     this tutorial.

     DESIGN NOTE — the top-bar back arrow no longer navigates straight
     to the pause page. It opens an in-page modal instead (reset the
     tutorial, or go to the real home page if the player has already
     unlocked it before — see backLink's click handler and
     nd-tut-back-modal below). /tutorial/paused/index.html still
     exists as its own page — for a direct link, a bookmarked URL, or
     any no-JS fallback — and now hides its "back to home" option
     unless that same unlocked flag is set.

     DEBUG NOTE (added while chasing the "grant didn't take" report) —
     grantTutorialStarters()/grantTutorialThreadIfNeeded() now also
     console.log what they actually did, and grantCharacter's logic
     was folded straight into grantTutorialStarters(), which builds
     ONE state object for the whole batch and calls saveOwnership()
     explicitly exactly once at the end, instead of the previous
     version's loadOwnership()/equip() pair called separately per
     character (which relied on equip()'s own internal save happening
     correctly on every single call). If a device still doesn't show
     these as owned in the Shop after this change, it's checkable
     straight from that device's own browser console — see the
     Shop-trip panel's log line and tutorial-parts.md's debugging
     note for exactly what to look at.

     HEADER: now a real, uncommented element again (was HTML-commented
     out) — hidden via the shared body[data-nd-header="hide"] rule in
     neur0doku-theme.css instead, so inject-layout.js's ResizeObserver
     and nav injection keep working. See that CSS file's own comment.

     PHASE 7 — reset-cycle branching (2026-09-01): the tutorial now
     reads getPlayerCycle() from meta-escalation.js and actually
     branches on it — see the "PHASE 7 — reset-cycle dialogue & cast"
     block inside the module script below for the full mechanism, and
     claude/prompt-tutorial-reset-cycle-dialogue.md /
     claude/dev-plan-phase6-metafiction.md for the design this
     implements. Cycle 0 (never reset) is byte-for-byte the same
     tutorial as before this pass; nothing about the rendering above
     this line changed.
-->
<!DOCTYPE html>
<html lang="en" data-nd-theme="neur0doku">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<script src="../js/nd-theme.js"></script>
<!-- <script src="/js/inject-head.js" defer></script> -->
<title>How to Play — neur0doku — neur0loom&reg;</title>

<link rel="stylesheet" href="../css/neur0doku-theme.css">
<link rel="stylesheet" href="../css/neur0doku-play-theme.css">
<link rel="stylesheet" href="../css/neur0doku-tutorial.css">
</head>
<body data-theme="light" data-nd-header="hide">
  <header class="site-header">
    <div id="site-nav"></div>
  </header>

  <main class="container site-main">
    <section class="neur0doku-tutorial" aria-label="How to play neur0doku">

      <div class="nd-tut-topbar">
        <a class="nd-icon-btn" id="nd-tut-back-link" href="paused/index.html" aria-label="Leave for now" style="width:2.5rem;height:2.5rem;display:flex;align-items:center;justify-content:center;border-radius:0.8rem;background:var(--nd-surface);border:1px solid var(--nd-border);box-shadow:0 3px 8px var(--nd-shadow);text-decoration:none;flex-shrink:0;">
          <img src="../images/neur0doku_tool-back.png" alt="" style="width:60%;height:60%;object-fit:contain;" />
        </a>

        <!-- Persistent rule-reminder row (Phase 2 scaffold). Each icon starts
            locked (disabled + .is-locked) until its topic's popup has been
            shown once — see registerTipIcon()/unlockTipIcon() in the script
            below. No popups are wired to these yet; that's later phases. -->
        <div class="nd-tut-rule-icons" id="nd-tut-rule-icons">
          <button class="nd-tut-rule-icon-btn is-locked" id="nd-tut-rule-icon-color" type="button" aria-label="Color rule (locked)" disabled>
            <img src="../images/neur0doku_tip-color.png" alt="" />
          </button>
          <button class="nd-tut-rule-icon-btn is-locked" id="nd-tut-rule-icon-rowcol" type="button" aria-label="Row and column rule (locked)" disabled>
            <img src="../images/neur0doku_tip-rowcol.png" alt="" />
          </button>
          <button class="nd-tut-rule-icon-btn is-locked" id="nd-tut-rule-icon-touch" type="button" aria-label="Touch rule (locked)" disabled>
            <img src="../images/neur0doku_tip-touch.png" alt="" />
          </button>
          <button class="nd-tut-rule-icon-btn is-locked" id="nd-tut-rule-icon-help" type="button" aria-label="How this board works (locked)" disabled>
            <img src="../images/neur0doku_marker-q.png" alt="" />
          </button>
        </div>

        <button class="nd-tut-next-btn" id="nd-tut-next-btn" type="button" disabled>Next</button>
      </div>

      <!-- Back-arrow modal — reset the tutorial, or (only once the
           player has actually unlocked it before) go to the real
           neur0doku home. See backLink's click handler below. -->
      <div class="nd-tut-modal-overlay" id="nd-tut-back-modal" hidden>
        <div class="nd-tut-modal" role="dialog" aria-modal="true" aria-labelledby="nd-tut-back-modal-title">
          <h2 id="nd-tut-back-modal-title">Leave the tutorial?</h2>
          <p id="nd-tut-back-modal-body">You can start over, or just close this and keep going.</p>
          <div class="nd-tut-modal-actions">
            <button class="nd-tut-modal-btn nd-tut-modal-btn-primary" id="nd-tut-back-modal-reset" type="button">Start the tutorial over</button>
            <button class="nd-tut-modal-btn" id="nd-tut-back-modal-home" type="button" hidden>Go to neur0doku home</button>
            <button class="nd-tut-modal-btn nd-tut-modal-btn-ghost" id="nd-tut-back-modal-cancel" type="button">Never mind</button>
          </div>
        </div>
      </div>

      <div class="nd-tut-speaker-row" id="nd-tut-speaker-row">
        <div class="nd-tut-speaker-avatar" id="nd-tut-speaker-avatar">
          <img id="nd-tut-speaker-img" src="../images/avatars/neur0doku_avatar-beta-g.png" alt="" />
        </div>
        <div class="nd-tut-speech">
          <span class="nd-tut-speaker-name" id="nd-tut-speaker-name">Beta</span>
          <span id="nd-tut-speech-text">Getting things ready&hellip;</span>
        </div>
      </div>

      <!-- Multi-line conversation transcript — used instead of the
           single speaker row above whenever more than one line needs
           to be on screen AT ONCE (no auto-advancing timers; see
           showConversation in the script below). Self-paced reading
           matters here, so every line the player needs stays visible
           until they hit Next themselves. From the Spindle row/column
           reveal onward, lines fade in one at a time (see the `fade`
           option) so it reads more like real back-and-forth talk. -->
      <div class="nd-tut-conversation" id="nd-tut-conversation" hidden></div>

      <!-- Choice cards — only shown for the Knot/Knell panel -->
      <div class="nd-tut-choice-row" id="nd-tut-choice-row" hidden></div>

      <!-- Name capture — only shown on the Shop-trip panel -->
      <!-- 2026-09-23: no typing any more. The birthday dropdowns (from
           ads.js) show first, then one button opens name-picker.js's
           word wheels. Nothing here takes focus on its own, so the
           phone keyboard never pops up unasked. -->
      <div class="nd-tut-name-row" id="nd-tut-name-row" hidden style="flex-wrap: wrap; justify-content: center;">
        <div id="nd-tut-birthday" style="width: 100%;" hidden></div>
        <button class="nd-tut-name-submit" id="nd-tut-name-submit" type="button">Choose my name</button>
      </div>

      <!-- "How this board works" walkthrough — 5 pips demoing
           click-and-drag marking, the row/column rule, the no-touch
           box around a face, the "?" maybe-marker, and the hint/undo
           flow, using a small self-contained demo grid (NOT the real
           board — see openHowtoModal/HOWTO_STEPS below). Opens once,
           automatically, the first time panel 11's board appears;
           closable via the X or a click on the backdrop; reopenable
           afterward via the tip row's "?" button. Closing ALWAYS
           redoes the current practice board fresh (goToPanel(11)) —
           per your "clear up a lot of confusion" note — whether this
           is the first automatic close or a later manual reopen.
           Every pip's animation LOOPS on its own (see playCurrentStep/
           howtoRunMaxDelay below) — it replays a beat after finishing
           and keeps going until Back/Next/close moves on — and the
           ↻ button restarts the current pip immediately on demand. -->
      <div class="nd-tut-modal-overlay" id="nd-tut-howto-modal" hidden>
        <div class="nd-tut-modal nd-tut-howto-modal-box" role="dialog" aria-modal="true" aria-labelledby="nd-tut-howto-title">
          <button class="nd-tut-howto-close" id="nd-tut-howto-close" type="button" aria-label="Close">&times;</button>
          <h2 id="nd-tut-howto-title">Additional help tools added.</h2>
          <div class="nd-tut-howto-demo">
            <div class="nd-tut-howto-grid" id="nd-tut-howto-grid"></div>
            <img class="nd-tut-howto-finger" id="nd-tut-howto-finger" src="../images/neur0doku_marker-finger.png" alt="" />
            <div class="nd-tut-howto-hearts" id="nd-tut-howto-hearts" hidden>
              <span data-heart="1">🧵</span><span data-heart="2">🧵</span><span data-heart="3">🧵</span>
            </div>
            <!-- Pip 4's marker-tool row: one icon that SWAPS its own
                 image between the X-marker and Q-marker art (rather
                 than two separate icons), plus a trash icon that
                 clears every placed "?" at once. Shares
                 .nd-tut-howto-hint-icons' positioning (bottom of the
                 demo area) since it and the real hint-icon row below
                 never show at the same time — resetHowtoDemo() hides
                 both at the start of every step. -->
            <div class="nd-tut-howto-hint-icons nd-tut-howto-marker-icons" id="nd-tut-howto-marker-icons" hidden>
              <span class="nd-tut-howto-hint-icon" id="nd-tut-howto-marker-toggle" aria-hidden="true">
                <img src="../images/neur0doku_marker-x.png" alt="" id="nd-tut-howto-marker-toggle-img" />
              </span>
              <span class="nd-tut-howto-hint-icon" id="nd-tut-howto-marker-trash" aria-hidden="true">
                <img src="../images/neur0doku_marker-trash.png" alt="" />
              </span>
            </div>
            <div class="nd-tut-howto-hint-icons" id="nd-tut-howto-hint-icons" hidden>
              <span class="nd-tut-howto-hint-icon" id="nd-tut-howto-hint-icon-undo" aria-hidden="true">
                <img src="../images/neur0doku_help-undo.png" alt="" />
              </span>
              <span class="nd-tut-howto-hint-icon" id="nd-tut-howto-hint-icon-xmarks" aria-hidden="true">
                <img src="../images/neur0doku_help-hint.png" alt="" />
              </span>
              <span class="nd-tut-howto-hint-icon" id="nd-tut-howto-hint-icon-face" aria-hidden="true">
                <img src="../images/neur0doku_help-face.png" alt="" />
              </span>
            </div>
          </div>
          <p class="nd-tut-howto-step-text" id="nd-tut-howto-step-text"></p>
          <div class="nd-tut-howto-pips" id="nd-tut-howto-pips" aria-hidden="true"></div>
          <div class="nd-tut-modal-actions nd-tut-howto-actions">
            <button class="nd-tut-modal-btn nd-tut-modal-btn-ghost" id="nd-tut-howto-back" type="button">Back</button>
            <button class="nd-tut-modal-btn nd-tut-modal-btn-ghost nd-tut-howto-replay" id="nd-tut-howto-replay" type="button" aria-label="Replay this step">&#8635;</button>
            <button class="nd-tut-modal-btn nd-tut-modal-btn-primary" id="nd-tut-howto-next" type="button">Next</button>
          </div>
        </div>
      </div>

      <div class="nd-tut-stage" id="nd-tut-stage"></div>
      <p class="nd-tut-target-hint" id="nd-tut-target-hint" hidden>Double-tap the glowing cell to place the face.</p>

      <!-- Part D — the REAL marker toggle + trash, live on the practice
           board itself (not just demoed in the help popup). Same idea
           as play.js's real markToggleBtn/clearQuestionsBtn, scoped to
           this tutorial's own practice board — shown/hidden alongside
           .nd-tut-hint-row (see panelHintPractice/clearAllMessages/
           renderShopTripPanel in the script below). -->
      <div class="nd-tut-marker-row" id="nd-tut-marker-row" hidden>
        <button class="nd-tut-marker-toggle-btn" id="nd-tut-marker-toggle-btn" type="button" aria-label="Currently marking with X. Tap to switch to ?" aria-pressed="false">
          <img id="nd-tut-marker-toggle-btn-img" src="../images/neur0doku_marker-x.png" alt="" />
        </button>
        <button class="nd-tut-marker-trash-btn" id="nd-tut-marker-trash-btn" type="button" aria-label="Clear all ? marks">
          <img src="../images/neur0doku_marker-trash.png" alt="" />
        </button>
      </div>

      <!-- Hint tools — shown/enabled for the 5x5 practice round.
           Each button is single-use per playthrough of that panel; see
           runColoredPracticeBoard in the script below. -->
      <div class="nd-tut-hint-row nd-tut-toolbar" id="nd-tut-hint-row" hidden>
        <div class="nd-tut-toolbar-group">
          <button class="nd-tut-power-btn" id="nd-tut-marker-toggle" type="button" aria-label="Currently marking with X. Tap to switch to ?">
            <img id="nd-tut-marker-toggle-img" src="../images/neur0doku_marker-x.png" alt="" />
          </button>
          <button class="nd-tut-power-btn" id="nd-tut-clear-questions" type="button" aria-label="Remove all ? marks">
            <img src="../images/neur0doku_marker-trash.png" alt="" />
          </button>
        </div>
        <div class="nd-tut-toolbar-group">
          <button class="nd-tut-power-btn" id="nd-tut-hint-face" type="button" aria-label="Reveal a face">
            <img src="../images/neur0doku_help-face.png" alt="" />
          </button>
          <button class="nd-tut-power-btn" id="nd-tut-hint-xmarks" type="button" aria-label="Reveal four X's">
            <img src="../images/neur0doku_help-hint.png" alt="" />
          </button>
          <button class="nd-tut-power-btn" id="nd-tut-hint-undo" type="button" aria-label="Undo">
            <img src="../images/neur0doku_help-undo.png" alt="" />
          </button>
        </div>
      </div>

    </section>
  </main>

  <div id="site-modals"></div>
  <div id="site-templates"></div>
  <script src="/js/site-bundle.js" defer></script>

  <script type="module">
    // ?v=3 (2026-09-22): ownership.js's tutorial Thread grant now TOPS UP
    // instead of adding (Thread survives Reset Account), so an old
    // cached copy must not be used here.
    import { loadOwnership, saveOwnership, getOwnedCharacterCount, applyTestingOverridesFromLocation, grantTutorialThreadIfNeeded } from '../js/ownership.js?v=3';
    // Player names + what Beta remembers across resets — see
    // name-memory.js's header and renderShopTripPanel()'s name step.
    import { resolveTutorialName, rememberChosenName, betaNameLine, getRememberedName } from '../js/name-memory.js';
    // 2026-09-23: pick-a-name word wheels + the birthday question.
    import { openNamePicker, partsFromName } from '../js/name-picker.js';
    import { buildBirthdayPicker, saveBirthday, hasAnsweredBirthday } from '../js/ads.js';
    import { getItem } from '../js/catalog.js';
    // (Site-root /js/firebase-init.js + /js/account.js used to be
    // imported here for writePlayerName()'s push to the shared account
    // name — removed 2026-09-22, see that function.)
    // PHASE 7 — reset-cycle branching. Reused directly per the prompt
    // doc's own instruction ("don't re-derive it locally") — the old
    // local getResetCycle() helper that used to live in this file is
    // gone; getPlayerCycle() (0-indexed: 0 = never reset) is now the
    // single source of truth this whole file branches on. See that
    // function's own header comment in meta-escalation.js.
    import { getPlayerCycle } from '../js/meta-escalation.js';

    (function () {
      'use strict';

      /* ==========================================================
         ARCHITECTURE NOTE

         This whole tutorial is a fully AUTHORED performance, not a
         solved puzzle — every board, every "correct" cell, and every
         wrong-answer reason is hand-placed per step. There is
         deliberately no dependency on play.js / real puzzle-solving
         logic: nothing here is ever actually validated against real
         adjacency math, because nothing here needs to be. Most steps
         run through one generic board renderer + wiring function
         (renderBoard); a handful of steps need custom per-cell click
         behavior (overriding an "already found" cell's message, two
         cells that are both valid, etc.) that the generic engine
         wasn't built for, so those are their own small, self-
         contained builder functions instead (renderSpindleRowFind,
         renderThirdFailBoard, renderKnotKnellStep, buildColoredFaceBoard).

         A generic-engine `step` describes one interactive moment on
         an n x n board:
           n                 - board size
           targets           - [{ pos, charId }] the correct cell(s)
                                for this step. Empty array means this
                                board has NO correct answer anywhere
                                (used for the "3rd character doesn't
                                fit on a 3x3" moment) — every click
                                is a miss, but the player can keep
                                trying; Next just enables after the
                                first attempt.
           placed             - [{ pos, charId }] cells already
                                resolved from earlier steps on this
                                board. Still shown (colored, face
                                visible), still clickable, but always
                                gives an "already found them" miss.
           traps              - { [pos]: reasonKey } specific wrong
                                cells that get a SPECIFIC miss reason
                                instead of the default one.
           defaultMissReason   - reason key for any blank cell not
                                listed in traps
           flatTargetStyle     - when true, target cells get the same
                                flat grey background as everywhere
                                else instead of the usual pulsing
                                "double-tap me" ring — used when the
                                correct cell must NOT visually stand
                                out from the traps around it.
           frayFlatTarget      - when true, the flat-grey cells use
                                the FIXED, never-tinted --nd-tut-fray-bg
                                color instead of the greyscale-fade's
                                --nd-tut-target-bg. No longer set by
                                frayStep() as of this pass — Fray's
                                board now uses the same
                                --nd-tut-target-bg as every other flat
                                board (see frayStep()'s own comment for
                                the visual tradeoff this reverses) —
                                kept as a mechanism (CSS + this flag)
                                in case that tradeoff needs revisiting.
           onCorrect(charId, pos) - fires the moment EACH target is
                                found (so a multi-target step like the
                                5-across Fray board can react per-face)
           onAllFound()        - fires once every target in `targets`
                                has been found
           onMiss(reasonKey, pos) - fires on every wrong click, every
                                time (not one-shot) — lets Beta/Spindle
                                react freshly no matter how many wrong
                                guesses the player makes

         Positions are 1-indexed, row-major, matching the planning
         grids (1 = top-left, reading left-to-right/top-to-bottom) —
         e.g. on a 3x3: 1 2 3 / 4 5 6 / 7 8 9.

         STILL TODO (out of scope for this pass, deliberately stubbed):
           - the "?" guess-marker toggle + trash-can clear button
             (only the black-X "don't go here" tap marker is wired up
             so far, introduced at the Knot/Knell 4x4 panel)
           - the real 6x6 live-play segment beyond this tutorial
         ========================================================== */

      // TESTING ONLY — same call every other neur0doku page makes.
      applyTestingOverridesFromLocation(location.search);

      const AVATAR_DIR = '../images/avatars/';
      // Grey-until-found avatars: every character portrait (speaker
      // row, conversation lines, board face images, choice cards)
      // resolves through this one function, so gating it here covers
      // all of them at once. Defaults to the "-g" (grey) asset until
      // markCharacterFound(id) has been called for that id; from then
      // on it resolves the normal color asset. This is SEPARATE from
      // setColorStage()'s page-wide greyscale-to-color foreshadowing —
      // that fades the whole page's chrome; this is per-character and
      // driven by whether THAT character has actually been placed.
      // Needs a real "-g" asset per character (e.g.
      // neur0doku_avatar-beta-g.png) or that character just renders a
      // broken image until found.
      const foundCharacterIds = new Set();
      // Timestamp of the last successful find. A stray second double-tap
      // landing on the just-found cell must not trigger an "already found"
      // reply or a red X, so those check justFoundSomeone() first.
      let lastFoundAt = 0;
      function markCharacterFound(id) { foundCharacterIds.add(id); lastFoundAt = Date.now(); }
      function justFoundSomeone() { return Date.now() - lastFoundAt < 800; }

      // Tapping a face that is already on the board does nothing, unless it
      // is tapped 5 times in a row quickly: then that character says a line.
      // DRAFT easter-egg lines, not final copy. Add or change any id here.
      const FACE_EASTER_EGG_LINES = {
        beta: 'Yes, that is still my face. You may keep tapping it. I will not mind.',
        spindle: 'Um… that tickles a little…',
        knot: 'Hello again. Still me. Still here.',
        knell: 'Hehe, that’s me! That’s fun, do it again!',
        fray: '-dook dook dook squeak-',
      };
      const foundFaceTaps = new WeakMap();
      // Returns true if the cell shows a face (so callers stay silent).
      function tapOnFoundFace(cell) {
        const img = cell.querySelector('.nd-tut-face-img');
        if (!img) return false;
        const now = Date.now();
        const rec = foundFaceTaps.get(cell) || { n: 0, t: 0 };
        rec.n = (now - rec.t < 1200) ? rec.n + 1 : 1;
        rec.t = now;
        if (rec.n >= 5) {
          rec.n = 0;
          const m = img.src.match(/avatar-([a-z0-9]+?)(?:-g)?\.png/);
          const id = m ? m[1] : 'beta';
          say(id, FACE_EASTER_EGG_LINES[id] || '…!');
        }
        foundFaceTaps.set(cell, rec);
        return true;
      }
      function avatarPath(id) {
        const suffix = foundCharacterIds.has(id) ? '' : '-g';
        return AVATAR_DIR + 'neur0doku_avatar-' + id + suffix + '.png';
      }
      function charName(id) {
        const item = getItem(id);
        return (item && item.name) || (id.charAt(0).toUpperCase() + id.slice(1));
      }
      function charColor(id) {
        const item = getItem(id);
        return (item && item.color) || '#999999';
      }

      /* ========== PHASE 7 — reset-cycle dialogue & cast ==========
         Wires getPlayerCycle() (meta-escalation.js — 0 = never reset,
         climbing by 1 per soft reset) into the tutorial for real. Per
         claude/prompt-tutorial-reset-cycle-dialogue.md and the two
         project-owner decisions this pass confirmed before writing
         any of this:

           - Cycle 2's "Umbrella and Builder replace Knot and Knell"
             is FULL REPLACEMENT — Knot/Knell are entirely absent from
             the tutorial from cycle 2 on; Umbrella/Builder occupy
             both their narrative slots AND their puzzle-piece slots.
           - This branches STRICTLY on playerCycle (world resets), not
             on tutorialReplayCount (tutorial replays). A player who
             replays the tutorial many times via "Replay tutorial"
             without ever soft-resetting keeps seeing the unchanged
             cycle-0 tutorial. tutorialReplayCount stays entirely on
             its own separate Existential-tier ladder in
             meta-escalation.js, untouched by anything below.

         REGRESSION CONTRACT: every branch below is gated behind an
         explicit `getPlayerCycle() >= N` (N >= 1) check. A never-reset
         account (playerCycle 0) must hit none of them and render
         byte-for-byte the same tutorial as before this pass — that's
         the one check that has to hold above everything else here.

         EXTENSION POINT for cycle 4+ (the cake conversation — a
         separate, much larger, NOT built here): every table below
         uses cycleLine()'s "nearest authored cycle at-or-below this
         one" fallback, and every board branch below uses `>= 3`
         rather than `=== 3`, so cycle 4, 5, 6... automatically keep
         showing cycle 3's cast/board/dialogue until real cycle-4+
         content is authored — nothing here needs restructuring for
         the cake work to plug in later; it can add its own `>= 4`
         checks and CYCLE_* table entries beside these. Do NOT add any
         cake-specific behavior in this file — see the dev-plan doc.

         All NEW dialogue below (cycle 2's "They both look familiar,"
         cycle 3's Beta/Spindle/R exchange) is first-draft text
         supplied during planning, NOT confirmed final copy — every
         such line is marked "DRAFT" in its own comment. Do not treat
         any of it as shipped copy without a final confirmation pass. */

      // Which two character ids fill the "pick either one first, then
      // find whoever's left" role that Knot/Knell have always filled.
      // Only cycle 0 is confirmed-original; cycle 2 is the confirmed
      // "full replacement" cast. Cycle 1 is deliberately NOT a key
      // here — per the prompt doc, cycle 1 is "small, subtle
      // acknowledgment only — no cast change" — so it falls through
      // to cycle 0's pair via cycleLine()'s fallback, same as cycle
      // 3+ falls through to cycle 2's pair until a cycle-4 entry (the
      // cake work) ever needs its own.
      const CYCLE_CAST = {
        knotKnellSlot: {
          0: ['knot', 'knell'],
          2: ['umbrella', 'builder'],
        },
      };

      // Looks up table[cycle]; if that exact cycle hasn't been authored,
      // falls back to the highest authored cycle AT OR BELOW it (so a
      // 5th-cycle player gets cycle 3's line rather than nothing, if
      // cycles 4/5 are never written). Every table used with this
      // should at minimum define cycle 0.
      function cycleLine(table, cycle) {
        if (table[cycle] != null) return table[cycle];
        let best = null, bestCycle = -1;
        Object.keys(table).forEach(function (key) {
          const c = Number(key);
          if (c <= cycle && c > bestCycle) { best = table[key]; bestCycle = c; }
        });
        return best;
      }

      function getKnotKnellSlotCast() {
        return cycleLine(CYCLE_CAST.knotKnellSlot, getPlayerCycle());
      }
      // True for cycle 0/1 (today's Knot/Knell tutorial); false from
      // cycle 2 on, once the confirmed full-replacement cast is live.
      // Derived from the single CYCLE_CAST table above rather than a
      // duplicated `getPlayerCycle() < 2` magic number, so it can
      // never drift out of sync with it.
      function usingOriginalTutorialCast() {
        return getKnotKnellSlotCast()[0] === 'knot';
      }

      // Per-character reaction lines keyed by narrative beat, not by
      // cycle — this answers "whichever character is in this slot,
      // what do they say," independent of which cycle put them there,
      // so a later cycle-4+ cast reusing this same slot mechanism
      // just needs new entries here, not new branching logic. Only
      // Knot/Knell have real, already-validated voice lines today;
      // any other id placed into this slot (Umbrella, Builder, ...)
      // falls back to SLOT_REACTION_FALLBACK until real voice lines
      // are authored for them — see claude/vision-metafiction-
      // worldbuilding.md's "Dialogue status" section.
      const SLOT_REACTION_LINES = {
        choicePick: {
          knot: '… what is this? Hello.',
          knell: 'Hello! Thank you for choosing me… Although, I am not sure why I’m here…',
        },
        find4x4: {
          knot: 'No touching faces… And not the same row or column, right? Probably in the teal area somewhere... maybe...',
          knell: 'I’m probably in the lavender area somewhere… Faces cannot touch and we can’t be in the same row or column… I got this!',
        },
        expandReaction: {
          knot: 'Oh… I think I see the pattern…',
          knell: 'This is a game, isn’t it? I love games!',
        },
      };
      // TODO Phase 7 — placeholder until Umbrella/Builder (and any
      // later reset-cycle cast) get real, voiced lines. Deliberately
      // neutral rather than invented "voice" for them.
      const SLOT_REACTION_FALLBACK = '…!';
      function slotReaction(key, charId) {
        const table = SLOT_REACTION_LINES[key] || {};
        return table[charId] || SLOT_REACTION_FALLBACK;
      }

      // Cycle 1 subtle acknowledgment — per the prompt doc: "no line
      // has been written for this yet... do not invent one silently."
      // Deliberately left with no cycle-1 entry — cycleLine() returns
      // null against an empty table, so panelHiWelcome() below simply
      // renders nothing extra until real copy lands here. Wired now
      // so authoring this later is a one-line table edit, not a new
      // code path.
      const CYCLE_SUBTLE_ACK = {};

      // Concrete first use of the pattern above — the Shop-trip
      // panel's greeting varies with playerCycle (see
      // hasResetHistory() and renderShopTripPanel() below). Keys are
      // now 0-indexed to match getPlayerCycle() directly (this used
      // to be keyed 1/2 against the old 1-indexed local getResetCycle()
      // — see this file's PHASE 7 import comment above for why that
      // helper is gone).
      const CYCLE_LINES = {
        shopTripFirstTime: {
          0: 'I think you are ready! I gave you some leftover Thread. Please, head to The Quirk Café and sponsor a character from Milo. First, what do you call yourself?',
        },
        shopTripReturning: {
          // 2026-09-22: returning players are asked their name again
          // (Beta already knows it — see renderShopTripPanel()), so this
          // line now ends on the question. The ask is DRAFT copy.
          1: 'Wonderful. Let’s get you ready to buy one more face from the shop. But first… what do you call yourself?',
          // 2+: TODO Phase 7 — e.g. the Dev Plan's "...I'm beginning to
          // think this is intentional" / "I have questions" escalation,
          // once that copy actually gets written.
        },
      };

      // ---- Cycle 3 — Fray brings R, G, and B back; board grows to
      // 8x8. See the lore doc: they appear SILENTLY (no names shown,
      // no dialogue attributed to them) — Fray brought them, not the
      // player or Beta. 8x8 = 64 cells is DELIBERATE, the exact same
      // 64 the Thread Network's Firestore reporting cadence uses
      // elsewhere in the design (see vision doc) — protect this
      // number if this board's sizing code is ever touched in a
      // general balance pass.
      //
      // Face positions below are a hand-verified non-touching, one-
      // per-row/column placement (no two faces share a row or a
      // column, and no two are orthogonally/diagonally adjacent) —
      // the same three constraints the real game enforces, just
      // authored by hand instead of solved, same as every other
      // board in this file. Every non-face cell is assigned to
      // whichever face is nearest (plain flood-fill), purely for the
      // "structure for free" coloring the 5x5 practice round already
      // does — those region shapes carry no puzzle-validity meaning
      // of their own, only the 8 face positions do.
      const CYCLE3_BOARD_N = 8;
      const CYCLE3_REGIONS = {
        spindle: { facePos: 6, region: [4, 5, 6, 7, 8, 13, 14, 15, 16, 22] },
        pick1: { facePos: 10, region: [1, 2, 3, 9, 10, 11, 17, 18, 26] },
        pick2: { facePos: 20, region: [12, 19, 20, 21, 27, 28] },
        beta: { facePos: 31, region: [23, 24, 30, 31, 32, 39, 40, 47] },
        r: { facePos: 37, region: [29, 35, 36, 37, 38, 44, 45, 46, 53, 54, 61] },
        g: { facePos: 41, region: [25, 33, 34, 41, 42, 49, 57] },
        b: { facePos: 51, region: [43, 50, 51, 52, 58, 59, 60] },
        fray: { facePos: 64, region: [48, 55, 56, 62, 63, 64] },
      };

      // Builds the cycle-3 Fray-reveal step (mirrors frayStep() below,
      // sized up to 8x8) — Umbrella/Builder/Beta/Spindle/R/G/B are all
      // already `placed` (R/G/B silently, per the lore doc); only
      // Fray is an active search target. Simpler trap categorization
      // than frayStep()'s hand-tuned 5x5 (two reasons instead of
      // four) — this is first-draft content, not final copy; see this
      // block's own header note above.
      function cycle3FrayStep() {
        const frayRegion = CYCLE3_REGIONS.fray.region;
        const frayFace = CYCLE3_REGIONS.fray.facePos;
        const traps = {};
        frayRegion.forEach(function (p) { if (p !== frayFace) traps[p] = 'sameColor'; });
        return {
          n: CYCLE3_BOARD_N,
          targets: [{ pos: frayFace, charId: 'fray', revealRegion: frayRegion }],
          highlightPositions: frayRegion,
          placed: [
            { charId: 'spindle', facePos: CYCLE3_REGIONS.spindle.facePos, region: CYCLE3_REGIONS.spindle.region },
            { charId: pick1Id, facePos: CYCLE3_REGIONS.pick1.facePos, region: CYCLE3_REGIONS.pick1.region },
            { charId: pick2Id, facePos: CYCLE3_REGIONS.pick2.facePos, region: CYCLE3_REGIONS.pick2.region },
            { charId: 'beta', facePos: CYCLE3_REGIONS.beta.facePos, region: CYCLE3_REGIONS.beta.region },
            // R, G, B — silently already present; never an active
            // search target, same as the lore doc's "no names, no
            // dialogue" note. Needs real "-g"/color avatar art for
            // 'r'/'g'/'b' or these render as broken images until that
            // exists — see avatarPath()'s own comment above.
            { charId: 'r', facePos: CYCLE3_REGIONS.r.facePos, region: CYCLE3_REGIONS.r.region },
            { charId: 'g', facePos: CYCLE3_REGIONS.g.facePos, region: CYCLE3_REGIONS.g.region },
            { charId: 'b', facePos: CYCLE3_REGIONS.b.facePos, region: CYCLE3_REGIONS.b.region },
          ],
          traps: traps,
          defaultMissReason: 'wrongSpot',
          flatTargetStyle: true,
          flashXOnMiss: true,
          hintText: 'His face can’t be in our row, column, color, or touch our face.',
          onCorrect: function () {
            setColorStage(4);
            showConversation([
              { speaker: 'fray', text: '-dook dook, happy squeak-' },
              { speaker: 'beta', text: 'Well done. I’m going to reset the board. Click any icon at the top to review the hints later.' },
            ], true);
            unlockTipIcon('help');
            setNextEnabled(true);
          },
          onMiss: function (reasonKey) {
            const missText = {
              sameColor: 'That’s Fray’s own color, just not his exact spot — try again!',
              wrongSpot: 'Not quite — remember, his face can’t share our row, column, or color, or touch our face.',
            };
            say('beta', missText[reasonKey] || missText.wrongSpot);
          },
        };
      }

      /* ========== DOM refs ========== */
      const stageEl = document.getElementById('nd-tut-stage');
      const speakerRowEl = document.getElementById('nd-tut-speaker-row');
      const speakerAvatarEl = document.getElementById('nd-tut-speaker-avatar');
      const speakerImg = document.getElementById('nd-tut-speaker-img');
      const speakerName = document.getElementById('nd-tut-speaker-name');
      const speechText = document.getElementById('nd-tut-speech-text');
      const conversationEl = document.getElementById('nd-tut-conversation');
      const choiceRow = document.getElementById('nd-tut-choice-row');
      const nameRow = document.getElementById('nd-tut-name-row');
      const birthdayBox = document.getElementById('nd-tut-birthday');
      const nameSubmitBtn = document.getElementById('nd-tut-name-submit');
      const howtoModal = document.getElementById('nd-tut-howto-modal');
      const howtoClose = document.getElementById('nd-tut-howto-close');
      const howtoGridEl = document.getElementById('nd-tut-howto-grid');
      const howtoFingerEl = document.getElementById('nd-tut-howto-finger');
      const howtoHeartsEl = document.getElementById('nd-tut-howto-hearts');
      const howtoHintIconsEl = document.getElementById('nd-tut-howto-hint-icons');
      const howtoHintIconFace = document.getElementById('nd-tut-howto-hint-icon-face');
      const howtoHintIconUndo = document.getElementById('nd-tut-howto-hint-icon-undo');
      const howtoHintIconXmarks = document.getElementById('nd-tut-howto-hint-icon-xmarks');
      const howtoMarkerIconsEl = document.getElementById('nd-tut-howto-marker-icons');
      const howtoMarkerToggleEl = document.getElementById('nd-tut-howto-marker-toggle');
      const howtoMarkerToggleImg = document.getElementById('nd-tut-howto-marker-toggle-img');
      const howtoMarkerTrashEl = document.getElementById('nd-tut-howto-marker-trash');
      const howtoStepTextEl = document.getElementById('nd-tut-howto-step-text');
      const howtoPipsEl = document.getElementById('nd-tut-howto-pips');
      const howtoBackBtn = document.getElementById('nd-tut-howto-back');
      const howtoNextBtn = document.getElementById('nd-tut-howto-next');
      const howtoReplayBtn = document.getElementById('nd-tut-howto-replay');
      const backLink = document.getElementById('nd-tut-back-link');
      const nextBtn = document.getElementById('nd-tut-next-btn');
      const targetHintEl = document.getElementById('nd-tut-target-hint');
      const hintRow = document.getElementById('nd-tut-hint-row');
      const hintUndoBtn = document.getElementById('nd-tut-hint-undo');
      const hintXBtn = document.getElementById('nd-tut-hint-xmarks');
      const hintFaceBtn = document.getElementById('nd-tut-hint-face');
      const markerToggleBtn = document.getElementById('nd-tut-marker-toggle');
      const markerToggleImg = document.getElementById('nd-tut-marker-toggle-img');
      const clearQuestionsBtn = document.getElementById('nd-tut-clear-questions');
      const markerRow = document.getElementById('nd-tut-marker-row');

      const markerRowToggleBtn = document.getElementById('nd-tut-marker-toggle-btn');
      const markerRowToggleBtnImg = document.getElementById('nd-tut-marker-toggle-btn-img');

      const markerTrashBtn = document.getElementById('nd-tut-marker-trash-btn');
      const tutorialSectionEl = document.querySelector('.neur0doku-tutorial');
      const backModal = document.getElementById('nd-tut-back-modal');
      const backModalHomeBtn = document.getElementById('nd-tut-back-modal-home');
      const backModalResetBtn = document.getElementById('nd-tut-back-modal-reset');
      const backModalCancelBtn = document.getElementById('nd-tut-back-modal-cancel');
      /* ========== PERSISTENT RULE-ICON ROW (Phase 2 scaffold) ==========
        One reusable registration point per icon — id matches the button's
        "nd-tut-rule-icon-<id>" suffix. `iconSrc` is optional; pass null to
        leave whatever's already in the HTML. `openPopupFn` is called on
        click ONLY once that icon has been unlocked (see unlockTipIcon).
        No popups are wired in yet — every call below passes null so
        clicking a locked icon (or, once unlocked, an icon with no popup
        assigned yet) is a safe no-op. */
      const ruleIconButtons = {};

      function registerTipIcon(id, iconSrc, openPopupFn) {
        const btn = document.getElementById('nd-tut-rule-icon-' + id);
        if (!btn) return;
        if (iconSrc) {
          const img = btn.querySelector('img');
          if (img) img.src = iconSrc;
        }
        ruleIconButtons[id] = { btn: btn, unlocked: false, openPopupFn: openPopupFn || null };
        btn.onclick = function () {
          const entry = ruleIconButtons[id];
          if (!entry || !entry.unlocked || !entry.openPopupFn) return;
          entry.openPopupFn();
        };
      }

      /** Call once a topic's popup has been shown for the first time — flips
       * that icon from locked/disabled to a normal, clickable reopen button. */
      function unlockTipIcon(id) {
        const entry = ruleIconButtons[id];
        if (!entry) return;
        entry.unlocked = true;
        entry.btn.disabled = false;
        entry.btn.classList.remove('is-locked');
        entry.btn.setAttribute('aria-label', entry.btn.getAttribute('aria-label').replace(' (locked)', ''));
      }

      // Shell registration — icons already carry their correct src in the
      // HTML, so iconSrc is null for all four. No openPopupFn yet; wiring
      // real popups (and calling unlockTipIcon) is a later phase.
      registerTipIcon('color', null, null);
      registerTipIcon('rowcol', null, null);
      registerTipIcon('touch', null, null);
      registerTipIcon('help', null, null);
      // Lets a later phase attach the real popup opener to an icon
      // registered in Phase 2 WITHOUT resetting its unlocked state —
      // registerTipIcon() itself always creates a fresh { unlocked: false }
      // entry, so calling it a second time would silently re-lock an
      // already-unlocked icon. This is the safe way to wire a popup in
      // after the fact.
      function setTipPopupHandler(id, fn) {
        const entry = ruleIconButtons[id];
        if (entry) entry.openPopupFn = fn;
      }

      /* ========== ONE-SHOT STAGE FINGER HINT (Phase 3, Part A) ==========
        See neur0doku-tutorial.css's own comment on .nd-tut-stage-finger —
        plays once, non-looping, purely cosmetic. stageFingerTimers is
        cleared on every goToPanel() so a stray animation from a panel the
        player already left can never fire into whatever's on screen now. */
      let stageFingerTimers = [];
      function clearStageFingerTimers() {
        stageFingerTimers.forEach(clearTimeout);
        stageFingerTimers = [];
        const stale = stageEl.querySelector('.nd-tut-stage-finger');
        if (stale) stale.remove();
      }
      function playStageFingerTap(pos) {
        const grid = stageEl.querySelector('.nd-tut-grid');
        const cell = grid && grid.querySelector('.nd-tut-cell[data-pos="' + pos + '"]');
        if (!grid || !cell) return;
        grid.style.position = 'relative';

        const finger = document.createElement('img');
        finger.className = 'nd-tut-stage-finger';
        finger.src = '../images/neur0doku_marker-finger.png';
        finger.alt = '';
        finger.style.left = (cell.offsetLeft + cell.offsetWidth / 2) + 'px';
        finger.style.top = (cell.offsetTop + cell.offsetHeight / 2) + 'px';
        grid.appendChild(finger);

        const t = (ms, fn) => stageFingerTimers.push(setTimeout(fn, ms));
        t(150, function () { finger.classList.add('is-visible'); });
        t(650, function () { finger.classList.add('is-tapping'); });
        t(800, function () { finger.classList.remove('is-tapping'); });
        t(950, function () { finger.classList.add('is-tapping'); });
        t(1100, function () { finger.classList.remove('is-tapping'); });
        t(1500, function () { finger.classList.remove('is-visible'); });
        t(1800, function () { finger.remove(); });
      }

      /* ========== LOOPING RULE POPUPS (Phase 3+) ==========
        One factory, reused for every self-contained "here's the rule"
        popup ("One Face per Color," and whatever comes after it) — each
        call builds its OWN independent modal instance (own overlay, own
        3x3 demo grid, own timers), lazily on first open (same
        build-once-reuse pattern as player-card-modal.js's ensureOverlay).
        Every instance loops its own animation lap until dismissed, same
        loop-and-replay shape as the Part 6 howto modal's pips — this is
        the generalized version of that pattern so a new rule doesn't need
        its own bespoke modal wired from scratch. Only one rule popup is
        ever open at once (see activeRulePopup below); opening a second one
        closes whichever was already open first. */
      let activeRulePopup = null;

      function createLoopingRulePopup(config) {
        let overlayEl = null, gridEl = null, fingerEl = null, closeBtn = null;
        let cellEls = null;
        let timers = [];
        let onCloseCallback = null;
        const api = {};

        function t(ms, fn) { timers.push(setTimeout(fn, ms)); }
        function clearTimers() { timers.forEach(clearTimeout); timers = []; }

        function build() {
          if (overlayEl) return;
          overlayEl = document.createElement('div');
          overlayEl.className = 'nd-tut-modal-overlay';
          overlayEl.hidden = true;
          overlayEl.innerHTML =
            '<div class="nd-tut-modal nd-tut-rulepop-box" role="dialog" aria-modal="true">' +
              '<button class="nd-tut-howto-close" type="button" aria-label="Close">&times;</button>' +
              '<h2 class="nd-tut-rulepop-title"></h2>' +
              '<div class="nd-tut-rulepop-demo">' +
                '<div class="nd-tut-rulepop-grid"></div>' +
                '<img class="nd-tut-rulepop-finger" src="../images/neur0doku_marker-finger.png" alt="" />' +
              '</div>' +
            '</div>';
          document.body.appendChild(overlayEl);

          gridEl = overlayEl.querySelector('.nd-tut-rulepop-grid');
          fingerEl = overlayEl.querySelector('.nd-tut-rulepop-finger');
          closeBtn = overlayEl.querySelector('.nd-tut-howto-close');
          overlayEl.querySelector('.nd-tut-rulepop-title').textContent = config.title;

          cellEls = new Map();
          for (let pos = 1; pos <= 9; pos++) {
            const cell = document.createElement('div');
            cell.className = 'nd-tut-howto-cell';
            cell.dataset.pos = String(pos);
            gridEl.appendChild(cell);
            cellEls.set(pos, cell);
          }

          closeBtn.addEventListener('click', closeImpl);
          overlayEl.addEventListener('click', function (e) { if (e.target === overlayEl) closeImpl(); });
        }

        function resetCells() {
          cellEls.forEach(function (cell) {
            cell.className = 'nd-tut-howto-cell';
            cell.innerHTML = '';
            cell.style.background = '';
          });
          fingerEl.classList.remove('is-visible');
        }

        function applyTint() {
          (config.tintCells || []).forEach(function (pos) {
            const cell = cellEls.get(pos);
            if (cell) cell.style.background = 'color-mix(in srgb, ' + charColor(config.tintCharId) + ' 35%, var(--nd-cell-bg) 65%)';
          });
        }

        function moveFinger(pos) {
          const cell = cellEls.get(pos);
          if (!cell) return;
          const demoEl = fingerEl.parentElement;
          const cellRect = cell.getBoundingClientRect();
          const demoRect = demoEl.getBoundingClientRect();
          fingerEl.style.left = (cellRect.left - demoRect.left + cellRect.width / 2) + 'px';
          fingerEl.style.top = (cellRect.top - demoRect.top + cellRect.height / 2) + 'px';
          fingerEl.classList.add('is-visible');
        }

        function markX(pos) {
          const cell = cellEls.get(pos);
          if (!cell || cell.querySelector('.nd-tut-rulepop-xmark')) return;
          const img = document.createElement('img');
          img.className = 'nd-tut-rulepop-xmark';
          img.src = '../images/doku_xmarkb.png';
          img.alt = '';
          cell.appendChild(img);
        }

        function placeFace(pos, charId) {
          const cell = cellEls.get(pos);
          if (!cell) return;
          cell.innerHTML = '';
          const img = document.createElement('img');
          img.className = 'nd-tut-howto-face-img';
          img.src = avatarPath(charId);
          img.alt = '';
          cell.appendChild(img);
        }

        function hideFinger() { fingerEl.classList.remove('is-visible'); }

        const helpers = { moveFinger: moveFinger, markX: markX, placeFace: placeFace, hideFinger: hideFinger, t: t };

        function runLap() {
          clearTimers();
          resetCells();
          applyTint();
          const duration = config.sequence(helpers) || 0;
          t(duration + 1000, runLap); // ~1s pause, per spec, then loop
        }

        function openImpl() {
          build();
          if (activeRulePopup && activeRulePopup !== api) activeRulePopup.close();
          activeRulePopup = api;
          overlayEl.hidden = false;
          runLap();
        }

        function closeImpl() {
          clearTimers();
          if (overlayEl) overlayEl.hidden = true;
          if (activeRulePopup === api) activeRulePopup = null;
          if (onCloseCallback) { const cb = onCloseCallback; onCloseCallback = null; cb(); }
        }

        api.open = function (onClose) { onCloseCallback = onClose || null; openImpl(); };
        api.close = closeImpl;
        return api;
      }

      // Shared by every auto-opening popup (color/rowcol/touch/help) —
      // gives the player a beat to actually SEE the panel underneath
      // before the popup covers it, instead of both painting in the
      // same frame (which read as "the popup appearing on top of the
      // PREVIOUS panel," since the browser never got a chance to
      // paint the new one on its own first).

      // The panel behind a popup is already fully rendered by the time
      // this runs (everything above is synchronous DOM work) — opening
      // immediately means the popup covers the panel right away, and
      // closing it reveals a panel that's been sitting there the whole
      // time, rather than the two racing to appear separately.
      function openRulePopup(popup, iconId) {
        popup.open(function () { unlockTipIcon(iconId); });
      }
      // Alias — a few earlier call sites still use the old delayed
      // name; keeping this means nothing else needs to be found/renamed.
      const openRulePopupDelayed = openRulePopup;

      // Greyscale-to-color foreshadowing, 4 steps — see the matching
      // comment in neur0doku-tutorial.css for the full stage list.
      // Only ever moves forward: a stale/duplicate call (e.g. from a
      // panel re-render) can't ever knock the page BACK to an earlier,
      // greyer stage. Applied to BOTH the tutorial section AND
      // document.body (so the actual page background/var(--bg) fades
      // too, not just the card) — see neur0doku-tutorial.css's
      // body.nd-tut-color-N rules.
      let colorStage = 0;
      function setColorStage(stage) {
        if (stage <= colorStage) return;
        colorStage = stage;
        const stageClasses = ['nd-tut-color-1', 'nd-tut-color-2', 'nd-tut-color-3', 'nd-tut-color-4'];
        if (tutorialSectionEl) {
          stageClasses.forEach(function (c) { tutorialSectionEl.classList.remove(c); });
          tutorialSectionEl.classList.add('nd-tut-color-' + stage);
        }
        stageClasses.forEach(function (c) { document.body.classList.remove(c); });
        document.body.classList.add('nd-tut-color-' + stage);
      }

      // `avatarSrc` is optional — only the merged intro panel
      // overrides it (full-body art before Spindle exists); everyone
      // else falls back to the small head avatar as before.
      //
      // Actively CLEARS the conversation container (not just hides
      // it) — relying on `hidden` alone previously left stale text
      // from an earlier panel visible on screen indefinitely, since a
      // CSS rule elsewhere was silently defeating the hidden attribute
      // (see neur0doku-tutorial.css's header note on this). Clearing
      // content directly means a panel's message can never linger
      // even if some future CSS change reintroduces that problem.
      function say(speakerId, text, avatarSrc) {
        conversationEl.hidden = true;
        conversationEl.innerHTML = '';
        speakerRowEl.hidden = false;
        speakerImg.src = avatarSrc || avatarPath(speakerId);
        speakerAvatarEl.classList.toggle('is-fullbody', Boolean(avatarSrc));
        speakerAvatarEl.classList.remove('is-hero'); // only the merged Part 1 intro uses this
        speakerName.textContent = charName(speakerId);
        speechText.textContent = text;
      }

      // Renders several lines as a stacked transcript. `lines` is
      // [{ speaker, text, avatarSrc?, small? }, ...]. When `fade` is
      // true (everywhere from the Spindle row/column reveal onward —
      // see the DESIGN NOTE at the top of this file) each line fades
      // in one at a time, staggered, instead of all appearing at once;
      // every line still stays on screen once shown (no auto-
      // advancing timers, no line ever disappears on its own) so
      // self-paced reading is unaffected, this just makes it feel
      // more like the characters are actually talking.
      //
      // `small: true` on a line (e.g. Spindle's "Where… am I?") adds
      // the nd-tut-line-small modifier class to that line's text span
      // — a reusable hook for a character talking to themselves
      // rather than to the player, rather than a one-off inline style.
      // See neur0doku-tutorial.css's .nd-tut-line-small rule.
      function showConversation(lines, fade) {
        speakerRowEl.hidden = true;
        speechText.textContent = ''; // see say()'s comment on why content is cleared, not just hidden
        conversationEl.hidden = false;
        conversationEl.innerHTML = '';
        lines.forEach(function (line, i) {
          const row = document.createElement('div');
          row.className = 'nd-tut-speaker-row nd-tut-conversation-line';
          if (fade) {
            row.classList.add('nd-tut-fade-in');
            row.style.animationDelay = (i * 0.5) + 's';
          }
          const avatar = document.createElement('div');
          avatar.className = 'nd-tut-speaker-avatar';
          const img = document.createElement('img');
          img.src = line.avatarSrc || avatarPath(line.speaker);
          img.alt = '';
          avatar.appendChild(img);
          const speech = document.createElement('div');
          speech.className = 'nd-tut-speech';
          const name = document.createElement('span');
          name.className = 'nd-tut-speaker-name';
          name.textContent = charName(line.speaker);
          const text = document.createElement('span');
          text.textContent = line.text;
          if (line.small) text.classList.add('nd-tut-line-small');
          speech.appendChild(name);
          speech.appendChild(text);
          row.appendChild(avatar);
          row.appendChild(speech);
          conversationEl.appendChild(row);
        });
      }
      function hideConversation() {
        conversationEl.hidden = true;
        conversationEl.innerHTML = '';
        speakerRowEl.hidden = false;
      }

      // Same ONE speech box as say(), but with several lines stacked
      // inside it (one speaker, one avatar, multiple rows of text) —
      // used for the merged Part 1 intro ("Hi, I'm Beta!" / "Welcome
      // to neur0doku!") instead of two separate boxes. Each line
      // still fades in on its own stagger, same timing as
      // showConversation's `fade` option.
      function sayLines(speakerId, lines, avatarSrc) {
        conversationEl.hidden = true;
        conversationEl.innerHTML = '';
        speakerRowEl.hidden = false;
        speakerImg.src = avatarSrc || avatarPath(speakerId);
        speakerAvatarEl.classList.toggle('is-fullbody', Boolean(avatarSrc));
        speakerAvatarEl.classList.remove('is-hero'); // caller adds it back if needed
        speakerName.textContent = charName(speakerId);
        speechText.innerHTML = '';
        lines.forEach(function (text, i) {
          const line = document.createElement('span');
          line.className = 'nd-tut-speech-line nd-tut-fade-in';
          line.style.animationDelay = (i * 0.5) + 's';
          line.textContent = text;
          speechText.appendChild(line);
        });
      }

      /* ========== "How this board works" walkthrough (Part 6) ==========
         A small, SELF-CONTAINED 3x3 demo grid — deliberately NOT the
         real board — walks through the 5 things worth knowing before
         the "figure it out yourself" practice round: click-and-drag
         marking (+ a found face's whole region filling in), the row/
         column rule, the no-touch box around a found face, a "?"
         maybe-marker toggle, and the hint-button/Undo/life flow.
         Opens once automatically the first time panel 11 loads (see
         panelHintPractice, howtoAutoShown below); reopenable afterward
         via the tip row's "?" button. Closing — first auto-close OR a
         later manual reopen — always calls goToPanel(11), i.e. a full
         fresh redo of the practice board, per your "clear up a lot of
         confusion" note.

         NOTE ON PIP 4 (the "?" marker): this file's own header
         comment lists the real "?" guess-marker toggle as STILL TODO,
         out of scope, not actually wired into gameplay anywhere yet —
         only the black-X "don't go here" marker is real today. This
         pip demonstrates it anyway, as a preview of a planned
         mechanic, inside this modal's own mock grid only — it doesn't
         (and can't yet) reflect real practice-board behavior. Worth
         confirming this is what you want pip 4 to say; the
         alternative is dropping it to match what's actually live.

         NOTE ON "LIVES": the real tutorial only ever narrates that a
         wrong double-tap "loses a life" (see the Knot/Knell hint
         line) — there's no on-screen life counter anywhere in the
         actual UI yet. Pip 5's three-heart row is this modal's own
         invented stand-in to illustrate the idea, not a readout of
         real state. */
      const HOWTO_DEMO_POSITIONS = [1, 2, 3, 4, 5, 6, 7, 8, 9]; // 3x3, row-major
      const HOWTO_FACE_POS = 5; // center — every pip's "found face" lives here
      let howtoCellEls = null;
      let howtoTimers = [];
      let howtoStepIndex = 0;
      let helpPopupAutoShown = false;

      function buildHowtoGrid() {
        if (howtoCellEls) return; // built once, reused across every open/step
        howtoCellEls = new Map();
        HOWTO_DEMO_POSITIONS.forEach(function (pos) {
          const cell = document.createElement('div');
          cell.className = 'nd-tut-howto-cell';
          cell.dataset.pos = String(pos);
          howtoGridEl.appendChild(cell);
          howtoCellEls.set(pos, cell);
        });
      }

      // howtoRunMaxDelay tracks the latest `ms` any playHowtoStepN() has
      // scheduled during its (synchronous) run — that's the exact
      // moment the current pip's animation finishes. playCurrentStep()
      // reads it right after calling step.run() to know when to loop
      // back around, without every step needing to declare its own
      // duration by hand.
      let howtoRunMaxDelay = 0;
      function howtoAfter(ms, fn) {
        if (ms > howtoRunMaxDelay) howtoRunMaxDelay = ms;
        howtoTimers.push(setTimeout(fn, ms));
      }
      function clearHowtoTimers() { howtoTimers.forEach(clearTimeout); howtoTimers = []; }

      function resetHowtoDemo() {
        howtoCellEls.forEach(function (cell) {
          cell.className = 'nd-tut-howto-cell';
          cell.textContent = '';
          cell.style.background = ''; // pip 1 sets inline background (Spindle/Beta tints) — clear it every reset/loop
        });
        howtoHeartsEl.hidden = true;
        howtoHeartsEl.querySelectorAll('[data-heart]').forEach(function (h) { h.classList.remove('is-lost'); });
        howtoHintIconsEl.hidden = true;
        howtoHintIconFace.classList.remove('is-pressed');
        howtoHintIconUndo.classList.remove('is-pressed');
        howtoHintIconXmarks.classList.remove('is-pressed');
        howtoMarkerIconsEl.hidden = true;
        howtoMarkerToggleEl.classList.remove('is-pressed');
        howtoMarkerToggleImg.src = MARKER_X_SRC;
        howtoMarkerTrashEl.classList.remove('is-pressed');
        howtoFingerEl.classList.remove('is-visible');
      }

      const MARKER_X_SRC = '../images/neur0doku_marker-x.png';
      const MARKER_Q_SRC = '../images/neur0doku_marker-q.png';
      const QUESTIONMARK_SRC = '../images/doku_questionmark.png';

      function placeHowtoQuestionMark(cell) {
        const img = document.createElement('img');
        img.className = 'nd-tut-howto-qmark';
        img.src = QUESTIONMARK_SRC;
        img.alt = '';
        cell.appendChild(img);
      }
      function clearHowtoQuestionMark(cell) {
        const existing = cell.querySelector('.nd-tut-howto-qmark');
        if (existing) existing.remove();
      }

      // Positions the finger image over `cell`'s center. Both the grid
      // and the finger share the same offsetParent (.nd-tut-howto-demo,
      // position: relative), so getBoundingClientRect deltas are all
      // that's needed — no scroll-offset math required since this is
      // all inside a fixed-position modal overlay.
      function moveFingerTo(cell) {
        const demoEl = howtoFingerEl.parentElement;
        const cellRect = cell.getBoundingClientRect();
        const demoRect = demoEl.getBoundingClientRect();
        howtoFingerEl.style.left = (cellRect.left - demoRect.left + cellRect.width / 2) + 'px';
        howtoFingerEl.style.top = (cellRect.top - demoRect.top + cellRect.height / 2) + 'px';
        howtoFingerEl.classList.add('is-visible');
      }

      // Renders `charId`'s real avatar inside `cell` (item 2 — no more
      // text-dot placeholder). By the time this modal can ever open
      // (Part 6's practice round), every tutorial character has already
      // been found earlier in the story (see runColoredPracticeBoard's
      // own defensive markCharacterFound call above), so avatarPath()
      // resolves to the real, non-grey art for both 'beta' and
      // 'spindle' here — no special-casing needed.
      function placeHowtoPortrait(cell, charId) {
        const img = document.createElement('img');
        img.className = 'nd-tut-howto-face-img';
        img.src = avatarPath(charId);
        img.alt = '';
        cell.appendChild(img);
      }

      function placeHowtoFace(pos) {
        const cell = howtoCellEls.get(pos);
        cell.classList.add('is-face');
        placeHowtoPortrait(cell, 'beta');
      }

      // ---- Pip 4 (now the first pip): marker-tool swap (X -> "?"), placing + clearing
      // question marks (see NOTE ON PIP 4 above — this whole toggle/
      // trash mechanic is still a planned feature, not real gameplay
      // yet; this pip previews it inside the demo grid only). ----
      function playHowtoStep4() {
        resetHowtoDemo();
        howtoMarkerIconsEl.hidden = false;
        const xPositions = [2, 4]; // demonstrate X-mode marking first
        const qPositions = [3, 7, 9]; // then swap to "?" mode and stamp a few more

        // ---- place two X's while still in the default X-marker mode ----
        var t = 300;
        xPositions.forEach(function (pos) {
          var cell = howtoCellEls.get(pos);
          howtoAfter(t, function () { moveFingerTo(cell); });
          howtoAfter(t + 220, function () { cell.classList.add('is-marked-x'); cell.textContent = '✕'; });
          t += 420;
        });

        // ---- swap the marker tool from X to "?" ----
        howtoAfter(t, function () { moveFingerTo(howtoMarkerToggleEl); });
        t += 350;
        howtoAfter(t, function () { howtoMarkerToggleEl.classList.add('is-pressed'); });
        t += 250;
        howtoAfter(t, function () {
          howtoMarkerToggleEl.classList.remove('is-pressed');
          howtoMarkerToggleImg.src = MARKER_Q_SRC;
        });
        t += 400;

        // ---- place question marks in "?" mode ----
        qPositions.forEach(function (pos) {
          var cell = howtoCellEls.get(pos);
          howtoAfter(t, function () { moveFingerTo(cell); });
          howtoAfter(t + 220, function () { placeHowtoQuestionMark(cell); });
          t += 420;
        });

        // ---- trash clears every "?" — the X's from earlier are untouched ----
        howtoAfter(t, function () { moveFingerTo(howtoMarkerTrashEl); });
        t += 250;
        howtoAfter(t, function () { howtoMarkerTrashEl.classList.add('is-pressed'); });
        t += 200;
        howtoAfter(t, function () {
          howtoMarkerTrashEl.classList.remove('is-pressed');
          qPositions.forEach(function (pos) { clearHowtoQuestionMark(howtoCellEls.get(pos)); });
        });
      }

      // ---- Pip 5: all three hint buttons (4 X's, Reveal face, Undo)
      // + a wrong tap costing (and Undo restoring) a life ----
      function playHowtoStep5() {
        resetHowtoDemo();
        howtoHeartsEl.hidden = false;
        howtoHintIconsEl.hidden = false;

        // 1) "4 X's" — marks four wrong (non-face) cells at once.
        howtoAfter(200, function () { howtoHintIconXmarks.classList.add('is-pressed'); });
        howtoAfter(500, function () {
          howtoHintIconXmarks.classList.remove('is-pressed');
          [1, 3, 7, 9].forEach(function (pos) {
            var c = howtoCellEls.get(pos);
            c.classList.add('is-marked-x');
            c.textContent = '✕';
          });
        });

        // 2) "Reveal face" — auto-places the center face.
        howtoAfter(1000, function () { howtoHintIconFace.classList.add('is-pressed'); });
        howtoAfter(1300, function () { howtoHintIconFace.classList.remove('is-pressed'); placeHowtoFace(HOWTO_FACE_POS); });

        // 3) A wrong double-tap elsewhere costs a life.
        howtoAfter(1750, function () { moveFingerTo(howtoCellEls.get(4)); });
        howtoAfter(2100, function () {
          var wrong = howtoCellEls.get(4);
          wrong.classList.remove('is-marked-x');
          wrong.textContent = '';
          wrong.classList.add('is-wrong-x');
          wrong.textContent = '✕';
          var heart3 = howtoHeartsEl.querySelector('[data-heart="3"]');
          if (heart3) heart3.classList.add('is-lost');
        });

        // 4) Undo takes back that last move and gives the life back —
        // it does NOT clear the "4 X's" hint marks (matching the real
        // hintUndoBtn, which only reverts the player's own last
        // placement + red fail marks, not hint-tool marks). Holds the
        // wrong "✕" on screen for about a second before Undo touches it
        // (item 5 — was only ~450ms, too quick to actually see).
        howtoAfter(3150, function () { howtoHintIconUndo.classList.add('is-pressed'); });
        howtoAfter(3450, function () {
          howtoHintIconUndo.classList.remove('is-pressed');
          var wrong = howtoCellEls.get(4);
          wrong.classList.remove('is-wrong-x');
          wrong.textContent = '';
          var heart3 = howtoHeartsEl.querySelector('[data-heart="3"]');
          if (heart3) heart3.classList.remove('is-lost');
        });
      }

      // Trimmed to the 2 hint-tool pips — color/row-col/touch are
      // retired here; those each have their own top-row icon+popup
      // now (oneFacePerColorPopup / noRowOrColumnPopup / noTouchingFacesPopup).
      const HOWTO_STEPS = [
        { text: 'Single-tap and drag places whichever marker is selected. Try “✕” first — then tap the marker tool to swap to “?”, and the trash icon clears every “?” at once (✕ marks are never touched). This can be useful at harder difficulties.', run: playHowtoStep4 },
        { text: 'Feeling stuck? The lightbulb icon will marks four wrong cells for you. The face icon will reveal a face. The Undo arrow takes back your last move. A wrong double-tap costs a life; Undo gives it back.', run: playHowtoStep5 },
      ];

      // Runs the current pip's animation, then re-arms itself to loop:
      // once howtoRunMaxDelay reports when that run's last scheduled
      // event lands, it schedules a fresh call to itself a beat later
      // (via howtoAfter, so a step/close/Replay always cancels it
      // cleanly through the ordinary clearHowtoTimers() path). The ↻
      // button below calls this directly to restart on demand.
      const HOWTO_LOOP_PAUSE_MS = 1100;
      function playCurrentStep() {
        clearHowtoTimers();
        howtoRunMaxDelay = 0;
        const step = HOWTO_STEPS[howtoStepIndex];
        step.run();
        howtoAfter(howtoRunMaxDelay + HOWTO_LOOP_PAUSE_MS, playCurrentStep);
      }

      function renderHowtoStep(i) {
        clearHowtoTimers();
        howtoStepIndex = i;
        const step = HOWTO_STEPS[i];
        howtoStepTextEl.textContent = step.text;
        howtoPipsEl.innerHTML = '';
        HOWTO_STEPS.forEach(function (s, idx) {
          const pip = document.createElement('span');
          pip.className = 'nd-tut-howto-pip' + (idx === i ? ' is-active' : '');
          howtoPipsEl.appendChild(pip);
        });
        howtoBackBtn.disabled = i === 0;
        howtoNextBtn.textContent = i === HOWTO_STEPS.length - 1 ? 'Got it' : 'Next';
        playCurrentStep();
      }

      function openHowtoModal() {
        buildHowtoGrid();
        howtoModal.hidden = false;
        renderHowtoStep(0);
      }

      // Per your "clear up a lot of confusion" note: closing this modal
      // ALWAYS redoes the current practice board fresh — whether this
      // is the automatic first-open close or a later manual reopen via
      // the tip row's "?" button. goToPanel(11) is the exact same path
      // normal navigation uses, so this gets the same clean reset
      // (clearAllMessages, a fresh board, hint buttons re-armed) rather
      // than a bespoke partial-reset function.
            function closeHowtoModal() {
        clearHowtoTimers();
        howtoModal.hidden = true;
        if (panelIndex === 11) goToPanel(11); // only reset the practice board if it's actually the panel on screen
      }

      howtoClose.addEventListener('click', closeHowtoModal);
      howtoModal.addEventListener('click', function (e) {
        if (e.target === howtoModal) closeHowtoModal();
      });
      howtoNextBtn.addEventListener('click', function () {
        if (howtoStepIndex >= HOWTO_STEPS.length - 1) { closeHowtoModal(); return; }
        renderHowtoStep(howtoStepIndex + 1);
      });
      howtoBackBtn.addEventListener('click', function () {
        if (howtoStepIndex > 0) renderHowtoStep(howtoStepIndex - 1);
      });
      howtoReplayBtn.addEventListener('click', playCurrentStep);

      // The top-row (?) icon opens this same modal now — see
      // registerTipIcon('help', ...) near the top of this script, and
      // frayStep's onCorrect (panel 10) for where it gets unlocked.
      setTipPopupHandler('help', openHowtoModal);

      function showTargetHint(text) {
        targetHintEl.hidden = false;
        targetHintEl.textContent = text || 'Double-tap the glowing cell.';
      }
      function hideTargetHint() {
        targetHintEl.hidden = true;
        targetHintEl.textContent = '';
      }
      // Small cooldown whenever Next becomes clickable, rather than a
      // hard instant enable — closes the gap where a fast double-click
      // (meant as one tap) could land a second click the instant the
      // button re-enables, skipping straight past a popup or a line of
      // dialogue the player hasn't read yet.
      const NEXT_BTN_COOLDOWN_MS = 350;
      let nextBtnCooldownTimer = null;
      function setNextEnabled(enabled) {
        if (nextBtnCooldownTimer) { clearTimeout(nextBtnCooldownTimer); nextBtnCooldownTimer = null; }
        if (!enabled) {
          nextBtn.disabled = true;
          return;
        }
        nextBtn.disabled = true;
        nextBtnCooldownTimer = setTimeout(function () {
          nextBtnCooldownTimer = null;
          nextBtn.disabled = false;
        }, NEXT_BTN_COOLDOWN_MS);
      }

      // Single place that fully resets every message/board-adjacent
      // region between panels — called first thing in goToPanel().
      // This is the direct answer to "clear everything after Next":
      // every one of these actually empties its content, not just
      // hides it, so nothing can ever visually linger from a
      // previous panel regardless of what CSS does elsewhere.
      function clearAllMessages() {
        hideConversation();
        hideTargetHint();
        choiceRow.hidden = true;
        choiceRow.innerHTML = '';
        nameRow.hidden = true;
        birthdayBox.hidden = true;
        birthdayBox.innerHTML = '';
        markerRow.hidden = true;
        hintRow.hidden = true;
      }

      /* ========== GENERIC BOARD ENGINE ========== */

      // 1-indexed, row-major, matching the planning grids.
      function posToRC(pos, n) {
        const i = pos - 1;
        return { row: Math.floor(i / n), col: i % n };
      }
      // Inverse of posToRC — used by the face-board builder, which
      // builds its layout from a row->column skeleton rather than a
      // hand-listed set of positions like the earlier boards.
      function rcToPos(row, col, n) {
        return row * n + col + 1;
      }

      // Smaller board as n grows, and smaller overall than the old
      // fixed 52px/44px cells — matches the tighter mockup sizing.
      // Cell size now grows with the screen. At 360px wide (tiny) it is
      // exactly the old fixed size; at 430px wide (large) the board fills
      // the content width (16px from each edge); in between (393 medium)
      // it lands partway. A height cap keeps a big board from crowding
      // the speech text on short screens.
      function cellPxFor(n) {
        const base = Math.max(34, 60 - (n - 3) * 8);        // the old size = tiny
        const vw = window.innerWidth || 360;
        const vh = window.innerHeight || 740;
        const contentW = Math.min(vw, 420) - 32;              // tutorial column minus its padding
        const chrome = 16 + 4 * (n - 1);                      // grid padding + gaps
        const maxCell = Math.floor((contentW - chrome) / n);  // cell size that fills the width
        const t = Math.max(0, Math.min(1, (vw - 360) / 100));  // 0 at 360px, 1 at 430px
        let cell = base + (maxCell - base) * t;
        const maxByHeight = Math.floor((vh * 0.5 - chrome) / n);
        cell = Math.min(cell, Math.max(base, maxByHeight));
        return Math.max(20, Math.min(Math.round(cell), maxCell));
      }

      // Shared <img> sizing for the tutorial's mark overlays (tap-mark
      // black X, persistent fail red X) — matches play.js's own
      // makeMarkImg() convention (a ratio of the CELL's actual current
      // pixel size, applied as inline max-width/max-height) instead of
      // leaving sizing entirely to a fixed CSS percentage. The CSS
      // percentages previously used here (50%/42%) worked out smaller
      // than play.js's real board (0.55 of cell size), which is why
      // these marks read noticeably smaller than the real game's.
      // cell.offsetWidth is read live rather than recomputed from
      // cellPxFor(n) so this stays correct even if a board's actual
      // rendered size ever drifts from that formula.
      const MARK_SIZE_RATIO = 0.55;
      function sizeMarkImg(img, cell) {
        const size = Math.max(10, Math.round(cell.offsetWidth * MARK_SIZE_RATIO));
        img.style.maxWidth = size + 'px';
        img.style.maxHeight = size + 'px';
      }

      // Single-tap (or click-and-drag across several cells) "don't go
      // here" marker — a black X image on a still-blank cell. Doesn't
      // interfere with the cell's own dblclick handler (double-tap
      // still attempts a placement). See the DESIGN NOTE at the top
      // of this file for scope: only this one black-X mode exists so
      // far, no "?" guess marker yet.
      //
      // Drag behavior: pressing down on a cell decides the "paint
      // mode" for the whole gesture from THAT cell's current state —
      // unmarked -> dragging adds marks to every cell the pointer
      // passes over; marked -> dragging removes them. A plain tap
      // (press + release without leaving the cell) just toggles that
      // one cell, same as before. One shared drag-mode variable is
      // enough since only one board is ever interactive at a time.
      //
      // BUG FIX — a genuine double-tap on a tap-markable cell used to
      // show a brief black X (from the FIRST tap's pointerdown) before
      // the double-tap's real result (face or persistent red X)
      // resolved, since both systems are wired to the same cell and a
      // double-tap is physically two separate pointerdown events. The
      // origin cell's own paint (not cells reached mid-drag — those
      // still paint immediately, so dragging stays responsive) is now
      // delayed by DOUBLE_TAP_GUARD_MS; a second pointerdown on that
      // SAME cell within the window (the back half of a double-tap)
      // cancels the pending paint outright, so only a genuine
      // stationary single tap ever actually shows the black X.
      let tapDragMode = null; // 'add' | 'remove' | null
      // Which marker the single-tap tool currently places — 'x' (the
      // long-standing "don't go here" mark) or 'question' (a maybe).
      // Only the panel 11 practice round lets the player switch this
      // (see runColoredPracticeBoard below); every earlier board just
      // leaves it at the 'x' default, same as before this existed.
      let practiceMarkMode = 'x';
      const TAP_MARK_SRC = {
        x: '../images/doku_xmarkb.png',
        question: '../images/doku_questionmark.png',
      };
      const DOUBLE_TAP_GUARD_MS = 350;
      let pendingOriginPaint = null; // { cell, willAdd, timer } | null
      function flushPendingOriginPaint() {
        if (pendingOriginPaint) {
          clearTimeout(pendingOriginPaint.timer);
          setTapMark(pendingOriginPaint.cell, pendingOriginPaint.willAdd);
          pendingOriginPaint = null;
        }
      }
      function cancelPendingOriginPaint() {
        if (pendingOriginPaint) {
          clearTimeout(pendingOriginPaint.timer);
          pendingOriginPaint = null;
        }
      }
      // ---- Part D: real marker mode (X vs ?) ----
      // Only ever meaningfully toggled on the practice board (panel
      // 11) — the toggle/trash buttons are hidden everywhere else —
      // but this stays a single module-level flag rather than a
      // per-board one, reset to 'x' on every goToPanel() (see below)
      // so it can never leak a stale '?' mode into an earlier panel
      // (Knot/Knell's 4x4, etc.) that only ever expects black-X marks.
      let tutorialMarkMode = 'x'; // 'x' | 'question'
      function setTutorialMarkMode(mode) {
        tutorialMarkMode = mode;
        markerRowToggleBtnImg.src = mode === 'question' ? MARKER_Q_SRC : MARKER_X_SRC;
        markerRowToggleBtn.setAttribute('aria-pressed', String(mode === 'question'));
        markerRowToggleBtn.setAttribute(
          'aria-label',
          mode === 'x' ? 'Currently marking with X. Tap to switch to ?' : 'Currently marking with ?. Tap to switch to X'
        );
      }
      markerRowToggleBtn.addEventListener('click', function () {
        setTutorialMarkMode(tutorialMarkMode === 'x' ? 'question' : 'x');
      });
      // Mirrors play.js's clearQuestionsBtn — clears every placed "?"
      // at once, and ONLY "?" marks, same as the real game (an X mark
      // is a real "don't go here" note the player placed on purpose,
      // not the "just testing a maybe" kind this button is for).
      function clearPracticeQuestionMarks() {
        stageEl.querySelectorAll('.nd-tut-tap-mark.is-question').forEach(function (img) { img.remove(); });
      }
      markerTrashBtn.addEventListener('click', clearPracticeQuestionMarks);

      // Toggling a cell (single tap, or a drag pass over it) always
      // just adds-or-removes THE mark that's currently there,
      // regardless of what mode is active right now — same "existing
      // mark just clears, it doesn't swap types" behavior play.js's
      // own setSingle() has (a blank cell always adopts the CURRENT
      // markMode; an already-marked cell always clears back to blank).
      function setTapMark(cell, on) {
        const existing = cell.querySelector('.nd-tut-tap-mark');
        if (on && !existing) {
          const img = document.createElement('img');
          img.className = 'nd-tut-tap-mark';
          img.src = TAP_MARK_SRC[practiceMarkMode] || TAP_MARK_SRC.x;
          img.alt = '';
          sizeMarkImg(img, cell);
          cell.appendChild(img);
        } else if (!on && existing) {
          existing.remove();
        }
      }
      function enableTapMarking(cell) {
        cell.onpointerdown = function () {
          // Second pointerdown on the same still-unpainted cell — the
          // back half of a double-tap. The dblclick handler is about
          // to resolve this cell for real (a placement or a miss);
          // drop the pending single-tap paint so it never flashes.
          if (pendingOriginPaint && pendingOriginPaint.cell === cell) {
            cancelPendingOriginPaint();
            tapDragMode = null;
            return;
          }
          cancelPendingOriginPaint();
          const willAdd = !cell.querySelector('.nd-tut-tap-mark');
                    tapDragMode = willAdd ? 'add' : 'remove';
          lastDragCell = cell; // the drag starts here (see TOUCH DRAG below)
          pendingOriginPaint = {
            cell: cell,
            willAdd: willAdd,
            timer: setTimeout(function () {
              pendingOriginPaint = null;
              setTapMark(cell, willAdd);
            }, DOUBLE_TAP_GUARD_MS),
          };
        };
        cell.onpointerenter = function () {
          if (!tapDragMode) return;
          // A real drag is happening (pointer entered a DIFFERENT
          // cell) — flush the origin cell's delayed paint immediately,
          // it's not going to become a double-tap now, then paint
          // this newly-entered cell same as before.
          flushPendingOriginPaint();
          setTapMark(cell, tapDragMode === 'add');
        };
      }
      function disableTapMarking(cell) {
        cell.onpointerdown = null;
        cell.onpointerenter = null;
        if (pendingOriginPaint && pendingOriginPaint.cell === cell) cancelPendingOriginPaint();
        const existing = cell.querySelector('.nd-tut-tap-mark');
        if (existing) existing.remove();
      }
      // Ends the drag gesture wherever the pointer is released, even
      // outside the board.
      document.addEventListener('pointerup', function () { tapDragMode = null; });
      document.addEventListener('pointercancel', function () { tapDragMode = null; });

      // TOUCH DRAG (2026-09-23): on phones a finger stays attached to
      // the cell it started on, so the cells it slides over never get
      // pointerenter. Find the cell under the finger instead, the same
      // way the real game's board does it.
      let lastDragCell = null;
      document.addEventListener('pointermove', function (e) {
        if (!tapDragMode || e.pointerType === 'mouse') return;
        const el = document.elementFromPoint(e.clientX, e.clientY);
        const cell = el && el.closest ? el.closest('.nd-tut-cell') : null;
        if (!cell || cell === lastDragCell) return;
        lastDragCell = cell;
        if (typeof cell.onpointerenter === 'function') cell.onpointerenter(e);
      });

      // Red "X" (doku_xmarkr.png) that PERSISTS on a wrong double-tap
      // (not just a brief flash) — from the touch-rule reveal onward
      // (Part 3), so a repeated wrong guess keeps showing the player
      // they already tried that cell instead of inviting another
      // double-tap. Deduped: a cell that's already marked doesn't
      // stack a second image. Cleared board-wide by clearAllFailMarks
      // (wired to the Undo hint button).
      function persistFailMark(cell) {
        if (justFoundSomeone() || cell.querySelector('.nd-tut-face-img')) return;
        if (cell.querySelector('.nd-tut-fail-x')) return;
        const img = document.createElement('img');
        img.className = 'nd-tut-fail-x';
        img.src = '../images/doku_xmarkr.png';
        img.alt = '';
        sizeMarkImg(img, cell);
        cell.appendChild(img);
      }
      function clearAllFailMarks() {
        stageEl.querySelectorAll('.nd-tut-fail-x').forEach(function (img) { img.remove(); });
      }

      // Renders `step` fresh into the stage and wires every cell.
      // Returns nothing — steps are stateless from the caller's POV;
      // all state (which targets are found) lives inside this closure
      // for the lifetime of the step.
      // `placed` entries accept either the original shape
      // ({ pos, charId } — a single colored cell, e.g. Beta's own
      // singleton spot) or the newer region shape
      // ({ charId, facePos, region: [...] } — every cell in `region`
      // gets that character's real color, but the face image only
      // ever appears at `facePos`). Both are normalized to the same
      // internal shape here so renderBoard doesn't need to care which
      // one a caller used.
      function normalizePlaced(entry) {
        if (entry.region) return { charId: entry.charId, facePos: entry.facePos, region: entry.region };
        return { charId: entry.charId, facePos: entry.pos, region: [entry.pos] };
      }

      function renderBoard(step) {
        const n = step.n;
        const cellPx = cellPxFor(n);
        const grid = document.createElement('div');
        grid.className = 'nd-tut-grid';
        grid.style.gridTemplateColumns = 'repeat(' + n + ', ' + cellPx + 'px)';
        grid.style.gridAutoRows = cellPx + 'px';

        const flatClass = step.frayFlatTarget ? 'is-flat-target-fray' : 'is-flat-target';

        const placedColorMap = new Map(); // pos -> charId, for every cell in a placed region
        const placedFaceMap = new Map();  // pos -> charId, only the one cell that shows the face image
        (step.placed || []).forEach(function (raw) {
          const entry = normalizePlaced(raw);
          entry.region.forEach(function (p) { placedColorMap.set(p, entry.charId); });
          placedFaceMap.set(entry.facePos, entry.charId);
        });
        const targetMap = new Map((step.targets || []).map(function (t) { return [t.pos, t]; }));
        const trapMap = step.traps || {};
        const foundTargets = new Set();
        const totalTargets = targetMap.size;
        const cellElsByPos = new Map(); // pos -> element, so a found target can also color its surrounding region

        function flashMiss(cell, reasonKey, pos) {
          cell.classList.add('is-blocked-flash');
          setTimeout(function () { cell.classList.remove('is-blocked-flash'); }, 320);
          if (justFoundSomeone()) return;
          if (tapOnFoundFace(cell)) return;
          if (step.onMiss) step.onMiss(reasonKey, pos);
        }

        for (let pos = 1; pos <= n * n; pos++) {
          const cell = document.createElement('div');
          cell.className = 'nd-tut-cell';
          cell.dataset.pos = String(pos);
          cellElsByPos.set(pos, cell);

          if (placedColorMap.has(pos)) {
            const charId = placedColorMap.get(pos);
            cell.style.background = charColor(charId);
            cell.classList.add('is-interactive');
            if (placedFaceMap.has(pos)) {
              const img = document.createElement('img');
              img.className = 'nd-tut-face-img';
              img.src = avatarPath(charId);
              img.alt = charName(charId);
              cell.appendChild(img);
            }
            cell.ondblclick = function () { flashMiss(cell, 'alreadyFound', pos); };
          } else if (targetMap.has(pos)) {
            const targetEntry = targetMap.get(pos);
            const charId = targetEntry.charId;
            // No inline background here (unless flatTargetStyle) —
            // `.is-target` in CSS gives it the darker "this one's
            // glowing" grey. Setting an inline style would win over
            // that class rule, so we leave it to CSS on purpose.
            if (step.flatTargetStyle) {
              cell.classList.add('is-interactive', flatClass);
            } else {
              cell.classList.add('is-interactive', 'is-target');
            }
            cell.ondblclick = function () {
              if (foundTargets.has(pos)) return;
              foundTargets.add(pos);
              markCharacterFound(charId); // grey→color avatar switch (covers Beta + Fray via this shared engine)
              disableTapMarking(cell);
              // `revealRegion` (optional) colors more than just the
              // clicked cell — e.g. finding Knot/Knell also lights up
              // their whole surrounding region, matching a real board's
              // look, not just one isolated square. Defaults to just
              // [pos] for targets that don't specify one (backward
              // compatible with every earlier single-cell target).
              const revealRegion = targetEntry.revealRegion || [pos];
              revealRegion.forEach(function (rp) {
                const rc = cellElsByPos.get(rp);
                rc.classList.remove('is-target', flatClass, 'is-search-area');
                rc.classList.add('is-interactive');
                rc.style.background = charColor(charId);
                rc.ondblclick = function () { flashMiss(rc, 'alreadyFound', rp); };
                disableTapMarking(rc);
              });
              const img = document.createElement('img');
              img.className = 'nd-tut-face-img';
              img.src = avatarPath(charId);
              img.alt = charName(charId);
              cellElsByPos.get(pos).appendChild(img);
              if (step.onCorrect) step.onCorrect(charId, pos);
              if (foundTargets.size === totalTargets && step.onAllFound) step.onAllFound();
            };
            if (step.tapMarkable) enableTapMarking(cell);
          } else {
            cell.classList.add('is-interactive');
            // flatTargetStyle covers trap cells too, not just the
            // real target — the whole "figure it out" region (e.g.
            // Fray's 7/12/16/17/21) should read as one uniform grey,
            // not just the one cell that happens to be correct.
            if (step.flatTargetStyle) cell.classList.add(flatClass);
            const reasonKey = trapMap[pos] || step.defaultMissReason || 'blank';
            cell.ondblclick = function () {
              flashMiss(cell, reasonKey, pos);
              if (step.flashXOnMiss) persistFailMark(cell);
            };
            if (step.tapMarkable) enableTapMarking(cell);
          }

          // Optional visual nudge: cells listed in `dimPositions` get
          // dimmed (see .is-dimmed in the CSS) to draw the eye toward
          // wherever the step actually wants the player looking.
          // Purely visual — click behavior above is unaffected.
          if (step.dimPositions && step.dimPositions.indexOf(pos) !== -1) {
            cell.classList.add('is-dimmed');
          }

          // Optional "search zone" outline: cells listed in
          // `highlightPositions` get a static (non-pulsing) accent
          // ring so the player knows which cells to focus on, without
          // singling out the one correct cell the way `.is-target`
          // does. Applies whether the cell turns out to be the real
          // target or one of the traps around it.
          if (step.highlightPositions && step.highlightPositions.indexOf(pos) !== -1) {
            cell.classList.add('is-search-area');
          }

          grid.appendChild(cell);
        }

        stageEl.innerHTML = '';
        stageEl.appendChild(grid);

        if (totalTargets > 0) showTargetHint(step.hintText);
        else hideTargetHint();
      }

      /* ========== BOARD DATA ==========
         Planning-grid positions per your latest spec. `pick1Id`/
         `pick2Id` are resolved once the player makes the Knot/Knell
         choice and reused on the 4x4 + 5x5 boards below. */

      let pick1Id = null;
      let pick2Id = null;
      // Which of the bottom row (7/8/9) the player actually double-
      // tapped to find Spindle — set once in renderSpindleRowFind's
      // onFound callback, then reused by every later static redisplay
      // of this board so his face stays wherever the player put it
      // instead of snapping to a hardcoded default. Falls back to 9
      // only in the defensive case a later panel somehow renders
      // before this is set.
      let spindleFacePos = null;

      // Which of the "advance" cells (4/5/6) the player double-tapped
      // on the Part 3 third-fail board to move past it — set in
      // renderThirdFailBoard's advance handler, reset to null each
      // time that board renders. Panel 7 re-applies a persistent red
      // X to this same cell on its own fresh board so the spot they
      // tried stays visibly marked across the transition, instead of
      // the mark vanishing the instant the board is rebuilt.
      let thirdFailClickedPos = null;

      // 3x3 — teaching board (color rule)
      //   1 2 3
      //   4 5 6
      //   7 8 9
      // Beta = 2 (top-middle).
      function teachBetaStep() {
        return {
          n: 3,
          targets: [{ pos: 2, charId: 'beta' }],
          placed: [],
          defaultMissReason: 'missBeta',
          hintText: 'Double-tap the glowing cell to place the face.',
          onCorrect: function () {
            say('beta', 'That’s my face. It seems you’ve given the cube color, wonderful job.');
            setNextEnabled(true);
          },
          onMiss: function (reasonKey) {
            say('beta', 'Oh, that was not where I was. Double-tap the glowing cube.');
          },
        };
      }

      // Shorthand for redisplaying Spindle's already-found region on
      // every later static board — always the same 3 cells, face at
      // wherever the player actually clicked (see spindleFacePos above).
      function spindleRegionPlaced() {
        return { charId: 'spindle', facePos: spindleFacePos || 9, region: [7, 8, 9] };
      }

      // 3x3 — Spindle's row/column reveal. ANY of the bottom row's two
      // VALID cells (7 or 9) completes this. Cell 8 is deliberately
      // NOT valid — it shares Beta's own column (col 1), which would
      // violate the very rule this step is teaching.
      //
      // Fail-state copy is grouped per your latest spec: cells
      // 1/3/5/8 share one message, cells 4/6 share another — not a
      // typo, just how the copy landed (8 is a genuine trap, not a
      // valid cell, even though it reads oddly next to 1/3/5).
      //
      // On finding Spindle, this immediately fades in the NEXT
      // panel's conversation on this SAME board — no Next click in
      // between (see the onFound callback below and its caller in
      // PANELS[4]).
      //
      // Built as its own function (like buildColoredFaceBoard further down)
      // rather than bent into the generic renderBoard(step) engine,
      // which only knows "one specific cell per target" — an "any of
      // these" group isn't worth generalizing into that shared path
      // for a single use.
      function renderSpindleRowFind(callbacks) {
        const n = 3;
        const cellPx = cellPxFor(n);
        const grid = document.createElement('div');
        grid.className = 'nd-tut-grid';
        grid.style.gridTemplateColumns = 'repeat(' + n + ', ' + cellPx + 'px)';
        grid.style.gridAutoRows = cellPx + 'px';

        const ROW = [7, 8, 9];
        const VALID_POSITIONS = [7, 9]; // 8 shares Beta's column — not valid
        const GROUP_A = [1, 3, 5];
        const GROUP_B = [4, 6];
        const cellEls = new Map();
        let resolved = false;

        // Brief flash, not persistent — this is the tutorial's FIRST
        // fail state, before the "so you stop double-tapping it
        // again" persistent marking kicks in from the touch-rule
        // reveal onward (Part 3). Deliberately its own local copy so
        // this one panel keeps the original transient behavior.
        function transientFailMark(cell) {
          if (cell.querySelector('.nd-tut-face-img')) return;
          const img = document.createElement('img');
          img.className = 'nd-tut-fail-x';
          img.src = '../images/doku_xmarkr.png';
          img.alt = '';
          sizeMarkImg(img, cell);
          cell.appendChild(img);
          setTimeout(function () { img.remove(); }, 460);
        }

        function flashMiss(cell, reasonKey, pos) {
          cell.classList.add('is-blocked-flash');
          transientFailMark(cell);
          setTimeout(function () { cell.classList.remove('is-blocked-flash'); }, 320);
          if (justFoundSomeone()) return;
          if (tapOnFoundFace(cell)) return;
          if (callbacks.onMiss) callbacks.onMiss(reasonKey, pos);
        }

        for (let pos = 1; pos <= n * n; pos++) {
          const cell = document.createElement('div');
          cell.className = 'nd-tut-cell is-interactive';
          cell.dataset.pos = String(pos);
          cellEls.set(pos, cell);
          grid.appendChild(cell);
        }

        // Same pulsing-ring "double-tap me" look as the two REAL
        // targets (7 and 9) — a believable decoy, not a visually
        // duller trap that gives itself away.
        cellEls.get(8).classList.add('is-target');

        // Beta's own placed singleton — same convention as every other board.
        const betaCell = cellEls.get(2);
        betaCell.style.background = charColor('beta');
        const betaImg = document.createElement('img');
        betaImg.className = 'nd-tut-face-img';
        betaImg.src = avatarPath('beta');
        betaImg.alt = charName('beta');
        betaCell.appendChild(betaImg);
        betaCell.ondblclick = function () { flashMiss(betaCell, 'alreadyFound', 2); };

        function resolveRow(clickedPos) {
          if (resolved) return;
          resolved = true;
          markCharacterFound('spindle'); // grey→color avatar switch
          ROW.forEach(function (p) {
            const c = cellEls.get(p);
            c.classList.remove('is-target');
            c.style.background = charColor('spindle');
            c.ondblclick = function () { flashMiss(c, 'alreadyFound', p); };
          });
          const img = document.createElement('img');
          img.className = 'nd-tut-face-img';
          img.src = avatarPath('spindle');
          img.alt = charName('spindle');
          cellEls.get(clickedPos).appendChild(img);
          // Foreshadowing stage 1 of 4 — the page has been flat
          // greyscale up to now; the moment the player actually finds
          // Spindle, color starts creeping in (see setColorStage).
          setColorStage(1);
          if (callbacks.onFound) callbacks.onFound(clickedPos);
        }

        VALID_POSITIONS.forEach(function (pos) {
          const cell = cellEls.get(pos);
          cell.classList.add('is-target');
          cell.ondblclick = function () { resolveRow(pos); };
        });

        GROUP_A.forEach(function (pos) {
          const cell = cellEls.get(pos);
          cell.ondblclick = function () { flashMiss(cell, 'groupA', pos); };
        });
        GROUP_B.forEach(function (pos) {
          const cell = cellEls.get(pos);
          cell.ondblclick = function () { flashMiss(cell, 'groupB', pos); };
        });
        const guessTrapCell = cellEls.get(8);
        guessTrapCell.ondblclick = function () { flashMiss(guessTrapCell, 'guessTrap', 8); };

        stageEl.innerHTML = '';
        stageEl.appendChild(grid);
        showTargetHint('Find Spindle’s glowing row.');
      }

      // Cell-group fail copy for renderSpindleRowFind, per your spec.
      const SPINDLE_FIND_MISS_TEXT = {
        groupA: 'That’s not his color and he can’t share a row or column with us. Try again!',
        groupB: 'That’s not his color, try double tapping the glowing row.',
        guessTrap: 'Not quite — try again, he cannot share my column.', // placeholder — swap for the real line once you've written it
      };

      /* ========== Part 3 — Knot/Knell choice + "3rd character has
         nowhere to go" board ==========
         Custom-built (like renderSpindleRowFind) because Spindle's
         already-placed cells (7/8/9) need their OWN specific miss
         copy here instead of the generic "already found" message —
         the generic engine's placedColorMap branch can't be
         parameterized per-cell, so this board wires every cell by
         hand instead.

         Cells 4/5/6 are the "advance" cells: styled the same grey as
         every other board's glowing target (#a7a7a7, via
         --nd-tut-target-bg) so it reads as an invitation to try there
         even though nothing is really "correct" — double-tapping any
         of them immediately advances the tutorial (touch rule reveal
         next), no Next click required. */
      function renderThirdFailBoard(thirdCharId, onAdvance) {
        const n = 3;
        const cellPx = cellPxFor(n);
        const grid = document.createElement('div');
        grid.className = 'nd-tut-grid';
        grid.style.gridTemplateColumns = 'repeat(' + n + ', ' + cellPx + 'px)';
        grid.style.gridAutoRows = cellPx + 'px';

        const cellEls = new Map();
        let advanced = false;
        thirdFailClickedPos = null;

        function flashMiss(cell, msg) {
          cell.classList.add('is-blocked-flash');
          setTimeout(function () { cell.classList.remove('is-blocked-flash'); }, 320);
          say('beta', msg);
          setNextEnabled(true); // manual fallback still works if the player never taps 4/5/6
        }

        for (let pos = 1; pos <= n * n; pos++) {
          const cell = document.createElement('div');
          cell.className = 'nd-tut-cell is-interactive';
          cell.dataset.pos = String(pos);
          cellEls.set(pos, cell);
          grid.appendChild(cell);
        }

        // cell 2 — Beta, already found
        const betaCell = cellEls.get(2);
        betaCell.style.background = charColor('beta');
        const betaImg = document.createElement('img');
        betaImg.className = 'nd-tut-face-img';
        betaImg.src = avatarPath('beta');
        betaImg.alt = charName('beta');
        betaCell.appendChild(betaImg);
        betaCell.ondblclick = function () { flashMiss(betaCell, 'That’s already my spot — try somewhere else.'); };

        // cells 7/8/9 — Spindle's region, already found, but with
        // their own specific miss copy per your spec (not a generic
        // "already found").
        const spindleMsg = 'That’s Spindle’s color and ' + charName(thirdCharId) + ' can’t share a row or column with us. Try again!';
        spindleRegionPlaced().region.forEach(function (pos) {
          const cell = cellEls.get(pos);
          cell.style.background = charColor('spindle');
          if (pos === (spindleFacePos || 9)) {
            const img = document.createElement('img');
            img.className = 'nd-tut-face-img';
            img.src = avatarPath('spindle');
            img.alt = charName('spindle');
            cell.appendChild(img);
          }
          cell.ondblclick = function () { flashMiss(cell, spindleMsg); };
        });

        // cells 1/3 — plain row/column trap
        const rowColMsg = charName(thirdCharId) + ' can’t share a row or column with us. Try again!';
        [1, 3].forEach(function (pos) {
          const cell = cellEls.get(pos);
          cell.ondblclick = function () { flashMiss(cell, rowColMsg); };
        });

        // cells 4/5/6 — the "advance" row: glowing #a7a7a7 like every
        // real target, but any double-tap here just advances — and
        // now leaves a persistent red X right where they clicked, plus
        // remembers the position so panel 7's fresh board can re-mark
        // the same spot (see thirdFailClickedPos above).
        [4, 5, 6].forEach(function (pos) {
          const cell = cellEls.get(pos);
          cell.classList.add('is-target');
          cell.ondblclick = function () {
            if (advanced) return;
            advanced = true;
            thirdFailClickedPos = pos;
            persistFailMark(cell);
            if (onAdvance) onAdvance();
          };
        });

        stageEl.innerHTML = '';
        stageEl.appendChild(grid);
        hideTargetHint();
      }

      // 4x4 — expansion board.
      //    1  2  3  4
      //    5  6  7  8
      //    9 10 11 12
      //   13 14 15 16
      const SPINDLE_4X4_REGION = { charId: 'spindle', facePos: 8, region: [3, 4, 8, 12, 16] };
      // FIXED assignment now — see DESIGN NOTE below for why the old
      // "either shape, whichever cell the player taps first" scheme
      // was removed. Region A always belongs to pick1Id (the
      // character chosen several panels ago), region B to whichever
      // of Knot/Knell that isn't.
      const FOUR_REGION_A = { face: 9, cells: [1, 5, 6, 7, 9] };
      const FOUR_REGION_B = { face: 15, cells: [10, 11, 13, 14, 15] };

      /* ========== Part 4 — Knot/Knell 4x4 ==========
         DESIGN NOTE (rewritten this pass) — the previous version let
         the player double-tap EITHER cell 9 or cell 15 first, and
         whichever one they picked became pick1Id's region — "either
         character can land in either shape." After two passes of
         static tracing couldn't pin down a reported bug (double-tap
         15 then 9, and the FIRST character's face appeared to move
         from 15 to 9 instead of staying put) and you noticed starting
         from area 9 always worked fine, we're removing the ambiguous
         path instead of continuing to chase it: pick1Id's region is
         now ALWAYS the cells around 9 (1, 5, 6, 7, 9), pre-tinted in
         pick1Id's own color the moment this board appears — since
         pick1Id was already decided by an earlier choice card, there
         was never a real reason to also leave WHICH board position it
         lands on undecided. This narrows the very first search to
         those 5 cells (instead of guessing blind across all 10
         remaining candidates), and the second character's region
         (10, 11, 13, 14, 15, face 15) stays completely untouched —
         no color, no flat-grey, no tap-marking, no dblclick handler at
         all — until pick1Id's face at 9 is actually found, at which
         point it's revealed the same flat/dark "figure it out" way
         every other search region on this board already works. Only
         one cell is ever the live target at a time.

         NOTE (Phase 7 pass) — this function's name still says "Knot/
         Knell" but its logic was already fully generic through pick1Id
         /pick2Id before this pass. The one spot that WASN'T generic —
         where pick2Id is actually assigned, in startPhase1() below,
         which used to hardcode `pick1Id === 'knot' ? 'knell' : 'knot'`
         — now reads the cycle's actual two-character cast from
         getKnotKnellSlotCast() and picks "whichever of the two wasn't
         picked," so it resolves correctly for Umbrella/Builder (or any
         later cast reusing this slot) too, not just Knot/Knell.

         Fail copy is grouped by ACTUAL board state (already-that-
         character's-color / already-Spindle's-color / still-hidden-
         search-region) — same normalization approach as before, just
         applied to the new fixed cell groups.

         This is also where the single-tap black-X "don't go here"
         marker is introduced — but now only for whichever region is
         actually live at the time (region A from the start, region B
         only once revealed), not every candidate cell on the board
         at once.

         HARDENING NOTE (carried over) — colorRegion() and
         startPhase2() still take the relevant character id(s) as
         explicit parameters rather than reading the shared
         pick1Id/pick2Id module variables again later, and colorRegion()
         still re-points EVERY cell in a just-colored region at a fresh
         "already found" handler. startPhase2() no longer separately
         re-wires foundRegion's cells at all — colorRegion() already
         did that correctly right before startPhase2() is called, so
         that second pass was dead weight at best and a stale-message
         risk at worst (it was overwriting colorRegion's "already
         found" handler with older row/col/touch copy). Debug
         console.log calls from the last pass are left in place. */
      function renderKnotKnellStep(onAllDone) {
        const n = 4;
        const cellPx = cellPxFor(n);
        const grid = document.createElement('div');
        grid.className = 'nd-tut-grid';
        grid.style.gridTemplateColumns = 'repeat(' + n + ', ' + cellPx + 'px)';
        grid.style.gridAutoRows = cellPx + 'px';

        const cellEls = new Map();
        let phase1Resolved = false;
        let phase2Resolved = false;

        // Persistent red-X marking starts here (Part 3: "so they can
        // start seeing visually getting it wrong, so they stop
        // double tapping it again") — every wrong double-tap on this
        // board and every board after it leaves a mark that stays
        // until the Undo hint clears it.
        function flashMiss(cell, msg) {
          cell.classList.add('is-blocked-flash');
          persistFailMark(cell);
          setTimeout(function () { cell.classList.remove('is-blocked-flash'); }, 320);
          if (justFoundSomeone()) return;
          if (tapOnFoundFace(cell)) return;
          if (msg) say('beta', msg);
        }

        for (let pos = 1; pos <= n * n; pos++) {
          const cell = document.createElement('div');
          cell.className = 'nd-tut-cell is-interactive';
          cell.dataset.pos = String(pos);
          cellEls.set(pos, cell);
          grid.appendChild(cell);
        }

        // Beta (already found)
        const betaCell = cellEls.get(2);
        betaCell.style.background = charColor('beta');
        const betaImg = document.createElement('img');
        betaImg.className = 'nd-tut-face-img';
        betaImg.src = avatarPath('beta');
        betaImg.alt = charName('beta');
        betaCell.appendChild(betaImg);
        betaCell.ondblclick = function () { flashMiss(betaCell, 'That’s already my spot — try somewhere else.'); };

        // Spindle's region (already found)
        SPINDLE_4X4_REGION.region.forEach(function (pos) {
          const cell = cellEls.get(pos);
          cell.style.background = charColor('spindle');
          if (pos === SPINDLE_4X4_REGION.facePos) {
            const img = document.createElement('img');
            img.className = 'nd-tut-face-img';
            img.src = avatarPath('spindle');
            img.alt = charName('spindle');
            cell.appendChild(img);
          }
        });
        function wireSpindleCell(pos, touching) {
          const cell = cellEls.get(pos);
          // searchName/msg are computed INSIDE the handler, not here at
          // wire time — this cell is never re-wired once phase 2
          // starts (unlike the region cells, which startPhase2
          // explicitly rewires), so a value captured at setup time
          // would stay stuck naming whoever was being searched for
          // during phase 1, even after the search moves on to pick2Id.
          cell.ondblclick = function () {
            const searchName = charName(phase1Resolved ? pick2Id : pick1Id);
            const msg = touching
              ? 'That’s Spindle’s color, also, ' + searchName + ' they can’t share a row or column with us or touch our face. Try again!'
              : 'That’s Spindle’s color, also, ' + searchName + ' they can’t share a row or column with us . Try again!';
            flashMiss(cell, msg);
          };
        }
        [3, 4, 12].forEach(function (pos) { wireSpindleCell(pos, true); });
        wireSpindleCell(16, false);
        const spindleFaceCell = cellEls.get(SPINDLE_4X4_REGION.facePos);
        spindleFaceCell.ondblclick = function () { flashMiss(spindleFaceCell, 'That’s already Spindle’s spot — try somewhere else.'); };

        // `finalCharId` is passed explicitly (rather than read from
        // pick1Id/pick2Id inside this function) so it's captured at
        // the exact MOMENT a region is claimed — see this function's
        // header note above.
        function colorRegion(region, finalCharId) {
          markCharacterFound(finalCharId); // grey→color avatar switch (both cast members pass through here)
          region.cells.forEach(function (pos) {
            const cell = cellEls.get(pos);
            cell.classList.remove('is-target', 'is-flat-target', 'is-interactive');
            cell.classList.add('is-interactive');
            cell.style.background = charColor(finalCharId);
            disableTapMarking(cell);
            // Re-point EVERY cell in this region (not just the face
            // cell) at a fresh "already found" handler bound to THIS
            // region/character — closes off any stale trap handler
            // from startPhase1/startPhase2 that might otherwise still
            // be attached (e.g. cell 13's "technically correct" decoy
            // message previously lingered here after coloring).
            cell.ondblclick = function () { flashMiss(cell, 'That’s already ' + charName(finalCharId) + '’s spot — try somewhere else.'); };
          });
          const faceCell = cellEls.get(region.face);
          const img = document.createElement('img');
          img.className = 'nd-tut-face-img';
          img.src = avatarPath(finalCharId);
          img.alt = charName(finalCharId);
          faceCell.appendChild(img);
        }

        // Every blank cell taps to a black "don't go here" marker
        // from the very start of this panel.
        function wireTapMarkable(pos) { enableTapMarking(cellEls.get(pos)); }

        function startPhase2(foundRegion, otherRegion, foundCharId, searchCharId) {
          const searchName = charName(searchCharId);
          // foundRegion's cells are NOT re-wired here — colorRegion()
          // (called right before startPhase2()) already re-pointed
          // every one of them at a fresh "already found" handler; a
          // second pass here used to immediately overwrite that with
          // older row/col/touch copy, which was dead weight at best.

          // Reveal otherRegion now — flat/dark and tap-markable, the
          // same "figure it out" treatment every search region on this
          // board gets. Nothing about these cells existed to the
          // player before this exact moment (see DESIGN NOTE above).
          otherRegion.cells.forEach(function (pos) {
            const cell = cellEls.get(pos);
            cell.classList.add('is-flat-target');
            wireTapMarkable(pos);
          });

          // Still-blank cells of otherRegion, except its face cell →
          // generic "can't share row/col or touch" trap.
          otherRegion.cells.forEach(function (pos) {
            if (pos === otherRegion.face) return;
            const cell = cellEls.get(pos);
            cell.ondblclick = function () {
              flashMiss(cell, searchName + ' they can’t share a row or column with us or touch our face. Try again!');
            };
          });

          // otherRegion's face cell is the real target — already
          // flat dark grey like the rest of otherRegion (see just
          // above), so it doesn't stand out either.
          const targetCell = cellEls.get(otherRegion.face);
          targetCell.ondblclick = function () {
            if (phase2Resolved) return;
            phase2Resolved = true;
            try {
              console.log('[neur0doku tutorial] pick2 phase2 resolve — clicked cell:', otherRegion.face, 'coloring region:', otherRegion.cells, 'as:', searchCharId, '(foundRegion was:', foundRegion.cells, 'as', foundCharId + ')');
            } catch (e) { /* console unavailable — not fatal */ }
            colorRegion(otherRegion, searchCharId);
            // Foreshadowing stage 3 of 4 — both pick1/pick2 found now.
            setColorStage(3);
            if (onAllDone) onAllDone();
          };
        }

        function startPhase1() {
          // Region A is the only thing on the board that's "live" right
          // now (see DESIGN NOTE above) — pre-tinted in pick1Id's own
          // color immediately, since who pick1Id is was already
          // decided panels ago. This IS the tell this time, on
          // purpose: it narrows the search to exactly these 5 cells
          // instead of leaving the player guessing across all 10.
          // Region B stays completely untouched (no color, no
          // flat-grey, no tap-marking, no dblclick) until this
          // resolves — see startPhase2()'s reveal step.
          FOUR_REGION_A.cells.forEach(function (pos) {
            cellEls.get(pos).style.background = charColor(pick1Id);
          });

          const pickName = charName(pick1Id);
          // The 4 non-face cells already show pick1Id's own color —
          // wrong here means "not their exact spot," not "wrong color."
          [1, 5, 6, 7].forEach(function (pos) {
            const cell = cellEls.get(pos);
            wireTapMarkable(pos);
            cell.ondblclick = function () {
              flashMiss(cell, 'That’s ' + pickName + '’s color, but not their exact spot — try again!');
            };
          });
          wireTapMarkable(FOUR_REGION_A.face);

          const faceCell = cellEls.get(FOUR_REGION_A.face);
          faceCell.ondblclick = function () {
            if (phase1Resolved) return;
            phase1Resolved = true;
            // pick2Id is actually ASSIGNED here — it's whichever of
            // this cycle's cast wasn't picked first (see
            // getKnotKnellSlotCast()/CYCLE_CAST near the top of this
            // file). Cast-generic replacement for the old hardcoded
            // `pick1Id === 'knot' ? 'knell' : 'knot'`.
            const cast = getKnotKnellSlotCast();
            const searchCharId = pick1Id === cast[0] ? cast[1] : cast[0];
            pick2Id = searchCharId;
            try {
              console.log('[neur0doku tutorial] pick1 phase1 resolve — pick1Id:', pick1Id, 'search target will be cell', FOUR_REGION_B.face, 'for', searchCharId);
            } catch (e) { /* console unavailable — not fatal */ }
            colorRegion(FOUR_REGION_A, pick1Id);
            // Foreshadowing stage 2 of 4 — the first of pick1/pick2 found.
            setColorStage(2);
            showConversation([
              { speaker: 'beta', text: 'Good job. It appears ' + charName(searchCharId) + ' has been waiting nearby for an opportunity to join us. Using the three rules, can you find them?' },
            ], true);
            startPhase2(FOUR_REGION_A, FOUR_REGION_B, pick1Id, searchCharId);
          };
        }

        startPhase1();

        stageEl.innerHTML = '';
        stageEl.appendChild(grid);
        const findReaction = slotReaction('find4x4', pick1Id);
        showConversation([
          { speaker: 'beta', text: 'Here, I’ve given us more room. Try to figure out which cell is ' + charName(pick1Id) + '’s.' },
          { speaker: pick1Id, text: findReaction },
        ], true);
        showTargetHint('Double-tap the cell you think is right.');
      }

      // 5x5 — Fray's board.
      //    1  2  3  4  5
      //    6  7  8  9 10
      //   11 12 13 14 15
      //   16 17 18 19 20
      //   21 22 23 24 25
      // Region map (unchanged from the previous pass):
      //   Spindle = [1,2,3,6,11],           face @ 1
      //   pick1   = [4,5,8,9,10,13,14],     face @ 8
      //   pick2   = [15,18,19,20,22,23,25], face @ 15
      //   Beta    = [24] (singleton, same convention as always)
      //   Fray    = [7,12,16,17,21],        face @ 17 (this step's target)
      //
      // flatTargetStyle: true — every non-placed cell is the SAME
      // fixed grey, target included, per your "don't show a glowing
      // box" note. This pass switches Fray's board from its own
      // fixed, never-tinted --nd-tut-fray-bg to the SAME
      // --nd-tut-target-bg every other flat board already uses (i.e.
      // frayFlatTarget is no longer set here) — per your request.
      // TRADEOFF, flagged from the previous pass's own comment: this
      // board always renders AFTER Knot/Knell are found, so colorStage
      // is already 2+ by the time it's on screen — --nd-tut-target-bg
      // has already drifted from plain grey toward blue at that point,
      // so Fray's "no visual tell" cells will read with a faint blue
      // cast rather than pure neutral grey. The --nd-tut-fray-bg
      // variable and is-flat-target-fray CSS class are left in place
      // (unused by this step now) in case that tradeoff turns out to
      // matter and this needs to be reverted.
      // Finding Fray immediately fades in the follow-up conversation
      // (his happy noise + Beta's hint-tools intro) on this SAME
      // finished board — no Next click. The board itself only
      // actually resets once the player clicks Next after THAT
      // conversation (see panelHintPractice below).
      //
      // PHASE 7 — this is cycle 0-2's 5x5 board specifically. Cycle
      // 3+ uses cycle3FrayStep() (8x8, see the PHASE 7 block near the
      // top of this file) instead — see panelFray() below for the
      // branch.
      function frayStep() {
        const missText = {
          groupWide: 'Uh oh, Fray cannot be in anyone’s color, same row or column, or touch their face. Try again!',
          groupColorCol: 'Close, but remember, Fray cannot be in the same color or even the same column or row as us.',
          groupRowColTouch: 'Almost, remember, Fray cannot share the same row or column as us, or touch our face. Try again!',
          groupRowCol: 'You almost had it, Fray cannot share the same row or column as us! Let’s try again!',
        };
        const traps = {};
        [2, 3, 4, 6, 8, 9, 12, 13, 18, 19, 20, 23, 25].forEach(function (p) { traps[p] = 'groupWide'; });
        [5, 11, 22].forEach(function (p) { traps[p] = 'groupColorCol'; });
        [7, 12].forEach(function (p) { traps[p] = 'groupRowColTouch'; });
        [16, 21].forEach(function (p) { traps[p] = 'groupRowCol'; });

        return {
          n: 5,
          targets: [{ pos: 17, charId: 'fray', revealRegion: [7, 12, 16, 17, 21] }],
          highlightPositions: [7, 12, 16, 17, 21],
          placed: [
            { charId: 'spindle', facePos: 1, region: [1, 2, 3, 6, 11] },
            { charId: pick1Id, facePos: 8, region: [4, 5, 8, 9, 10, 13, 14] },
            { charId: pick2Id, facePos: 15, region: [15, 18, 19, 20, 22, 23, 25] },
            { pos: 24, charId: 'beta' },
          ],
          traps: traps,
          defaultMissReason: 'groupWide',
          flatTargetStyle: true,
          flashXOnMiss: true,
          hintText: 'His face can’t be in our row, column, color, or touch our face.',
                    onCorrect: function () {
            // Foreshadowing stage 4 of 4 — Fray found, full color.
            setColorStage(4);
            showConversation([
              { speaker: 'fray', text: '-dook dook, happy squeak-' },
              { speaker: 'beta', text: 'Well done. I’m going to reset the board. Click any icon at the top to review the hints later.' },
            ], true);
            // The (?) icon is introduced by this exact line, not
            // earned by closing an earlier popup — unlocked here,
            // not at panelFray's own load, so it becomes clickable
            // at the same moment Beta tells the player to use it.
            unlockTipIcon('help');
            setNextEnabled(true);
          },
          onMiss: function (reasonKey) {
            say('beta', missText[reasonKey] || missText.groupWide);
          },
        };
      }

      /* ========== COLORED FACE BOARD (5x5 practice round) ==========
         Not built on the generic `renderBoard(step)` engine — the
         hint buttons need to reach back into board state (undo needs
         to know the last-placed cell; the two other hints need the
         list of not-yet-found targets / not-a-target cells) in ways
         the one-shot `step` object doesn't expose. Kept as its own
         small, self-contained builder instead of stretching the
         generic engine to cover a case it wasn't designed for.

         Unlike the earlier pass's plain hidden-dot board, every
         cell here is pre-colored by which character's region it
         belongs to (same region shapes as frayStep) — the player
         gets that much structure for free and has to find the exact
         face cell within each colored region themselves. `entries`
         is [{ charId, facePos, region }, ...]; the regions must
         together cover the whole board with no gaps or overlaps.
         Works for ANY n/entries combination — see panelHintPractice()
         below, which passes it a 5-entry/5x5 board for cycle 0-2 and
         an 8-entry/8x8 board for cycle 3+, with no changes needed
         here. */
      function buildColoredFaceBoard(n, entries) {
        const cellPx = cellPxFor(n);
        const grid = document.createElement('div');
        grid.className = 'nd-tut-grid';
        grid.style.gridTemplateColumns = 'repeat(' + n + ', ' + cellPx + 'px)';
        grid.style.gridAutoRows = cellPx + 'px';

        const regionCharMap = new Map(); // pos -> charId, every cell in the board
        const facePosMap = new Map();    // pos -> charId, only the exact face cells
        entries.forEach(function (entry) {
          entry.region.forEach(function (p) { regionCharMap.set(p, entry.charId); });
          facePosMap.set(entry.facePos, entry.charId);
        });

        const cellEls = new Map();
        for (let pos = 1; pos <= n * n; pos++) {
          const cell = document.createElement('div');
          cell.className = 'nd-tut-cell is-interactive';
          cell.dataset.pos = String(pos);
          cell.style.background = charColor(regionCharMap.get(pos));
          grid.appendChild(cell);
          cellEls.set(pos, cell);
        }

        stageEl.innerHTML = '';
        stageEl.appendChild(grid);

        return { cellEls: cellEls, regionCharMap: regionCharMap, facePosMap: facePosMap };
      }

      // Runs the practice round on `board` (from buildColoredFaceBoard).
      // `onAllFound` fires once every face has been found (via
      // double-tap OR the reveal-face hint). Wrong double-taps (any
      // non-face cell) leave a persistent red X, same as every board
      // since the touch-rule reveal — Undo clears ALL of those marks
      // in addition to undoing the last placement, since otherwise
      // they'd have no way to go away once the daily hint is spent.
      function runColoredPracticeBoard(board, onAllFound) {
        const foundOrder = []; // positions the PLAYER placed via double-tap, in order — what Undo undoes
        const foundSet = new Set();
        let undoUsed = false, xUsed = false, faceUsed = false;
        const total = board.facePosMap.size;
        const nonFacePositions = Array.from(board.regionCharMap.keys()).filter(function (p) { return !board.facePosMap.has(p); });

        // Fresh board, fresh marker mode — always starts back on "X"
        // regardless of what the player left it on last time.
        practiceMarkMode = 'x';
        if (markerToggleImg) markerToggleImg.src = TAP_MARK_SRC.x;
        if (markerToggleBtn) {
          markerToggleBtn.disabled = false;
          markerToggleBtn.setAttribute('aria-label', 'Currently marking with X. Tap to switch to ?');
          markerToggleBtn.onclick = function () {
            practiceMarkMode = practiceMarkMode === 'x' ? 'question' : 'x';
            markerToggleImg.src = TAP_MARK_SRC[practiceMarkMode];
            markerToggleBtn.setAttribute(
              'aria-label',
              practiceMarkMode === 'x' ? 'Currently marking with X. Tap to switch to ?' : 'Currently marking with ?. Tap to switch to X'
            );
          };
        }
        // Clears every placed "?" on the board — matches the real
        // game's trash button, which only ever touches "?" marks,
        // never "X" marks.
        if (clearQuestionsBtn) {
          clearQuestionsBtn.disabled = false;
          clearQuestionsBtn.onclick = function () {
            stageEl.querySelectorAll('.nd-tut-tap-mark').forEach(function (img) {
              if (img.src.indexOf('doku_questionmark') !== -1) img.remove();
            });
          };
        }

        function revealAt(pos, viaHint) {
          const charId = board.facePosMap.get(pos);
          markCharacterFound(charId); // defensive/idempotent — everyone should already be found by this practice round
          const cell = board.cellEls.get(pos);
          cell.innerHTML = '';
          disableTapMarking(cell); // found — no more marking a face cell
          const img = document.createElement('img');
          img.className = 'nd-tut-face-img';
          img.src = avatarPath(charId);
          img.alt = charName(charId);
          cell.appendChild(img);
          foundSet.add(pos);
          if (!viaHint) foundOrder.push(pos);
          if (foundSet.size === total && onAllFound) onAllFound();
        }

        function hideAt(pos) {
          const cell = board.cellEls.get(pos);
          cell.innerHTML = '';
          enableTapMarking(cell); // blank again — marking available once more
          foundSet.delete(pos);
        }

        board.facePosMap.forEach(function (charId, pos) {
          const cell = board.cellEls.get(pos);
          cell.ondblclick = function () {
            if (foundSet.has(pos)) return;
            revealAt(pos, false);
          };
        });
        nonFacePositions.forEach(function (pos) {
          const cell = board.cellEls.get(pos);
          cell.ondblclick = function () {
            cell.classList.add('is-blocked-flash');
            persistFailMark(cell);
            setTimeout(function () { cell.classList.remove('is-blocked-flash'); }, 320);
          };
        });
        // Single-tap / click-and-drag black-X marking (Part 6) — every
        // cell is markable until its face is found (see revealAt/hideAt).
        board.cellEls.forEach(function (cell) { enableTapMarking(cell); });

        hintRow.hidden = false;
        hintUndoBtn.disabled = false;
        hintXBtn.disabled = false;
        hintFaceBtn.disabled = false;

        // ---- Undo: single use. Reverts the player's own most recent
        // placement (not a hint-revealed one), AND clears every red X
        // left on the board so far — otherwise they'd have no way to
        // go away once this single-use button is spent. ----
        hintUndoBtn.onclick = function () {
          if (undoUsed) return;
          undoUsed = true;
          hintUndoBtn.disabled = true;
          const lastPos = foundOrder.pop();
          if (lastPos) hideAt(lastPos);
          clearAllFailMarks();
        };

        // ---- 4 X's: single use. Marks up to four random cells that
        // are NOT anyone's exact face cell. ----
        hintXBtn.onclick = function () {
          if (xUsed) return;
          xUsed = true;
          hintXBtn.disabled = true;
          const pool = nonFacePositions.filter(function (p) { return !foundSet.has(p); });
          const picks = [];
          while (picks.length < 4 && pool.length) {
            const idx = Math.floor(Math.random() * pool.length);
            picks.push(pool.splice(idx, 1)[0]);
          }
          picks.forEach(function (pos) {
            const cell = board.cellEls.get(pos);
            cell.classList.add('is-marked-x');
            cell.textContent = '✕';
          });
        };

        // ---- Reveal a face: single use. Auto-places one random
        // not-yet-found face, exactly like a correct double-tap. ----
        hintFaceBtn.onclick = function () {
          if (faceUsed) return;
          faceUsed = true;
          hintFaceBtn.disabled = true;
          const unfoundPositions = [];
          board.facePosMap.forEach(function (charId, pos) {
            if (!foundSet.has(pos)) unfoundPositions.push(pos);
          });
          if (!unfoundPositions.length) return;
          const pos = unfoundPositions[Math.floor(Math.random() * unfoundPositions.length)];
          revealAt(pos, true);
        };
      }

      let panelIndex = 0;

      const PANEL_COUNT = 13;

      function defaultAdvance() {
        if (panelIndex < PANEL_COUNT - 1) goToPanel(panelIndex + 1);
      }
      function goToPanel(index) {
        if (activeRulePopup) activeRulePopup.close();
        clearStageFingerTimers();
        setTutorialMarkMode('x'); // always start fresh — see this flag's own comment above
        panelIndex = index;
        clearAllMessages();
        nextBtn.textContent = 'Next';
        nextBtn.onclick = defaultAdvance;
        setNextEnabled(false);
        PANELS[index]();
      }

      // Used when a step transitions the player straight into the
      // NEXT panel's content on its own (double-tap / choice made),
      // with no Next click in between. Only updates bookkeeping
      // (panelIndex + the Next button's default target) — deliberately
      // does NOT call clearAllMessages() or re-render the stage, so
      // whatever the just-finished board looks like stays on screen.
      function advanceBookkeepingTo(index) {
        panelIndex = index;
        nextBtn.textContent = 'Next';
        nextBtn.onclick = defaultAdvance;
      }

      const BETA_FULLBODY_SRC = '../images/neur0doku_hero-beta-g.png';

      // Shared by PANELS[5] and the direct jump out of PANELS[4] so
      // both paths show identical content.
      function panelThirdColumnTeaseLines() {
        return [
          { speaker: 'spindle', text: 'Hey, that looks like me… and there are two colors now!' },
          { speaker: 'beta', text: 'Yes — you could have been in either of those two corners. But we still have a 3rd row… let’s add someone else.' },
        ];
      }

            const noRowOrColumnPopup = createLoopingRulePopup({
        title: 'Rules 2: One face per Row & Column',
        tintCells: [1, 2, 3, 5, 8],
        tintCharId: 'beta',
        sequence: function (h) {
          h.moveFinger(2);
          h.t(500, function () { h.placeFace(2, 'beta'); });
          // press cell 1, drag to 3 — marks the row
          h.t(1000, function () { h.moveFinger(1); });
          h.t(1220, function () { h.markX(1); });
          h.t(1670, function () { h.moveFinger(3); });
          h.t(1890, function () { h.markX(3); });
          // press cell 5, drag to 8 — marks the column
          h.t(2340, function () { h.moveFinger(5); });
          h.t(2560, function () { h.markX(5); });
          h.t(3010, function () { h.moveFinger(8); });
          h.t(3230, function () { h.markX(8); });
          return 3230;
        },
      });

            const oneFacePerColorPopup = createLoopingRulePopup({
        title: 'Rule 1: One Face per Color',
        tintCells: [1, 2, 3, 4, 5, 7],
        tintCharId: 'beta',
        sequence: function (h) {
          h.moveFinger(5);
          h.t(500, function () { h.placeFace(5, 'beta'); });
          const dragPath = [7, 4, 1, 2, 3];
          let time = 1000;
          dragPath.forEach(function (pos) {
            h.t(time, function () { h.moveFinger(pos); });
            h.t(time + 220, function () { h.markX(pos); });
            time += 450;
          });
          return time;
        },
      });

      // Phase 5 — triggered mid-panel-7 (panelExpandIntro) by the
      // player's OWN first double-tap on that board, not on panel
      // load like the popups above. All 9 cells tinted Beta's color.
      // The ring sweep reuses the exact same 8-cell clockwise order
      // the old howto modal's pip 3 used (now retired — see Phase 6
      // Part C) rather than a rewritten version. hideFinger() lets
      // the finger vanish right as the sweep ends, while the marks
      // linger through the factory's own built-in ~1s pause before
      // the next lap's reset wipes them — matching "finger
      // disappears, X's disappear a second later" with no new
      // factory plumbing beyond hideFinger itself.
      const noTouchingFacesPopup = createLoopingRulePopup({
        title: 'Rules 3: No Touching Faces',
        tintCells: [1, 2, 3, 4, 5, 6, 7, 8, 9],
        tintCharId: 'beta',
        sequence: function (h) {
          h.moveFinger(5);
          h.t(500, function () { h.placeFace(5, 'beta'); });
          const ring = [1, 2, 3, 6, 9, 8, 7, 4];
          let time = 1000;
          ring.forEach(function (pos) {
            h.t(time, function () { h.moveFinger(pos); });
            h.t(time + 200, function () { h.markX(pos); });
            time += 350;
          });
          h.t(time, function () { h.hideFinger(); });
          return time;
        },
      });

      const PANELS = [
        // 0 — merged: "Hi, I'm Beta!" + "Welcome to neur0doku!" as one
        // panel (Part 1) — one less click before the lesson starts.
        // Both lines now live in the SAME speech box (one per row,
        // each still fading in on its own), not two separate boxes —
        // see sayLines(). The full-body avatar frame is sized up too
        // (.is-hero) to read as more of a welcoming hero portrait.
        // BETA_FULLBODY_SRC now points at the real grey hero art
        // (neur0doku_hero-beta-g.png) — grey is correct here on
        // purpose: Beta hasn't been "found" on a board yet at this
        // point (see avatarPath()'s grey-until-found mechanism
        // further up), and this art is never reused after she has
        // been (it's a one-time panel-0 intro shot), so it doesn't
        // need to dynamically swap to a colored variant the way
        // avatarPath() does — it's just permanently the grey asset.
        //
        // PHASE 7 — cycle 1's "small, subtle acknowledgment" (see the
        // PHASE 7 block near the top of this file) would land here,
        // as a third fading line after the welcome — CYCLE_SUBTLE_ACK
        // has no cycle-1 entry yet, so this is currently a no-op for
        // every cycle, including cycle 1, exactly matching "no line
        // has been written for this yet, don't invent one silently."
        function panelHiWelcome() {
          stageEl.innerHTML = '';
          const introLines = ['Hello, I’m Beta!', 'Welcome to neur0doku!'];
          const subtleAck = cycleLine(CYCLE_SUBTLE_ACK, getPlayerCycle());
          if (subtleAck) introLines.push(subtleAck);
          sayLines('beta', introLines, BETA_FULLBODY_SRC);
          speakerAvatarEl.classList.add('is-hero');
          setNextEnabled(true);
        },
                // 1 — color rule, 3x3.
        function panelTeachBeta() {
          say('beta', 'There isn’t much color here… do you see that colored cube? Please, double-tap it.');
          renderBoard(teachBetaStep());
          playStageFingerTap(2); // one-shot, non-blocking — see this file's own header comment
        },
        // 2 — introduce the one-face-per-color rule + Spindle arrives
        function panelIntroSpindlePoof() {
          renderBoard({ n: 3, targets: [], placed: [{ pos: 2, charId: 'beta' }], defaultMissReason: 'notYet' });
          say('beta', 'There is only one of me. Rule 1: Only one face per color. Here, let’s add another rule… meet Spindle.');
          setNextEnabled(true);
        },
        // 3 — Spindle wakes up confused, Beta pitches the game. Fades
        // in like every other multi-line conversation now — most
        // noticeable here since three different people are talking.
        function panelSpindleConvo() {
          renderBoard({ n: 3, targets: [], placed: [{ pos: 2, charId: 'beta' }], defaultMissReason: 'notYet' });
          showConversation([
            { speaker: 'spindle', text: 'Oh… hi there…?' },
            { speaker: 'beta', text: 'Spindle, I’m Beta. Would you like to join a game? neur0doku is great for your attention span, pattern recognition, and working memory.' },
            { speaker: 'spindle', text: 'Oh… okay…?' },
          ], true);
          setNextEnabled(true);
          setTipPopupHandler('color', function () {
            oneFacePerColorPopup.open(function () { unlockTipIcon('color'); });
          });
          openRulePopupDelayed(oneFacePerColorPopup, 'color');
        },
        // 4 — row/column rule, find Spindle on the 3x3. Fades in from
        // here on (Part 2). Finding Spindle jumps straight into panel
        // 5's fading conversation on the SAME board — no Next click.
        function panelTeachSpindle() {
          showConversation([
            { speaker: 'beta', text: 'I put Spindle somewhere on the bottom row. Rule 2: Faces cannot share rows or columns. Can you find him? Double tap the spot.' },
            { speaker: 'spindle', text: 'Where… am I?', small: true },
          ], true);
          renderSpindleRowFind({
            onFound: function (pos) {
              spindleFacePos = pos;
              advanceBookkeepingTo(5);
              showConversation(panelThirdColumnTeaseLines(), true);
              setNextEnabled(true);
              openRulePopupDelayed(noRowOrColumnPopup, 'rowcol');
            },
            onMiss: function (reasonKey) {
              say('beta', SPINDLE_FIND_MISS_TEXT[reasonKey] || SPINDLE_FIND_MISS_TEXT.groupA);
            },
          });
          setTipPopupHandler('rowcol', function () {
            noRowOrColumnPopup.open(function () { unlockTipIcon('rowcol'); });
          });
        },
        // 5 — reaction + set up the "3rd column" tease. Normally
        // reached automatically from panel 4 (see above); kept as its
        // own PANELS entry too so replay / direct navigation still work.
        function panelThirdColumnTease() {
          renderBoard({ n: 3, targets: [], placed: [{ pos: 2, charId: 'beta' }, spindleRegionPlaced()], defaultMissReason: 'notYet' });
          showConversation(panelThirdColumnTeaseLines(), true);
          setNextEnabled(true);
          openRulePopupDelayed(noRowOrColumnPopup, 'rowcol');
        },
        // 6 — the pick1/pick2 choice, then immediately the "3rd
        // character has nowhere to go" proof on the same board
        // (Part 3, redesigned). Picking a card hides both cards and
        // swaps the static board straight into the live fail board in
        // the same click handler; double-tapping any of the "advance"
        // cells (4/5/6) then jumps straight to panel 7, no Next click.
        //
        // PHASE 7 — the two choice cards now come from
        // getKnotKnellSlotCast() instead of a hardcoded ['knot',
        // 'knell'] array, so cycle 2+ shows Umbrella/Builder here
        // instead (full-replacement cast — see the PHASE 7 block near
        // the top of this file). Everything downstream of pick1Id/
        // pick2Id already worked generically before this pass.
        function panelChoiceAndThirdFail() {
          renderBoard({ n: 3, targets: [], placed: [{ pos: 2, charId: 'beta' }, spindleRegionPlaced()], defaultMissReason: 'notYet' });
          const cast = getKnotKnellSlotCast();
          say('beta', 'This is ' + charName(cast[0]) + ' and ' + charName(cast[1]) + ' — who do you want to add to the thread?');
          choiceRow.hidden = false;
          choiceRow.innerHTML = '';
          cast.forEach(function (id) {
            const card = document.createElement('button');
            card.type = 'button';
            card.className = 'nd-tut-choice-card';
            card.innerHTML =
              '<span class="nd-tut-choice-avatar"><img src="' + avatarPath(id) + '" alt="" /></span>' +
              '<span class="nd-tut-choice-name">' + charName(id) + '</span>';
            card.addEventListener('click', function () {
              pick1Id = id;
              choiceRow.hidden = true; // both cards gone the instant one is picked
              const choiceReaction = slotReaction('choicePick', pick1Id);
              showConversation([
                { speaker: 'beta', text: 'You chose ' + charName(pick1Id) + ', perfect. Double tap on where you think they are.' },
                { speaker: pick1Id, text: choiceReaction },
              ], true);
              renderThirdFailBoard(pick1Id, function () {
                advanceBookkeepingTo(7);
                goToPanel(7);
              });
            });
            choiceRow.appendChild(card);
          });
        },
        // 7 — the touch rule lands + "let's make room" transition.
        // Persistent red-X marking (Part 3) starts on THIS board too —
        // previously only wired from panel 8 onward, which is why a
        // wrong tap here wasn't leaving a mark.
                function panelExpandIntro() {
          renderBoard({ n: 3, targets: [], placed: [{ pos: 2, charId: 'beta' }, spindleRegionPlaced()], defaultMissReason: 'notYet', flashXOnMiss: true });
          if (thirdFailClickedPos) {
            const markedCell = stageEl.querySelector('.nd-tut-cell[data-pos="' + thirdFailClickedPos + '"]');
            if (markedCell) persistFailMark(markedCell);
          }
          const expandReaction = slotReaction('expandReaction', pick1Id);
          showConversation([
            { speaker: 'beta', text: 'The highlighted spaces were... misleading. I thought that might be an amusing teaching tool. ...Was it successful? Perhaps I should have explained first. Rule 3: Faces cannot touch each other, even at a corner. Let’s make the area larger.' },
            { speaker: pick1Id, text: expandReaction },
          ], true);
          setNextEnabled(true);
          setTipPopupHandler('touch', function () {
            noTouchingFacesPopup.open(function () { unlockTipIcon('touch'); });
          });
        },
        // 8 — pick1/pick2 4x4 (Part 4, redesigned): pick cell 9 or 15,
        // then find whoever's left, tap-marking enabled throughout.
        // Finding the 2nd character jumps straight to panel 9 on a
        // fresh board with all three speaking — no Next click.
        function panelKnotKnell4x4() {
          renderKnotKnellStep(function () {
            advanceBookkeepingTo(9);
            renderSpindleFrayChirpPanel();
          });
          openRulePopupDelayed(noTouchingFacesPopup, 'touch');
        },
        // 9 — Spindle + Fray + (new) Beta all react. Reached
        // automatically from panel 8; kept as its own PANELS entry too.
        function panelSpindleFrayChirp() {
          renderSpindleFrayChirpPanel();
        },
        // 10 — Beta introduces finding Fray; board becomes the 5x5
        // (8x8 from cycle 3 on), no glowing "tell" on the correct
        // cell (Part 5). Finding him fades in the follow-up
        // conversation on the SAME finished board (see frayStep's /
        // cycle3FrayStep's onCorrect) — Next only then advances into
        // the actual board reset on panel 11.
        function panelFray() {
          showConversation([
            { speaker: 'fray', text: '-dook dook chirp-' },
            { speaker: 'beta', text: 'Oh, look, Fray wants to play and the area expanded. It seems he is hiding somewhere. Try to find him.' },
          ], true);
          renderBoard(getPlayerCycle() >= 3 ? cycle3FrayStep() : frayStep());
        },
        // 11 — 5x5 practice round (8x8 from cycle 3 on) (Part 6).
        // Board resets (fresh, colored by region so the player has
        // SOME structure to go on, faces hidden) for a real "figure
        // it out yourself" round — no target hint, no glowing cell.
        // Undo / 4 X's / Reveal-face are live from the start. Finding
        // the last face jumps straight to the Shop-trip panel — no
        // Next click — with the finished grid kept on screen.
          function panelHintPractice() {
          say('beta', 'Now, it is your turn to cast the thread. Follow the rules and see what takes shape. I believe you are ready.');
          // BUG FIX: Next was reachable here before the board was
          // solved — clicking it jumped straight to the Shop-trip
          // panel, which clears the board/hint buttons out from under
          // an unfinished practice round. Next only becomes clickable
          // again once every face is found (see
          // runColoredPracticeBoard's onAllFound callback below).
          setNextEnabled(false);
          let n, entries;
          if (getPlayerCycle() >= 3) {
            // Cycle 3+ — same 8 regions cycle3FrayStep() already
            // placed (protect the 8x8/64 — see that block's own
            // comment), just reused here as findable targets instead
            // of pre-placed decoration.
            n = CYCLE3_BOARD_N;
            entries = [
              { charId: 'spindle', facePos: CYCLE3_REGIONS.spindle.facePos, region: CYCLE3_REGIONS.spindle.region },
              { charId: pick1Id, facePos: CYCLE3_REGIONS.pick1.facePos, region: CYCLE3_REGIONS.pick1.region },
              { charId: pick2Id, facePos: CYCLE3_REGIONS.pick2.facePos, region: CYCLE3_REGIONS.pick2.region },
              { charId: 'fray', facePos: CYCLE3_REGIONS.fray.facePos, region: CYCLE3_REGIONS.fray.region },
              { charId: 'beta', facePos: CYCLE3_REGIONS.beta.facePos, region: CYCLE3_REGIONS.beta.region },
              { charId: 'r', facePos: CYCLE3_REGIONS.r.facePos, region: CYCLE3_REGIONS.r.region },
              { charId: 'g', facePos: CYCLE3_REGIONS.g.facePos, region: CYCLE3_REGIONS.g.region },
              { charId: 'b', facePos: CYCLE3_REGIONS.b.facePos, region: CYCLE3_REGIONS.b.region },
            ];
          } else {
            n = 5;
            entries = [
              { charId: 'spindle', facePos: 1, region: [1, 2, 3, 6, 11] },
              { charId: pick1Id, facePos: 8, region: [4, 5, 8, 9, 10, 13, 14] },
              { charId: pick2Id, facePos: 15, region: [15, 18, 19, 20, 22, 23, 25] },
              { charId: 'fray', facePos: 17, region: [7, 12, 16, 17, 21] },
              { charId: 'beta', facePos: 24, region: [24] },
            ];
          }
          const board = buildColoredFaceBoard(n, entries);
          runColoredPracticeBoard(board, function () {
            advanceBookkeepingTo(12);
            renderShopTripPanel(true);
          });
          // Auto-opens exactly ONCE per playthrough, on arrival from
          // panel 10. Must NOT retrigger when closeHowtoModal() itself
          // calls goToPanel(11) to reset the board on dismiss — that
          // would just reopen the modal forever — so this only ever
          // fires the first time.
          if (!helpPopupAutoShown) {
            helpPopupAutoShown = true;
            openHowtoModal();
          }
        },
      ];

      // Factored out of PANELS[12] so panel 11's direct jump (no Next
      // click, board kept on screen) and normal forward navigation
      // both work. `keepBoard` skips clearing the stage/tip row.
      function renderShopTripPanel(keepBoard) {
        if (!keepBoard) {
          stageEl.innerHTML = '';
          hideTargetHint();
        }
        markerRow.hidden = true;
        hintRow.hidden = true;
        // Re-run the starter grant here too (belt-and-suspenders, on
        // top of the one at module load below) — if anything ever
        // kept that first call from reaching storage on a given
        // device, the player still gets one more chance right before
        // they walk into the Shop. Both calls are idempotent.
        grantTutorialStarters();
        // One-time 20-Thread grant for a first-time player who hasn't
        // finished the tutorial yet — idempotent (see ownership.js),
        // so replaying this panel never grants a second helping. 20 is
        // exactly enough for ONE of Apple/Eggy (both 20 at the
        // choiceGroup's first-pick price — see catalog.js), which
        // takes the 5 tutorial starters to 6 owned — the real
        // "roster complete" threshold this tutorial resumes on
        // (getOwnedCharacterCount >= 6, same number the shop's own
        // ?from=tutorial resume check already uses) and matches
        // catalog.js's TIER_CHARACTER_REQUIREMENT.Simple. A previous
        // pass briefly bumped this to 50 on the mistaken assumption the
        // Shop's back button required 7 owned — it actually requires 6
        // (see index-shop.html's REQUIRED_TO_LEAVE); 20 was correct all
        // along, and one purchase is all a first-time player needs.
        const threadState = grantTutorialThreadIfNeeded(20);
        try { console.log('[neur0doku tutorial] Shop-trip panel — threads:', threadState.threads, 'owned:', threadState.owned); } catch (e) { /* not fatal */ }

        function goToShop() {
          nextBtn.textContent = 'Go to the Shop →';
          nextBtn.onclick = function () {
            location.href = '../quirk-cafe/shop/?from=tutorial';
          };
          setNextEnabled(true);
        }

        // NAME STEP (2026-09-22): asked EVERY cycle now, not just the
        // first. A reset unwinds the story's memory for the player and
        // the cast — but not for Beta. So after a reset she asks again,
        // and name-memory.js's resolveTutorialName() decides how she
        // answers (the returned `reaction`):
        //   'first'      — a brand-new player typed a name: her original
        //                  "Well met, …! I had calculated as much." line
        //   'same'       — they typed the name she remembers
        //   'different'  — they typed a new one: she notices it isn't
        //                  the name she remembers, and accepts it (it
        //                  becomes the one she remembers from now on)
        //   'remembered' — they left it empty: she uses the one she
        //                  remembers, even though they don't
        //   'random'     — empty, and she's never been told a name: a
        //                  generated one ("Plum7") that is NOT remembered
        // (Previously returning-cycle players skipped the ask entirely,
        // and an empty answer meant "friend" with no name saved.)
        // 2026-09-23: BIRTHDAY, then NAME. The birthday comes first so
        // the name picker can warn if the chosen number is the player's
        // birthday or birth year. Only asked if it hasn't been answered
        // before. The birth year is used to set the ad age band and then
        // dropped; only month + day are kept (see ads.js).
        const SHOP_HANDOFF = 'When ready I’ll send you to the shop to buy another character. Once you have your story will begin.';
        let nameSubmitted = false;
        let birthYearThisVisit = null; // in memory only, never saved

        function askBirthday() {
          // DRAFT copy for Beta.
          say('beta', 'Before anything else… when’s your birthday? I like to celebrate those.');
          nameRow.hidden = false;
          birthdayBox.hidden = false;
          const picker = buildBirthdayPicker(birthdayBox);
          nameSubmitBtn.textContent = 'Continue';
          nameSubmitBtn.disabled = true;
          picker.onChange(function () { nameSubmitBtn.disabled = !picker.value(); });
          nameSubmitBtn.onclick = function () {
            const v = picker.value();
            if (!v) return;
            saveBirthday(v.year, v.month, v.day);
            birthYearThisVisit = v.year;
            birthdayBox.hidden = true;
            birthdayBox.innerHTML = '';
            askName();
          };
        }

        function askName() {
          say('beta', hasResetHistory()
            ? cycleLine(CYCLE_LINES.shopTripReturning, getPlayerCycle())
            : cycleLine(CYCLE_LINES.shopTripFirstTime, getPlayerCycle()));
          nameRow.hidden = false;
          nameSubmitBtn.textContent = 'Choose my name';
          nameSubmitBtn.disabled = false;
          nameSubmitBtn.onclick = async function () {
            if (nameSubmitted) return;
            const picked = await openNamePicker({
              birthYear: birthYearThisVisit,
              initialName: getRememberedName(), // Beta remembers, even after a reset
              save: false,                      // writePlayerName() below saves it
              // Signed-in players get the same "Taken!" check as the Profile rename; guests pass through.
              check: async function (n) { const svc = await import('../js/name-service.js'); return svc.checkNameAvailable(n); },
              cancelLabel: 'Let Beta choose',
            });
            // "Let Beta choose" = the old empty answer: she uses the name
            // she remembers, or makes one up (see name-memory.js).
            submitName(picked ? picked.name : '');
          };
        }

        function submitName(chosenName) {
          if (nameSubmitted) return; // never answer twice
          nameSubmitted = true;
          const outcome = resolveTutorialName(chosenName);
          writePlayerName(outcome);
          try { localStorage.setItem('neur0doku:nameChosenCycle', String(getPlayerCycle())); } catch (e) { /* not fatal */ }
          nameRow.hidden = true;
          const reply = outcome.reaction === 'first'
            ? 'Well met, ' + outcome.name + '! I had calculated as much.'
            : betaNameLine(outcome);
          say('beta', reply + ' ' + SHOP_HANDOFF);
          goToShop();
        }

                function savedNameThisCycle() {
          try {
            if (localStorage.getItem('neur0doku:nameChosenCycle') !== String(getPlayerCycle())) return null;
            const p = readProfile();
            return (p && p.name) ? p.name : null;
          } catch (e) { return null; }
        }

        const nameAlreadyChosen = savedNameThisCycle();
        if (nameAlreadyChosen) {
          say('beta', 'Welcome back, ' + nameAlreadyChosen + '. ' + SHOP_HANDOFF);
          goToShop();
        } else if (hasAnsweredBirthday()) askName();
        else askBirthday();
      }

      // Factored out of PANELS[9] so panel 8's direct jump (no Next
      // click) and normal forward navigation render identical content.
      //
      // PHASE 7 — for cycle 0/1 (usingOriginalTutorialCast()), this is
      // byte-for-byte the same Knot/Knell-voiced banter as before this
      // pass. From cycle 2 on, that banter is replaced with Spindle's
      // confirmed "They both look familiar." line (DRAFT — first-pass
      // text, not yet confirmed final copy) instead of inventing
      // Umbrella/Builder voice lines that don't exist yet. From cycle
      // 3 on, the R/G/B arrival beat (also DRAFT text) is appended on
      // top of that — see the PHASE 7 block near the top of this file
      // for the full design this implements and the extension point
      // for cycle 4+.
      function renderSpindleFrayChirpPanel() {
        renderBoard({
          n: 4,
          targets: [],
          placed: [
            { pos: 2, charId: 'beta' },
            SPINDLE_4X4_REGION,
            { charId: pick1Id, facePos: FOUR_REGION_A.face, region: FOUR_REGION_A.cells },
            { charId: pick2Id, facePos: FOUR_REGION_B.face, region: FOUR_REGION_B.cells },
          ],
          defaultMissReason: 'notYet',
        });
        const lines = [
          { speaker: 'spindle', text: 'Okay... I think I get it…', small: true },
          { speaker: 'fray', text: '-chirp chirp psst shhh squeak-' },
        ];
        if (usingOriginalTutorialCast()) {
          // Whoever WASN'T picked first (pick1Id) reacts here — the
          // other of the two original characters.
          const thirdSpeaker = pick1Id === 'knot' ? 'knell' : 'knot';
          const thirdReaction = pick1Id === 'knot'
            ? 'Did anyone else see that flash of red?'
            : 'I think I saw a fast red threadling run into here?';
          lines.push({ speaker: thirdSpeaker, text: thirdReaction });
        } else {
          // Reset-cycle 2+ — DRAFT line, confirmed as first-draft text
          // in planning, not yet confirmed final copy. Replaces the
          // Knot/Knell-voiced banter above since Umbrella/Builder
          // don't have written voices yet (see SLOT_REACTION_LINES).
          lines.push({ speaker: 'spindle', text: 'They both look familiar.' });
        }
        if (getPlayerCycle() >= 3) {
          // Reset-cycle 3 — Fray brings R, G, and B back, on his own
          // accord (see lore doc — not summoned by Beta or the
          // player). All DRAFT text, not yet confirmed final copy.
          // "One of them (R) points toward the board" is a silent,
          // non-verbal beat per the lore doc (R/G/B are deliberately,
          // permanently minor) — left as a stage direction only, no
          // interactive board element for it in this pass.
          lines.push({ speaker: 'beta', text: 'Oh, look. These three showed up. I guess it was bound to happen.' });
          lines.push({ speaker: 'spindle', text: '...Do you know them?' });
          // (R silently points toward the board — no dialogue of their own.)
          lines.push({ speaker: 'spindle', text: 'I thought so.' });
          lines.push({ speaker: 'beta', text: 'Spindle. The tutorial. Please.' });
        }
        showConversation(lines, true);
        setNextEnabled(true);
      }

      // Back arrow now opens an in-page modal instead of navigating
      // straight to the pause page — "reset" always works, "go to
      // neur0doku home" only shows once the player has actually
      // unlocked it before (same `introSeen` flag index-paused.html
      // now checks, so both surfaces agree on what "unlocked" means).
      function isTutorialUnlocked() {
        try { return JSON.parse(localStorage.getItem('neur0doku:introSeen') || 'false') === true; }
        catch (e) { return false; }
      }
      function openBackModal() {
        backModalHomeBtn.hidden = !isTutorialUnlocked();
        backModal.hidden = false;
      }
      function closeBackModal() {
        backModal.hidden = true;
      }
      backLink.onclick = function (e) {
        e.preventDefault();
        openBackModal();
      };
      backModalCancelBtn.onclick = closeBackModal;
      backModal.onclick = function (e) {
        if (e.target === backModal) closeBackModal();
      };
      document.addEventListener('keydown', function (e) {
        if (e.key === 'Escape' && !backModal.hidden) closeBackModal();
      });
      backModalResetBtn.onclick = function () {
        location.href = location.pathname + '?replay=1';
      };
      backModalHomeBtn.onclick = function () {
        location.href = '../';
      };

      /* ========== TUTORIAL-ONLY GRANT ==========
         Bypasses purchase()'s requiresAll gate so pick1/pick2 can be
         picked in either order during the tutorial.

         Rewritten to be ATOMIC: one loadOwnership() at the start of
         the whole batch, mutate that SAME state object for every
         character, then ONE explicit saveOwnership() at the end —
         instead of a previous version that called loadOwnership()/
         equip() separately per character (relying on equip()'s own
         internal save happening correctly every single time). Also
         re-reads storage right after saving and logs what actually
         landed, so a device that still isn't granting these can be
         diagnosed straight from its own browser console.

         PHASE 7 — the granted roster now follows whichever cast THIS
         cycle's tutorial actually taught (getTutorialStartingCharacters()
         below), instead of a hardcoded ['beta','spindle','knot','knell',
         'fray'] — so a cycle-2+ player ends up OWNING Umbrella/Builder,
         not Knot/Knell, matching what they were just shown. R/G/B are
         deliberately NOT granted here even at cycle 3+ — they appear
         silently in that cycle's boards but are never actually
         "earned" through the tutorial itself; see the lore doc's
         "deliberately, permanently minor" note. Wiring a real
         ownership/ unlock path for them is out of scope for this pass. */
      function getTutorialStartingCharacters() {
        return ['beta', 'spindle'].concat(getKnotKnellSlotCast(), ['fray']);
      }
      function grantTutorialStarters() {
        const state = loadOwnership();
        const before = state.owned.slice();
        getTutorialStartingCharacters().forEach(function (id) {
          if (state.owned.indexOf(id) === -1) {
            state.owned.push(id);
          }
          if (state.equipped.indexOf(id) === -1 && state.equipped.length < 10) {
            state.equipped.push(id);
          }
        });
        saveOwnership(state);
        try {
          const after = loadOwnership();
          const allGranted = getTutorialStartingCharacters().every(function (id) { return after.owned.indexOf(id) !== -1; });
          console.log('[neur0doku tutorial] grantTutorialStarters — before:', before, 'after:', after.owned, 'fully granted:', allGranted);
          if (!allGranted) console.error('[neur0doku tutorial] grantTutorialStarters did NOT persist — localStorage may be unavailable/blocked in this browser context.');
        } catch (e) { /* console/localStorage unavailable — not fatal */ }
        return state;
      }

      function writeIntroSeen() {
        try { localStorage.setItem('neur0doku:introSeen', JSON.stringify(true)); }
        catch (err) { /* not fatal */ }
      }

      // Reads the SAME neur0doku:profile shape index-home.html's
      // Profile modal owns ({ avatarId, name, renameUsed }) — see
      // writePlayerName() below for why this tutorial now writes
      // into that key instead of (well, in addition to) its own
      // separate neur0doku:playerName.
      function readProfile() {
        try { return JSON.parse(localStorage.getItem('neur0doku:profile') || 'null'); }
        catch (err) { return null; }
      }

      // Writes the name typed on the Shop-trip panel into BOTH
      // neur0doku:playerName (kept for back-compat with anything that
      // may still read it) AND neur0doku:profile — the shape
      // index-home.html's Profile modal itself reads/writes
      // ({ avatarId, name, renameUsed }, via that page's own
      // loadProfile()/saveProfile()) and the one play.js's checkWin()
      // actually pulls a display name from for Daily/Weekly/Random
      // leaderboard submissions (readJSON('neur0doku:profile').name —
      // see play.js). Previously this only wrote playerName, which
      // nothing downstream actually read.
      //
      // Merges onto any EXISTING profile object rather than
      // clobbering it — in particular, never stomps a real avatarId
      // if one somehow already exists this early — and marks
      // renameUsed: true, same as a real name change on the Profile
      // modal, so a later visit there correctly shows "you've already
      // used your one free name change" instead of offering a second
      // free one.
      //
      // It does NOT touch the cross-app account profile
      // (players/{uid}.profile.displayName, owned by /js/account.js and
      // shared with neur0loom.xyz and neur0list) — see the NICKNAME ONLY
      // note at the end of this function.
      //
      // 2026-09-22: takes name-memory.js's resolveTutorialName() outcome
      // instead of a raw string. A name the player chose (typed, or the
      // one Beta remembered) is saved as before AND remembered by Beta
      // (rememberChosenName). A generated name ('random') is saved with
      // nameIsRandom: true, is NOT remembered, and is NOT pushed to the
      // account-wide display name — their Google name is a better
      // public-card name than "Plum7".
      //
      // FREE RENAME (2026-09-22): the tutorial's name no longer counts
      // as the free rename — a player who has never had a name saved
      // gets one free change on Home afterwards. But a reset must not
      // become a way to farm free renames, so if Beta ALREADY remembered
      // a name before this answer (outcome.rememberedName — set for the
      // 'same' / 'different' / 'remembered' reactions), the free rename
      // stays used. First-time players ('first') and anyone who's only
      // ever had a generated name ('random') keep it available.
      function writePlayerName(outcome) {
        const name = outcome.name;
        const isRandom = Boolean(outcome.isRandom);
        const freeRenameAlreadyHad = Boolean(outcome.rememberedName);
        try { localStorage.setItem('neur0doku:playerName', JSON.stringify(name)); }
        catch (err) { /* not fatal */ }
        try {
          const existing = readProfile() || {};
          // nameParts (2026-09-23): the picker's word positions, so a
          // word can be fixed later without touching saves (see
          // name-picker.js). null for an older typed name.
          const profile = Object.assign({ avatarId: 'beta' }, existing, { name: name, nameParts: partsFromName(name), renameUsed: freeRenameAlreadyHad, nameIsRandom: isRandom });
          localStorage.setItem('neur0doku:profile', JSON.stringify(profile));
        } catch (err) { /* not fatal */ }
        if (isRandom) return;
        try { rememberChosenName(name); } catch (err) { /* not fatal */ }
        // NICKNAME ONLY (2026-09-22): this used to also push the name to
        // the shared account profile (/js/account.js's setDisplayName ->
        // players/{uid}.profile.displayName), which neur0loom.xyz and
        // neur0list use too — so a name typed here renamed the player
        // everywhere. neur0doku now keeps its own nickname
        // (neur0doku:profile.name, synced by cloud-save.js and shown on
        // the public card — see public-card.js) and leaves the main
        // account name alone.
      }

      // getPlayerCycle() (imported from meta-escalation.js) IS the
      // real neur0doku:resetHistory-derived count now — see this
      // file's PHASE 7 import comment above. hasResetHistory() is
      // kept as a thin, differently-named wrapper only because
      // renderShopTripPanel() reads it as a boolean gate; it no
      // longer re-derives anything from localStorage itself.
      function hasResetHistory() {
        return getPlayerCycle() > 0;
      }

      grantTutorialStarters();
      const startState = loadOwnership();
      const forceReplay = new URLSearchParams(location.search).get('replay') === '1';
      if (forceReplay) {
        goToPanel(0);
      } else if (getOwnedCharacterCount(startState) >= 6) {
        // Returning from the Shop with a 6th character — the tutorial
        // is DONE, no unlock screen of its own (Part 8): straight to
        // the real neur0doku home page.
        writeIntroSeen();
        location.href = '../';
      } else {
        goToPanel(0);
      }
    })();
  </script>
  <script type="module" src="../js/app-heartbeat.js"></script>
</body>
</html>