@nadicodeai/design-system 0.1.0

package/README.md

@@ -0,0 +1,123 @@
+# NadicodeAI Design System
+
+The `@nadicodeai/design-system` package. [`DESIGN.md`](./DESIGN.md) is the normative implementation contract for reusable design tokens and package output; the canonical human brand book lives in the monorepo at `brand/brand-book/index.html`.
+
+`DESIGN.md` defines the normative NadicodeAI design system contract: tokens, typography, layout, components, do's and don'ts, written to the [@google/design.md](https://github.com/google-labs-code/design.md) spec. `npm run build` emits two consumable exports: `dist/tokens/nadicode.dtcg.json` (DTCG token format) and `dist/tailwind/nadicode.tailwind.json` (Tailwind config).
+
+For Tailwind CSS v4 CSS-first projects, `npm run build` also emits `dist/tailwind/nadicode.theme.css`, exported as `@nadicodeai/design-system/tailwind/theme.css`. Import it from the consuming app's CSS entry:
+
+```css
+@import "tailwindcss";
+@import "@nadicodeai/design-system/tailwind/theme.css";
+```
+
+The CSS adapter provides shadcn-compatible semantic utilities such as `bg-background`, `text-foreground`, `bg-primary`, `text-primary-foreground`, `border-border`, and `ring-ring`. NadicodeAI-specific spacing utilities are namespaced, for example `p-nadicode-lg` and `h-nadicode-h-cell-sm`, so standard Tailwind/shadcn classes such as `max-w-3xl` keep their normal Tailwind behavior. React consumers normally get this through `@nadicodeai/ui/globals.css`.
+
+Geist and Geist Mono (SIL Open Font License 1.1) ship inside the package under `src/assets/fonts/`. Consumers can pull the `@font-face` shim directly:
+
+```css
+@import "@nadicodeai/design-system/assets/fonts/geist.css";
+```
+
+Individual font files are also exposed under `@nadicodeai/design-system/assets/fonts/*` if the consumer needs to write its own `@font-face` declarations.
+
+## The `/css` bundle
+
+`DESIGN.md` is the token contract (Surface 1, exported as values). The CSS bundle is Surface 2: the hand-authored, framework-agnostic stylesheet that turns those tokens into the actual NadicodeAI website geometry, chrome, and the agent-chat experience. Import it with one line:
+
+```css
+@import "@nadicodeai/design-system/css";
+```
+
+That single import delivers:
+
+- the kernel page geometry — the 12-column page frame, the centered 10-column active lane, and single-owner seams;
+- the framework-agnostic brand display vocabulary: the agent-chat component family, run-state tags, `image`, artifact surfaces, and workflow state chrome;
+- the brand motion contract (`--nc-duration-*` / `--nc-ease-*` tokens, the `nc-msg-in` / `nc-typing` / `nc-pulse` keyframes, and a `prefers-reduced-motion: reduce` block that disables them);
+- the agent-chat CSS components — `nc-chat-thread`, `nc-chat-bubble-user`, `nc-chat-bubble-agent`, `nc-tool-call-trace`, `nc-memory-item`, `nc-handoff-banner`, `nc-approval-gate`, `nc-artifact-preview`, `nc-typing-dots`, `nc-state-row`, plus `nc-agent-avatar` and `nc-usage-meter`.
+
+Everything is token-only (`var(--nc-*)`); there is no hard-coded hex in the CSS components or structural geometry. Individual files are also reachable under `@nadicodeai/design-system/css/*` (for example `@nadicodeai/design-system/css/components/chat-thread.css`).
+
+The built bundle mirrors every kept partial into `dist/css/`. Generic marketing/SaaS sections and interactive components ship from `@nadicodeai/ui`, not this CSS package.
+
+### The eight-layer cascade
+
+The bundle declares one explicit `@layer` order up front, then imports each partial into its own layer:
+
+```css
+@layer tokens, reset, foundation, motion, layout, primitives, components;
+```
+
+Because the order is declared data, consumer overrides are predictable: layer your own rules in a layer that comes *after* the bundle and they win regardless of selector specificity. Open a page-local block with `@layer page;` and write page overrides into `@layer page { … }`, which sits after `components`:
+
+```css
+@layer page;
+@layer page {
+  /* page-specific overrides — always win over the bundle */
+}
+```
+
+### Relationship to `theme.css` and shadcn
+
+The `/css` bundle and the Tailwind `theme.css` adapter are complementary:
+
+- `@nadicodeai/design-system/tailwind/theme.css` publishes the shadcn `:root` token variables (the semantic `bg-background` / `text-foreground` / `border-border` family), so interactive shadcn app islands land on-brand when they need JS-driven accessibility behavior such as dialogs or comboboxes.
+- The `/css` bundle ships NadicodeAI's framework-agnostic page grammar, CSS components, brand motion contract, and agent-chat surfaces.
+- `@nadicodeai/ui` ships the React shadcn-style components and reusable section/app compositions on top of those tokens and CSS components.
+
+Use both together: React apps import `@nadicodeai/ui/globals.css` for Tailwind/shadcn utilities and `@import "@nadicodeai/design-system/css"` for NadicodeAI geometry and CSS components.
+
+### The agent-chat CSS components and the optional auto-play enhancer
+
+The chat CSS components render a complete, static agent conversation from CSS alone — no JavaScript required. `nc-chat-bubble-agent` carries a 3px accent edge whose color is switched by `[data-accent]` (for example `data-accent="green"`), mapped to existing `--nc-*` tokens.
+
+For motion, the package ships exactly one optional, vanilla, dependency-free enhancer: `chat-autoplay.js`, exported as `@nadicodeai/design-system/css/chat-autoplay.js`. It is the **only** JavaScript in the package — no React, no framework, no registry, no module/CDN imports. It is pure progressive enhancement:
+
+- add `data-nc-autoplay` to a `nc-chat-thread` and include the script; messages then reveal in scripted order, a typing indicator shows between turns, the thread scrolls to the newest message, and the cycle loops;
+- playback starts when the thread scrolls into view (`IntersectionObserver`);
+- under `prefers-reduced-motion: reduce`, the full thread is shown immediately with no loop;
+- **with the script absent, the full thread renders statically** — the components are usable framework-agnostically, with zero React.
+
+### Worked example (static HTML)
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <!-- Geist + Geist Mono, then the bundle -->
+    <link rel="stylesheet" href="https://unpkg.com/@nadicodeai/design-system/assets/fonts/geist.css" />
+    <link rel="stylesheet" href="https://unpkg.com/@nadicodeai/design-system/css" />
+    <!-- In a bundler, prefer a CSS entry: @import "@nadicodeai/design-system/css"; -->
+  </head>
+  <body>
+    <main class="nc-page-system">
+      <div class="nc-page-frame">
+        <section class="nc-page-row">
+          <div class="nc-row-lane nc-row-lane-active">
+            <!-- A playing chat thread: opt in with data-nc-autoplay -->
+            <div class="nc-chat-thread" data-nc-autoplay>
+              <div class="nc-chat-thread-body">
+                <div class="nc-chat-bubble-user">Which contract template should I use?</div>
+                <div class="nc-chat-bubble-agent" data-accent="green">
+                  Use the approved 2026 revision in Drive · Legal · Templates. It already has the updated privacy clauses.
+                </div>
+              </div>
+            </div>
+          </div>
+        </section>
+      </div>
+    </main>
+
+    <!-- Optional: omit this script and the thread above stays a full static conversation. -->
+    <script src="https://unpkg.com/@nadicodeai/design-system/css/chat-autoplay.js"></script>
+  </body>
+</html>
+```
+
+`examples/chat-showcase.html` is a live proof page that composes the chat CSS components with the auto-play enhancer across twelve conversations.
+
+Use the monorepo's `brand/brand-book/` for NadicodeAI story, positioning, buyer, promise, method, use cases, technology story, trust doctrine, identity, voice, visual direction, sales behavior, language, and boundaries.
+
+The archived `design-canvas/` prototype source-of-record (the chat motion and component prototypes the kernel re-expresses) lives in the monorepo's `docs/experiments` and is not package runtime or current brand canon.

package/dist/css/chat-autoplay.js

@@ -0,0 +1,544 @@
+/*
+ * chat-autoplay.js — the single optional vanilla enhancer for NadicodeAI chat
+ * threads. The ONLY JavaScript in @nadicodeai/design-system.
+ *
+ * It is pure progressive enhancement, framework-free, dependency-free, with no
+ * module-loader statements and no third-party runtime. It turns an
+ * already-static `.nc-chat-thread` into the auto-playing, looping agent
+ * conversation from the archived prototype
+ * `docs/experiments/design-canvas/chat-anim.jsx` — re-expressed as plain DOM.
+ *
+ * Contract (mirrors AC-018 and the M5 motion contract):
+ *
+ *  (a) Motion on: messages are hidden, then revealed in scripted source order by
+ *      toggling the M5 `.nc-anim-msg-in` hook (the rise-in). A typing indicator
+ *      (`.nc-typing-dots`) shows between turns, the thread body auto-scrolls to
+ *      the newest message, the `.nc-usage-meter-fill` is driven via `--nc-usage`,
+ *      and after `loopHold` (default 2400ms) the cycle restarts.
+ *
+ *  (b) `prefers-reduced-motion: reduce`: the FULL thread is shown immediately,
+ *      every message visible, NO loop, no typing animation. (We also stop if the
+ *      preference changes to reduce mid-play.)
+ *
+ *  (c) Script absent: the conversation renders FULLY and statically from CSS
+ *      alone. The atoms set `animation-name: nc-msg-in` but, without the M5
+ *      `.nc-anim-msg-in` hook supplying a duration, that is inert and every
+ *      message is visible. This file is the ONLY thing that ever hides a message
+ *      (via the per-element inline `display` it sets while playing). No hidden
+ *      class is ever present in static markup, so no-JS == full static thread.
+ *
+ *  (d) Playback starts on scroll-into-view via `IntersectionObserver`; it pauses
+ *      (resets to the static full thread and re-arms) when scrolled fully out.
+ *
+ * Timing parity with `src/css/motion.css`: the loop reads the M5 duration tokens
+ * (`--nc-duration-stagger`) from the thread's computed style and uses the
+ * per-role `defaultTiming()` rhythm ported verbatim from the prototype's
+ * `defaultTiming` (typingMs / holdMs per role + `loopHold`). The stagger unit
+ * comes from CSS, not a re-typed magic number; the per-role typing/hold cadence
+ * is the documented constants table below, carried with a parity note because
+ * the prototype owns those numbers in JS, not in CSS.
+ *
+ * Opt-in: only `.nc-chat-thread[data-nc-autoplay]` elements are enhanced. A
+ * thread without the attribute is left fully static.
+ *
+ * Usage (no bundler assumed):
+ *   <script src="…/css/chat-autoplay.js"></script>
+ * It self-initializes on DOMContentLoaded and also exposes
+ * `window.ncChatAutoplay.init(root?)` for manual / dynamic init.
+ */
+(function () {
+  "use strict";
+
+  if (typeof window === "undefined" || typeof document === "undefined") return;
+
+  // ── Per-role timing, ported verbatim from chat-anim.jsx `defaultTiming`. ──
+  // PARITY NOTE: these (typingMs, holdMs) pairs and `LOOP_HOLD` live in JS in the
+  // prototype (they are sequencing logic, not CSS), so they are mirrored here as
+  // a documented constants table rather than read from motion.css. The CSS owns
+  // the *visual* cadence (the stagger step), which we DO read from motion.css
+  // below; this table owns the *sequencing* cadence.
+  var LOOP_HOLD = 6000; // chat-anim.jsx loopHold default (raised: payoff frame dominates loop duty cycle)
+  var START_DELAY = 240; // chat-anim.jsx `await sleep(startDelay + 240)` with startDelay 0
+
+  function defaultTiming(role, textLen) {
+    var len = textLen || 0;
+    switch (role) {
+      case "user":
+        return { typingMs: 0, holdMs: 1100 + len * 8 };
+      case "tool":
+        return { typingMs: 380, holdMs: 700 };
+      case "state":
+        return { typingMs: 220, holdMs: 700 };
+      case "memory":
+        return { typingMs: 380, holdMs: 900 };
+      case "handoff":
+        return { typingMs: 420, holdMs: 1300 };
+      case "approval":
+        return { typingMs: 460, holdMs: 1600 };
+      case "artifact":
+        return { typingMs: 600, holdMs: 1800 };
+      case "agent":
+      default:
+        return { typingMs: 680, holdMs: 900 + len * 12 };
+    }
+  }
+
+  // Infer a message's role from its NadicodeAI atom class so authors don't have
+  // to duplicate the role in a data attribute. An explicit `data-nc-role`
+  // overrides. Falls back to "agent" (the slowest, safest cadence).
+  var ROLE_BY_CLASS = [
+    ["nc-chat-bubble-user", "user"],
+    ["nc-chat-bubble-agent", "agent"],
+    ["nc-tool-call-trace", "tool"],
+    ["nc-memory-item", "memory"],
+    ["nc-handoff-banner", "handoff"],
+    ["nc-approval-gate", "approval"],
+    ["nc-artifact-preview", "artifact"],
+    ["nc-state-row", "state"],
+  ];
+
+  function roleOf(el) {
+    var explicit = el.getAttribute("data-nc-role");
+    if (explicit) return explicit;
+    for (var i = 0; i < ROLE_BY_CLASS.length; i++) {
+      if (el.classList.contains(ROLE_BY_CLASS[i][0])) return ROLE_BY_CLASS[i][1];
+    }
+    return "agent";
+  }
+
+  function reducedMotion() {
+    return (
+      typeof window.matchMedia === "function" &&
+      window.matchMedia("(prefers-reduced-motion: reduce)").matches
+    );
+  }
+
+  // Read a duration token (e.g. "--nc-duration-stagger") off a live element and
+  // return milliseconds. Falls back to a documented default that equals the
+  // motion.css value if the bundle is not loaded (graceful, never throws).
+  function durationToken(el, name, fallbackMs) {
+    var raw = getComputedStyle(el).getPropertyValue(name).trim();
+    if (!raw) return fallbackMs;
+    if (raw.slice(-2) === "ms") return parseFloat(raw) || fallbackMs;
+    if (raw.slice(-1) === "s") return (parseFloat(raw) || 0) * 1000 || fallbackMs;
+    var n = parseFloat(raw);
+    return isNaN(n) ? fallbackMs : n;
+  }
+
+  // ── One thread's player ───────────────────────────────────────────────────
+  function ChatThreadPlayer(thread) {
+    this.thread = thread;
+    this.body = thread.querySelector(".nc-chat-thread-body");
+    // Stable, source-ordered list of message atoms inside the body. The typing
+    // indicator and any element flagged to ignore are NOT messages.
+    this.messages = this.body
+      ? Array.prototype.filter.call(this.body.children, function (el) {
+          return (
+            el.nodeType === 1 &&
+            !el.classList.contains("nc-typing-dots") &&
+            el.getAttribute("data-nc-autoplay-ignore") === null
+          );
+        })
+      : [];
+    this.typing = this.body ? this.body.querySelector(".nc-typing-dots") : null;
+    this.meterFill = thread.querySelector(".nc-usage-meter-fill");
+    this.staggerMs = 160; // overwritten from the CSS token at enhance()
+    this.timers = [];
+    this.running = false;
+    this.cancelled = false;
+    // Monotonic loop epoch. `_runLoop` captures the value live at start and every
+    // guard checks it. `stop()`/`rearm()` bump it so a stale continuation — a
+    // `_sleep` timer that already fired but whose `.then` is still queued when the
+    // player is stopped and immediately re-armed on scroll-in — sees a mismatched
+    // epoch and dies permanently, instead of resuming once `cancelled` flips back
+    // to false and racing the fresh loop. Single, uninterrupted playback never
+    // changes the epoch mid-run, so the observed sequence is unchanged.
+    this.generation = 0;
+    // WCAG 2.2.2 user-pause latch. Set true when the user presses the pause button;
+    // cleared when the user presses resume. play() and the in-view observer branch
+    // both check it; a paused thread stays paused across scroll-out/in.
+    this.userPaused = false;
+    // Set to true once the sequence has reached its end at least once. Used by
+    // the IntersectionObserver entry branch: a thread that has completed is shown
+    // in its final visible state on re-entry rather than replayed from blank, so
+    // a reader who scrolls back sees the payoff frame instead of an empty/typing state.
+    this.completedOnce = false;
+    // Accent for an auto-created typing bubble, inferred from the first agent
+    // bubble's data-accent (default green, matching the prototype).
+    this.accent = "green";
+    var firstAgent = thread.querySelector(".nc-chat-bubble-agent[data-accent]");
+    if (firstAgent) this.accent = firstAgent.getAttribute("data-accent") || "green";
+  }
+
+  ChatThreadPlayer.prototype._clearTimers = function () {
+    for (var i = 0; i < this.timers.length; i++) clearTimeout(this.timers[i]);
+    this.timers = [];
+  };
+
+  ChatThreadPlayer.prototype._sleep = function (ms) {
+    var self = this;
+    return new Promise(function (resolve) {
+      var t = setTimeout(resolve, ms);
+      self.timers.push(t);
+    });
+  };
+
+  // Fully static, fully visible end-state. Used for no-loop (reduced-motion),
+  // for pause-out-of-view, and as the baseline each loop resets from. Removes
+  // every trace the player added so the DOM matches the no-JS static thread.
+  ChatThreadPlayer.prototype._showAll = function () {
+    for (var i = 0; i < this.messages.length; i++) {
+      var m = this.messages[i];
+      m.style.display = "";
+      m.classList.remove("nc-anim-msg-in");
+    }
+    this._hideTyping();
+    this.thread.removeAttribute("data-nc-playing");
+  };
+
+  ChatThreadPlayer.prototype._hideAllMessages = function () {
+    for (var i = 0; i < this.messages.length; i++) {
+      this.messages[i].style.display = "none";
+      this.messages[i].classList.remove("nc-anim-msg-in");
+    }
+  };
+
+  ChatThreadPlayer.prototype._scrollToBottom = function () {
+    var body = this.body;
+    if (!body) return;
+    requestAnimationFrame(function () {
+      body.scrollTop = body.scrollHeight;
+    });
+  };
+
+  // Ensure a typing indicator exists; create one if the markup has none so the
+  // "typing between turns" behaviour works on any thread. Created element is
+  // tagged so _showAll can drop it.
+  ChatThreadPlayer.prototype._ensureTyping = function () {
+    if (this.typing) return this.typing;
+    if (!this.body) return null;
+    var el = document.createElement("div");
+    el.className = "nc-typing-dots";
+    el.setAttribute("data-accent", this.accent);
+    el.setAttribute("aria-hidden", "true");
+    el.setAttribute("data-nc-autoplay-created", "");
+    for (var i = 0; i < 3; i++) {
+      var dot = document.createElement("span");
+      dot.className = "nc-typing-dots-dot nc-anim-typing";
+      dot.style.setProperty("--nc-anim-delay", i * this.staggerMs + "ms");
+      el.appendChild(dot);
+    }
+    el.style.display = "none";
+    this.body.appendChild(el);
+    this.typing = el;
+    return el;
+  };
+
+  ChatThreadPlayer.prototype._showTyping = function () {
+    var el = this._ensureTyping();
+    if (!el) return;
+    // Move the indicator to the end of the body so it sits below revealed turns.
+    this.body.appendChild(el);
+    el.style.display = "";
+    this._scrollToBottom();
+  };
+
+  ChatThreadPlayer.prototype._hideTyping = function () {
+    if (this.typing) this.typing.style.display = "none";
+  };
+
+  ChatThreadPlayer.prototype._setMeter = function (fraction) {
+    if (!this.meterFill) return;
+    var pct = Math.max(0, Math.min(1, fraction)) * 100;
+    this.meterFill.style.setProperty("--nc-usage", pct + "%");
+  };
+
+  ChatThreadPlayer.prototype._reveal = function (msg, index) {
+    msg.style.display = "";
+    // Re-trigger the M5 rise-in: the hook supplies duration/easing; the atom
+    // already carries `animation-name: nc-msg-in`. Force a reflow so re-adding
+    // the class restarts the animation on a re-loop.
+    msg.style.setProperty("--nc-anim-delay", "0ms");
+    msg.classList.remove("nc-anim-msg-in");
+    void msg.offsetWidth;
+    msg.classList.add("nc-anim-msg-in");
+    this._setMeter((index + 1) / this.messages.length);
+    this._scrollToBottom();
+  };
+
+  // The reveal loop — a vanilla re-expression of chat-anim.jsx's `run()`. A loop
+  // is "stale" once it is cancelled OR a newer epoch has started; either way it
+  // must stop touching the DOM. `myGen` is captured once at start so a queued
+  // continuation can detect that the player was stopped-and-re-armed underneath
+  // it (see the `generation` note in the constructor).
+  ChatThreadPlayer.prototype._runLoop = function () {
+    var self = this;
+    var myGen = this.generation;
+    var stale = function () {
+      return self.cancelled || self.generation !== myGen;
+    };
+    return (function loop() {
+      if (stale()) return Promise.resolve();
+      self._hideAllMessages();
+      self._hideTyping();
+      self._setMeter(0);
+      return self
+        ._sleep(START_DELAY)
+        .then(function () {
+          var chain = Promise.resolve();
+          self.messages.forEach(function (msg, i) {
+            chain = chain.then(function () {
+              if (stale()) return;
+              var role = roleOf(msg);
+              var t = defaultTiming(role, (msg.textContent || "").trim().length);
+              var step = function () {
+                if (stale()) return;
+                self._hideTyping();
+                self._reveal(msg, i);
+                return self._sleep(t.holdMs);
+              };
+              if (t.typingMs > 0) {
+                self._showTyping();
+                return self._sleep(t.typingMs).then(step);
+              }
+              return step();
+            });
+          });
+          return chain;
+        })
+        .then(function () {
+          if (stale()) return;
+          // Mark completion before the hold so the observer entry branch can
+          // show the final state on re-entry without replaying from blank.
+          self.completedOnce = true;
+          return self._sleep(LOOP_HOLD);
+        })
+        .then(function () {
+          if (stale()) return;
+          return loop();
+        });
+    })();
+  };
+
+  ChatThreadPlayer.prototype.play = function () {
+    if (this.running || this.cancelled) return;
+    // WCAG 2.2.2: user-pressed pause wins over every automatic restart.
+    if (this.userPaused) return;
+    // (b) Reduced motion: show the full thread immediately, no loop, no typing.
+    if (reducedMotion()) {
+      this._showAll();
+      this._setMeter(1);
+      return;
+    }
+    if (!this.messages.length) return;
+    this.running = true;
+    this.thread.setAttribute("data-nc-playing", "");
+    this._runLoop();
+  };
+
+  // Stop and reset to the fully-visible static thread (re-armable).
+  ChatThreadPlayer.prototype.stop = function () {
+    this.cancelled = true;
+    this.generation++; // retire the running loop's queued continuations
+    this._clearTimers();
+    this.running = false;
+    this._showAll();
+    this._setMeter(1);
+  };
+
+  // Re-arm a stopped player (used when the thread scrolls back into view). Bump
+  // the epoch again so a still-queued continuation from the just-stopped loop can
+  // never resume now that `cancelled` is cleared — only the loop `play()` starts
+  // next will match the current epoch.
+  ChatThreadPlayer.prototype.rearm = function () {
+    this.cancelled = false;
+    this.generation++;
+    this.running = false;
+  };
+
+  // Inject the enhancer-owned pause/resume button into the thread card.
+  // One button per thread, positioned top-right above the body. Uses
+  // data-nc-autoplay-name for an accessible per-thread subject, e.g.
+  // "Pause <value>"/"Resume <value>"; falls back to "Pause demonstration".
+  // Never called in reduced-motion mode (contract (b): no button for a path
+  // that plays nothing).
+  ChatThreadPlayer.prototype._injectPauseButton = function () {
+    var self = this;
+    var thread = this.thread;
+    var subject = thread.getAttribute("data-nc-autoplay-name") || "demonstration";
+    var btn = document.createElement("button");
+    btn.type = "button";
+    btn.className = "nc-chat-pause";
+    btn.setAttribute("aria-pressed", "false");
+    btn.textContent = "Pause " + subject;
+    btn.addEventListener("click", function () {
+      if (self.userPaused) {
+        // Resume: clear the latch, rearm and play.
+        self.userPaused = false;
+        btn.setAttribute("aria-pressed", "false");
+        btn.textContent = "Pause " + subject;
+        self.rearm();
+        self.play();
+      } else {
+        // Pause: set the latch, stop and reveal full content.
+        self.userPaused = true;
+        btn.setAttribute("aria-pressed", "true");
+        btn.textContent = "Resume " + subject;
+        self.stop();
+      }
+    });
+    // Insert before the body so the button sits above the scrolling content.
+    var body = thread.querySelector(".nc-chat-thread-body");
+    if (body) {
+      thread.insertBefore(btn, body);
+    } else {
+      thread.appendChild(btn);
+    }
+    this.pauseBtn = btn;
+  };
+
+  // ── Initialisation ──────────────────────────────────────────────────────
+  var players = [];
+  var observer = null;
+
+  function enhance(thread) {
+    if (thread.__ncAutoplayPlayer) return thread.__ncAutoplayPlayer;
+    var player = new ChatThreadPlayer(thread);
+    // Read the M5 stagger token off the live thread (parity with motion.css);
+    // fallback equals the motion.css default (160ms) if the bundle is absent.
+    player.staggerMs = durationToken(thread, "--nc-duration-stagger", 160);
+    thread.__ncAutoplayPlayer = player;
+    players.push(player);
+    // Inject the pause/resume button unless reduced-motion is on (that path
+    // plays nothing and must inject no button — WCAG 2.2.2 scope follows the
+    // animation).
+    if (!reducedMotion()) {
+      player._injectPauseButton();
+    }
+    return player;
+  }
+
+  function startObserving() {
+    if (typeof window.IntersectionObserver !== "function") {
+      // No IntersectionObserver: degrade by playing immediately (still respects
+      // reduced motion inside play()).
+      for (var i = 0; i < players.length; i++) players[i].play();
+      return;
+    }
+    // Manual re-init (the documented `window.ncChatAutoplay.init(root)` path for
+    // dynamic content) calls this again; tear down the prior observer first so a
+    // repeat init replaces — rather than stacks — observers. A single self-init
+    // (the common path) hits this once and `observer` is null, so behavior is
+    // unchanged; only repeated manual init benefits (no leaked observers, no
+    // duplicate intersection callbacks per thread).
+    if (observer) observer.disconnect();
+    observer = new IntersectionObserver(
+      function (entries) {
+        for (var i = 0; i < entries.length; i++) {
+          var entry = entries[i];
+          var player = entry.target.__ncAutoplayPlayer;
+          if (!player) continue;
+          if (entry.isIntersecting) {
+            // (d) Start when scrolled into view — but only if the player is not
+            // already running its loop. Re-arming a mid-loop player kills and
+            // restarts it from blank (the long right thread reads as dead under
+            // scroll crossings). A player is "running" once play() sets the flag
+            // and until stop() clears it; the loop recursion holds this state.
+            // WCAG 2.2.2: do not override a user-pressed pause on scroll-in.
+            if (player.userPaused) continue;
+            if (!player.running) {
+              if (player.completedOnce) {
+                // The sequence finished at least once. Show the full final state
+                // immediately so the reader sees the payoff frame, not a blank/
+                // typing restart. The loop resumes from this state on the next
+                // natural cycle if the thread stays in view.
+                player._showAll();
+                player._setMeter(1);
+              } else {
+                player.rearm();
+                player.play();
+              }
+            }
+          } else if (entry.intersectionRatio === 0) {
+            // Stop only when the thread is FULLY out of view (ratio exactly 0).
+            // At partial visibility (e.g. ratio 0.228) do nothing — collapsing
+            // to the finished card while the thread is still on screen is the
+            // bug this guard fixes.
+            if (player.running) {
+              player.stop();
+            }
+          }
+        }
+      },
+      { threshold: [0, 0.25] },
+    );
+    for (var j = 0; j < players.length; j++) observer.observe(players[j].thread);
+  }
+
+  // ── Settle module — enhancer-armed, run-once scroll entrance ─────────────
+  // Arms .nc-settle elements that are fully below the viewport at init.
+  // On first IntersectionObserver entry, switches data-nc-settle from "armed"
+  // to "in" (triggers the CSS nc-msg-in animation) and immediately unobserves
+  // so the rise-in fires once and is never reversed on scroll-back. Elements
+  // already visible at load are left unarmed (no flash; hero region untouched).
+  // prefers-reduced-motion: skip entirely — page fully visible without JS.
+  function initSettle(scope) {
+    if (reducedMotion()) return;
+    if (typeof window.IntersectionObserver !== "function") return;
+    var settleElements = (scope || document).querySelectorAll(".nc-settle");
+    if (!settleElements.length) return;
+    var settleObserver = new IntersectionObserver(
+      function (entries, obs) {
+        for (var i = 0; i < entries.length; i++) {
+          if (entries[i].isIntersecting) {
+            entries[i].target.setAttribute("data-nc-settle", "in");
+            obs.unobserve(entries[i].target);
+          }
+        }
+      },
+      { threshold: 0.1 },
+    );
+    for (var i = 0; i < settleElements.length; i++) {
+      var el = settleElements[i];
+      var rect = el.getBoundingClientRect();
+      // Arm only elements whose top edge is fully below the viewport.
+      if (rect.top > window.innerHeight) {
+        el.setAttribute("data-nc-settle", "armed");
+        settleObserver.observe(el);
+      }
+    }
+  }
+
+  function init(root) {
+    var scope = root || document;
+    var threads = scope.querySelectorAll(".nc-chat-thread[data-nc-autoplay]");
+    for (var i = 0; i < threads.length; i++) enhance(threads[i]);
+    initSettle(scope);
+    startObserving();
+    return players;
+  }
+
+  // Respond to a runtime change of the reduced-motion preference: collapse any
+  // running player to the static full thread.
+  if (typeof window.matchMedia === "function") {
+    var mq = window.matchMedia("(prefers-reduced-motion: reduce)");
+    var onChange = function () {
+      if (!mq.matches) return;
+      for (var i = 0; i < players.length; i++) {
+        if (players[i].running) players[i].stop();
+      }
+    };
+    if (typeof mq.addEventListener === "function") mq.addEventListener("change", onChange);
+    else if (typeof mq.addListener === "function") mq.addListener(onChange);
+  }
+
+  window.ncChatAutoplay = { init: init, players: players };
+
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", function () {
+      init();
+    });
+  } else {
+    init();
+  }
+})();