diff --git a/docs/app/components/docs/sidebar.tsx b/docs/app/components/docs/sidebar.tsx
index 391a9cdb..794e3556 100644
--- a/docs/app/components/docs/sidebar.tsx
+++ b/docs/app/components/docs/sidebar.tsx
@@ -103,7 +103,9 @@ function NavLink({ node, current }: { node: NavNode; current: string }) {
   );
 }
 
-/** A subsection with children — collapsible, auto-opens around the active page. */
+/** A subsection with children — collapsible at any depth, auto-opens around the
+ *  active page. The label itself toggles (same behaviour as a top-level group),
+ *  so a subsection-of-a-subsection expands/collapses on click just like its parent. */
 function NavSection({ node, current }: { node: NavNode; current: string }) {
   const active = node.children?.some((c) => containsHref(c, current)) ?? false;
   const [open, setOpen] = useState(active);
@@ -112,15 +114,21 @@ function NavSection({ node, current }: { node: NavNode; current: string }) {
       setOpen(true);
     }
   }, [active]);
+  const toggle = () => setOpen((o) => !o);
   return (
     <div className="nav-subsection">
       <div className="nav-sub-head">
-        <NavLink node={node} current={current} />
-        <Caret
-          open={open}
-          onToggle={() => setOpen((o) => !o)}
-          title={node.title}
-        />
+        <button
+          type="button"
+          className={`nav-item nav-sub-toggle ${
+            node.href === current ? "active" : ""
+          }`.trim()}
+          aria-expanded={open}
+          onClick={toggle}
+        >
+          {node.title}
+        </button>
+        <Caret open={open} onToggle={toggle} title={node.title} />
       </div>
       {open ? <NavTree nodes={node.children ?? []} current={current} /> : null}
     </div>
@@ -189,25 +197,44 @@ function NavGroup({ group, current }: { group: NavNode; current: string }) {
   );
 }
 
-export function Sidebar({ onSearch }: { onSearch?: () => void }) {
+export function Sidebar({
+  onSearch,
+  open = false,
+  onClose,
+}: {
+  onSearch?: () => void;
+  /** Drawer open state — only affects the mobile (≤860px) overlay layout. */
+  open?: boolean;
+  onClose?: () => void;
+}) {
   const { pathname } = useLocation();
   const current = pathname.replace(/\/$/, "") || "/";
   const sdk = useActiveSdk();
   return (
-    <aside className="sidebar">
-      <button type="button" className="side-search" onClick={onSearch}>
-        Search docs
-        <span className="sk">
-          <kbd>⌘</kbd>
-          <kbd>K</kbd>
-        </span>
-      </button>
-      <SdkSwitch sdk={sdk} current={current} />
-      <nav id="sidenav">
-        {navForSdk(sdk).map((group) => (
-          <NavGroup key={group.title} group={group} current={current} />
-        ))}
-      </nav>
-    </aside>
+    <>
+      {/* Backdrop sits under the drawer on mobile; tapping it closes the menu. */}
+      <button
+        type="button"
+        className={`sidebar-backdrop ${open ? "open" : ""}`.trim()}
+        aria-label="Close navigation menu"
+        tabIndex={open ? 0 : -1}
+        onClick={onClose}
+      />
+      <aside className={`sidebar ${open ? "open" : ""}`.trim()}>
+        <button type="button" className="side-search" onClick={onSearch}>
+          Search docs
+          <span className="sk">
+            <kbd>⌘</kbd>
+            <kbd>K</kbd>
+          </span>
+        </button>
+        <SdkSwitch sdk={sdk} current={current} />
+        <nav id="sidenav">
+          {navForSdk(sdk).map((group) => (
+            <NavGroup key={group.title} group={group} current={current} />
+          ))}
+        </nav>
+      </aside>
+    </>
   );
 }
diff --git a/docs/app/components/landing/demo-modal.tsx b/docs/app/components/landing/demo-modal.tsx
new file mode 100644
index 00000000..30afcd54
--- /dev/null
+++ b/docs/app/components/landing/demo-modal.tsx
@@ -0,0 +1,192 @@
+import { useEffect, useRef, useState } from "react";
+import { useThemeMode } from "@/lib/theme";
+
+/** A live demo the finder can open: the embed id + a human title for the bar. */
+export interface DemoTarget {
+  /** Demo id understood by `demos/interactive.html?embed=` (e.g. "ratelimit"). */
+  id: string;
+  /** Title shown in the modal bar. */
+  title: string;
+}
+
+function prefersReducedMotion(): boolean {
+  if (typeof window === "undefined") return false;
+  return Boolean(
+    window.matchMedia?.("(prefers-reduced-motion: reduce)").matches,
+  );
+}
+
+const PLAY_ICON = (
+  <svg
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth={2}
+    strokeLinecap="round"
+    strokeLinejoin="round"
+    aria-hidden="true"
+  >
+    <path d="m8 5 11 7-11 7V5z" />
+  </svg>
+);
+
+const CLOSE_ICON = (
+  <svg
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth={2.2}
+    strokeLinecap="round"
+    strokeLinejoin="round"
+    aria-hidden="true"
+  >
+    <path d="M18 6 6 18M6 6l12 12" />
+  </svg>
+);
+
+/**
+ * Centered overlay that opens a finder scenario's live demo in an `<iframe>`,
+ * pointed at the vendored `demos/interactive.html` embed mode (theme inherited
+ * from the host). React port of `INTEGRATION-scenario-finder.md` §6: focus moves
+ * to the close button on open and restores on close, Escape + backdrop close,
+ * background scroll is locked, and the enter transition is motion-aware.
+ *
+ * `demo === null` keeps the modal closed; a brief exit transition plays before
+ * the iframe unmounts so the demo stops running.
+ */
+export function DemoModal({
+  demo,
+  onClose,
+}: {
+  demo: DemoTarget | null;
+  onClose: () => void;
+}) {
+  const theme = useThemeMode();
+  // Mounted target (survives the exit transition after `demo` goes null).
+  const [current, setCurrent] = useState<DemoTarget | null>(demo);
+  // Drives the `.open` class — toggled a frame after mount so the enter plays.
+  const [shown, setShown] = useState(false);
+  const [loading, setLoading] = useState(true);
+  const closeRef = useRef<HTMLButtonElement>(null);
+  const dialogRef = useRef<HTMLDivElement>(null);
+  const restoreRef = useRef<HTMLElement | null>(null);
+
+  useEffect(() => {
+    if (demo) {
+      restoreRef.current = (document.activeElement as HTMLElement) ?? null;
+      setCurrent(demo);
+      setLoading(true);
+      const raf = requestAnimationFrame(() => setShown(true));
+      return () => cancelAnimationFrame(raf);
+    }
+    setShown(false);
+    const timer = setTimeout(
+      () => setCurrent(null),
+      prefersReducedMotion() ? 0 : 260,
+    );
+    return () => clearTimeout(timer);
+  }, [demo]);
+
+  // While a demo is mounted: lock scroll, close on Escape, and trap Tab focus
+  // inside the dialog so keyboard users can't reach background content.
+  useEffect(() => {
+    if (!current) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") {
+        onClose();
+        return;
+      }
+      if (e.key !== "Tab") return;
+      const dialog = dialogRef.current;
+      if (!dialog) return;
+      const focusable = dialog.querySelectorAll<HTMLElement>(
+        'a[href], button:not([disabled]), iframe, [tabindex]:not([tabindex="-1"])',
+      );
+      const first = focusable[0];
+      const last = focusable[focusable.length - 1];
+      if (!first || !last) return;
+      const active = document.activeElement;
+      if (e.shiftKey && active === first) {
+        e.preventDefault();
+        last.focus();
+      } else if (!e.shiftKey && active === last) {
+        e.preventDefault();
+        first.focus();
+      }
+    };
+    document.addEventListener("keydown", onKey);
+    document.body.style.overflow = "hidden";
+    return () => {
+      document.removeEventListener("keydown", onKey);
+      document.body.style.overflow = "";
+    };
+  }, [current, onClose]);
+
+  // Move focus into the dialog on open; restore it to the trigger on close.
+  useEffect(() => {
+    if (shown) closeRef.current?.focus();
+  }, [shown]);
+  useEffect(() => {
+    if (!current && restoreRef.current) {
+      restoreRef.current.focus?.();
+      restoreRef.current = null;
+    }
+  }, [current]);
+
+  if (!current) return null;
+
+  // `import.meta.env.BASE_URL` ends with "/" and respects DOCS_BASE_PATH.
+  const src = `${import.meta.env.BASE_URL}demos/interactive.html?embed=${current.id}&theme=${theme}&accent=brand#${current.id}`;
+
+  return (
+    <div className={`dm-overlay${shown ? " open" : ""}`} aria-hidden={!shown}>
+      <button
+        type="button"
+        className="dm-backdrop"
+        tabIndex={-1}
+        aria-hidden="true"
+        onClick={onClose}
+      />
+      <div
+        className="dm-dialog"
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby="dm-title"
+        ref={dialogRef}
+      >
+        <div className="dm-bar">
+          <span className="dm-mark">{PLAY_ICON}</span>
+          <div className="dm-meta">
+            <span className="dm-eyebrow">Live demo</span>
+            <span className="dm-title" id="dm-title">
+              {current.title}
+            </span>
+          </div>
+          <div className="dm-actions">
+            <button
+              type="button"
+              className="dm-x"
+              ref={closeRef}
+              onClick={onClose}
+              aria-label="Close demo"
+            >
+              {CLOSE_ICON}
+            </button>
+          </div>
+        </div>
+        <div className="dm-stage">
+          <div className={`dm-loading${loading ? "" : " hide"}`}>
+            <span className="dm-spin" />
+            Loading demo…
+          </div>
+          <iframe
+            className="dm-frame"
+            title={`${current.title} — interactive demo`}
+            src={src}
+            onLoad={() => setLoading(false)}
+          />
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/docs/app/components/landing/index.ts b/docs/app/components/landing/index.ts
index 1991a1b3..be0f09bd 100644
--- a/docs/app/components/landing/index.ts
+++ b/docs/app/components/landing/index.ts
@@ -1,6 +1,7 @@
 export { Footer } from "./footer";
 export { Hero } from "./hero";
 export { useReveal } from "./reveal";
+export { ScenarioFinder } from "./scenario-finder";
 export {
   Comparison,
   CTA,
diff --git a/docs/app/components/landing/scenario-finder.tsx b/docs/app/components/landing/scenario-finder.tsx
new file mode 100644
index 00000000..ebd2c595
--- /dev/null
+++ b/docs/app/components/landing/scenario-finder.tsx
@@ -0,0 +1,585 @@
+import { type KeyboardEvent, useEffect, useRef, useState } from "react";
+import { Link } from "react-router";
+import { RawHtml } from "@/components/ui";
+import { DemoModal, type DemoTarget } from "./demo-modal";
+
+interface Bullet {
+  /** Short mono label in the left rail. */
+  k: string;
+  /** Trusted inline HTML (may contain `<code>`). */
+  v: string;
+}
+
+interface Scenario {
+  /** Slug — stable key + tab/panel id. */
+  id: string;
+  /** Plain-language problem shown in the left pane. */
+  q: string;
+  /** Category surfaced on the answer card. */
+  tag: string;
+  /** Inner SVG markup for a 24×24 stroke icon. */
+  icon: React.ReactNode;
+  title: string;
+  /** Trusted inline HTML (may contain `<code>`). */
+  blurb: string;
+  /** Exactly three points on how it works; `v` is trusted inline HTML. */
+  bullets: [Bullet, Bullet, Bullet];
+  /** Pre-highlighted Python (span-tokenized HTML, `\n`-separated). */
+  code: string;
+  /** Primary CTA — opens the matching live demo in a modal. */
+  demo: DemoTarget & { label: string };
+  /** Secondary CTA — the guide that goes deeper. */
+  guide: { to: string; label: string };
+}
+
+const SCENARIOS: Scenario[] = [
+  {
+    id: "heavy",
+    q: "A user uploaded something huge and the request is hanging",
+    tag: "Heavy processing",
+    icon: (
+      <>
+        <path d="M12 3v12" />
+        <path d="m8 11 4 4 4-4" />
+        <path d="M4 17v2a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2v-2" />
+      </>
+    ),
+    title: "Hand it off, return instantly, stream the progress back",
+    blurb:
+      "Never make a user watch a spinner. Push the work into taskito, respond in milliseconds, and report a live percentage as it runs.",
+    bullets: [
+      {
+        k: "Respond now",
+        v: "<code>.delay()</code> queues the job and your endpoint returns immediately",
+      },
+      {
+        k: "Report progress",
+        v: "call <code>progress.update()</code> from inside the task",
+      },
+      {
+        k: "User sees it move",
+        v: "your UI subscribes and shows a live % bar",
+      },
+    ],
+    code: `<span class="fn">@queue.task</span>
+<span class="kw">def</span> <span class="def">process</span>(file_id):
+    <span class="kw">for</span> i, chunk <span class="kw">in</span> <span class="def">enumerate</span>(chunks):
+        <span class="def">crunch</span>(chunk)
+        progress.<span class="def">update</span>((i+<span class="num">1</span>)/total)  <span class="cmt"># ← live %</span>`,
+    demo: {
+      id: "scaling",
+      title: "Worker scaling playground",
+      label: "Watch workers drain a queue",
+    },
+    guide: {
+      to: "/python/guides/advanced-execution/streaming",
+      label: "Read the guide",
+    },
+  },
+  {
+    id: "blocked",
+    q: "My API provider keeps blocking me with 429 errors",
+    tag: "Rate limiting",
+    icon: (
+      <>
+        <circle cx="12" cy="12" r="9" />
+        <path d="M5.6 5.6l12.8 12.8" />
+      </>
+    ),
+    title: "Back off, retry, and keep everything else flowing",
+    blurb:
+      "taskito catches the 429, waits with exponential backoff, and retries — while your other jobs keep draining. Add a rate limit and you never hammer them again.",
+    bullets: [
+      {
+        k: "Auto-retry",
+        v: "a raised error re-queues the job, it is never dropped",
+      },
+      { k: "Exponential backoff", v: "each retry waits longer — 1s, 2s, 4s…" },
+      {
+        k: "Stay under the cap",
+        v: "<code>rate_limit</code> throttles calls to their limit",
+      },
+    ],
+    code: `<span class="fn">@queue.task</span>(max_retries=<span class="num">5</span>, backoff=<span class="str">"exponential"</span>)
+<span class="fn">@queue.rate_limit</span>(<span class="str">"100/min"</span>)        <span class="cmt"># ← stay under their cap</span>
+<span class="kw">def</span> <span class="def">call_api</span>(payload):
+    resp = provider.<span class="def">send</span>(payload)
+    resp.<span class="def">raise_for_status</span>()         <span class="cmt"># 429 → auto-retry</span>`,
+    demo: {
+      id: "ratelimit",
+      title: "Rate limiting — what happens at 429",
+      label: "Trigger a 429 yourself",
+    },
+    guide: {
+      to: "/python/guides/reliability/rate-limiting",
+      label: "Read the guide",
+    },
+  },
+  {
+    id: "failed",
+    q: "A job failed halfway through — now what happens to it?",
+    tag: "Failure recovery",
+    icon: (
+      <>
+        <path d="M3 12a9 9 0 1 0 3-6.7L3 8" />
+        <path d="M3 3v5h5" />
+        <path d="M12 8v4l2 2" />
+      </>
+    ),
+    title: "Retry a few times, then dead-letter it — never silently lose it",
+    blurb:
+      "Transient failures retry automatically. When a job truly can't succeed, it lands in the dead-letter queue so you can inspect, fix, and replay it — instead of it vanishing.",
+    bullets: [
+      { k: "Every attempt logged", v: "see the error and timing for each try" },
+      {
+        k: "Then dead-letter",
+        v: "after <code>max_retries</code> the job moves to the DLQ",
+      },
+      {
+        k: "Replay by hand",
+        v: "requeue DLQ jobs once you've fixed the cause",
+      },
+    ],
+    code: `<span class="fn">@queue.task</span>(max_retries=<span class="num">3</span>, dead_letter=<span class="kw">True</span>)
+<span class="kw">def</span> <span class="def">charge</span>(order_id):
+    gateway.<span class="def">charge</span>(order_id)   <span class="cmt"># fails 3× → DLQ, not lost</span>`,
+    demo: {
+      id: "recovery",
+      title: "Failure recovery — a job's lifecycle",
+      label: "Scrub a job's lifecycle",
+    },
+    guide: {
+      to: "/python/guides/reliability/retries",
+      label: "Read the guide",
+    },
+  },
+  {
+    id: "burst",
+    q: "I need to fire off thousands of tasks at once",
+    tag: "Scaling",
+    icon: (
+      <>
+        <rect x="3" y="3" width="7" height="7" rx="1.5" />
+        <rect x="14" y="3" width="7" height="7" rx="1.5" />
+        <rect x="3" y="14" width="7" height="7" rx="1.5" />
+        <rect x="14" y="14" width="7" height="7" rx="1.5" />
+      </>
+    ),
+    title: "Queue the whole burst, then scale workers to match",
+    blurb:
+      "Enqueue as fast as you can loop. The queue absorbs the spike and workers pull at their own pace — add more workers or concurrency to go faster, with memory staying flat.",
+    bullets: [
+      { k: "Nothing is lost", v: "the queue buffers the entire burst" },
+      {
+        k: "Tune throughput",
+        v: "<code>workers × concurrency</code> sets your rate",
+      },
+      { k: "Backpressure built in", v: "slow consumers don't blow up memory" },
+    ],
+    code: `<span class="kw">for</span> email <span class="kw">in</span> mailing_list:        <span class="cmt"># 10,000 jobs, instantly</span>
+    send_email.<span class="def">delay</span>(email)
+
+<span class="cmt"># $ taskito worker --workers 6 --concurrency 8</span>`,
+    demo: {
+      id: "scaling",
+      title: "Worker scaling playground",
+      label: "Open the scaling playground",
+    },
+    guide: { to: "/python/guides/core/workers", label: "Read the guide" },
+  },
+  {
+    id: "deps",
+    q: "Some tasks can't start until earlier ones finish",
+    tag: "Workflows",
+    icon: (
+      <>
+        <circle cx="5" cy="6" r="2.4" />
+        <circle cx="19" cy="6" r="2.4" />
+        <circle cx="12" cy="18" r="2.4" />
+        <path d="M7 7l3.5 9M17 7l-3.5 9" />
+      </>
+    ),
+    title: "Wire them into a workflow and taskito runs them in order",
+    blurb:
+      "Chain tasks in sequence, fan them out in parallel, and join the results. taskito resolves the dependency graph and only starts a step once its inputs are ready.",
+    bullets: [
+      {
+        k: "Sequential",
+        v: "<code>chain()</code> runs steps one after another",
+      },
+      { k: "Parallel", v: "<code>group()</code> fans out independent work" },
+      {
+        k: "Join",
+        v: "<code>chord()</code> collects a group into one callback",
+      },
+    ],
+    code: `workflow = <span class="def">chain</span>(
+    fetch.<span class="def">s</span>(url),
+    parse.<span class="def">s</span>(),
+    <span class="def">group</span>(index.<span class="def">s</span>(), notify.<span class="def">s</span>()),   <span class="cmt"># parallel fan-out</span>
+)
+workflow.<span class="def">delay</span>()`,
+    demo: {
+      id: "workflow",
+      title: "Workflow execution — DAG",
+      label: "Watch the DAG execute",
+    },
+    guide: { to: "/python/guides/workflows", label: "Read the guide" },
+  },
+  {
+    id: "mesh",
+    q: "I need workers spread across many machines or regions",
+    tag: "Mesh scheduling",
+    icon: (
+      <>
+        <circle cx="6" cy="6" r="2.2" />
+        <circle cx="18" cy="6" r="2.2" />
+        <circle cx="6" cy="18" r="2.2" />
+        <circle cx="18" cy="18" r="2.2" />
+        <path d="M8.2 6H16M6 8.2V16M18 8.2V16M8.2 18H16M7.6 7.6l8.8 8.8" />
+      </>
+    ),
+    title: "Run a worker mesh — route each job to the node built for it",
+    blurb:
+      "Because the queue lives in a shared store, any number of worker nodes pull straight from it — there's no broker to coordinate. Tag a job with a routing key and it lands on the pool meant to run it: GPU boxes, a specific region, or a low-priority lane.",
+    bullets: [
+      {
+        k: "Brokerless mesh",
+        v: "every node reads the same store — add machines and they just join",
+      },
+      {
+        k: "Routing keys",
+        v: '<code>queue="gpu"</code> sends a job only to GPU workers',
+      },
+      {
+        k: "Safe coordination",
+        v: "distributed locks stop two nodes grabbing the same job",
+      },
+    ],
+    code: `<span class="fn">@queue.task</span>(queue=<span class="str">"gpu"</span>, max_retries=<span class="num">2</span>)
+<span class="kw">def</span> <span class="def">render</span>(frame):
+    gpu.<span class="def">render</span>(frame)
+
+<span class="cmt"># each machine runs only the pool it is built for:</span>
+<span class="cmt"># $ taskito worker --queues gpu --concurrency 2   # GPU box</span>
+<span class="cmt"># $ taskito worker --queues default,email         # web box</span>`,
+    demo: {
+      id: "mesh",
+      title: "Mesh scheduling — route jobs across the worker mesh",
+      label: "Watch the mesh route",
+    },
+    guide: { to: "/python/guides/operations/mesh", label: "Read the guide" },
+  },
+  {
+    id: "saga",
+    q: "A multi-step process failed and I need to undo earlier steps",
+    tag: "Saga · compensation",
+    icon: (
+      <>
+        <path d="M9 14 4 9l5-5" />
+        <path d="M4 9h11a5 5 0 0 1 0 10h-4" />
+      </>
+    ),
+    title: "Compensate as you go — roll back the steps that already ran",
+    blurb:
+      "Model a distributed transaction as a workflow where every step carries a compensating action. If a later step fails, taskito runs the compensations in reverse order — so a half-finished booking never leaves a charged card or a reserved seat stranded.",
+    bullets: [
+      {
+        k: "Per-step rollback",
+        v: "attach a compensating task to each step",
+      },
+      {
+        k: "Reverse unwind",
+        v: "a failure triggers compensations newest-first",
+      },
+      {
+        k: "No stuck state",
+        v: "the saga ends either fully done or fully undone",
+      },
+    ],
+    code: `saga = <span class="def">chain</span>(
+    reserve_seat.<span class="def">s</span>(trip),  compensate=release_seat.<span class="def">s</span>(),
+    charge_card.<span class="def">s</span>(trip),   compensate=refund_card.<span class="def">s</span>(),
+    book_hotel.<span class="def">s</span>(trip),    compensate=cancel_hotel.<span class="def">s</span>(),
+)
+saga.<span class="def">delay</span>()   <span class="cmt"># any failure → compensations run in reverse</span>`,
+    demo: {
+      id: "saga",
+      title: "Saga — compensation & rollback",
+      label: "Watch the saga roll back",
+    },
+    guide: { to: "/python/guides/workflows/sagas", label: "Read the guide" },
+  },
+  {
+    id: "worksteal",
+    q: "One region is swamped while another sits idle",
+    tag: "Work-stealing",
+    icon: (
+      <>
+        <circle cx="12" cy="12" r="9" />
+        <path d="M3 12h18M12 3a14 14 0 0 1 0 18M12 3a14 14 0 0 0 0 18" />
+      </>
+    ),
+    title: "Idle regions steal the backlog from busy ones — over HTTP",
+    blurb:
+      "Run taskito in several regions and they gossip queue depth peer-to-peer. When one region's backlog spikes, an idle peer pulls a batch of jobs over HTTP and runs them. Load self-balances across the mesh — still with no central broker to stand up.",
+    bullets: [
+      { k: "Gossip mesh", v: "regions share queue depth peer-to-peer" },
+      {
+        k: "Steal over HTTP",
+        v: "an idle region pulls a batch from the busiest peer",
+      },
+      { k: "Self-balancing", v: "load evens out without a coordinator" },
+    ],
+    code: `queue = <span class="def">Queue</span>(db_path=<span class="str">"tasks.db"</span>, region=<span class="str">"eu-west"</span>)
+queue.<span class="def">mesh</span>(peers=[<span class="str">"us-west-2"</span>, <span class="str">"ap-south-1"</span>], steal=<span class="kw">True</span>)
+
+<span class="cmt"># idle workers pull from the busiest peer over HTTP</span>
+<span class="cmt"># $ taskito worker --mesh --steal-threshold 8</span>`,
+    demo: {
+      id: "worksteal",
+      title: "Work-stealing — balance load across regions",
+      label: "Watch regions steal work",
+    },
+    guide: { to: "/python/guides/operations/mesh", label: "Read the guide" },
+  },
+];
+
+/** Wraps a scenario's inner SVG paths in the shared 24×24 stroke frame. */
+function FinderIcon({ children }: { children: React.ReactNode }) {
+  return (
+    <svg
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={1.9}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      {children}
+    </svg>
+  );
+}
+
+const OPTION_ARROW = (
+  <svg
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth={2.4}
+    strokeLinecap="round"
+    strokeLinejoin="round"
+    aria-hidden="true"
+  >
+    <path d="M5 12h14M13 6l6 6-6 6" />
+  </svg>
+);
+
+const CTA_ARROW = (
+  <svg
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth={2.5}
+    strokeLinecap="round"
+    strokeLinejoin="round"
+    aria-hidden="true"
+  >
+    <path d="M5 12h14M13 6l6 6-6 6" />
+  </svg>
+);
+
+function motionDisabled(): boolean {
+  if (typeof document === "undefined") return true;
+  if (document.documentElement.getAttribute("data-motion") === "off")
+    return true;
+  return Boolean(
+    window.matchMedia?.("(prefers-reduced-motion: reduce)").matches,
+  );
+}
+
+/**
+ * "Tell us what's going wrong" — a two-pane problem-picker for first-time
+ * visitors. Left rail = APG tablist of plain-language problems; right = an answer
+ * card (category, headline, three points, snippet, CTAs). React port of
+ * `INTEGRATION-scenario-finder.md`; the primary CTA opens the matching live demo
+ * in {@link DemoModal}, the secondary links the guide that goes deeper.
+ */
+export function ScenarioFinder() {
+  const [selected, setSelected] = useState(0);
+  // Drives the card's enter animation; re-triggered on every selection change.
+  const [entered, setEntered] = useState(true);
+  const [activeDemo, setActiveDemo] = useState<DemoTarget | null>(null);
+  const optionRefs = useRef<(HTMLButtonElement | null)[]>([]);
+
+  useEffect(() => {
+    if (motionDisabled()) {
+      setEntered(true);
+      return;
+    }
+    setEntered(false);
+    const raf = requestAnimationFrame(() => setEntered(true));
+    return () => cancelAnimationFrame(raf);
+  }, []);
+
+  function select(next: number, focus: boolean) {
+    const i = (next + SCENARIOS.length) % SCENARIOS.length;
+    setSelected(i);
+    if (!motionDisabled()) {
+      setEntered(false);
+      requestAnimationFrame(() => setEntered(true));
+    }
+    if (focus) optionRefs.current[i]?.focus();
+  }
+
+  function onKeyDown(e: KeyboardEvent<HTMLButtonElement>, i: number) {
+    switch (e.key) {
+      case "ArrowDown":
+      case "ArrowRight":
+        e.preventDefault();
+        select(i + 1, true);
+        break;
+      case "ArrowUp":
+      case "ArrowLeft":
+        e.preventDefault();
+        select(i - 1, true);
+        break;
+      case "Home":
+        e.preventDefault();
+        select(0, true);
+        break;
+      case "End":
+        e.preventDefault();
+        select(SCENARIOS.length - 1, true);
+        break;
+      default:
+        break;
+    }
+  }
+
+  const active = SCENARIOS[selected];
+
+  return (
+    <section className="section" id="finder">
+      <div className="wrap">
+        <div className="section-head reveal">
+          <div className="kicker">New here?</div>
+          <h2>Tell us what's going wrong</h2>
+          <p>
+            Not sure you need a task queue? Pick the problem that sounds like
+            yours — taskito shows you how it handles it, with the exact code and
+            a live demo you can try.
+          </p>
+        </div>
+
+        <div className="finder reveal">
+          <div className="fd-ask">
+            <div className="fd-asklabel">
+              <span className="fd-pin">?</span>
+              Which sounds like you?
+            </div>
+            <div
+              className="fd-opts"
+              role="tablist"
+              aria-label="Common situations"
+              aria-orientation="vertical"
+            >
+              {SCENARIOS.map((s, i) => (
+                <button
+                  key={s.id}
+                  type="button"
+                  role="tab"
+                  id={`fd-tab-${s.id}`}
+                  className="fd-opt"
+                  aria-selected={i === selected}
+                  aria-controls="fd-panel"
+                  tabIndex={i === selected ? 0 : -1}
+                  ref={(el) => {
+                    optionRefs.current[i] = el;
+                  }}
+                  onClick={() => select(i, false)}
+                  onKeyDown={(e) => onKeyDown(e, i)}
+                >
+                  <span className="fd-optq">{s.q}</span>
+                  <span className="fd-optarr">{OPTION_ARROW}</span>
+                </button>
+              ))}
+            </div>
+            <div className="fd-foot">
+              <span className="fd-dots">
+                <i />
+                <i />
+                <i />
+              </span>
+              Pick a problem — see how taskito handles it.
+            </div>
+          </div>
+
+          <div className="fd-answer">
+            <div
+              id="fd-panel"
+              role="tabpanel"
+              aria-labelledby={`fd-tab-${active.id}`}
+              aria-live="polite"
+              className={`fd-card ${entered ? "fd-in" : "fd-enter"}`}
+            >
+              <div className="fd-cardtop">
+                <span className="fd-ic">
+                  <FinderIcon>{active.icon}</FinderIcon>
+                </span>
+                <div className="fd-said">
+                  <span className="fd-saidlbl">taskito handles this</span>
+                  <span className="fd-tag">{active.tag}</span>
+                </div>
+              </div>
+
+              <h3 className="fd-title">{active.title}</h3>
+              <RawHtml as="p" className="fd-blurb" html={active.blurb} />
+
+              <ul className="fd-bullets">
+                {active.bullets.map((b) => (
+                  <li key={b.k}>
+                    <span className="fd-bk">{b.k}</span>
+                    <RawHtml as="span" className="fd-bv" html={b.v} />
+                  </li>
+                ))}
+              </ul>
+
+              <div className="fd-codewrap">
+                <div className="fd-codebar">
+                  <span className="fd-dot r" />
+                  <span className="fd-dot y" />
+                  <span className="fd-dot g" />
+                  <span className="fd-codefn">tasks.py</span>
+                </div>
+                <RawHtml as="pre" className="fd-code" html={active.code} />
+              </div>
+
+              <div className="fd-cta">
+                <button
+                  type="button"
+                  className="btn pri"
+                  onClick={() =>
+                    setActiveDemo({
+                      id: active.demo.id,
+                      title: active.demo.title,
+                    })
+                  }
+                >
+                  {active.demo.label}
+                  {CTA_ARROW}
+                </button>
+                <Link className="btn sec" to={active.guide.to}>
+                  {active.guide.label}
+                </Link>
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+
+      <DemoModal demo={activeDemo} onClose={() => setActiveDemo(null)} />
+    </section>
+  );
+}
diff --git a/docs/app/components/ui/site-nav.tsx b/docs/app/components/ui/site-nav.tsx
index fdb251ce..f5400e43 100644
--- a/docs/app/components/ui/site-nav.tsx
+++ b/docs/app/components/ui/site-nav.tsx
@@ -1,4 +1,4 @@
-import { Search } from "lucide-react";
+import { Menu, Search } from "lucide-react";
 import { Link } from "react-router";
 import { ThemeToggle } from "@/components/ui/theme-toggle";
 
@@ -25,10 +25,28 @@ const LINKS = [
   { label: "Changelog", href: "/resources/changelog" },
 ];
 
-/** Sticky top navigation, shared by the landing and docs shells. */
-export function SiteNav({ onSearch }: { onSearch?: () => void }) {
+/** Sticky top navigation, shared by the landing and docs shells. `onMenu` is
+ *  passed only by the docs shell — it renders the mobile button that opens the
+ *  sidebar drawer (the landing has no sidebar, so it omits it). */
+export function SiteNav({
+  onSearch,
+  onMenu,
+}: {
+  onSearch?: () => void;
+  onMenu?: () => void;
+}) {
   return (
     <nav className="nav">
+      {onMenu ? (
+        <button
+          type="button"
+          className="menu-btn"
+          onClick={onMenu}
+          aria-label="Open navigation menu"
+        >
+          <Menu size={18} />
+        </button>
+      ) : null}
       <Link to="/" className="brand">
         <span className="logo" aria-hidden="true" />
         <span>
diff --git a/docs/app/lib/nav.ts b/docs/app/lib/nav.ts
index 6485f2e7..93e90e58 100644
--- a/docs/app/lib/nav.ts
+++ b/docs/app/lib/nav.ts
@@ -98,6 +98,7 @@ export const NODE_SECTIONS = [
   "node/guides",
   "architecture",
   "node/api-reference",
+  "node/more/examples",
   "resources",
 ];
 
diff --git a/docs/app/root.tsx b/docs/app/root.tsx
index eaa60842..62b3495d 100644
--- a/docs/app/root.tsx
+++ b/docs/app/root.tsx
@@ -18,7 +18,7 @@ export const links: Route.LinksFunction = () => [
   },
   {
     rel: "stylesheet",
-    href: "https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500;600;700&family=IBM+Plex+Sans:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600;700&family=Shantell+Sans:wght@500;600;700&display=swap",
+    href: "https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500;600;700&family=IBM+Plex+Sans:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600;700&family=Shantell+Sans:wght@500;600;700&display=optional",
   },
 ];
 
diff --git a/docs/app/routes/docs-layout.tsx b/docs/app/routes/docs-layout.tsx
index 9cf853c3..d1042599 100644
--- a/docs/app/routes/docs-layout.tsx
+++ b/docs/app/routes/docs-layout.tsx
@@ -8,10 +8,18 @@ import { forcedSdkForPath } from "@/lib";
 /** Shell for every docs page: top nav + sidebar + article outlet + on-this-page TOC. */
 export default function DocsLayout() {
   const [searchOpen, setSearchOpen] = useState(false);
+  const [navOpen, setNavOpen] = useState(false);
   const { pathname } = useLocation();
   const { setSdk } = useSdk();
   const sdk = useActiveSdk();
 
+  // Close the mobile sidebar drawer whenever the route changes (i.e. a nav link
+  // was tapped) so it never lingers over the freshly-loaded page.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: close on navigation
+  useEffect(() => {
+    setNavOpen(false);
+  }, [pathname]);
+
   // Visiting an SDK-specific page (`/python/*`,`/node/*`) makes that SDK sticky,
   // so walking onto a shared page keeps the choice. No-op on shared pages.
   useEffect(() => {
@@ -34,9 +42,16 @@ export default function DocsLayout() {
   }, []);
   return (
     <>
-      <SiteNav onSearch={() => setSearchOpen(true)} />
+      <SiteNav
+        onSearch={() => setSearchOpen(true)}
+        onMenu={() => setNavOpen(true)}
+      />
       <div className="docs-shell">
-        <Sidebar onSearch={() => setSearchOpen(true)} />
+        <Sidebar
+          open={navOpen}
+          onClose={() => setNavOpen(false)}
+          onSearch={() => setSearchOpen(true)}
+        />
         <Outlet />
         <Toc />
       </div>
diff --git a/docs/app/routes/docs.$.tsx b/docs/app/routes/docs.$.tsx
index 5c457197..3c871edf 100644
--- a/docs/app/routes/docs.$.tsx
+++ b/docs/app/routes/docs.$.tsx
@@ -104,9 +104,16 @@ export default function DocRoute({ params }: Route.ComponentProps) {
       <MDXProvider components={mdxComponents}>
         {/* Key by path: client-side navigation between two pages that share this
             splat route re-suspends the lazy page. Without a fresh boundary per
-            path, React retains the previous committed tree for the whole route
-            during the navigation transition and never swaps in the new page. */}
-        <Suspense key={path} fallback={null}>
+            path, React retains the previous committed tree for the whole route.
+
+            React.lazy has no SSR hydration: on the client the chunk re-loads, so
+            the prerendered body briefly drops to the fallback and re-expands.
+            Reserve vertical space so that swap doesn't shove the prev/next footer
+            up and down (layout shift). */}
+        <Suspense
+          key={path}
+          fallback={<div className="doc-loading" aria-hidden="true" />}
+        >
           <Page />
         </Suspense>
       </MDXProvider>
diff --git a/docs/app/routes/home.tsx b/docs/app/routes/home.tsx
index 86a91b4d..ce8bcc96 100644
--- a/docs/app/routes/home.tsx
+++ b/docs/app/routes/home.tsx
@@ -8,6 +8,7 @@ import {
   Hero,
   HowItWorks,
   Integrations,
+  ScenarioFinder,
   UseCases,
   useReveal,
 } from "@/components/landing";
@@ -53,6 +54,7 @@ export default function Home() {
       <SiteNav onSearch={() => setSearchOpen(true)} />
       <main>
         <Hero />
+        <ScenarioFinder />
         <HowItWorks />
         <Features />
         <UseCases />
diff --git a/docs/app/styles/docs.css b/docs/app/styles/docs.css
index 3b150dd9..ebe53c60 100644
--- a/docs/app/styles/docs.css
+++ b/docs/app/styles/docs.css
@@ -217,6 +217,11 @@ body {
   min-width: 0;
   max-width: 840px;
 }
+/* Reserve vertical space while a lazily-loaded page chunk re-resolves on
+   hydration, so the prev/next footer below it doesn't shift (CLS). */
+.doc-loading {
+  min-height: 70vh;
+}
 .crumb {
   display: flex;
   align-items: center;
@@ -1048,6 +1053,36 @@ body {
 /* mobile */
 .menu-btn {
   display: none;
+  width: 38px;
+  height: 38px;
+  margin-right: 2px;
+  place-items: center;
+  border: 1px solid var(--line2);
+  border-radius: 10px;
+  background: var(--panel);
+  color: var(--txt);
+  cursor: pointer;
+  transition:
+    color 0.2s,
+    border-color 0.2s;
+}
+.menu-btn:hover {
+  border-color: var(--line3);
+}
+/* Backdrop behind the mobile drawer — only visible while the drawer is open. */
+.sidebar-backdrop {
+  display: none;
+  position: fixed;
+  inset: 0;
+  z-index: 60;
+  border: 0;
+  padding: 0;
+  background: color-mix(in oklch, var(--bg) 55%, transparent);
+  -webkit-backdrop-filter: blur(3px);
+  backdrop-filter: blur(3px);
+  cursor: pointer;
+  opacity: 0;
+  transition: opacity 0.2s ease;
 }
 @media (max-width: 1180px) {
   .docs-shell {
@@ -1061,18 +1096,56 @@ body {
   .docs-shell {
     grid-template-columns: 1fr;
   }
-  .sidebar {
-    display: none;
-  }
   .article {
     padding: 32px 22px 72px;
   }
   .menu-btn {
     display: grid;
   }
+  /* Drawer nav reads a touch tighter than the desktop sidebar. */
+  .nav-item {
+    font-size: 13px;
+  }
   .next-grid {
     grid-template-columns: 1fr;
   }
+  /* Sidebar becomes an off-canvas drawer: hidden by default, slid in when open. */
+  .sidebar {
+    position: fixed;
+    top: 0;
+    left: 0;
+    z-index: 70;
+    width: min(310px, 84vw);
+    height: 100dvh;
+    margin: 0;
+    padding-top: 24px;
+    background: var(--bg);
+    border-right: 1px solid var(--line2);
+    box-shadow: var(--shadow-lg);
+    transform: translateX(-100%);
+    /* Hide off-canvas so closed-drawer links leave the tab order; the
+       visibility flip is delayed until the slide-out finishes. */
+    visibility: hidden;
+    transition:
+      transform 0.24s cubic-bezier(0.2, 0.6, 0.2, 1),
+      visibility 0s linear 0.24s;
+  }
+  .sidebar.open {
+    transform: none;
+    visibility: visible;
+    transition:
+      transform 0.24s cubic-bezier(0.2, 0.6, 0.2, 1),
+      visibility 0s;
+  }
+  .sidebar-backdrop.open {
+    display: block;
+    opacity: 1;
+  }
+}
+@media (max-width: 860px) and (prefers-reduced-motion: reduce) {
+  .sidebar {
+    transition: none;
+  }
 }
 
 /* Error boundary fallback */
@@ -1118,6 +1191,19 @@ body {
 .gt-toggle:hover {
   color: var(--txt);
 }
+/* Subsection label is a toggle button (collapses/expands its children on click,
+   like a top-level group) — reset the native button chrome to match .nav-item. */
+.nav-sub-toggle {
+  appearance: none;
+  border: 0;
+  background: transparent;
+  /* family only — keep .nav-item's 13px (the `font` shorthand would reset size
+     to the larger inherited value, making toggles bigger than leaf links). */
+  font-family: inherit;
+  font-weight: inherit;
+  text-align: left;
+  cursor: pointer;
+}
 .nav-subsection {
   margin: 2px 0;
 }
diff --git a/docs/app/styles/landing.css b/docs/app/styles/landing.css
index b7e55e07..82aceb07 100644
--- a/docs/app/styles/landing.css
+++ b/docs/app/styles/landing.css
@@ -167,6 +167,13 @@ main {
   transform: translateX(3px);
 }
 
+/* Grid items must be allowed to shrink below their content's intrinsic width,
+   else the terminal's `white-space: pre` code + the language tab row blow the
+   1fr track past the viewport (horizontal overflow on mobile). */
+.hero .left,
+.hero .right {
+  min-width: 0;
+}
 .right {
   display: flex;
   flex-direction: column;
@@ -266,6 +273,8 @@ main {
   white-space: pre;
   min-height: 296px;
   tab-size: 4;
+  /* Long lines scroll within the terminal instead of being clipped on mobile. */
+  overflow-x: auto;
 }
 .code .cur {
   display: inline-block;
@@ -329,6 +338,15 @@ main {
   padding: 9px 11px;
   border-bottom: 1px solid var(--line);
   background: color-mix(in oklch, var(--panel) 65%, #000);
+  /* The tab row scrolls on narrow screens rather than widening the terminal. */
+  overflow-x: auto;
+  scrollbar-width: none;
+}
+.langtabs::-webkit-scrollbar {
+  display: none;
+}
+.langtab {
+  flex: none;
 }
 [data-theme="light"] .langtabs {
   background: var(--panel2);
@@ -1356,3 +1374,566 @@ main {
 .twk-seg button[data-on="1"] .fn {
   color: var(--indigo-br);
 }
+
+/* ============================================================
+   Scenario finder — "Tell us what's going wrong" problem-picker.
+   Ported from INTEGRATION-scenario-finder.md §4. All selectors are
+   namespaced .finder / .fd-* (no collisions). Code-token colors
+   (.kw/.def/.str/.num/.cmt/.fn) come from atoms.css.
+   ============================================================ */
+.finder {
+  display: grid;
+  grid-template-columns: 0.92fr 1.08fr;
+  gap: 18px;
+  align-items: start;
+}
+/* Both panes must shrink below their content's intrinsic width so the snippet
+   (`white-space: pre`) and CTA buttons never widen the track past the viewport. */
+.fd-ask,
+.fd-answer {
+  min-width: 0;
+}
+.fd-ask {
+  background: var(--panel);
+  border: 1px solid var(--line2);
+  border-radius: 18px;
+  padding: 20px;
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+  position: sticky;
+  top: 84px;
+}
+.fd-asklabel {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  font-size: 14.5px;
+  font-weight: 600;
+  color: var(--txt);
+  letter-spacing: -0.01em;
+}
+.fd-pin {
+  width: 24px;
+  height: 24px;
+  flex: none;
+  border-radius: 8px;
+  display: grid;
+  place-items: center;
+  font-family: var(--mono);
+  font-size: 14px;
+  font-weight: 700;
+  color: var(--indigo-br);
+  background: var(--indigo-soft);
+  border: 1px solid var(--indigo-line);
+}
+.fd-opts {
+  display: flex;
+  flex-direction: column;
+  gap: 9px;
+}
+.fd-opt {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  text-align: left;
+  cursor: pointer;
+  padding: 14px;
+  border-radius: 12px;
+  border: 1px solid var(--line2);
+  background: var(--panel2);
+  transition:
+    border-color 0.18s,
+    background 0.18s,
+    transform 0.12s;
+}
+.fd-opt:hover {
+  border-color: var(--line3);
+  transform: translateX(2px);
+}
+.fd-optq {
+  flex: 1;
+  font-size: 14.5px;
+  line-height: 1.4;
+  color: var(--txt2);
+  font-weight: 500;
+}
+.fd-optarr {
+  flex: none;
+  width: 26px;
+  height: 26px;
+  border-radius: 8px;
+  display: grid;
+  place-items: center;
+  color: var(--dim);
+  border: 1px solid transparent;
+  transition:
+    color 0.18s,
+    background 0.18s,
+    border-color 0.18s;
+}
+.fd-optarr svg {
+  width: 15px;
+  height: 15px;
+}
+.fd-opt:hover .fd-optarr {
+  color: var(--mut);
+}
+.fd-opt[aria-selected="true"] {
+  border-color: var(--indigo-line);
+  background: linear-gradient(180deg, var(--indigo-soft), var(--panel2));
+}
+.fd-opt[aria-selected="true"] .fd-optq {
+  color: var(--txt);
+}
+.fd-opt[aria-selected="true"] .fd-optarr {
+  color: var(--indigo-br);
+  background: var(--indigo-soft);
+  border-color: var(--indigo-line);
+}
+.fd-foot {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  font-family: var(--mono);
+  font-size: 11.5px;
+  color: var(--dim);
+  border-top: 1px dashed var(--line2);
+  padding-top: 13px;
+  line-height: 1.4;
+}
+.fd-dots {
+  display: inline-flex;
+  gap: 4px;
+  flex: none;
+}
+.fd-dots i {
+  width: 5px;
+  height: 5px;
+  border-radius: 50%;
+  background: var(--indigo);
+  opacity: 0.4;
+}
+.fd-dots i:nth-child(2) {
+  opacity: 0.7;
+}
+.fd-dots i:nth-child(3) {
+  opacity: 1;
+}
+
+.fd-answer {
+  min-height: 420px;
+}
+.fd-card {
+  background: linear-gradient(180deg, var(--panel), var(--panel2));
+  border: 1px solid var(--line2);
+  border-radius: 18px;
+  padding: 24px 24px 22px;
+  box-shadow:
+    var(--shadow-md),
+    0 0 0 1px var(--line);
+  position: relative;
+  overflow: hidden;
+}
+.fd-card::before {
+  content: "";
+  position: absolute;
+  top: 0;
+  right: 0;
+  width: 200px;
+  height: 200px;
+  background: radial-gradient(
+    circle at top right,
+    var(--indigo-soft),
+    transparent 70%
+  );
+  opacity: 0.7;
+  pointer-events: none;
+}
+.fd-card > * {
+  position: relative;
+}
+.fd-cardtop {
+  display: flex;
+  align-items: center;
+  gap: 13px;
+  margin-bottom: 16px;
+}
+.fd-ic {
+  width: 46px;
+  height: 46px;
+  flex: none;
+  border-radius: 12px;
+  display: grid;
+  place-items: center;
+  background: var(--indigo-soft);
+  border: 1px solid var(--indigo-line);
+  color: var(--indigo-br);
+}
+.fd-ic svg {
+  width: 23px;
+  height: 23px;
+}
+.fd-said {
+  display: flex;
+  flex-direction: column;
+  gap: 3px;
+}
+.fd-saidlbl {
+  font-family: var(--mono);
+  font-size: 10px;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--grn);
+}
+.fd-tag {
+  font-size: 15px;
+  font-weight: 600;
+  color: var(--txt);
+  letter-spacing: -0.01em;
+}
+.fd-title {
+  font-size: 21px;
+  line-height: 1.18;
+  letter-spacing: -0.02em;
+  font-weight: 600;
+  color: var(--txt);
+  text-wrap: balance;
+}
+.fd-blurb {
+  margin-top: 11px;
+  font-size: 14.5px;
+  line-height: 1.6;
+  color: var(--mut);
+}
+.fd-blurb code,
+.fd-bv code {
+  font-family: var(--mono);
+  font-size: 0.86em;
+  background: var(--panel3);
+  padding: 1px 5px;
+  border-radius: 5px;
+  color: var(--txt2);
+  border: 1px solid var(--line);
+}
+.fd-bullets {
+  list-style: none;
+  margin: 18px 0 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 11px;
+}
+.fd-bullets li {
+  display: flex;
+  gap: 12px;
+  align-items: baseline;
+}
+.fd-bk {
+  flex: none;
+  width: 118px;
+  font-family: var(--mono);
+  font-size: 11.5px;
+  font-weight: 600;
+  color: var(--indigo-br);
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+.fd-bk::before {
+  content: "";
+  width: 6px;
+  height: 6px;
+  border-radius: 2px;
+  background: var(--indigo);
+  flex: none;
+}
+.fd-bv {
+  font-size: 13.5px;
+  line-height: 1.5;
+  color: var(--txt2);
+}
+.fd-codewrap {
+  margin-top: 20px;
+  border: 1px solid var(--line2);
+  border-radius: 12px;
+  overflow: hidden;
+  background: var(--bg-soft);
+}
+.fd-codebar {
+  display: flex;
+  align-items: center;
+  gap: 7px;
+  padding: 9px 13px;
+  border-bottom: 1px solid var(--line);
+  background: color-mix(in oklch, var(--panel) 60%, #000);
+}
+[data-theme="light"] .fd-codebar {
+  background: var(--panel2);
+}
+.fd-dot {
+  width: 9px;
+  height: 9px;
+  border-radius: 50%;
+}
+.fd-dot.r {
+  background: #ff5f57;
+}
+.fd-dot.y {
+  background: #febc2e;
+}
+.fd-dot.g {
+  background: #28c840;
+}
+.fd-codefn {
+  margin-left: 6px;
+  font-family: var(--mono);
+  font-size: 11.5px;
+  color: var(--mut);
+}
+.fd-code {
+  font-family: var(--code);
+  font-size: 13px;
+  line-height: 1.72;
+  padding: 15px 16px;
+  white-space: pre;
+  overflow-x: auto;
+  color: var(--txt);
+  margin: 0;
+  tab-size: 4;
+}
+.fd-code::-webkit-scrollbar {
+  height: 7px;
+}
+.fd-code::-webkit-scrollbar-thumb {
+  background: var(--line3);
+  border-radius: 7px;
+}
+.fd-cta {
+  display: flex;
+  gap: 11px;
+  margin-top: 20px;
+  flex-wrap: wrap;
+}
+.fd-cta .btn {
+  font-size: 13.5px;
+  padding: 10px 16px;
+}
+.fd-enter {
+  opacity: 0;
+  transform: translateY(12px);
+}
+.fd-in {
+  opacity: 1;
+  transform: none;
+  transition:
+    opacity 0.42s cubic-bezier(0.2, 0.6, 0.2, 1),
+    transform 0.42s cubic-bezier(0.2, 0.6, 0.2, 1);
+}
+@media (max-width: 860px) {
+  .finder {
+    grid-template-columns: 1fr;
+    gap: 14px;
+  }
+  .fd-ask {
+    position: static;
+  }
+  .fd-answer {
+    min-height: 0;
+  }
+  .fd-bk {
+    width: 100px;
+  }
+}
+@media (prefers-reduced-motion: reduce) {
+  .fd-in {
+    transition: none;
+  }
+}
+
+/* ============================================================
+   Demo modal — opens a finder scenario's live demo in an iframe.
+   Ported from INTEGRATION-scenario-finder.md §6 (.dm-* namespace).
+   ============================================================ */
+.dm-overlay {
+  position: fixed;
+  inset: 0;
+  z-index: 9000;
+  display: none;
+  align-items: center;
+  justify-content: center;
+  padding: 24px;
+}
+.dm-overlay.open {
+  display: flex;
+}
+.dm-backdrop {
+  position: absolute;
+  inset: 0;
+  border: 0;
+  padding: 0;
+  cursor: pointer;
+  background: color-mix(in oklch, var(--bg) 64%, transparent);
+  -webkit-backdrop-filter: blur(7px);
+  backdrop-filter: blur(7px);
+}
+.dm-dialog {
+  position: relative;
+  width: min(1060px, 95vw);
+  height: min(86vh, 880px);
+  display: flex;
+  flex-direction: column;
+  background: var(--bg);
+  border: 1px solid var(--line2);
+  border-radius: 18px;
+  overflow: hidden;
+  box-shadow:
+    var(--shadow-lg),
+    0 0 0 1px var(--line);
+  transform: translateY(12px) scale(0.985);
+  opacity: 0;
+  transition:
+    transform 0.26s cubic-bezier(0.2, 0.6, 0.2, 1),
+    opacity 0.26s;
+}
+.dm-overlay.open .dm-dialog {
+  transform: none;
+  opacity: 1;
+}
+.dm-bar {
+  display: flex;
+  align-items: center;
+  gap: 13px;
+  padding: 13px 13px 13px 18px;
+  border-bottom: 1px solid var(--line);
+  background: var(--panel);
+}
+.dm-mark {
+  flex: none;
+  width: 30px;
+  height: 30px;
+  border-radius: 9px;
+  display: grid;
+  place-items: center;
+  background: var(--indigo-soft);
+  border: 1px solid var(--indigo-line);
+  color: var(--indigo-br);
+}
+.dm-mark svg {
+  width: 16px;
+  height: 16px;
+}
+.dm-meta {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  min-width: 0;
+}
+.dm-eyebrow {
+  font-family: var(--mono);
+  font-size: 10px;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--grn);
+}
+.dm-title {
+  font-size: 14.5px;
+  font-weight: 600;
+  color: var(--txt);
+  letter-spacing: -0.01em;
+  line-height: 1.2;
+}
+.dm-actions {
+  margin-left: auto;
+  display: flex;
+  gap: 8px;
+  align-items: center;
+}
+.dm-x {
+  appearance: none;
+  border: 1px solid var(--line2);
+  background: var(--panel2);
+  color: var(--mut);
+  width: 34px;
+  height: 34px;
+  border-radius: 9px;
+  cursor: pointer;
+  display: grid;
+  place-items: center;
+  transition:
+    color 0.15s,
+    border-color 0.15s,
+    background 0.15s;
+}
+.dm-x:hover {
+  color: var(--txt);
+  border-color: var(--line3);
+  background: var(--panel3);
+}
+.dm-x svg {
+  width: 16px;
+  height: 16px;
+}
+.dm-stage {
+  flex: 1;
+  position: relative;
+  background: var(--bg);
+  min-height: 0;
+}
+.dm-frame {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  border: 0;
+  background: var(--bg);
+}
+.dm-loading {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 11px;
+  font-family: var(--mono);
+  font-size: 12.5px;
+  color: var(--mut);
+  background: var(--bg);
+  transition: opacity 0.3s;
+}
+.dm-loading.hide {
+  opacity: 0;
+  pointer-events: none;
+}
+.dm-spin {
+  width: 16px;
+  height: 16px;
+  border-radius: 50%;
+  border: 2px solid var(--line3);
+  border-top-color: var(--indigo-br);
+  animation: dmspin 0.7s linear infinite;
+}
+@keyframes dmspin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+@media (prefers-reduced-motion: reduce) {
+  .dm-dialog {
+    transition: none;
+  }
+  .dm-spin {
+    animation: none;
+  }
+}
+@media (max-width: 600px) {
+  .dm-overlay {
+    padding: 0;
+  }
+  .dm-dialog {
+    width: 100vw;
+    height: 100vh;
+    border-radius: 0;
+    border: 0;
+  }
+}
diff --git a/docs/biome.json b/docs/biome.json
index 5932a5d0..970c64e0 100644
--- a/docs/biome.json
+++ b/docs/biome.json
@@ -7,7 +7,14 @@
   },
   "files": {
     "ignoreUnknown": true,
-    "includes": ["**", "!node_modules", "!build", "!.react-router", "!content"]
+    "includes": [
+      "**",
+      "!node_modules",
+      "!build",
+      "!.react-router",
+      "!content",
+      "!public/demos"
+    ]
   },
   "formatter": {
     "enabled": true,
diff --git a/docs/content/docs/node/more/examples/benchmark.mdx b/docs/content/docs/node/more/examples/benchmark.mdx
new file mode 100644
index 00000000..31347690
--- /dev/null
+++ b/docs/content/docs/node/more/examples/benchmark.mdx
@@ -0,0 +1,87 @@
+---
+title: Benchmark
+description: "A self-contained throughput script: measure enqueue rate, processing rate, and end-to-end latency on your own hardware."
+---
+
+Numbers depend heavily on your machine, backend, and task body, so the only
+number that matters is the one you measure. This script stages a batch of no-op
+jobs, drains them with a worker, and reports the three rates that bound a queue.
+
+## benchmark.ts
+
+```ts
+import { Queue } from "taskito";
+
+const N = 50_000;
+const queue = new Queue({ dbPath: "bench.db" });
+
+queue.task("noop", (_n: number) => undefined);
+
+// 1. Enqueue throughput — stage N jobs in batches of 1,000.
+const t0 = Date.now();
+for (let i = 0; i < N; i += 1_000) {
+  queue.enqueueMany("noop", Array.from({ length: 1_000 }, (_, k) => ({ args: [i + k] })));
+}
+const enqueueMs = Date.now() - t0;
+
+// 2. Processing throughput — drain the backlog, polling stats until empty.
+const t1 = Date.now();
+const worker = queue.runWorker({ queues: ["default"], batchSize: 64, channelCapacity: 512 });
+while (queue.stats().complete < N) {
+  await new Promise((r) => setTimeout(r, 20));
+}
+const processMs = Date.now() - t1;
+worker.stop();
+
+// 3. End-to-end latency — created → completed across a sample of jobs.
+const sample = queue.listJobs({ status: "complete", limit: 1_000 });
+const latencies = sample
+  .filter((j) => j.completedAt)
+  .map((j) => (j.completedAt as number) - j.createdAt)
+  .sort((a, b) => a - b);
+const p50 = latencies[Math.floor(latencies.length * 0.5)];
+const p99 = latencies[Math.floor(latencies.length * 0.99)];
+
+console.log(`enqueue:  ${Math.round(N / (enqueueMs / 1000))} jobs/s`);
+console.log(`process:  ${Math.round(N / (processMs / 1000))} jobs/s`);
+console.log(`latency:  p50 ${p50}ms  p99 ${p99}ms`);
+```
+
+## Running it
+
+```bash
+node benchmark.ts
+```
+
+Sample output (illustrative — measure your own):
+
+```
+enqueue:  120000 jobs/s
+process:  35000 jobs/s
+latency:  p50 8ms  p99 42ms
+```
+
+## What drives the numbers
+
+| Lever | Effect |
+| --- | --- |
+| `enqueueMany` | one storage round-trip per batch instead of per job |
+| `batchSize` | jobs claimed per scheduler poll — fewer polls under load |
+| `channelCapacity` | in-flight buffer between the scheduler and the worker |
+| Backend | SQLite (WAL) for a single node; Postgres/Redis to scale out workers |
+| Task body | a real handler's I/O usually dominates — benchmark *your* task too |
+
+<Callout type="info">
+  The hot path is the Rust core — enqueue, dequeue, and result handling never
+  touch the JS event loop except to run your handler. Raise `batchSize` and
+  `channelCapacity` together to keep a busy worker saturated.
+</Callout>
+
+## Key patterns
+
+| Pattern | Where |
+| --- | --- |
+| Batched staging | `queue.enqueueMany` |
+| Drain to a target | poll `queue.stats().complete` |
+| Worker throughput knobs | `runWorker({ batchSize, channelCapacity })` |
+| Latency percentiles | `listJobs` + `completedAt - createdAt` |
diff --git a/docs/content/docs/node/more/examples/bulk-emails.mdx b/docs/content/docs/node/more/examples/bulk-emails.mdx
new file mode 100644
index 00000000..586ea5f3
--- /dev/null
+++ b/docs/content/docs/node/more/examples/bulk-emails.mdx
@@ -0,0 +1,103 @@
+---
+title: Bulk emails
+description: "Fan a large recipient list out with enqueueMany, then bound the send rate and concurrency with per-task limits."
+---
+
+Sending to a large list is an enqueue-throughput problem: stage every message as
+its own job in as few round-trips as possible, then let per-task limits pace the
+actual sends so you stay within your provider's quota.
+
+<Callout type="info">
+  The Node SDK has no implicit task-batching (the Python SDK's `batch=` collector
+  is Python-specific). The idiomatic Node approach is **batch enqueue**
+  (`enqueueMany`) plus per-task `maxConcurrent` / `rateLimit` — one job per
+  message, with the worker doing the pacing.
+</Callout>
+
+## tasks.ts
+
+One job per recipient keeps retries and failures isolated — a bad address never
+blocks the rest. The limits cap how fast and how many run at once.
+
+```ts
+import { Queue } from "taskito";
+
+export const queue = new Queue({ dbPath: "bulk-email.db" });
+
+queue.task("sendEmail", async (to: string, subject: string, body: string) => {
+  await provider.send(to, subject, body);
+}, {
+  rateLimit: "600/m",     // stay under the provider's quota
+  maxConcurrent: 20,      // at most 20 in flight at once
+  maxRetries: 5,
+  retryBackoff: { baseMs: 2_000, maxMs: 300_000 },
+});
+```
+
+## send.ts
+
+`enqueueMany` stages a whole chunk in a single storage round-trip. Chunk a very
+large list so each call stays a reasonable size.
+
+```ts
+import { queue } from "./tasks";
+
+function* chunks<T>(items: T[], size: number) {
+  for (let i = 0; i < items.length; i += size) {
+    yield items.slice(i, i + size);
+  }
+}
+
+export function sendCampaign(recipients: string[], subject: string, body: string) {
+  const ids: string[] = [];
+  for (const chunk of chunks(recipients, 1_000)) {
+    ids.push(...queue.enqueueMany("sendEmail", chunk.map((to) => ({
+      args: [to, subject, body],
+    }))));
+  }
+  return ids; // one job id per recipient
+}
+```
+
+<Callout type="warn">
+  `enqueueMany` does not apply `uniqueKey` dedup — the batch path trades
+  idempotency for throughput. If you must not double-send, dedup the recipient
+  list before enqueueing, or use single `enqueue` calls with a `uniqueKey`.
+</Callout>
+
+## Monitoring the send
+
+Watch the backlog drain and catch addresses that exhausted their retries.
+
+```ts
+console.log(queue.statsByQueue("default")); // { pending, running, complete, failed, dead, cancelled }
+
+for (const dead of queue.deadLetters(50)) {
+  console.warn(`gave up on ${dead.taskName}: ${dead.error}`);
+}
+```
+
+## Running it
+
+<Tabs items={["Terminal 1 — Worker", "Terminal 2 — Send"]}>
+  <Tab value="Terminal 1 — Worker">
+    ```bash
+    node worker.ts   # registers sendEmail, runWorker()
+    ```
+  </Tab>
+  <Tab value="Terminal 2 — Send">
+    ```bash
+    node -e "const list=['a@example.com','b@example.com']; import('./send.ts').then(s => s.sendCampaign(list, 'Launch', '<html>'))"
+    ```
+  </Tab>
+</Tabs>
+
+## Key patterns
+
+| Pattern | Where |
+| --- | --- |
+| One round-trip per chunk | `queue.enqueueMany` |
+| Provider quota | `task(..., { rateLimit })` |
+| Concurrency cap | `task(..., { maxConcurrent })` |
+| Isolated failures | one job per recipient |
+| Drain + failure visibility | `statsByQueue` + `deadLetters` |
diff --git a/docs/content/docs/node/more/examples/data-pipeline.mdx b/docs/content/docs/node/more/examples/data-pipeline.mdx
new file mode 100644
index 00000000..fbaad270
--- /dev/null
+++ b/docs/content/docs/node/more/examples/data-pipeline.mdx
@@ -0,0 +1,135 @@
+---
+title: ETL data pipeline
+description: "A diamond-shaped extract → transform → load DAG with progress reporting, error inspection, and skip-on-failure cascading."
+---
+
+A classic ETL job: pull rows from a source, run two independent transforms over
+the staged data, then load the merged result. Modeling it as a workflow gives you
+dependency ordering, per-step retries, and a queryable run you can monitor.
+
+<Mermaid
+  chart={`graph LR
+    extract:::source --> clean
+    extract --> enrich
+    clean --> load:::sink
+    enrich --> load
+    classDef source fill:#1f6feb,color:#fff
+    classDef sink fill:#238636,color:#fff`}
+/>
+
+## Project structure
+
+```
+pipeline/
+  pipeline.ts  # the four tasks + the DAG
+  monitor.ts   # analyze + inspect a run
+  worker.ts    # the worker process
+```
+
+## pipeline.ts
+
+Each step coordinates through a staging store (the DB, S3, a temp dir) rather than
+passing results down the graph — the standard ETL shape. `load` runs only after
+both transforms complete. The long transform reports progress as it goes.
+
+```ts
+import { Queue, currentJob } from "taskito";
+
+export const queue = new Queue({ dbPath: "pipeline.db" });
+
+queue.task("extract", async (runId: string) => {
+  const rows = await source.read();
+  await staging.write(runId, "raw", rows);
+}, { maxRetries: 3 });
+
+queue.task("clean", async (runId: string) => {
+  const rows = await staging.read(runId, "raw");
+  const job = currentJob();
+  const out = [];
+  for (let i = 0; i < rows.length; i++) {
+    out.push(normalize(rows[i]));
+    if (i % 1000 === 0) job?.setProgress(Math.round((i / rows.length) * 100));
+  }
+  await staging.write(runId, "clean", out);
+});
+
+queue.task("enrich", async (runId: string) => {
+  const rows = await staging.read(runId, "raw");
+  await staging.write(runId, "enrich", await enrichAll(rows));
+}, { rateLimit: "200/m" }); // enrichment calls a metered API
+
+queue.task("load", async (runId: string) => {
+  const merged = merge(
+    await staging.read(runId, "clean"),
+    await staging.read(runId, "enrich"),
+  );
+  await warehouse.load(merged);
+});
+
+export function runPipeline(runId: string) {
+  return queue.workflows
+    .define("etl", 1)
+    .step("extract", "extract", { args: [runId] })
+    .step("clean", "clean", { args: [runId], after: "extract" })
+    .step("enrich", "enrich", { args: [runId], after: "extract", queue: "io" })
+    .step("load", "load", { args: [runId], after: ["clean", "enrich"], priority: 10 })
+    .submit({ queueDefault: "default", params: { runId } });
+}
+```
+
+## monitor.ts
+
+`analyze` gives you a structural view of the run; `getJobErrors` surfaces the
+failure history of any step's underlying job.
+
+```ts
+import { queue } from "./pipeline";
+
+export function report(runId: string) {
+  const analysis = queue.workflows.analyze(runId);
+  if (!analysis) return;
+
+  console.log("critical path:", analysis.criticalPath().join(" → "));
+  console.log("stats:", analysis.stats());
+
+  // Inspect the failure history of a specific step.
+  const node = analysis.node("enrich");
+  if (node?.jobId) {
+    for (const err of queue.getJobErrors(node.jobId)) {
+      console.log(`enrich attempt ${err.attempt}: ${err.error}`);
+    }
+  }
+}
+```
+
+<Callout type="warn">
+  If a required step fails, its still-pending dependents are skipped and the run
+  ends `completed_with_failures` (or `failed`). Add a `condition: "on_failure"`
+  step after the at-risk node to run cleanup or alerting on that path.
+</Callout>
+
+## Running it
+
+<Tabs items={["Terminal 1 — Worker", "Terminal 2 — Run"]}>
+  <Tab value="Terminal 1 — Worker">
+    ```bash
+    node worker.ts   # runWorker({ queues: ["default", "io"] })
+    ```
+  </Tab>
+  <Tab value="Terminal 2 — Run">
+    ```bash
+    node -e "import('./pipeline.ts').then(p => p.runPipeline(crypto.randomUUID()))"
+    ```
+  </Tab>
+</Tabs>
+
+## Key patterns
+
+| Pattern | Where |
+| --- | --- |
+| Diamond dependency DAG | `.step(..., { after })` |
+| Per-step queue / priority | `step` options |
+| Progress reporting | `currentJob().setProgress` |
+| Structural analysis | `workflows.analyze().criticalPath()` |
+| Per-attempt error history | `queue.getJobErrors` |
+| Skip-on-failure cascade | required step failure ⇒ pending dependents skipped |
diff --git a/docs/content/docs/node/more/examples/express-service.mdx b/docs/content/docs/node/more/examples/express-service.mdx
new file mode 100644
index 00000000..13fde123
--- /dev/null
+++ b/docs/content/docs/node/more/examples/express-service.mdx
@@ -0,0 +1,173 @@
+---
+title: Express image service
+description: "A REST API that enqueues image jobs, streams progress to the browser over SSE, and cancels work in flight."
+---
+
+A thin Express front end accepts upload requests, enqueues a Taskito job, and
+hands back a job id immediately. The browser then follows progress over
+server-sent events (SSE) fed by the task's published partial results, and can
+cancel a running job.
+
+## Project structure
+
+```
+image-service/
+  app.ts       # Express app + queue + the processImage task
+  worker.ts    # the worker process
+  client.html  # a browser page that streams progress
+```
+
+## app.ts
+
+The task reports progress with `currentJob()` — `setProgress` for the dashboard,
+`publish` for the live stream — and checks `signal.aborted` between stages so a
+cancel request stops it cleanly.
+
+```ts
+import express from "express";
+import { Queue, currentJob } from "taskito";
+
+const queue = new Queue({ dbPath: "image-service.db" });
+
+queue.task(
+  "processImage",
+  async (url: string, sizes: number[]) => {
+    const job = currentJob();
+    const variants: { size: number; key: string }[] = [];
+
+    for (let i = 0; i < sizes.length; i++) {
+      if (job?.signal.aborted) {
+        throw new Error("cancelled before completion");
+      }
+      const size = sizes[i];
+      await resize(url, size); // your real work here
+      const variant = { size, key: `${url}@${size}.webp` };
+      variants.push(variant);
+
+      job?.setProgress(Math.round(((i + 1) / sizes.length) * 100));
+      job?.publish({ done: i + 1, total: sizes.length, variant });
+    }
+    return variants;
+  },
+  { maxRetries: 2, timeoutMs: 120_000 },
+);
+
+const app = express();
+app.use(express.json());
+
+// Enqueue and return the job id immediately.
+app.post("/images", (req, res) => {
+  const { url, sizes } = req.body as { url: string; sizes: number[] };
+  const id = queue.enqueue("processImage", [url, sizes], { priority: 5 });
+  res.status(202).json({ jobId: id });
+});
+
+// Poll a job's terminal result.
+app.get("/images/:id", (req, res) => {
+  const job = queue.getJob(req.params.id);
+  if (!job) {
+    res.status(404).json({ error: "unknown job" });
+    return;
+  }
+  res.json({ status: job.status, progress: job.progress, error: job.error });
+});
+
+// Stream progress to the browser as it is published.
+app.get("/images/:id/stream", async (req, res) => {
+  res.writeHead(200, {
+    "Content-Type": "text/event-stream",
+    "Cache-Control": "no-cache",
+    Connection: "keep-alive",
+  });
+  for await (const partial of queue.stream(req.params.id, { timeoutMs: 120_000 })) {
+    res.write(`data: ${JSON.stringify(partial)}\n\n`);
+  }
+  res.write("event: done\ndata: {}\n\n");
+  res.end();
+});
+
+// Cooperatively cancel a running job.
+app.post("/images/:id/cancel", (req, res) => {
+  const requested = queue.requestCancel(req.params.id);
+  res.json({ requested });
+});
+
+app.listen(3000);
+```
+
+<Callout type="info">
+  `queue.stream` polls the job's published partials and stops when the job
+  terminates. The task must call `currentJob().publish(value)` for anything to
+  appear — `setProgress` alone drives the dashboard, not the stream.
+</Callout>
+
+## worker.ts
+
+The worker is a separate process that shares the same database. It registers the
+same task so it knows how to run `processImage`.
+
+```ts
+import { Queue, currentJob } from "taskito";
+
+const queue = new Queue({ dbPath: "image-service.db" });
+
+queue.task("processImage", async (url: string, sizes: number[]) => {
+  // ...identical handler body as app.ts (share it via a module in real code)
+});
+
+const worker = queue.runWorker({ queues: ["default"] });
+process.on("SIGINT", () => {
+  worker.stop();
+  process.exit(0);
+});
+```
+
+## client.html
+
+The browser opens an `EventSource` and renders each partial as it arrives.
+
+```html
+<script>
+  async function run(url) {
+    const res = await fetch("/images", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ url, sizes: [256, 512, 1024] }),
+    });
+    const { jobId } = await res.json();
+
+    const events = new EventSource(`/images/${jobId}/stream`);
+    events.onmessage = (e) => {
+      const { done, total } = JSON.parse(e.data);
+      console.log(`progress: ${done}/${total}`);
+    };
+    events.addEventListener("done", () => events.close());
+  }
+</script>
+```
+
+## Running it
+
+<Tabs items={["Terminal 1 — API", "Terminal 2 — Worker"]}>
+  <Tab value="Terminal 1 — API">
+    ```bash
+    node app.ts
+    # POST http://localhost:3000/images  { "url": "...", "sizes": [256,512,1024] }
+    ```
+  </Tab>
+  <Tab value="Terminal 2 — Worker">
+    ```bash
+    node worker.ts
+    ```
+  </Tab>
+</Tabs>
+
+## Key patterns
+
+| Pattern | Where |
+| --- | --- |
+| Enqueue and return a job id (`202 Accepted`) | `POST /images` |
+| Live progress over SSE | `queue.stream` + `currentJob().publish` |
+| Dashboard progress | `currentJob().setProgress` |
+| Cooperative cancellation | `queue.requestCancel` + `signal.aborted` |
+| Mounting a ready-made REST API | [`taskitoRouter`](/node/guides/integrations/express) |
diff --git a/docs/content/docs/node/more/examples/index.mdx b/docs/content/docs/node/more/examples/index.mdx
new file mode 100644
index 00000000..fbe10cb9
--- /dev/null
+++ b/docs/content/docs/node/more/examples/index.mdx
@@ -0,0 +1,22 @@
+---
+title: Examples
+description: "End-to-end, runnable TypeScript examples — each demonstrating a slice of Taskito's Node SDK in a realistic setting."
+---
+
+Each example is a self-contained project you can copy, run, and adapt. They build
+on the [core guides](/node/guides/core/tasks) — read those for the concepts, come here for working code.
+
+| Example | Demonstrates |
+| --- | --- |
+| [Express service](/node/more/examples/express-service) | REST API that enqueues jobs, streams progress over SSE, and cancels in flight |
+| [Notification service](/node/more/examples/notifications) | Delayed scheduling, idempotency, priority, periodic tasks, batch enqueue |
+| [Web scraper](/node/more/examples/web-scraper) | Rate limiting, retries, named queues, middleware hooks, fan-out workflows |
+| [ETL data pipeline](/node/more/examples/data-pipeline) | A multi-stage DAG with progress, error history, and cascade cancellation |
+| [DAG workflows](/node/more/examples/workflows) | Fan-out/fan-in, gates, conditions, sub-workflows, caching, critical-path analysis |
+| [Saga — checkout](/node/more/examples/saga-checkout) | Compensating transactions with reverse-order rollback |
+| [Bulk emails](/node/more/examples/bulk-emails) | High-volume `enqueueMany` with concurrency caps and rate limits |
+| [Predicate-gated jobs](/node/more/examples/predicate-gated-jobs) | Enqueue-time gates with `allOf` / `anyOf` / `not` predicate composition |
+| [Benchmark](/node/more/examples/benchmark) | Measuring enqueue, processing, and end-to-end latency and throughput |
+
+Every snippet targets the standalone Node SDK — `import { Queue } from "taskito"` —
+with no Python in the loop. Pick the one closest to your problem and start there.
diff --git a/docs/content/docs/node/more/examples/meta.json b/docs/content/docs/node/more/examples/meta.json
new file mode 100644
index 00000000..ef7dfeeb
--- /dev/null
+++ b/docs/content/docs/node/more/examples/meta.json
@@ -0,0 +1,14 @@
+{
+  "title": "Examples",
+  "pages": [
+    "express-service",
+    "notifications",
+    "web-scraper",
+    "data-pipeline",
+    "workflows",
+    "saga-checkout",
+    "bulk-emails",
+    "predicate-gated-jobs",
+    "benchmark"
+  ]
+}
diff --git a/docs/content/docs/node/more/examples/notifications.mdx b/docs/content/docs/node/more/examples/notifications.mdx
new file mode 100644
index 00000000..85c40b65
--- /dev/null
+++ b/docs/content/docs/node/more/examples/notifications.mdx
@@ -0,0 +1,126 @@
+---
+title: Notification service
+description: "Delayed sends, idempotent enqueues, priority lanes, periodic digests, and batch fan-out for a notification system."
+---
+
+A notification service is a natural fit for a queue: every send is independent,
+some are scheduled for later, duplicates must be suppressed, and urgent alerts
+should jump the line. This example wires those requirements onto the Node SDK.
+
+## Project structure
+
+```
+notifications/
+  tasks.ts     # one task per channel + a periodic digest
+  service.ts   # the producer API the rest of the app calls
+  worker.ts    # the worker process
+```
+
+## tasks.ts
+
+Each channel is its own task so they retry, rate-limit, and scale independently.
+
+```ts
+import { Queue } from "taskito";
+
+export const queue = new Queue({ dbPath: "notifications.db" });
+
+queue.task("sendEmail", async (to: string, subject: string, body: string) => {
+  await emailProvider.send(to, subject, body);
+}, { maxRetries: 5, retryBackoff: { baseMs: 2_000, maxMs: 300_000 } });
+
+queue.task("sendSms", async (to: string, text: string) => {
+  await smsProvider.send(to, text);
+}, { maxRetries: 3, rateLimit: "100/m" });
+
+queue.task("sendDigest", async () => {
+  const due = await pendingDigests();
+  queue.enqueueMany("sendEmail", due.map((d) => ({
+    args: [d.email, "Your daily digest", d.html],
+  })));
+});
+```
+
+## service.ts
+
+The producer-facing helpers map application events onto enqueue options.
+
+```ts
+import { queue } from "./tasks";
+
+// 1. Delayed scheduling — remind 24h from now.
+export function scheduleReminder(email: string) {
+  return queue.enqueue("sendEmail", [email, "Reminder", "..."], {
+    delayMs: 24 * 60 * 60 * 1000,
+  });
+}
+
+// 2. Idempotency — a duplicate enqueue with the same key is a no-op while the
+//    first is still pending or running.
+export function sendWelcomeOnce(userId: string, email: string) {
+  return queue.enqueue("sendEmail", [email, "Welcome", "..."], {
+    uniqueKey: `welcome:${userId}`,
+  });
+}
+
+// 3. Priority — security alerts preempt routine mail.
+export function sendSecurityAlert(phone: string, text: string) {
+  return queue.enqueue("sendSms", [phone, text], { priority: 100 });
+}
+
+// 4. Cancellation — pull a not-yet-started send.
+export function cancelScheduled(jobId: string) {
+  return queue.cancelJob(jobId); // false if it already started
+}
+
+// 5. Inspection — what's still pending?
+export function pendingSends() {
+  return queue.listJobs({ status: "pending", task: "sendEmail", limit: 50 });
+}
+```
+
+## worker.ts
+
+The worker runs the channels and registers the periodic digest at `08:00`
+America/New_York time.
+
+```ts
+import { queue } from "./tasks";
+
+queue.registerPeriodic("daily-digest", "sendDigest", "0 8 * * *", {
+  timezone: "America/New_York",
+});
+
+const worker = queue.runWorker({ queues: ["default"] });
+process.on("SIGINT", () => {
+  worker.stop();
+  process.exit(0);
+});
+```
+
+## Running it
+
+<Tabs items={["Terminal 1 — Worker", "Terminal 2 — Producer"]}>
+  <Tab value="Terminal 1 — Worker">
+    ```bash
+    node worker.ts
+    ```
+  </Tab>
+  <Tab value="Terminal 2 — Producer">
+    ```bash
+    node -e "import('./service.ts').then(s => s.sendSecurityAlert('+1...', 'Login from a new device'))"
+    ```
+  </Tab>
+</Tabs>
+
+## Key patterns
+
+| Pattern | Where |
+| --- | --- |
+| Delayed / scheduled send | `enqueue(..., { delayMs })` |
+| Idempotent send | `enqueue(..., { uniqueKey })` |
+| Priority lane | `enqueue(..., { priority })` |
+| Cancel a pending job | `queue.cancelJob` |
+| Recurring digest | `queue.registerPeriodic` (cron) |
+| Batch fan-out | `queue.enqueueMany` |
+| Pending-work inspection | `queue.listJobs` |
diff --git a/docs/content/docs/node/more/examples/predicate-gated-jobs.mdx b/docs/content/docs/node/more/examples/predicate-gated-jobs.mdx
new file mode 100644
index 00000000..48c84948
--- /dev/null
+++ b/docs/content/docs/node/more/examples/predicate-gated-jobs.mdx
@@ -0,0 +1,100 @@
+---
+title: Predicate-gated jobs
+description: "Reject enqueues that don't meet a policy at submit time, composing business-hours, feature-flag, and quota predicates."
+---
+
+A predicate is a function evaluated when a job is enqueued. If it returns `false`,
+the enqueue is rejected with a `PredicateRejectedError` and no job is created —
+backpressure at the front door, before any work is staged.
+
+## What this gates
+
+- promotional sends only during business hours,
+- an expensive re-index only when its feature flag is on,
+- a tenant's exports only while under quota.
+
+## predicates.ts
+
+A predicate receives `{ taskName, args }` — the positional args after any
+`onEnqueue` rewrites. Compose them with `allOf` / `anyOf` / `not`.
+
+```ts
+import type { Predicate } from "taskito";
+
+export const duringBusinessHours: Predicate = () => {
+  const hour = new Date().getUTCHours();
+  return hour >= 13 && hour < 22; // 9–6 ET
+};
+
+export const featureEnabled = (flag: string): Predicate => () => flags.isOn(flag);
+
+export const underQuota: Predicate = ({ args }) => {
+  const [tenantId] = args as [string];
+  return usage.exports(tenantId) < usage.limit(tenantId);
+};
+```
+
+## app.ts
+
+`queue.gate` attaches one or more predicates to a task; every gate must pass.
+
+```ts
+import { Queue, allOf, not } from "taskito";
+import { duringBusinessHours, featureEnabled, underQuota } from "./predicates";
+
+export const queue = new Queue({ dbPath: "gated.db" });
+
+queue.task("sendPromo", (audience: string) => mailer.blast(audience));
+queue.task("reindex", () => search.rebuild());
+queue.task("exportData", (tenantId: string) => exporter.run(tenantId));
+
+queue.gate("sendPromo", duringBusinessHours);
+queue.gate("reindex", featureEnabled("expensive-reindex"));
+queue.gate("exportData", allOf(underQuota, not(duringBusinessHours))); // off-peak only
+```
+
+## Enqueuing against a gate
+
+A rejected enqueue throws synchronously — handle it where you submit.
+
+```ts
+import { PredicateRejectedError } from "taskito";
+
+try {
+  queue.enqueue("sendPromo", ["newsletter-subscribers"]);
+} catch (err) {
+  if (err instanceof PredicateRejectedError) {
+    res.status(409).json({ error: "blocked by policy", task: err.taskName });
+  } else {
+    throw err;
+  }
+}
+```
+
+## Observing outcomes
+
+Gates run before a job exists, so there is no job event for a rejection — the
+thrown error is your signal. Subscribe to the lifecycle events to observe jobs
+that *did* pass the gate.
+
+```ts
+queue.on("job.completed", (e) => console.log(`${e.taskName} ${e.jobId} ok`));
+queue.on("job.dead", (e) => console.warn(`${e.taskName} ${e.jobId} dead: ${e.error}`));
+```
+
+<Callout type="info">
+  Predicates run at **enqueue time** in the producer process, synchronously.
+  Keep them cheap and side-effect-free — a slow predicate slows every enqueue.
+  For checks that need the worker (resource state, external I/O), gate inside the
+  task and fail it instead.
+</Callout>
+
+## Key patterns
+
+| Pattern | Where |
+| --- | --- |
+| Attach a gate | `queue.gate(task, predicate)` |
+| Compose policies | `allOf` / `anyOf` / `not` |
+| Args-aware gate | `({ args }) => …` |
+| Handle rejection | `catch (PredicateRejectedError)` |
+| Observe passers | `queue.on("job.completed" \| "job.dead")` |
diff --git a/docs/content/docs/node/more/examples/saga-checkout.mdx b/docs/content/docs/node/more/examples/saga-checkout.mdx
new file mode 100644
index 00000000..dcfa7088
--- /dev/null
+++ b/docs/content/docs/node/more/examples/saga-checkout.mdx
@@ -0,0 +1,103 @@
+---
+title: Saga — e-commerce checkout
+description: "A multi-step checkout with compensating transactions: when a later step fails, completed steps roll back in reverse order."
+---
+
+A checkout touches several systems — inventory, payments, shipping — with no
+distributed transaction across them. The saga pattern models each forward step
+with a compensator; if a later step fails, Taskito runs the compensators for the
+already-completed steps in reverse-dependency order.
+
+## tasks.ts
+
+Declare each forward task and its rollback. A compensator receives the forward
+step's result as its single argument, so it knows exactly what to undo.
+
+```ts
+import { Queue } from "taskito";
+
+export const queue = new Queue({ dbPath: "checkout.db" });
+
+queue.task("reserveInventory", (order: Order) => inventory.reserve(order));   // → { reservationId }
+queue.task("releaseInventory", (r: { reservationId: string }) => inventory.release(r.reservationId));
+
+queue.task("chargePayment", (order: Order) => payments.charge(order));        // → { chargeId }
+queue.task("refundPayment", (c: { chargeId: string }) => payments.refund(c.chargeId));
+
+queue.task("createShipment", (order: Order) => shipping.create(order));       // → { shipmentId }
+queue.task("cancelShipment", (s: { shipmentId: string }) => shipping.cancel(s.shipmentId));
+```
+
+## checkout.ts
+
+Each step names its `compensate` task. The steps run in dependency order; the
+compensators are wired automatically.
+
+```ts
+import { queue } from "./tasks";
+
+export function checkout(order: Order) {
+  return queue.workflows
+    .define("checkout", 1)
+    .step("reserve", "reserveInventory", { args: [order], compensate: "releaseInventory" })
+    .step("charge", "chargePayment", { args: [order], after: "reserve", compensate: "refundPayment" })
+    .step("ship", "createShipment", { args: [order], after: "charge", compensate: "cancelShipment" })
+    .submit();
+}
+```
+
+## Running it
+
+```ts
+const run = checkout(order);
+const final = await run.wait({ timeoutMs: 60_000 });
+
+switch (final.state) {
+  case "completed":
+    console.log("order placed");
+    break;
+  case "compensated":
+    console.log("rolled back cleanly — customer charged nothing");
+    break;
+  case "compensation_failed":
+    console.error("manual intervention needed");
+    break;
+}
+```
+
+## What happens on failure
+
+If `createShipment` throws, `reserve` and `charge` have already completed. Taskito
+runs their compensators in reverse order:
+
+```
+ship      ✗ failed
+charge    → refundPayment({ chargeId })   (compensate)
+reserve   → releaseInventory({ reservationId })  (compensate)
+```
+
+The run lands in `compensated` if every compensator succeeds, or
+`compensation_failed` if one of them throws.
+
+<Callout type="warn">
+  Compensators should be idempotent. A refund or release may be retried, and a
+  partially-applied rollback that re-runs must not double-refund or release twice.
+</Callout>
+
+## Run states
+
+| State | Meaning |
+| --- | --- |
+| `completed` | every forward step succeeded |
+| `compensating` | a step failed; compensators are running |
+| `compensated` | rollback finished cleanly |
+| `compensation_failed` | a compensator threw — needs manual repair |
+
+## Key patterns
+
+| Pattern | Where |
+| --- | --- |
+| Forward + rollback pair | `.step(..., { compensate })` |
+| Reverse-order rollback | automatic on step failure |
+| Result-aware undo | compensator receives the forward result |
+| Outcome branching | `final.state` |
diff --git a/docs/content/docs/node/more/examples/web-scraper.mdx b/docs/content/docs/node/more/examples/web-scraper.mdx
new file mode 100644
index 00000000..87df09a3
--- /dev/null
+++ b/docs/content/docs/node/more/examples/web-scraper.mdx
@@ -0,0 +1,147 @@
+---
+title: Web scraper pipeline
+description: "A polite, rate-limited scraper: retries, named queues, middleware logging, and a fan-in workflow that aggregates results."
+---
+
+Scraping is bursty, failure-prone, and must respect the target's limits. This
+example fetches a set of pages under a strict rate limit, retries transient
+failures with backoff, isolates network work on its own queue, and joins the
+results with a workflow.
+
+## Project structure
+
+```
+scraper/
+  tasks.ts     # fetch / extract / store / aggregate, plus logging middleware
+  run.ts       # submit a chord: fetch-all → aggregate
+  worker.ts    # worker + periodic cleanup
+```
+
+## tasks.ts
+
+`fetchPage` is rate-limited to 30 requests/minute and retries with exponential
+backoff. Network tasks run on a dedicated `network` queue so a backlog there
+never starves CPU-bound extraction.
+
+```ts
+import { Queue } from "taskito";
+
+export const queue = new Queue({ dbPath: "scraper.db" });
+
+queue.task("fetchPage", async (url: string) => {
+  const res = await fetch(url);
+  if (!res.ok) {
+    throw new Error(`HTTP ${res.status} for ${url}`);
+  }
+  return res.text();
+}, {
+  rateLimit: "30/m",
+  maxRetries: 4,
+  retryBackoff: { baseMs: 1_000, maxMs: 60_000 },
+});
+
+queue.task("extractLinks", (html: string) => {
+  return [...html.matchAll(/href="(https?:\/\/[^"]+)"/g)].map((m) => m[1]);
+});
+
+// Source step: supplies the URL list the fan-out expands over.
+queue.task("listUrls", (urls: string[]) => urls);
+
+// Fan-in combiner: receives one entry per fetched page (each child's result).
+queue.task("aggregate", (pages: string[]) => {
+  const links = pages.flatMap((html) =>
+    [...html.matchAll(/href="(https?:\/\/[^"]+)"/g)].map((m) => m[1]),
+  );
+  return { pages: pages.length, links: links.length, unique: new Set(links).size };
+});
+
+queue.task("cleanupCache", async (olderThanMs: number) => {
+  queue.purgeCompleted(olderThanMs);
+});
+
+// Middleware: one log line per execution and per failure.
+queue.use({
+  before(ctx) {
+    console.log(`→ ${ctx.taskName} ${ctx.jobId}`);
+  },
+  after(ctx) {
+    console.log(`✓ ${ctx.taskName} ${ctx.jobId}`);
+  },
+  onError(ctx, err) {
+    console.warn(`✗ ${ctx.taskName} ${ctx.jobId}: ${String(err)}`);
+  },
+});
+```
+
+## run.ts
+
+A [fan-out / fan-in](/node/guides/workflows/fan-out) expands the URL list into
+one `fetchPage` child per URL, then `aggregate` receives every fetched page as
+`[html, …]`. The fetches land on the `network` queue; the join runs on the default.
+
+```ts
+import { queue } from "./tasks";
+
+const urls = ["https://a.example", "https://b.example", "https://c.example"];
+
+const run = queue.workflows
+  .define("scrape", 1)
+  .step("list", "listUrls", { args: [urls] })
+  .fanOut("fetch", { after: "list", task: "fetchPage", itemsFrom: "list", queue: "network" })
+  .fanIn("aggregate", { after: "fetch", task: "aggregate" })
+  .submit({ queueDefault: "default" });
+
+const final = await run.wait({ timeoutMs: 120_000 });
+console.log(run.runId, final.state);
+```
+
+<Callout type="info">
+  Fan-in passes the children's results to its task as `[childResult, …]`, so
+  `aggregate` sees every fetched page. A `chord` would instead join on
+  *completion* and call the callback with its own `args` — use it when the join
+  doesn't need the children's results.
+</Callout>
+
+## worker.ts
+
+The worker consumes both queues and sweeps completed jobs hourly.
+
+```ts
+import { queue } from "./tasks";
+
+queue.registerPeriodic("cache-sweep", "cleanupCache", "0 * * * *", {
+  args: [24 * 60 * 60 * 1000],
+});
+
+const worker = queue.runWorker({ queues: ["default", "network"] });
+process.on("SIGINT", () => {
+  worker.stop();
+  process.exit(0);
+});
+```
+
+## Running it
+
+<Tabs items={["Terminal 1 — Worker", "Terminal 2 — Run"]}>
+  <Tab value="Terminal 1 — Worker">
+    ```bash
+    node worker.ts
+    ```
+  </Tab>
+  <Tab value="Terminal 2 — Run">
+    ```bash
+    node run.ts
+    ```
+  </Tab>
+</Tabs>
+
+## Key patterns
+
+| Pattern | Where |
+| --- | --- |
+| Politeness via rate limit | `task(..., { rateLimit: "30/m" })` |
+| Transient-failure retries | `retryBackoff` |
+| Workload isolation | `network` queue + `runWorker({ queues })` |
+| Cross-cutting logging | `queue.use({ before, after, onError })` |
+| Parallel-then-join | workflow `chord` |
+| Scheduled maintenance | `registerPeriodic` + `purgeCompleted` |
diff --git a/docs/content/docs/node/more/examples/workflows.mdx b/docs/content/docs/node/more/examples/workflows.mdx
new file mode 100644
index 00000000..dd479c5c
--- /dev/null
+++ b/docs/content/docs/node/more/examples/workflows.mdx
@@ -0,0 +1,139 @@
+---
+title: DAG workflow examples
+description: "Fan-out/fan-in map-reduce, approval gates, error-handling conditions, sub-workflows, caching, and critical-path analysis."
+---
+
+These are focused recipes for the workflow builder. Each is independent — combine
+them as your orchestration needs grow. See the
+[workflows guide](/node/guides/workflows) for the underlying model.
+
+## Map-reduce with fan-out / fan-in
+
+`fanOut` reads the array result of its predecessor and expands one child per item;
+`fanIn` collects those children's results into a single array for a combiner.
+
+<Mermaid
+  chart={`graph LR
+    split --> map_0["map[0]"]
+    split --> map_1["map[1]"]
+    split --> map_2["map[2]"]
+    map_0 --> reduce
+    map_1 --> reduce
+    map_2 --> reduce`}
+/>
+
+```ts
+queue.task("split", (corpus: string) => corpus.split("\n\n"));   // → string[]
+queue.task("scoreChunk", (chunk: string) => model.score(chunk)); // per item
+queue.task("reduce", (scores: number[]) => avg(scores));         // [childResult, …]
+
+const run = queue.workflows
+  .define("score-corpus", 1)
+  .step("split", "split", { args: [corpus] })
+  .fanOut("map", { after: "split", task: "scoreChunk" }) // itemsFrom defaults to "split"
+  .fanIn("reduce", { after: "map", task: "reduce" })
+  .submit();
+
+const final = await run.wait({ timeoutMs: 300_000 });
+console.log(final.state);
+```
+
+## Approval gate
+
+A gate pauses the run until a human resolves it (or it times out). Resolve it from
+anywhere — an admin route, a Slack action — the plan is read from storage.
+
+```ts
+const run = queue.workflows
+  .define("publish", 1)
+  .step("build", "buildArtifact")
+  .gate("review", { after: "build", timeoutMs: 86_400_000, onTimeout: "reject",
+                    message: "Approve production deploy?" })
+  .step("deploy", "deployArtifact", { after: "review" })
+  .submit();
+
+// elsewhere, once a reviewer clicks "approve":
+queue.workflows.approveGate(run.runId, "review");
+// or: queue.workflows.rejectGate(run.runId, "review", "failed QA");
+```
+
+## Error-handling with conditions
+
+A step's `condition` decides when it runs relative to its predecessors' outcomes.
+`on_failure` builds an error path that fires only when an upstream step fails.
+
+```ts
+queue.workflows
+  .define("import", 1)
+  .step("load", "loadBatch")
+  .step("notifyOk", "notifySuccess", { after: "load", condition: "on_success" })
+  .step("quarantine", "quarantineBatch", { after: "load", condition: "on_failure" })
+  .submit();
+```
+
+## Sub-workflows
+
+Compose a child workflow as a single step. The tracker submits it as a child run
+and resolves the parent node when the child finalizes.
+
+```ts
+const validate = queue.workflows
+  .define("validate-region", 1)
+  .step("schema", "checkSchema")
+  .step("dupes", "checkDuplicates", { after: "schema" })
+  .build(); // build, don't submit
+
+queue.workflows
+  .define("regional-etl", 1)
+  .step("extract", "extract")
+  .subWorkflow("validate", { after: "extract", workflow: validate })
+  .step("load", "load", { after: "validate" })
+  .submit();
+```
+
+## Cacheable, incremental steps
+
+Mark an expensive step `cache: true` to reuse its result across runs when its
+task, args, and upstream results are unchanged — the basis for incremental
+re-runs. A cacheable step must have a predecessor.
+
+```ts
+queue.workflows
+  .define("nightly", 1)
+  .step("fetch", "fetchRaw", { args: [date] })
+  .step("featurize", "buildFeatures", { after: "fetch", cache: { ttlMs: 86_400_000 } })
+  .step("train", "trainModel", { after: "featurize" })
+  .submit();
+```
+
+## Pre- and post-run analysis
+
+`analyze` is pure graph computation over a run's DAG plus its node statuses — use
+it to preview structure before submitting or to inspect progress after.
+
+```ts
+const a = queue.workflows.analyze(run.runId);
+if (a) {
+  console.log("roots:", a.roots());
+  console.log("levels:", a.topologicalLevels());
+  console.log("critical path:", a.criticalPath());
+  console.log("stats:", a.stats()); // { total, completed, failed, running, pending }
+}
+```
+
+<Callout type="info">
+  `wait` resolves once the run reaches a terminal state — `completed`,
+  `completed_with_failures`, `failed`, `cancelled`, `compensated`, or
+  `compensation_failed`. Check `final.state` to branch on the outcome.
+</Callout>
+
+## Key patterns
+
+| Pattern | Builder |
+| --- | --- |
+| Map-reduce | `.fanOut(...).fanIn(...)` |
+| Human approval | `.gate(...)` + `approveGate` / `rejectGate` |
+| Error branch | `.step(..., { condition: "on_failure" })` |
+| Composition | `.subWorkflow(...)` |
+| Incremental re-runs | `.step(..., { cache })` |
+| Inspection | `workflows.analyze(runId)` |
diff --git a/docs/public/demos/README.md b/docs/public/demos/README.md
new file mode 100644
index 00000000..530c0474
--- /dev/null
+++ b/docs/public/demos/README.md
@@ -0,0 +1,39 @@
+# Interactive demos (vendored static micro-app)
+
+These files power the **live demos** the homepage scenario finder opens in a modal
+(`app/components/landing/demo-modal.tsx`). They are a self-contained vanilla
+HTML/CSS/JS micro-app, served verbatim as static assets and loaded into an
+`<iframe>` in **embed mode**:
+
+```text
+/demos/interactive.html?embed=<demoId>&theme=<light|dark>&accent=brand#<demoId>
+```
+
+The modal is the only entry point, so `interactive.html` carries no standalone
+page chrome — it is purely the embed host. The inline bootstrap keeps only the
+requested demo and inherits the host theme.
+
+`demoId` ∈ `ratelimit · recovery · scaling · workflow · mesh · saga · worksteal`.
+
+## Provenance
+
+Copied from the design sign-off package `Taskito docs design 2/taskito/`. **Edits
+on import, all in `interactive.html`:**
+
+1. Removed the `<script src="landing.js">` (nav/theme-toggle) and
+   `<script src="search.js">` (⌘K palette) tags — chrome-only, unused in embed.
+2. Since `landing.js` also ran the scroll-reveal observer, the embed bootstrap now
+   adds `.in` to the shown demo's `.reveal` children directly (they default to
+   `opacity:0`), so the demo is visible without that observer.
+3. Removed the page chrome (nav, hero, CTA, footer, capability probe) — the
+   homepage modal loads this file only in embed mode, so the standalone page was
+   dead weight.
+
+The demo sections and `demo-*.js` are otherwise verbatim. To update a demo,
+re-copy the matching `demo-*.js` from the source package.
+
+## Files
+- `interactive.html` — demo host page + embed-mode bootstrap
+- `theme.css`, `interactive.css` — design tokens + demo styles
+- `demo-{ratelimit,recovery,playground,workflow,mesh,saga,worksteal}.js` — one per demo
+- `favicon.svg`
diff --git a/docs/public/demos/demo-mesh.js b/docs/public/demos/demo-mesh.js
new file mode 100644
index 00000000..540e847c
--- /dev/null
+++ b/docs/public/demos/demo-mesh.js
@@ -0,0 +1,238 @@
+/* ============================================================
+   taskito · Demo 05 — Mesh scheduling
+   Jobs carry a routing key; the brokerless mesh sends each to a
+   worker pool built to run it (gpu / default / email). Click a
+   machine to drop it and watch its work reroute across the mesh.
+   Tier-1: SVG + requestAnimationFrame. No WebGL.
+   ============================================================ */
+(function(){
+  var root=document.getElementById('mesh-root');
+  if(!root) return;
+
+  var W=940,H=330;
+  var DISP={x:92,y:165};
+  var EX=430;                 // pool entry x
+  var SPEED=560;
+  var POOLS=[
+    {key:'gpu',     label:'gpu · render',  col:'var(--cyan)',      y:60,  n:2, dur:1650},
+    {key:'default', label:'default · web', col:'var(--indigo-br)', y:165, n:3, dur:900},
+    {key:'email',   label:'email · notify',col:'var(--amber)',     y:270, n:2, dur:720}
+  ];
+  var NX0=560, NSTEP=128, NW=104, NH=46;
+  var WEIGHT={gpu:0.24, default:0.52, email:0.24};
+
+  // build node models
+  POOLS.forEach(function(p){
+    p.nodes=[]; p.wait=[];
+    for(var i=0;i<p.n;i++) p.nodes.push({x:NX0+i*NSTEP, y:p.y, busy:null, off:false, pip:null, rect:null, xg:null, g:null});
+  });
+  var metrics={routed:0, rerouted:0};
+
+  // ---- DOM ----
+  root.innerHTML=
+  '<div class="demo-bar">'+
+    '<span class="title"><span class="ld"></span>worker-mesh · live</span>'+
+    '<div class="demo-controls">'+
+      '<span class="mesh-hint"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 17v.01M12 13.5a2 2 0 0 0 .914-3.782 1.98 1.98 0 0 0-2.414.483"/><circle cx="12" cy="12" r="9"/></svg>click a machine to drop it</span>'+
+      '<button class="ctl pri" id="mesh-burst"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"><path d="M13 2 3 14h7l-1 8 10-12h-7l1-8z"/></svg>Send burst (6)</button>'+
+    '</div>'+
+  '</div>'+
+  '<div class="stage"><svg id="mesh-svg" viewBox="0 0 '+W+' '+H+'" role="img" aria-label="Mesh scheduling: jobs leave a dispatcher and route by key to one of three worker pools — gpu, default, and email. Click a worker to take it offline and its jobs reroute to the rest of its pool.">'+
+    '<defs><marker id="mesh-ar" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="6" markerHeight="6" orient="auto"><path d="M1 1 L9 5 L1 9" fill="none" stroke="var(--line3)" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round"/></marker></defs>'+
+    '<g id="mesh-wires"></g>'+
+    // dispatcher
+    '<g><rect x="36" y="133" width="112" height="64" rx="13" fill="var(--panel3)" stroke="var(--line2)"/>'+
+      '<text x="92" y="159" text-anchor="middle" font-family="var(--mono)" font-size="11" fill="var(--mut)">dispatcher</text>'+
+      '<text x="92" y="178" text-anchor="middle" font-family="var(--code)" font-size="11" font-weight="600" fill="var(--txt2)">route()</text></g>'+
+    '<g id="mesh-pools"></g>'+
+    '<g id="mesh-tokens"></g>'+
+  '</svg></div>'+
+  '<div class="legend">'+
+    '<span><i style="background:var(--cyan)"></i>gpu job</span>'+
+    '<span><i style="background:var(--indigo-br)"></i>default job</span>'+
+    '<span><i style="background:var(--amber)"></i>email job</span>'+
+    '<span><i style="background:var(--grn)"></i>worker busy</span>'+
+    '<span><i style="background:var(--dim)"></i>offline</span>'+
+  '</div>'+
+  '<div class="readout">'+
+    stat('nodes online','mesh-online')+stat('routing','mesh-flight')+stat('waiting','mesh-wait','warn')+
+    stat('routed','mesh-routed','good')+stat('rerouted','mesh-reroute')+
+  '</div>';
+
+  function stat(k,id,cls){ return '<div class="stat"><span class="k">'+k+'</span><span class="v'+(cls?' '+cls:'')+'" id="'+id+'">0</span></div>'; }
+  function el(id){ return document.getElementById(id); }
+  var SVGNS='http://www.w3.org/2000/svg';
+
+  // ---- wires + pools render ----
+  var gWires=el('mesh-wires'), gPools=el('mesh-pools'), gTok=el('mesh-tokens');
+  POOLS.forEach(function(p){
+    // dispatcher → entry
+    var mx=(148+EX)/2;
+    addPath('M148 165 C '+mx+' 165, '+mx+' '+p.y+', '+EX+' '+p.y, 'var(--line2)', true);
+    // pool lane chip
+    var chip=document.createElementNS(SVGNS,'g');
+    chip.innerHTML='<rect x="300" y="'+(p.y-15)+'" width="120" height="30" rx="9" fill="var(--panel)" stroke="'+p.col+'" opacity="1"/>'+
+      '<rect x="300" y="'+(p.y-15)+'" width="120" height="30" rx="9" fill="none" stroke="color-mix(in oklch,'+p.col+' 40%,transparent)"/>'+
+      '<circle cx="316" cy="'+p.y+'" r="4" fill="'+p.col+'"/>'+
+      '<text x="328" y="'+(p.y+4)+'" font-family="var(--mono)" font-size="11" fill="var(--txt2)">'+p.label+'</text>';
+    gPools.appendChild(chip);
+    p.nodes.forEach(function(node){
+      addPath('M420 '+p.y+' H '+(node.x-NW/2), 'var(--line2)', false);
+      var g=document.createElementNS(SVGNS,'g'); g.setAttribute('class','mesh-node'); g.style.cursor='pointer';
+      g.setAttribute('tabindex','0'); g.setAttribute('role','button'); g.setAttribute('aria-pressed','false'); g.setAttribute('aria-label',p.key+' worker — click to toggle offline');
+      var rect=document.createElementNS(SVGNS,'rect');
+      rect.setAttribute('x',node.x-NW/2); rect.setAttribute('y',node.y-NH/2); rect.setAttribute('width',NW); rect.setAttribute('height',NH);
+      rect.setAttribute('rx','11'); rect.setAttribute('fill','var(--panel2)'); rect.setAttribute('stroke','var(--line2)');
+      var pip=document.createElementNS(SVGNS,'circle');
+      pip.setAttribute('cx',node.x+NW/2-13); pip.setAttribute('cy',node.y-NH/2+13); pip.setAttribute('r','4'); pip.setAttribute('fill','var(--dim)');
+      var t=document.createElementNS(SVGNS,'text');
+      t.setAttribute('x',node.x-NW/2+12); t.setAttribute('y',node.y+4); t.setAttribute('font-family','var(--code)'); t.setAttribute('font-size','11');
+      t.setAttribute('font-weight','600'); t.setAttribute('fill','var(--txt2)'); t.textContent=p.key+'-'+(p.nodes.indexOf(node)+1);
+      var xg=document.createElementNS(SVGNS,'path');
+      xg.setAttribute('d','M'+(node.x-9)+' '+(node.y-9)+' l18 18 M'+(node.x+9)+' '+(node.y-9)+' l-18 18');
+      xg.setAttribute('stroke','var(--red)'); xg.setAttribute('stroke-width','2'); xg.setAttribute('stroke-linecap','round'); xg.setAttribute('opacity','0');
+      g.appendChild(rect); g.appendChild(pip); g.appendChild(t); g.appendChild(xg);
+      gPools.appendChild(g);
+      node.rect=rect; node.pip=pip; node.xg=xg; node.g=g; node.pool=p;
+      g.addEventListener('click',function(){ toggleNode(node); });
+      g.addEventListener('keydown',function(e){ if(e.key==='Enter'||e.key===' '){ e.preventDefault(); toggleNode(node); } });
+    });
+  });
+  function addPath(d,stroke,arrow){
+    var pth=document.createElementNS(SVGNS,'path');
+    pth.setAttribute('d',d); pth.setAttribute('fill','none'); pth.setAttribute('stroke',stroke);
+    pth.setAttribute('stroke-width','2'); pth.setAttribute('stroke-dasharray','2 7'); pth.setAttribute('stroke-linecap','round');
+    if(arrow) pth.setAttribute('marker-end','url(#mesh-ar)');
+    gWires.appendChild(pth);
+  }
+
+  // ---- tokens ----
+  var tokens=[];
+  function poolByKey(k){ return POOLS.filter(function(p){return p.key===k;})[0]; }
+  function pickKey(){ var r=Math.random(); if(r<WEIGHT.gpu) return 'gpu'; if(r<WEIGHT.gpu+WEIGHT.default) return 'default'; return 'email'; }
+
+  function emit(n){
+    for(var i=0;i<n;i++){
+      if(tokens.length>34) break;
+      var key=pickKey(), p=poolByKey(key);
+      var t={key:key,pool:p,x:DISP.x+22,y:DISP.y+(Math.random()*16-8),r:6,node:null,phase:'toentry',tx:EX,ty:p.y,pUntil:0};
+      var c=document.createElementNS(SVGNS,'circle'); c.setAttribute('r','6'); c.style.fill=p.col; t.el=c; gTok.appendChild(c);
+      tokens.push(t);
+    }
+  }
+
+  function freeNode(p){ for(var i=0;i<p.nodes.length;i++){ var nd=p.nodes[i]; if(!nd.off && !nd.busy) return nd; } return null; }
+  function assignPool(p){
+    var nd;
+    while(p.wait.length && (nd=freeNode(p))){
+      var t=p.wait.shift(); nd.busy=t; t.node=nd; t.phase='tonode'; t.tx=nd.x; t.ty=nd.y;
+    }
+  }
+  function arriveEntry(t){
+    var nd=freeNode(t.pool);
+    if(nd){ nd.busy=t; t.node=nd; t.phase='tonode'; t.tx=nd.x; t.ty=nd.y; }
+    else { t.phase='waiting'; var idx=t.pool.wait.length; t.pool.wait.push(t); t.tx=445; t.ty=t.pool.y-20+idx*13; }
+  }
+
+  function toggleNode(node){
+    node.off=!node.off;
+    if(node.off && node.busy){
+      var t=node.busy; node.busy=null;
+      // requeue to front, reroute
+      metrics.rerouted++;
+      t.node=null; t.phase='waiting'; node.pool.wait.unshift(t); t.tx=445; t.ty=node.pool.y-20;
+    }
+    paintNode(node);
+    if(!node.off) assignPool(node.pool);
+    if(motionOff()) staticRender();
+  }
+
+  function paintNode(nd){
+    // Mirror online/offline into ARIA: pressed === taken offline.
+    nd.g.setAttribute('aria-pressed', nd.off?'true':'false');
+    nd.g.setAttribute('aria-label', nd.pool.key+' worker — '+(nd.off?'offline, click to bring online':'online, click to take offline'));
+    if(nd.off){
+      nd.rect.setAttribute('fill','var(--panel)'); nd.rect.setAttribute('stroke','var(--line2)');
+      nd.rect.setAttribute('stroke-dasharray','3 5'); nd.pip.setAttribute('fill','var(--dim)'); nd.xg.setAttribute('opacity','.8');
+      nd.g.style.opacity='.55';
+    } else {
+      nd.rect.setAttribute('stroke-dasharray',''); nd.xg.setAttribute('opacity','0'); nd.g.style.opacity='1';
+      if(nd.busy){
+        nd.rect.setAttribute('fill','color-mix(in oklch,'+nd.pool.col+' 16%,transparent)');
+        nd.rect.setAttribute('stroke','color-mix(in oklch,'+nd.pool.col+' 50%,transparent)');
+        nd.pip.setAttribute('fill','var(--grn)');
+      } else {
+        nd.rect.setAttribute('fill','var(--panel2)'); nd.rect.setAttribute('stroke','var(--line2)');
+        nd.pip.setAttribute('fill','var(--dim)');
+      }
+    }
+  }
+
+  function step(now,dt){
+    if(!motionOff()){ emitAcc+=dt; if(emitAcc>880){ emitAcc=0; if(tokens.length<26) emit(1); } }
+    var move=SPEED*dt/1000;
+    // re-stack waiting tokens
+    POOLS.forEach(function(p){ p.wait.forEach(function(t,i){ t.tx=445; t.ty=p.y-20+i*13; }); assignPool(p); });
+    for(var i=tokens.length-1;i>=0;i--){
+      var t=tokens[i], dx=t.tx-t.x, dy=t.ty-t.y, d=Math.hypot(dx,dy);
+      if(d>0.5){ var s=Math.min(move,d); t.x+=dx/d*s; t.y+=dy/d*s; }
+      var arrived=d<2.5;
+      switch(t.phase){
+        case 'toentry': if(arrived) arriveEntry(t); break;
+        case 'tonode': if(arrived){ t.phase='processing'; t.pUntil=now+t.pool.dur*(0.82+Math.random()*0.4); } break;
+        case 'processing':
+          if(now>=t.pUntil){ var nd=t.node; if(nd){ nd.busy=null; paintNode(nd); assignPool(t.pool); } metrics.routed++; t.phase='done'; t.tx=W+30; t.ty=t.y; }
+          break;
+        case 'done': if(t.x>W+20){ rm(t,i); } break;
+      }
+      if(t.el){ t.el.setAttribute('cx',t.x.toFixed(1)); t.el.setAttribute('cy',t.y.toFixed(1));
+        t.el.setAttribute('r', t.phase==='processing'?'6.5':'6');
+        t.el.style.opacity = t.phase==='waiting'?'0.8':'1'; }
+    }
+    POOLS.forEach(function(p){ p.nodes.forEach(paintNode); });
+    paintStats();
+  }
+  function rm(t,i){ if(t.el&&t.el.parentNode) t.el.parentNode.removeChild(t.el); tokens.splice(i,1); }
+
+  function paintStats(){
+    var online=0,total=0,busy=0,waiting=0;
+    POOLS.forEach(function(p){ p.nodes.forEach(function(nd){ total++; if(!nd.off) online++; if(nd.busy) busy++; }); waiting+=p.wait.length; });
+    var flight=tokens.filter(function(t){return t.phase==='toentry'||t.phase==='tonode';}).length;
+    setTxt('mesh-online',online+' / '+total);
+    setTxt('mesh-flight',flight+busy);
+    var w=el('mesh-wait'); w.textContent=waiting; w.className='v '+(waiting>0?'warn':'');
+    setTxt('mesh-routed',metrics.routed);
+    var r=el('mesh-reroute'); r.textContent=metrics.rerouted; r.className='v '+(metrics.rerouted>0?'bad':'');
+  }
+  function setTxt(id,v){ el(id).textContent=v; }
+
+  // ---- controls / motion ----
+  function motionOff(){ return window.__motionOff || (window.matchMedia && window.matchMedia('(prefers-reduced-motion:reduce)').matches); }
+  el('mesh-burst').addEventListener('click',function(){ emit(6); if(motionOff()) staticRender(); });
+
+  var emitAcc=0,last=0,raf=null;
+  function loop(now){ if(!last) last=now; var dt=Math.min(now-last,60); last=now; step(now,dt); raf=requestAnimationFrame(loop); }
+  function start(){ if(raf) return; last=0; raf=requestAnimationFrame(loop); }
+  function stop(){ if(raf){ cancelAnimationFrame(raf); raf=null; } }
+
+  function staticRender(){
+    POOLS.forEach(function(p){ p.wait.forEach(function(t,i){ t.x=445; t.y=p.y-20+i*13; }); assignPool(p);
+      p.nodes.forEach(function(nd){ if(nd.busy){ nd.busy.x=nd.x; nd.busy.y=nd.y; nd.busy.phase='processing'; } paintNode(nd); }); });
+    tokens.forEach(function(t){ if(t.el){ t.el.setAttribute('cx',t.x.toFixed(1)); t.el.setAttribute('cy',t.y.toFixed(1)); } });
+    paintStats();
+  }
+  function seedStatic(){
+    emit(7);
+    tokens.forEach(function(t){ t.x=EX; t.y=t.pool.y; arriveEntry(t); });
+    staticRender();
+  }
+
+  window.__taskitoDemos=window.__taskitoDemos||{};
+  var pm=window.__taskitoDemos.motion, pr=window.__taskitoDemos.recolor;
+  window.__taskitoDemos.motion=function(off){ if(pm)pm(off); if(off){ stop(); staticRender(); } else { start(); } };
+  window.__taskitoDemos.recolor=function(){ if(pr)pr(); POOLS.forEach(function(p){ p.nodes.forEach(paintNode); }); };
+
+  POOLS.forEach(function(p){ p.nodes.forEach(paintNode); });
+  if(motionOff()){ seedStatic(); }
+  else { emit(3); start(); }
+})();
diff --git a/docs/public/demos/demo-playground.js b/docs/public/demos/demo-playground.js
new file mode 100644
index 00000000..980e0d7e
--- /dev/null
+++ b/docs/public/demos/demo-playground.js
@@ -0,0 +1,213 @@
+/* ============================================================
+   taskito · Demo 03 — Worker scaling playground
+   Sliders drive a stochastic queue simulation; throughput,
+   queue-depth and latency charts respond live on Canvas 2D.
+   Tier-1: Canvas 2D + requestAnimationFrame. No WebGL.
+   ============================================================ */
+(function(){
+  var root=document.getElementById('wp-root');
+  if(!root) return;
+
+  var P={ workers:4, conc:2, lambda:18, jobMs:300, rate:0 }; // rate 0 = off
+  var FIELDS=[
+    {k:'workers', n:'Workers', sub:'pool size',     min:1, max:12, step:1, fmt:function(v){return v;}},
+    {k:'conc',    n:'Concurrency', sub:'per worker', min:1, max:8,  step:1, fmt:function(v){return '×'+v;}},
+    {k:'lambda',  n:'Arrival rate', sub:'jobs / s',  min:1, max:80, step:1, fmt:function(v){return v+'/s';}},
+    {k:'jobMs',   n:'Avg job time', sub:'milliseconds',min:50, max:1200, step:25, fmt:function(v){return v+'ms';}},
+    {k:'rate',    n:'Rate limit', sub:'0 = unlimited',min:0, max:60, step:2, fmt:function(v){return v===0?'off':v+'/s';}}
+  ];
+
+  root.innerHTML=
+  '<div class="demo-bar">'+
+    '<span class="title"><span class="ld"></span>worker-pool · simulation</span>'+
+    '<div class="demo-controls">'+
+      '<button class="ctl" id="wp-reset"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"><path d="M3 12a9 9 0 1 0 3-6.7L3 8"/><path d="M3 3v5h5"/></svg>Reset</button>'+
+    '</div>'+
+  '</div>'+
+  '<div class="wp-grid">'+
+    '<div class="wp-ctl" id="wp-fields"></div>'+
+    '<div class="wp-charts">'+
+      chart('throughput','Throughput','wp-c-thr','wp-v-thr','/s','var(--indigo-br)')+
+      chart('queue','Queue depth','wp-c-q','wp-v-q','jobs','var(--amber)')+
+      chart('latency','Latency (p50)','wp-c-lat','wp-v-lat','ms','var(--cyan)')+
+    '</div>'+
+  '</div>';
+
+  function chart(id,title,cid,vid,unit,col){
+    return '<div class="wp-chart"><div class="ch-hd"><span class="t"><i style="background:'+col+'"></i>'+title+'</span>'+
+      '<span class="now" id="'+vid+'">0<span class="u">'+unit+'</span></span></div>'+
+      '<canvas class="wp-canvas" id="'+cid+'"></canvas></div>';
+  }
+
+  // ---- build sliders ----
+  var fieldsEl=document.getElementById('wp-fields');
+  FIELDS.forEach(function(f){
+    var wrap=document.createElement('div'); wrap.className='wp-field';
+    wrap.innerHTML='<div class="lab"><span class="n">'+f.n+' <small>'+f.sub+'</small></span><span class="val" id="wp-val-'+f.k+'">'+f.fmt(P[f.k])+'</span></div>'+
+      '<input type="range" class="wp-range" id="wp-rg-'+f.k+'" min="'+f.min+'" max="'+f.max+'" step="'+f.step+'" value="'+P[f.k]+'" aria-label="'+f.n+'">';
+    fieldsEl.appendChild(wrap);
+    var rg=wrap.querySelector('input');
+    rg.addEventListener('input',function(){
+      P[f.k]=+rg.value;
+      document.getElementById('wp-val-'+f.k).textContent=f.fmt(P[f.k]);
+      if(motionOff()) staticEval();
+    });
+  });
+  var capEl=document.createElement('div'); capEl.className='wp-cap'; capEl.id='wp-cap'; fieldsEl.appendChild(capEl);
+
+  document.getElementById('wp-reset').addEventListener('click',function(){
+    P={workers:4,conc:2,lambda:18,jobMs:300,rate:0};
+    FIELDS.forEach(function(f){ var rg=document.getElementById('wp-rg-'+f.k); rg.value=P[f.k]; document.getElementById('wp-val-'+f.k).textContent=f.fmt(P[f.k]); });
+    N=0; reseed(); if(motionOff()) staticEval();
+  });
+
+  // ---- simulation ----
+  var N=0;            // jobs in system
+  var tokens=0;       // rate-limit token bucket
+  var thrEMA=0, latEMA=0;
+  var BUF=170;
+  var hThr=new Array(BUF).fill(0), hQ=new Array(BUF).fill(0), hLat=new Array(BUF).fill(0);
+
+  function poisson(mean){ // small-mean sampler (Knuth)
+    if(mean<=0) return 0;
+    if(mean>30) return Math.max(0,Math.round(mean+Math.sqrt(mean)*gauss()));
+    var L=Math.exp(-mean),k=0,p=1;
+    do{ k++; p*=Math.random(); }while(p>L);
+    return k-1;
+  }
+  function gauss(){ var u=Math.random(),v=Math.random(); return Math.sqrt(-2*Math.log(u||1e-9))*Math.cos(6.283185*v); }
+
+  function stepSim(dt){
+    var C=P.workers*P.conc;
+    var inService=Math.min(N,C);
+    // arrivals
+    var arr=poisson(P.lambda*dt);
+    N+=arr;
+    inService=Math.min(N,C);
+    // rate-limit bucket
+    var rl=P.rate>0;
+    if(rl){ tokens=Math.min(P.rate, tokens+P.rate*dt); }
+    // service completions ~ inService * dt / jobTime
+    var svcMean=inService*dt/(P.jobMs/1000);
+    var done=poisson(svcMean);
+    done=Math.min(done, N);
+    if(rl){ done=Math.min(done, Math.floor(tokens)); tokens-=done; }
+    N-=done;
+    // metrics
+    var inst=dt>0?done/dt:0; // jobs/s this step
+    thrEMA=thrEMA+(inst-thrEMA)*Math.min(1,dt*3.2);
+    var q=Math.max(0,N-C);
+    var lat = thrEMA>0.2 ? (N/thrEMA)*1000 : (N>0? 9000 : 0); // Little's law, ms
+    latEMA=latEMA+(lat-latEMA)*Math.min(1,dt*2.2);
+    push(thrEMA,q,latEMA);
+  }
+  function push(t,q,l){ hThr.push(t);hThr.shift(); hQ.push(q);hQ.shift(); hLat.push(l);hLat.shift(); }
+  function reseed(){ hThr=new Array(BUF).fill(0);hQ=new Array(BUF).fill(0);hLat=new Array(BUF).fill(0);thrEMA=0;latEMA=0;tokens=P.rate; }
+
+  // ---- chart drawing ----
+  var cv={thr:cvs('wp-c-thr'),q:cvs('wp-c-q'),lat:cvs('wp-c-lat')};
+  function cvs(id){ var c=document.getElementById(id); return {c:c,ctx:c.getContext('2d'),w:0,h:0}; }
+  var probe=document.createElement('span'); probe.style.cssText='position:absolute;opacity:0;pointer-events:none'; document.body.appendChild(probe);
+  function rgb(varexpr){ probe.style.color=varexpr; return getComputedStyle(probe).color; }
+  var COLORS={};
+  function refreshColors(){
+    COLORS={ thr:rgb('var(--indigo-br)'), q:rgb('var(--amber)'), lat:rgb('var(--cyan)'),
+             grid:rgb('var(--line)'), txt:rgb('var(--dim)') };
+  }
+  function sizeCanvas(o){
+    var dpr=Math.min(2,window.devicePixelRatio||1);
+    var w=o.c.clientWidth, h=o.c.clientHeight||84;
+    o.w=w; o.h=h; o.c.width=w*dpr; o.c.height=h*dpr; o.ctx.setTransform(dpr,0,0,dpr,0,0);
+  }
+  function sizeAll(){ sizeCanvas(cv.thr);sizeCanvas(cv.q);sizeCanvas(cv.lat); }
+
+  function drawChart(o,data,color,yMin,yMaxFloor){
+    var ctx=o.ctx,w=o.w,h=o.h; ctx.clearRect(0,0,w,h);
+    var pad=6, gh=h-pad*2;
+    var max=yMaxFloor;
+    for(var i=0;i<data.length;i++){ if(data[i]>max) max=data[i]; }
+    max=max*1.18+0.001;
+    // baseline grid
+    ctx.strokeStyle=COLORS.grid; ctx.lineWidth=1;
+    ctx.beginPath(); ctx.moveTo(0,h-pad); ctx.lineTo(w,h-pad); ctx.stroke();
+    ctx.beginPath(); ctx.moveTo(0,pad); ctx.lineTo(w,pad); ctx.globalAlpha=.5; ctx.stroke(); ctx.globalAlpha=1;
+    var n=data.length, dx=w/(n-1);
+    function X(i){return i*dx;} function Y(v){return pad+gh-(Math.min(v,max)/max)*gh;}
+    // fill
+    ctx.beginPath(); ctx.moveTo(0,h-pad);
+    for(var i=0;i<n;i++){ ctx.lineTo(X(i),Y(data[i])); }
+    ctx.lineTo(w,h-pad); ctx.closePath();
+    var grad=ctx.createLinearGradient(0,pad,0,h);
+    grad.addColorStop(0,withAlpha(color,.30)); grad.addColorStop(1,withAlpha(color,.02));
+    ctx.fillStyle=grad; ctx.fill();
+    // line
+    ctx.beginPath();
+    for(var i=0;i<n;i++){ var x=X(i),y=Y(data[i]); i?ctx.lineTo(x,y):ctx.moveTo(x,y); }
+    ctx.strokeStyle=color; ctx.lineWidth=2; ctx.lineJoin='round'; ctx.stroke();
+    // head dot
+    var hx=X(n-1),hy=Y(data[n-1]);
+    ctx.beginPath(); ctx.arc(hx,hy,3,0,6.2832); ctx.fillStyle=color; ctx.fill();
+    ctx.beginPath(); ctx.arc(hx,hy,5.5,0,6.2832); ctx.strokeStyle=withAlpha(color,.4); ctx.lineWidth=1.5; ctx.stroke();
+  }
+  function withAlpha(rgbStr,a){ var m=rgbStr.match(/\d+/g); if(!m) return rgbStr; return 'rgba('+m[0]+','+m[1]+','+m[2]+','+a+')'; }
+
+  function drawAll(){
+    drawChart(cv.thr,hThr,COLORS.thr,0,8);
+    drawChart(cv.q,hQ,COLORS.q,0,6);
+    drawChart(cv.lat,hLat,COLORS.lat,0,400);
+    // readouts
+    setV('wp-v-thr', hThr[BUF-1].toFixed(1), '/s');
+    setV('wp-v-q', Math.round(hQ[BUF-1]), 'jobs');
+    setV('wp-v-lat', Math.round(hLat[BUF-1]), 'ms');
+    paintCap();
+  }
+  function setV(id,val,u){ var e=document.getElementById(id); e.innerHTML=val+'<span class="u">'+u+'</span>'; }
+
+  function paintCap(){
+    var C=P.workers*P.conc;
+    var svcCap=C/(P.jobMs/1000);
+    var cap=P.rate>0?Math.min(svcCap,P.rate):svcCap;
+    var verdict,vcls;
+    if(cap>=P.lambda*1.12){ verdict='Keeping up — pool has headroom.'; vcls='good'; }
+    else if(cap>=P.lambda*0.97){ verdict='Saturated — running near capacity.'; vcls='warn'; }
+    else { verdict='Overloaded — queue is growing.'; vcls='bad'; }
+    capEl.innerHTML='<b>'+C+'</b> in-flight slots · capacity <b>≈'+cap.toFixed(0)+'/s</b> vs demand <b>'+P.lambda+'/s</b>'+
+      (P.rate>0?' · capped at '+P.rate+'/s':'')+
+      '<span class="verdict '+vcls+'">'+verdict+'</span>';
+  }
+
+  // ---- loop ----
+  function motionOff(){ return window.__motionOff || (window.matchMedia && window.matchMedia('(prefers-reduced-motion:reduce)').matches); }
+  var raf=null,last=0;
+  function loop(now){
+    if(!last) last=now; var dt=Math.min((now-last)/1000,0.05); last=now;
+    var sub=2; for(var i=0;i<sub;i++) stepSim(dt/sub*1.6);
+    drawAll();
+    raf=requestAnimationFrame(loop);
+  }
+  function start(){ if(raf||motionOff()) return; last=0; raf=requestAnimationFrame(loop); }
+  function stop(){ if(raf){cancelAnimationFrame(raf);raf=null;} }
+
+  function staticEval(){
+    // fill buffers with steady-ish snapshot (no animation)
+    reseed();
+    for(var i=0;i<260;i++) stepSim(0.1);
+    refreshColors(); sizeAll(); drawAll();
+  }
+
+  window.addEventListener('resize',function(){ sizeAll(); refreshColors(); drawAll(); });
+
+  window.__taskitoDemos=window.__taskitoDemos||{};
+  var pm=window.__taskitoDemos.motion, pr=window.__taskitoDemos.recolor;
+  window.__taskitoDemos.motion=function(off){ if(pm)pm(off); if(off){ stop(); staticEval(); } else { reseed(); start(); } };
+  window.__taskitoDemos.recolor=function(){ if(pr)pr(); refreshColors(); drawAll(); };
+  // theme flips → recolor
+  new MutationObserver(function(){ refreshColors(); drawAll(); }).observe(document.documentElement,{attributes:true,attributeFilter:['data-theme']});
+
+  // init
+  requestAnimationFrame(function(){
+    sizeAll(); refreshColors();
+    if(motionOff()){ staticEval(); }
+    else { reseed(); tokens=P.rate; start(); }
+  });
+})();
diff --git a/docs/public/demos/demo-ratelimit.js b/docs/public/demos/demo-ratelimit.js
new file mode 100644
index 00000000..e53786d8
--- /dev/null
+++ b/docs/public/demos/demo-ratelimit.js
@@ -0,0 +1,293 @@
+/* ============================================================
+   taskito · Demo 01 — API rate limiting
+   Request -> Queue -> Workers -> External API, with 429 + backoff.
+   Tier-1: SVG + requestAnimationFrame. No WebGL.
+   ============================================================ */
+(function(){
+  var root=document.getElementById('rl-root');
+  if(!root) return;
+
+  var W=960,H=300,CY=152;
+  var NWORK=5;
+  var PROC=1050, BACKOFF_BASE=620, MAX_RETRY=4, SPEED=560;
+  var SPAWN_MS=1000, QCAP=12;
+
+  // worker slot anchors
+  var slots=[];
+  for(var i=0;i<NWORK;i++){ slots.push({x:622, y:86+i*38, busy:null}); }
+  var PRO={x:90,y:CY}, QBOX={x:286,w:108,y:CY}, API={x:862,y:CY};
+
+  // ---- build DOM ----
+  root.innerHTML =
+  '<div class="demo-bar">'+
+    '<span class="title"><span class="ld"></span>rate-limit · live</span>'+
+    '<div class="demo-controls">'+
+      '<button class="ctl pri" id="rl-burst"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"><path d="M13 2 3 14h7l-1 8 10-12h-7l1-8z"/></svg>Send burst (8)</button>'+
+      '<div class="seg" id="rl-api" role="group" aria-label="External API status">'+
+        '<button data-v="ok" class="good" data-on="1"><span class="dot"></span>API: 200 OK</button>'+
+        '<button data-v="429" class="bad" data-on="0"><span class="dot"></span>API: 429</button>'+
+      '</div>'+
+    '</div>'+
+  '</div>'+
+  '<div class="stage"><svg id="rl-svg" viewBox="0 0 '+W+' '+H+'" role="img" aria-label="Animated pipeline: requests move from your code into a queue, are picked up by a pool of workers, and call an external API. When the API returns 429, calls fail and retry with exponential backoff.">'+
+    '<defs>'+
+      '<marker id="rl-ar" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="6" markerHeight="6" orient="auto"><path d="M1 1 L9 5 L1 9" fill="none" stroke="var(--line3)" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round"/></marker>'+
+    '</defs>'+
+    // guide wires
+    '<path d="M150 152 H286" fill="none" stroke="var(--line2)" stroke-width="2" stroke-dasharray="2 7" stroke-linecap="round" marker-end="url(#rl-ar)"/>'+
+    '<path d="M394 152 H560" fill="none" stroke="var(--line2)" stroke-width="2" stroke-dasharray="2 7" stroke-linecap="round" marker-end="url(#rl-ar)"/>'+
+    '<path d="M690 152 H800" fill="none" stroke="var(--line2)" stroke-width="2" stroke-dasharray="2 7" stroke-linecap="round" marker-end="url(#rl-ar)"/>'+
+    // retry return curve
+    '<path id="rl-retpath" d="M862 196 C 862 270, 340 286, 300 244" fill="none" stroke="color-mix(in oklch,var(--red) 45%,transparent)" stroke-width="2" stroke-dasharray="2 7" stroke-linecap="round" opacity="0"/>'+
+    '<text x="560" y="284" text-anchor="middle" id="rl-retlbl" font-family="var(--mono)" font-size="11" fill="var(--red)" opacity="0">retry · exponential backoff</text>'+
+    // producer box
+    '<g><rect x="30" y="120" width="120" height="64" rx="13" fill="var(--panel3)" stroke="var(--line2)"/>'+
+      '<text x="90" y="146" text-anchor="middle" font-family="var(--mono)" font-size="11" fill="var(--mut)">your code</text>'+
+      '<text x="90" y="165" text-anchor="middle" font-family="var(--code)" font-size="12" font-weight="600" fill="var(--txt2)">.delay()</text></g>'+
+    // queue box
+    '<g><rect x="280" y="86" width="120" height="132" rx="13" fill="var(--panel)" stroke="var(--line2)"/>'+
+      '<text x="340" y="106" text-anchor="middle" font-family="var(--mono)" font-size="11" fill="var(--mut)">QUEUE</text>'+
+      '<text x="340" y="240" text-anchor="middle" font-family="var(--code)" font-size="11" fill="var(--dim)" id="rl-qovf"></text></g>'+
+    // worker pool frame
+    '<g><rect x="560" y="64" width="124" height="176" rx="13" fill="none" stroke="var(--line2)" stroke-dasharray="3 6"/>'+
+      '<text x="622" y="58" text-anchor="middle" font-family="var(--mono)" font-size="11" fill="var(--mut)">WORKERS · '+NWORK+'</text></g>'+
+    workerSlotsSVG()+
+    // api box
+    '<g id="rl-apibox"><rect x="800" y="110" width="128" height="84" rx="13" fill="var(--panel3)" stroke="var(--line2)" id="rl-apirect"/>'+
+      '<text x="864" y="138" text-anchor="middle" font-family="var(--mono)" font-size="11" fill="var(--mut)">external API</text>'+
+      '<g id="rl-apistat" transform="translate(864,162)"><rect x="-34" y="-13" width="68" height="26" rx="13" fill="color-mix(in oklch,var(--grn) 16%,transparent)" stroke="color-mix(in oklch,var(--grn) 40%,transparent)" id="rl-apipill"/>'+
+        '<text x="0" y="5" text-anchor="middle" font-family="var(--code)" font-size="12" font-weight="700" fill="var(--grn)" id="rl-apitext">200</text></g></g>'+
+    '<g id="rl-tokens"></g>'+
+  '</svg></div>'+
+  '<div class="legend">'+
+    '<span><i style="background:var(--indigo-br)"></i>queued</span>'+
+    '<span><i style="background:var(--cyan)"></i>processing</span>'+
+    '<span><i style="background:var(--grn)"></i>succeeded</span>'+
+    '<span><i style="background:var(--red)"></i>429 · retrying</span>'+
+    '<span><i style="background:var(--amber)"></i>backoff wait</span>'+
+  '</div>'+
+  '<div class="readout">'+
+    stat('queue depth','rl-qd')+stat('in flight','rl-if')+stat('retries','rl-rt')+
+    stat('429 blocked','rl-bk','bad')+stat('succeeded','rl-sc','good')+stat('backoff','rl-bo','warn','s')+
+  '</div>';
+
+  function workerSlotsSVG(){
+    var s='';
+    slots.forEach(function(w,i){
+      s+='<rect x="'+(w.x-22)+'" y="'+(w.y-15)+'" width="44" height="30" rx="8" fill="var(--panel2)" stroke="var(--line2)" id="rl-ws'+i+'"/>';
+    });
+    return s;
+  }
+  function stat(k,id,cls,u){
+    return '<div class="stat"><span class="k">'+k+'</span><span class="v'+(cls?' '+cls:'')+'" id="'+id+'">0'+(u?'<span class="u">'+u+'</span>':'')+'</span></div>';
+  }
+
+  // ---- state ----
+  var tokens=[], idc=0, apiOK=true;
+  var metrics={retries:0, blocked:0, succeeded:0};
+  var gTok=document.getElementById('rl-tokens');
+  var elQd=g('rl-qd'),elIf=g('rl-if'),elRt=g('rl-rt'),elBk=g('rl-bk'),elSc=g('rl-sc'),elBo=g('rl-bo'),elOvf=g('rl-qovf');
+  function g(id){return document.getElementById(id);}
+
+  var COL={queued:'var(--indigo-br)',proc:'var(--cyan)',toapi:'var(--cyan)',success:'var(--grn)',block:'var(--red)',backoff:'var(--amber)'};
+  function colorFor(t){
+    if(t.phase==='success') return COL.success;
+    if(t.phase==='backoff') return COL.backoff;
+    if(t.blocked) return COL.block;
+    if(t.phase==='processing'||t.phase==='toworker'||t.phase==='toapi') return COL.proc;
+    return COL.queued;
+  }
+
+  function spawn(n){
+    for(var i=0;i<n;i++){
+      if(tokens.length>40) break;
+      var t={id:++idc,x:PRO.x,y:PRO.y+(Math.random()*20-10),phase:'toqueue',retries:0,blocked:false,
+        tx:QBOX.x+12,ty:CY,r:6,worker:null,pUntil:0,bUntil:0,born:performance.now()};
+      var el=document.createElementNS('http://www.w3.org/2000/svg','circle');
+      el.setAttribute('r','6'); t.el=el; gTok.appendChild(el);
+      tokens.push(t);
+    }
+  }
+
+  function queuedList(){ return tokens.filter(function(t){return t.phase==='queued';}); }
+
+  function assignWorkers(){
+    var q=queuedList();
+    slots.forEach(function(w){
+      if(w.busy==null && q.length){
+        var t=q.shift();
+        w.busy=t.id; t.worker=slots.indexOf(w);
+        t.phase='toworker'; t.tx=w.x; t.ty=w.y;
+      }
+    });
+  }
+
+  function resolveAPI(t){
+    var w=slots[t.worker];
+    if(apiOK){
+      t.phase='success'; t.blocked=false; t.tx=W; t.ty=CY;
+      metrics.succeeded++;
+      if(w) w.busy=null; t.worker=null;
+    } else {
+      metrics.blocked++; t.retries++; t.blocked=true;
+      if(w) w.busy=null; t.worker=null;
+      if(t.retries>MAX_RETRY){
+        t.phase='dead'; t.tx=t.x; t.ty=t.y+0; t.dead=performance.now();
+      } else {
+        metrics.retries++;
+        t.phase='backoff'; t.bUntil=performance.now()+BACKOFF_BASE*Math.pow(2,t.retries-1);
+        t.tx=QBOX.x+QBOX.w/2; t.ty=CY+58; // park below queue on the return lane
+      }
+    }
+  }
+
+  function step(now,dt){
+    // spawn cadence
+    if(!motionOff()){
+      spawnAcc+=dt;
+      if(spawnAcc>SPAWN_MS){ spawnAcc=0; if(queuedList().length<22) spawn(1); }
+    }
+    assignWorkers();
+
+    // position queued tokens into a packed grid
+    var ql=queuedList();
+    ql.forEach(function(t,i){
+      var col=i%3, rowi=Math.floor(i/3);
+      t.tx=300+col*34; t.ty=120+rowi*30;
+    });
+
+    var move=SPEED*dt/1000;
+    for(var i=tokens.length-1;i>=0;i--){
+      var t=tokens[i];
+      // arrival-driven transitions
+      var dx=t.tx-t.x, dy=t.ty-t.y, d=Math.hypot(dx,dy);
+      if(d>0.5){
+        var s=Math.min(move,d);
+        t.x+=dx/d*s; t.y+=dy/d*s;
+      }
+      var arrived=d<3;
+      switch(t.phase){
+        case 'toqueue': if(arrived){ t.phase='queued'; t.blocked=false; } break;
+        case 'toworker': if(arrived){ t.phase='processing'; t.pUntil=now+PROC*(0.8+Math.random()*0.5); } break;
+        case 'processing': if(now>=t.pUntil){ t.phase='toapi'; t.tx=API.x-26; t.ty=CY; } break;
+        case 'toapi': if(arrived){ resolveAPI(t); } break;
+        case 'backoff': if(now>=t.bUntil){ t.phase='toqueue'; t.tx=QBOX.x+12; t.ty=CY; } break;
+        case 'success': if(t.x>=W-1){ remove(t,i); } break;
+        case 'dead': if(now-t.dead>900){ remove(t,i); } break;
+      }
+      // render
+      if(t.el){
+        t.el.setAttribute('cx',t.x.toFixed(1));
+        t.el.setAttribute('cy',t.y.toFixed(1));
+        t.el.style.fill=colorFor(t);
+        var op = '1';
+        if(t.phase==='dead') op='0.25';
+        else if(t.phase==='backoff') op='0.85';
+        else if(t.phase==='success') op=Math.max(0,1-(t.x-API.x)/(W-API.x)).toFixed(2); // fade out as it exits
+        t.el.style.opacity=op;
+        t.el.setAttribute('r', t.phase==='processing'?'6.5':'6');
+      }
+    }
+    paintWorkers();
+    paintMetrics(ql.length);
+  }
+  function remove(t,i){ if(t.el&&t.el.parentNode) t.el.parentNode.removeChild(t.el); tokens.splice(i,1); }
+
+  function paintWorkers(){
+    slots.forEach(function(w,i){
+      var r=document.getElementById('rl-ws'+i);
+      if(!r) return;
+      var busy=w.busy!=null;
+      r.setAttribute('fill', busy? (apiOK?'color-mix(in oklch,var(--cyan) 18%,transparent)':'color-mix(in oklch,var(--red) 16%,transparent)') : 'var(--panel2)');
+      r.setAttribute('stroke', busy? (apiOK?'color-mix(in oklch,var(--cyan) 45%,transparent)':'color-mix(in oklch,var(--red) 45%,transparent)') : 'var(--line2)');
+    });
+  }
+
+  function paintMetrics(qd){
+    var inflight=tokens.filter(function(t){return t.phase==='toworker'||t.phase==='processing'||t.phase==='toapi';}).length;
+    var backoff=tokens.filter(function(t){return t.phase==='backoff';}).length;
+    var maxBo=0; tokens.forEach(function(t){ if(t.phase==='backoff'){ var s=(t.bUntil-performance.now())/1000; if(s>maxBo)maxBo=s; } });
+    elQd.firstChild ? (elQd.childNodes[0].nodeValue=qd) : (elQd.textContent=qd);
+    setNum(elQd,qd); setNum(elIf,inflight); setNum(elRt,metrics.retries);
+    setNum(elBk,metrics.blocked); setNum(elSc,metrics.succeeded);
+    elBo.innerHTML=(maxBo>0?maxBo.toFixed(1):'0')+'<span class="u">s</span>';
+    elBo.className='v '+(maxBo>0?'warn':'');
+    var ovf=qd-QCAP; elOvf.textContent = ovf>0? '+'+ovf+' more' : '';
+    // retry lane visibility
+    var ret=document.getElementById('rl-retpath'), rl=document.getElementById('rl-retlbl');
+    var on = backoff>0 || !apiOK;
+    ret.setAttribute('opacity', on?'0.7':'0'); rl.setAttribute('opacity', on?'0.9':'0');
+  }
+  function setNum(el,v){ el.childNodes.length>1 ? (el.childNodes[0].nodeValue=v) : (el.textContent=v); }
+
+  function setAPI(ok){
+    apiOK=ok;
+    var pill=document.getElementById('rl-apipill'), txt=document.getElementById('rl-apitext'), rect=document.getElementById('rl-apirect');
+    if(ok){
+      pill.setAttribute('fill','color-mix(in oklch,var(--grn) 16%,transparent)');
+      pill.setAttribute('stroke','color-mix(in oklch,var(--grn) 40%,transparent)');
+      txt.setAttribute('fill','var(--grn)'); txt.textContent='200';
+      rect.setAttribute('stroke','var(--line2)');
+    } else {
+      pill.setAttribute('fill','color-mix(in oklch,var(--red) 18%,transparent)');
+      pill.setAttribute('stroke','color-mix(in oklch,var(--red) 48%,transparent)');
+      txt.setAttribute('fill','var(--red)'); txt.textContent='429';
+      rect.setAttribute('stroke','color-mix(in oklch,var(--red) 40%,transparent)');
+    }
+    var segBtns=document.querySelectorAll('#rl-api button');
+    segBtns.forEach(function(b){ b.setAttribute('data-on', (b.getAttribute('data-v')==='ok')===ok ? '1':'0'); });
+  }
+
+  // ---- controls ----
+  document.getElementById('rl-burst').addEventListener('click',function(){ spawn(8); if(motionOff()) staticRender(); });
+  document.querySelectorAll('#rl-api button').forEach(function(b){
+    b.addEventListener('click',function(){ setAPI(b.getAttribute('data-v')==='ok'); if(motionOff()) staticRender(); });
+  });
+
+  // ---- motion / loop ----
+  function motionOff(){ return window.__motionOff || (window.matchMedia && window.matchMedia('(prefers-reduced-motion:reduce)').matches); }
+  var spawnAcc=0, last=0, raf=null;
+  function loop(now){
+    if(!last) last=now; var dt=Math.min(now-last,60); last=now;
+    step(now,dt);
+    raf=requestAnimationFrame(loop);
+  }
+  function start(){ if(raf) return; last=0; raf=requestAnimationFrame(loop); }
+  function stop(){ if(raf){ cancelAnimationFrame(raf); raf=null; } }
+
+  function staticRender(){
+    // snapshot frame for reduced motion: snap positions, single step of layout.
+    // Promote in-flight burst tokens (heading for the queue) so they show up in
+    // queue depth instead of stranding at the producer until motion resumes.
+    tokens.forEach(function(t){ if(t.phase==='toqueue'){ t.phase='queued'; t.blocked=false; } });
+    var ql=queuedList();
+    ql.forEach(function(t,i){ var col=i%3,rowi=Math.floor(i/3); t.x=300+col*34; t.y=120+rowi*30; });
+    tokens.forEach(function(t){ if(t.el){ t.el.setAttribute('cx',t.x.toFixed(1)); t.el.setAttribute('cy',t.y.toFixed(1)); t.el.style.fill=colorFor(t);} });
+    assignWorkers(); paintWorkers(); paintMetrics(ql.length);
+  }
+
+  function seedStatic(){
+    spawn(9);
+    // pre-place: some queued, fill workers
+    tokens.forEach(function(t){ t.phase='queued'; });
+    assignWorkers();
+    tokens.forEach(function(t){ if(t.worker!=null){ t.phase='processing'; t.x=slots[t.worker].x; t.y=slots[t.worker].y; } });
+    staticRender();
+  }
+
+  // expose for tweaks
+  window.__taskitoDemos=window.__taskitoDemos||{};
+  var prevMotion=window.__taskitoDemos.motion, prevRecolor=window.__taskitoDemos.recolor;
+  window.__taskitoDemos.motion=function(off){ if(prevMotion)prevMotion(off); if(off){ stop(); staticRender(); } else { start(); } };
+  window.__taskitoDemos.recolor=function(){ if(prevRecolor)prevRecolor(); /* svg uses var() inline, repaints automatically */ };
+
+  setAPI(true);
+  // start when visible (lazy) — but kick a static seed immediately
+  if(motionOff()){ seedStatic(); }
+  else {
+    spawn(4);
+    var io=new IntersectionObserver(function(es){ es.forEach(function(e){ if(e.isIntersecting){ start(); } else { /* keep running */ } }); },{threshold:0.05});
+    io.observe(root);
+    start();
+  }
+})();
diff --git a/docs/public/demos/demo-recovery.js b/docs/public/demos/demo-recovery.js
new file mode 100644
index 00000000..b192f20c
--- /dev/null
+++ b/docs/public/demos/demo-recovery.js
@@ -0,0 +1,236 @@
+/* ============================================================
+   taskito · Demo 02 — Failure recovery (scrubbable timeline)
+   Drag the playhead across one job's lifecycle. Toggle the
+   ending: recover on the last retry, or exhaust into the DLQ.
+   Tier-1: HTML + CSS + pointer events. No WebGL.
+   ============================================================ */
+(function(){
+  var root=document.getElementById('fr-root');
+  if(!root) return;
+
+  var STATES={
+    Queued:  {c:'var(--indigo-br)', soft:'var(--indigo-soft)', line:'var(--indigo-line)'},
+    Running: {c:'var(--cyan)',  soft:'color-mix(in oklch,var(--cyan) 14%,transparent)', line:'color-mix(in oklch,var(--cyan) 40%,transparent)'},
+    Failed:  {c:'var(--red)',   soft:'color-mix(in oklch,var(--red) 13%,transparent)',  line:'color-mix(in oklch,var(--red) 42%,transparent)'},
+    Retrying:{c:'var(--amber)', soft:'color-mix(in oklch,var(--amber) 14%,transparent)',line:'color-mix(in oklch,var(--amber) 42%,transparent)'},
+    Complete:{c:'var(--grn)',   soft:'color-mix(in oklch,var(--grn) 14%,transparent)',  line:'color-mix(in oklch,var(--grn) 42%,transparent)'},
+    Dead:    {c:'var(--txt2)',  soft:'var(--panel3)', line:'var(--line3)'}
+  };
+
+  function base(){
+    return [
+      {t:0,    state:'Queued',  att:0, ttl:'Enqueued', d:'Accepted into the queue · status pending'},
+      {t:800,  state:'Running', att:1, ttl:'Dispatched', d:'Worker picked up the job · attempt 1'},
+      {t:2600, state:'Failed',  att:1, ttl:'Error', d:'ConnectionError: upstream returned 503'},
+      {t:3000, state:'Retrying',att:1, ttl:'Backoff', d:'Waiting 2.0s before retry 2'},
+      {t:5000, state:'Running', att:2, ttl:'Dispatched', d:'Worker picked up the job · attempt 2'},
+      {t:6800, state:'Failed',  att:2, ttl:'Error', d:'ConnectionError: upstream returned 503'},
+      {t:7200, state:'Retrying',att:2, ttl:'Backoff', d:'Waiting 4.0s before retry 3'},
+      {t:11200,state:'Running', att:3, ttl:'Dispatched', d:'Worker picked up the job · attempt 3'}
+    ];
+  }
+  var SCEN={
+    recover: base().concat([
+      {t:12700, state:'Complete', att:3, ttl:'Success', d:'Returned in 1.5s · result written to store'}
+    ]),
+    dlq: base().concat([
+      {t:13000, state:'Failed', att:3, ttl:'Error', d:'ConnectionError: upstream returned 503'},
+      {t:13300, state:'Dead',  att:3, ttl:'Dead-letter', d:'Max retries (3) exhausted → moved to DLQ'}
+    ])
+  };
+  var TAIL=1400;
+
+  root.innerHTML=
+  '<div class="demo-bar">'+
+    '<span class="title"><span class="ld"></span>job 01J8…f3 · lifecycle</span>'+
+    '<div class="demo-controls">'+
+      '<button class="ctl" id="fr-play"><svg viewBox="0 0 24 24" fill="currentColor" stroke="none"><path d="M8 5v14l11-7z"/></svg>Play</button>'+
+      '<div class="seg" id="fr-out" role="group" aria-label="Outcome">'+
+        '<button data-v="recover" data-on="1" aria-pressed="true" class="good"><span class="dot"></span>Recovers</button>'+
+        '<button data-v="dlq" data-on="0" aria-pressed="false" class="bad"><span class="dot"></span>Dead-letter</button>'+
+      '</div>'+
+    '</div>'+
+  '</div>'+
+  '<div class="fr-scrubwrap">'+
+    '<div class="fr-track" id="fr-track" tabindex="0" role="slider" aria-label="Job timeline scrubber" aria-valuemin="0" aria-valuemax="100" aria-valuenow="0">'+
+      '<div class="fr-rail" id="fr-rail"></div>'+
+      '<div class="fr-fill" id="fr-fill"></div>'+
+      '<div class="fr-handle" id="fr-handle"></div>'+
+    '</div>'+
+    '<div class="fr-axis"><span>0.0s</span><span id="fr-axmid"></span><span id="fr-axend"></span></div>'+
+  '</div>'+
+  '<div class="fr-grid">'+
+    '<div class="fr-state">'+
+      '<span class="fr-pill" id="fr-pill"><span class="pd"></span><span id="fr-pilltext">Queued</span></span>'+
+      '<div class="big" id="fr-msg"></div>'+
+      '<div class="fr-meta">'+
+        '<div class="m"><span class="k">Elapsed</span><span class="v" id="fr-elapsed">0.0s</span></div>'+
+        '<div class="m"><span class="k">Attempt</span><span class="v" id="fr-att">0 / 3</span></div>'+
+        '<div class="m"><span class="k" id="fr-nxk">Next retry</span><span class="v" id="fr-nx">—</span></div>'+
+      '</div>'+
+      '<div><div class="k" style="font-family:var(--mono);font-size:10px;letter-spacing:.06em;text-transform:uppercase;color:var(--dim);margin-bottom:7px">Attempts</div>'+
+      '<div class="fr-attempts" id="fr-attempts"></div></div>'+
+    '</div>'+
+    '<div class="fr-log" id="fr-log"></div>'+
+  '</div>';
+
+  var scen='recover', events=SCEN[scen], DUR=dur();
+  function dur(){ return events[events.length-1].t+TAIL; }
+
+  var track=el('fr-track'), rail=el('fr-rail'), fill=el('fr-fill'), handle=el('fr-handle');
+  var elPill=el('fr-pill'), elPillT=el('fr-pilltext'), elMsg=el('fr-msg'),
+      elElapsed=el('fr-elapsed'), elAtt=el('fr-att'), elNxK=el('fr-nxk'), elNx=el('fr-nx'),
+      elAtts=el('fr-attempts'), elLog=el('fr-log');
+  function el(id){return document.getElementById(id);}
+
+  var play=0; // 0..DUR
+
+  function buildRailSegments(){
+    // colored segments + ticks
+    [].slice.call(rail.querySelectorAll('.fr-seg')).forEach(function(n){n.remove();});
+    [].slice.call(track.querySelectorAll('.fr-tick')).forEach(function(n){n.remove();});
+    for(var i=0;i<events.length;i++){
+      var a=events[i].t, b=(i+1<events.length)?events[i+1].t:DUR;
+      var seg=document.createElement('div'); seg.className='fr-seg';
+      seg.style.left=(a/DUR*100)+'%'; seg.style.width=((b-a)/DUR*100)+'%';
+      seg.style.background='color-mix(in oklch,'+STATES[events[i].state].c+' 30%, transparent)';
+      rail.appendChild(seg);
+      if(i>0){
+        var tk=document.createElement('div'); tk.className='fr-tick';
+        tk.style.left=(a/DUR*100)+'%'; tk.style.background=STATES[events[i].state].c;
+        track.appendChild(tk);
+      }
+    }
+    el('fr-axmid').textContent=(DUR/2000).toFixed(1)+'s';
+    el('fr-axend').textContent=(DUR/1000).toFixed(1)+'s';
+  }
+
+  function buildLog(){
+    elLog.innerHTML=events.map(function(e,i){
+      var st=STATES[e.state];
+      return '<div class="fr-ev" data-i="'+i+'" style="--c:'+st.c+'">'+
+        '<div class="dotcol"><span class="ed"></span><span class="eline"></span></div>'+
+        '<div class="etxt"><span class="et">'+e.ttl+'</span><span class="ed2">'+e.d+'</span></div>'+
+        '<span class="ets">'+(e.t/1000).toFixed(1)+'s</span>'+
+      '</div>';
+    }).join('');
+  }
+
+  function curIndex(){
+    var idx=0;
+    for(var i=0;i<events.length;i++){ if(events[i].t<=play+0.001) idx=i; else break; }
+    return idx;
+  }
+
+  function render(){
+    var pct=play/DUR*100;
+    fill.style.width=pct+'%'; handle.style.left=pct+'%';
+    track.setAttribute('aria-valuenow', Math.round(pct));
+    var idx=curIndex(), ev=events[idx], st=STATES[ev.state];
+    // pill
+    elPillT.textContent=ev.state;
+    elPill.style.color=st.c; elPill.style.background=st.soft; elPill.style.borderColor=st.line;
+    elPill.querySelector('.pd').style.background=st.c;
+    elMsg.innerHTML='<b>'+ev.ttl+'.</b> '+ev.d;
+    elElapsed.textContent=(play/1000).toFixed(1)+'s';
+    elAtt.textContent=ev.att+' / 3';
+    // next retry countdown
+    if(ev.state==='Retrying'){
+      var nxt=(idx+1<events.length)?events[idx+1].t:DUR;
+      elNxK.textContent='Next retry'; elNx.textContent=Math.max(0,(nxt-play)/1000).toFixed(1)+'s'; elNx.style.color='var(--amber)';
+    } else if(ev.state==='Complete'){ elNxK.textContent='Result'; elNx.textContent='stored'; elNx.style.color='var(--grn)'; }
+    else if(ev.state==='Dead'){ elNxK.textContent='Routed to'; elNx.textContent='DLQ'; elNx.style.color='var(--txt2)'; }
+    else if(ev.state==='Running'){ elNxK.textContent='Worker'; elNx.textContent='busy'; elNx.style.color='var(--cyan)'; }
+    else { elNxK.textContent='Next retry'; elNx.textContent='—'; elNx.style.color='var(--mut)'; }
+    // attempts chips
+    paintAttempts(idx);
+    // log
+    var evs=elLog.querySelectorAll('.fr-ev');
+    evs.forEach(function(n,i){ n.classList.toggle('on', i<=idx); n.classList.toggle('cur', i===idx); });
+    var curEl=evs[idx];
+    if(curEl){ var top=curEl.offsetTop-elLog.clientHeight/2+curEl.clientHeight/2; elLog.scrollTop=Math.max(0,top); }
+  }
+
+  function paintAttempts(idx){
+    // determine outcome of each attempt up to idx
+    var res={1:'',2:'',3:''};
+    for(var i=0;i<=idx;i++){
+      var e=events[i];
+      if(e.att>=1){
+        if(e.state==='Running'&&!res[e.att]) res[e.att]='pending';
+        if(e.state==='Failed') res[e.att]='fail';
+        if(e.state==='Complete') res[e.att]='ok';
+        if(e.state==='Dead') res[e.att]='dead';
+      }
+    }
+    var html='';
+    for(var a=1;a<=3;a++){
+      var r=res[a], cls='', label=a;
+      if(r==='ok'){cls='ok';label='✓';}
+      else if(r==='fail'){cls='fail';label='✕';}
+      else if(r==='dead'){cls='dead';label='☠';}
+      else if(r==='pending'){cls='';}
+      html+='<div class="a '+cls+'" title="attempt '+a+'">'+label+'</div>';
+      if(a<3) html+='<span style="color:var(--dim);font-size:11px">›</span>';
+    }
+    elAtts.innerHTML=html;
+  }
+
+  // ---- scrub interaction ----
+  var dragging=false;
+  function setFromX(clientX){
+    var r=track.getBoundingClientRect();
+    var ratio=Math.max(0,Math.min(1,(clientX-r.left)/r.width));
+    play=ratio*DUR; stopPlay(); render();
+  }
+  track.addEventListener('pointerdown',function(e){ dragging=true; track.setPointerCapture(e.pointerId); setFromX(e.clientX); });
+  track.addEventListener('pointermove',function(e){ if(dragging) setFromX(e.clientX); });
+  track.addEventListener('pointerup',function(){ dragging=false; });
+  track.addEventListener('pointercancel',function(){ dragging=false; });
+  track.addEventListener('keydown',function(e){
+    var stepK=DUR/40;
+    if(e.key==='ArrowRight'){ play=Math.min(DUR,play+stepK); stopPlay(); render(); e.preventDefault(); }
+    else if(e.key==='ArrowLeft'){ play=Math.max(0,play-stepK); stopPlay(); render(); e.preventDefault(); }
+    else if(e.key==='Home'){ play=0; stopPlay(); render(); e.preventDefault(); }
+    else if(e.key==='End'){ play=DUR; stopPlay(); render(); e.preventDefault(); }
+  });
+
+  // ---- play ----
+  var raf=null, lastT=0;
+  function motionOff(){ return window.__motionOff || (window.matchMedia && window.matchMedia('(prefers-reduced-motion:reduce)').matches); }
+  function tick(now){
+    if(!lastT) lastT=now; var dt=now-lastT; lastT=now;
+    play+=dt;
+    if(play>=DUR){ play=DUR; render(); stopPlay(); return; }
+    render(); raf=requestAnimationFrame(tick);
+  }
+  function startPlay(){
+    if(motionOff()){ play=DUR; render(); return; }
+    if(play>=DUR) play=0;
+    lastT=0; setPlayBtn(true); raf=requestAnimationFrame(tick);
+  }
+  function stopPlay(){ if(raf){ cancelAnimationFrame(raf); raf=null; } setPlayBtn(false); }
+  function setPlayBtn(on){
+    var b=el('fr-play');
+    b.innerHTML = on
+      ? '<svg viewBox="0 0 24 24" fill="currentColor" stroke="none"><rect x="6" y="5" width="4" height="14" rx="1"/><rect x="14" y="5" width="4" height="14" rx="1"/></svg>Pause'
+      : '<svg viewBox="0 0 24 24" fill="currentColor" stroke="none"><path d="M8 5v14l11-7z"/></svg>Play';
+  }
+  el('fr-play').addEventListener('click',function(){ if(raf) stopPlay(); else startPlay(); });
+
+  // ---- outcome toggle ----
+  document.querySelectorAll('#fr-out button').forEach(function(b){
+    b.addEventListener('click',function(){
+      scen=b.getAttribute('data-v'); events=SCEN[scen]; DUR=dur();
+      document.querySelectorAll('#fr-out button').forEach(function(x){ var on=x===b; x.setAttribute('data-on', on?'1':'0'); x.setAttribute('aria-pressed', on?'true':'false'); });
+      play=Math.min(play,DUR);
+      buildRailSegments(); buildLog(); render();
+    });
+  });
+
+  window.__taskitoDemos=window.__taskitoDemos||{};
+  var pm=window.__taskitoDemos.motion;
+  window.__taskitoDemos.motion=function(off){ if(pm)pm(off); if(off) stopPlay(); };
+
+  buildRailSegments(); buildLog(); render();
+})();
diff --git a/docs/public/demos/demo-saga.js b/docs/public/demos/demo-saga.js
new file mode 100644
index 00000000..ada3629b
--- /dev/null
+++ b/docs/public/demos/demo-saga.js
@@ -0,0 +1,234 @@
+/* ============================================================
+   taskito · Demo 06 — Saga / compensation
+   A distributed transaction as a chain of steps, each with a
+   compensating action. Pick where it fails and run it: forward
+   steps commit, then on failure the compensations unwind in
+   reverse so nothing is left half-done.
+   Tier-1: SVG + requestAnimationFrame. No WebGL.
+   ============================================================ */
+(function(){
+  var root=document.getElementById('saga-root');
+  if(!root) return;
+
+  var W=940,H=292, FDUR=720, CDUR=620;
+  var STEPS=[
+    {fwd:'reserve seat', f:'reserve_seat.s()', comp:'release seat', c:'release_seat.s()'},
+    {fwd:'charge card',  f:'charge_card.s()',  comp:'refund card',  c:'refund_card.s()'},
+    {fwd:'book hotel',   f:'book_hotel.s()',   comp:'cancel hotel', c:'cancel_hotel.s()'},
+    {fwd:'issue ticket', f:'issue_ticket.s()', comp:'void ticket',  c:'void_ticket.s()'}
+  ];
+  var N=STEPS.length;
+  var CX=[143,361,579,797], CYC=104, CW=178, CH=88;
+  var SVGNS='http://www.w3.org/2000/svg';
+
+  root.innerHTML=
+  '<div class="demo-bar">'+
+    '<span class="title"><span class="ld"></span>booking-saga · transaction</span>'+
+    '<div class="demo-controls">'+
+      '<div class="seg" id="saga-fail" role="group" aria-label="Where it fails">'+
+        '<button data-v="1" class="bad" data-on="1" aria-pressed="true"><span class="dot"></span>charge fails</button>'+
+        '<button data-v="2" class="bad" data-on="0" aria-pressed="false"><span class="dot"></span>hotel fails</button>'+
+        '<button data-v="-1" class="good" data-on="0" aria-pressed="false"><span class="dot"></span>all succeed</button>'+
+      '</div>'+
+      '<button class="ctl pri" id="saga-run"><svg viewBox="0 0 24 24" fill="currentColor" stroke="none"><path d="M8 5v14l11-7z"/></svg>Run saga</button>'+
+      '<button class="ctl" id="saga-reset"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"><path d="M3 12a9 9 0 1 0 3-6.7L3 8"/><path d="M3 3v5h5"/></svg>Reset</button>'+
+    '</div>'+
+  '</div>'+
+  '<div class="stage"><svg id="saga-svg" viewBox="0 0 '+W+' '+H+'" role="img" aria-label="A booking saga: reserve seat, charge card, book hotel, issue ticket. Each step has a compensating action. When a step fails, taskito runs the compensations of the committed steps in reverse order.">'+
+    '<g id="saga-edges"></g><g id="saga-cards"></g>'+
+    '<g id="saga-tokenF"><circle r="6" fill="var(--cyan)" opacity="0" id="saga-dotF"/></g>'+
+  '</svg></div>'+
+  '<div class="legend">'+
+    '<span><i style="background:var(--cyan)"></i>running</span>'+
+    '<span><i style="background:var(--grn)"></i>committed</span>'+
+    '<span><i style="background:var(--red)"></i>failed</span>'+
+    '<span><i style="background:var(--amber)"></i>compensating</span>'+
+    '<span><i style="background:var(--dim)"></i>undone</span>'+
+  '</div>'+
+  '<div class="readout">'+
+    stat('step','saga-step')+stat('committed','saga-commit','good')+stat('compensated','saga-comp','warn')+
+    stat('outcome','saga-outcome')+
+  '</div>';
+
+  function stat(k,id,cls){ return '<div class="stat"><span class="k">'+k+'</span><span class="v'+(cls?' '+cls:'')+'" id="'+id+'" style="font-size:16px">—</span></div>'; }
+  function el(id){ return document.getElementById(id); }
+
+  var gEdges=el('saga-edges'), gCards=el('saga-cards'), dotF=el('saga-dotF');
+
+  // ---- forward + reverse edges ----
+  var fEdges=[], rEdges=[];
+  for(var i=0;i<N-1;i++){
+    var x1=CX[i]+CW/2, x2=CX[i+1]-CW/2;
+    var f=mkPath('M'+x1+' '+(CYC-6)+' H '+x2, 'var(--line2)', true, gEdges);
+    fEdges.push(f);
+    var r=mkPath('M'+x2+' '+(CYC+CH/2+30)+' H '+x1, 'color-mix(in oklch,var(--amber) 50%,transparent)', true, gEdges);
+    r.setAttribute('opacity','0'); rEdges.push(r);
+  }
+  function mkPath(d,stroke,arrow,parent){
+    var p=document.createElementNS(SVGNS,'path'); p.setAttribute('d',d); p.setAttribute('fill','none');
+    p.setAttribute('stroke',stroke); p.setAttribute('stroke-width','2'); p.setAttribute('stroke-linecap','round');
+    if(arrow){ p.setAttribute('marker-end','url(#saga-ar-'+(stroke.indexOf('amber')>=0?'c':'f')+')'); }
+    parent.appendChild(p); return p;
+  }
+  // markers
+  var defs=document.createElementNS(SVGNS,'defs');
+  defs.innerHTML='<marker id="saga-ar-f" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="6" markerHeight="6" orient="auto"><path d="M1 1 L9 5 L1 9" fill="none" stroke="var(--line3)" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round"/></marker>'+
+    '<marker id="saga-ar-c" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="6" markerHeight="6" orient="auto"><path d="M1 1 L9 5 L1 9" fill="none" stroke="var(--amber)" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round"/></marker>';
+  el('saga-svg').insertBefore(defs, gEdges);
+
+  // ---- cards ----
+  var cards=[];
+  STEPS.forEach(function(s,i){
+    var cx=CX[i], x=cx-CW/2, y=CYC-CH/2;
+    var g=document.createElementNS(SVGNS,'g');
+    g.innerHTML=
+      '<rect x="'+x+'" y="'+y+'" width="'+CW+'" height="'+CH+'" rx="13" fill="var(--panel2)" stroke="var(--line2)" data-rect/>'+
+      '<text x="'+(x+15)+'" y="'+(y+22)+'" font-family="var(--mono)" font-size="9.5" letter-spacing=".06em" fill="var(--dim)">STEP '+(i+1)+'</text>'+
+      '<circle cx="'+(x+CW-16)+'" cy="'+(y+18)+'" r="4.5" fill="var(--dim)" data-pip/>'+
+      '<text x="'+(x+15)+'" y="'+(y+45)+'" font-family="var(--sans)" font-size="14.5" font-weight="600" fill="var(--txt2)" data-title>'+s.fwd+'</text>'+
+      '<text x="'+(x+15)+'" y="'+(y+66)+'" font-family="var(--code)" font-size="11" fill="var(--mut)" data-fn>'+s.f+'</text>'+
+      // compensation chip
+      '<rect x="'+(x+18)+'" y="'+(CYC+CH/2+16)+'" width="'+(CW-36)+'" height="28" rx="8" fill="var(--panel)" stroke="var(--line2)" stroke-dasharray="3 4" data-crect/>'+
+      '<path d="M'+(x+30)+' '+(CYC+CH/2+27)+' l-5 3 l5 3" fill="none" stroke="var(--dim)" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" data-carrow/>'+
+      '<text x="'+(x+40)+'" y="'+(CYC+CH/2+34)+'" font-family="var(--mono)" font-size="10.5" fill="var(--dim)" data-ctext>'+s.comp+'</text>';
+    gCards.appendChild(g);
+    cards.push({g:g, rect:g.querySelector('[data-rect]'), pip:g.querySelector('[data-pip]'),
+      title:g.querySelector('[data-title]'), crect:g.querySelector('[data-crect]'),
+      ctext:g.querySelector('[data-ctext]'), carrow:g.querySelector('[data-carrow]')});
+  });
+
+  // ---- state ----
+  var st=[], failAt=1, phase='idle', raf=null, t0=0, idx=0, stepStart=0, compQueue=[], outcome='';
+  function reset(){
+    st=STEPS.map(function(){return 'pending';});
+    phase='idle'; idx=0; compQueue=[]; outcome='';
+    fEdges.forEach(function(e){ e.setAttribute('stroke','var(--line2)'); });
+    rEdges.forEach(function(e){ e.setAttribute('opacity','0'); });
+    dotF.setAttribute('opacity','0');
+    cards.forEach(function(_,i){ paint(i); });
+    setStats(); setRunBtn(false);
+  }
+
+  var COL={
+    pending:{fill:'var(--panel2)',stroke:'var(--line2)',pip:'var(--dim)',t:'var(--txt2)'},
+    running:{fill:'color-mix(in oklch,var(--cyan) 15%,transparent)',stroke:'color-mix(in oklch,var(--cyan) 52%,transparent)',pip:'var(--cyan)',t:'var(--txt)'},
+    done:{fill:'color-mix(in oklch,var(--grn) 13%,transparent)',stroke:'color-mix(in oklch,var(--grn) 48%,transparent)',pip:'var(--grn)',t:'var(--txt)'},
+    failed:{fill:'color-mix(in oklch,var(--red) 14%,transparent)',stroke:'color-mix(in oklch,var(--red) 52%,transparent)',pip:'var(--red)',t:'var(--txt)'},
+    comp:{fill:'color-mix(in oklch,var(--amber) 15%,transparent)',stroke:'color-mix(in oklch,var(--amber) 52%,transparent)',pip:'var(--amber)',t:'var(--txt)'},
+    undone:{fill:'var(--panel)',stroke:'var(--line2)',pip:'var(--dim)',t:'var(--dim)'}
+  };
+  function paint(i){
+    var c=cards[i], s=st[i], k=COL[s];
+    c.rect.setAttribute('fill',k.fill); c.rect.setAttribute('stroke',k.stroke);
+    c.pip.setAttribute('fill',k.pip); c.title.setAttribute('fill',k.t);
+    if(s==='undone'){ c.title.setAttribute('text-decoration','line-through'); } else { c.title.setAttribute('text-decoration','none'); }
+    // compensation chip active during comp / undone
+    var active = (s==='comp'||s==='undone');
+    c.crect.setAttribute('stroke', s==='comp'?'color-mix(in oklch,var(--amber) 52%,transparent)':(s==='undone'?'var(--line3)':'var(--line2)'));
+    c.crect.setAttribute('fill', s==='comp'?'color-mix(in oklch,var(--amber) 12%,transparent)':'var(--panel)');
+    c.crect.setAttribute('stroke-dasharray', active?'':'3 4');
+    c.ctext.setAttribute('fill', s==='comp'?'var(--amber)':(s==='undone'?'var(--txt2)':'var(--dim)'));
+    c.carrow.setAttribute('stroke', s==='comp'?'var(--amber)':(s==='undone'?'var(--txt2)':'var(--dim)'));
+  }
+
+  function setStats(){
+    var step = phase==='idle'?'—':(phase==='forward'?(idx+1)+' / '+N:(phase==='compensate'?'unwind':'done'));
+    el('saga-step').textContent=step;
+    el('saga-commit').textContent=st.filter(function(x){return x==='done';}).length;
+    el('saga-comp').textContent=st.filter(function(x){return x==='undone';}).length;
+    var o=el('saga-outcome');
+    o.textContent = outcome || '—';
+    o.className='v '+(outcome==='committed'?'good':(outcome==='rolled back'?'bad':''));
+    o.style.fontSize='15px';
+    o.textContent = outcome? (outcome==='committed'?'committed':'rolled back') : '—';
+  }
+  function setRunBtn(on){
+    var b=el('saga-run');
+    b.innerHTML= on? '<svg viewBox="0 0 24 24" fill="currentColor" stroke="none"><rect x="6" y="5" width="4" height="14" rx="1"/><rect x="14" y="5" width="4" height="14" rx="1"/></svg>Running…'
+      : '<svg viewBox="0 0 24 24" fill="currentColor" stroke="none"><path d="M8 5v14l11-7z"/></svg>Run saga';
+    b.toggleAttribute('disabled',on);
+  }
+
+  // ---- run ----
+  function motionOff(){ return window.__motionOff || (window.matchMedia && window.matchMedia('(prefers-reduced-motion:reduce)').matches); }
+  function run(){
+    reset(); phase='forward'; idx=0; setRunBtn(true);
+    if(motionOff()){ instant(); return; }
+    st[0]='running'; paint(0); stepStart=performance.now(); t0=stepStart;
+    if(raf) cancelAnimationFrame(raf); raf=requestAnimationFrame(tick);
+  }
+  function tick(now){
+    if(phase==='forward'){
+      var prog=(now-stepStart)/FDUR;
+      moveDotF(idx,Math.min(1,prog));
+      if(prog>=1){
+        if(idx===failAt){
+          st[idx]='failed'; paint(idx); dotF.setAttribute('opacity','0');
+          // build compensation queue for committed steps (reverse)
+          compQueue=[]; for(var j=idx-1;j>=0;j--){ if(st[j]==='done') compQueue.push(j); }
+          if(compQueue.length){ phase='compensate'; startComp(now); }
+          else { phase='done'; outcome='rolled back'; finish(); }
+        } else {
+          st[idx]='done'; paint(idx);
+          if(idx<N-1){ fEdges[idx].setAttribute('stroke','color-mix(in oklch,var(--grn) 45%,transparent)'); idx++; st[idx]='running'; paint(idx); stepStart=now; }
+          else { phase='done'; outcome='committed'; dotF.setAttribute('opacity','0'); finish(); }
+        }
+        setStats();
+      }
+      raf=requestAnimationFrame(tick);
+    } else if(phase==='compensate'){
+      var ci=compQueue[0];
+      var cp=(now-stepStart)/CDUR;
+      if(cp>=1){
+        st[ci]='undone'; paint(ci); compQueue.shift();
+        // light reverse edge from this step back to previous comp
+        if(ci<N-1) rEdges[ci].setAttribute('opacity','0');
+        if(ci>0) rEdges[ci-1].setAttribute('opacity','0.9');
+        setStats();
+        if(compQueue.length){ stepStart=now; st[compQueue[0]]='comp'; paint(compQueue[0]); }
+        else { phase='done'; outcome='rolled back'; finish(); return; }
+      }
+      raf=requestAnimationFrame(tick);
+    }
+  }
+  function startComp(now){
+    var ci=compQueue[0]; st[ci]='comp'; paint(ci); stepStart=now;
+    if(ci<N-1) rEdges[ci].setAttribute('opacity','0.9');
+  }
+  function moveDotF(i,p){
+    if(i>=N-1){ dotF.setAttribute('opacity','0'); return; }
+    var x1=CX[i]+CW/2, x2=CX[i+1]-CW/2;
+    dotF.setAttribute('opacity', st[i]==='running'?'1':'0');
+    dotF.setAttribute('cx', x1+(x2-x1)*p); dotF.setAttribute('cy', CYC-6);
+  }
+  function finish(){ phase='done'; setRunBtn(false); setStats(); if(raf){ cancelAnimationFrame(raf); raf=null; } }
+
+  function instant(){
+    if(failAt<0){ st=STEPS.map(function(){return 'done';}); outcome='committed'; fEdges.forEach(function(e){e.setAttribute('stroke','color-mix(in oklch,var(--grn) 45%,transparent)');}); }
+    else { for(var i=0;i<failAt;i++) st[i]='undone'; st[failAt]='failed'; for(var j=failAt+1;j<N;j++) st[j]='pending'; outcome='rolled back'; }
+    phase='done'; cards.forEach(function(_,i){ paint(i); }); setRunBtn(false); setStats();
+  }
+
+  // ---- controls ----
+  document.querySelectorAll('#saga-fail button').forEach(function(b){
+    b.addEventListener('click',function(){
+      failAt=parseInt(b.getAttribute('data-v'),10);
+      document.querySelectorAll('#saga-fail button').forEach(function(x){ var on=x===b; x.setAttribute('data-on', on?'1':'0'); x.setAttribute('aria-pressed', on?'true':'false'); });
+      reset();
+    });
+  });
+  el('saga-run').addEventListener('click',function(){ if(phase==='forward'||phase==='compensate') return; run(); });
+  el('saga-reset').addEventListener('click',function(){ if(raf) cancelAnimationFrame(raf); raf=null; reset(); });
+
+  window.__taskitoDemos=window.__taskitoDemos||{};
+  var pm=window.__taskitoDemos.motion;
+  window.__taskitoDemos.motion=function(off){ if(pm)pm(off); if(off && raf){ cancelAnimationFrame(raf); raf=null; instant(); } };
+
+  reset();
+  if(motionOff()){ instant(); }
+  else if(document.body.hasAttribute('data-embed')){ run(); }
+  else {
+    var io=new IntersectionObserver(function(es){ es.forEach(function(e){ if(e.isIntersecting && phase==='idle'){ run(); io.disconnect(); } }); },{threshold:0.3});
+    io.observe(root);
+  }
+})();
diff --git a/docs/public/demos/demo-workflow.js b/docs/public/demos/demo-workflow.js
new file mode 100644
index 00000000..6d63d215
--- /dev/null
+++ b/docs/public/demos/demo-workflow.js
@@ -0,0 +1,281 @@
+/* ============================================================
+   taskito · Demo 04 — Workflow DAG execution
+   A real dependency graph: chain → group (parallel) → chord
+   (join) → fan-out. Run it and execution propagates as each
+   task's inputs become ready; click a node to trace/run a branch.
+   Tier-1: SVG + requestAnimationFrame. No WebGL.
+   ============================================================ */
+(function(){
+  var root=document.getElementById('wf-root');
+  if(!root) return;
+
+  var W=760,H=372;
+  // node model: center coords on the SVG canvas
+  var NODES=[
+    {id:'ingest',  label:'ingest',    fn:'fetch_source()',    type:'Source',     x:78,  y:186, dur:700},
+    {id:'probe',   label:'probe',     fn:'inspect.s()',       type:'Chain step', x:222, y:186, dur:620},
+    {id:'t720',    label:'transcode 720p', fn:'encode.s(720)',type:'Group · parallel', x:392, y:84,  dur:1500},
+    {id:'t1080',   label:'transcode 1080p',fn:'encode.s(1080)',type:'Group · parallel',x:392, y:186, dur:2000},
+    {id:'audio',   label:'extract audio',  fn:'audio.s()',    type:'Group · parallel', x:392, y:288, dur:1150},
+    {id:'package', label:'package',   fn:'chord(mux.s())',    type:'Chord · join', x:560, y:186, dur:950},
+    {id:'notify',  label:'notify',    fn:'webhook.s()',       type:'Fan-out',    x:704, y:120, dur:520},
+    {id:'cdn',     label:'publish CDN',fn:'upload.s()',       type:'Fan-out',    x:704, y:252, dur:760}
+  ];
+  var EDGES=[
+    ['ingest','probe'],
+    ['probe','t720'],['probe','t1080'],['probe','audio'],
+    ['t720','package'],['t1080','package'],['audio','package'],
+    ['package','notify'],['package','cdn']
+  ];
+  var NW=120, NH=46;
+  var byId={}; NODES.forEach(function(n){ byId[n.id]=n; n.deps=[]; n.kids=[]; });
+  EDGES.forEach(function(e){ byId[e[1]].deps.push(e[0]); byId[e[0]].kids.push(e[1]); });
+
+  // critical path (longest dur sum)
+  (function(){
+    var memo={};
+    function cp(id){ if(memo[id]!=null) return memo[id]; var n=byId[id];
+      var m=0; n.kids.forEach(function(k){ m=Math.max(m,cp(k)); }); return memo[id]=n.dur+m; }
+    window.__wfCrit=Math.max.apply(null,NODES.filter(function(n){return n.deps.length===0;}).map(function(n){return cp(n.id);}));
+  })();
+
+  root.innerHTML=
+  '<div class="demo-bar">'+
+    '<span class="title"><span class="ld"></span>media-pipeline · DAG</span>'+
+    '<div class="demo-controls">'+
+      '<button class="ctl pri" id="wf-run"><svg viewBox="0 0 24 24" fill="currentColor" stroke="none"><path d="M8 5v14l11-7z"/></svg>Run workflow</button>'+
+      '<button class="ctl" id="wf-reset"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"><path d="M3 12a9 9 0 1 0 3-6.7L3 8"/><path d="M3 3v5h5"/></svg>Reset</button>'+
+    '</div>'+
+  '</div>'+
+  '<div class="wf-grid">'+
+    '<div class="wf-graph"><svg id="wf-svg" viewBox="0 0 '+W+' '+H+'" role="img" aria-label="Workflow dependency graph: ingest then probe, fanning out to three parallel transcode tasks, joined by a package step, then publishing to notify and CDN. Run animates execution in dependency order.">'+
+      '<defs>'+
+        '<marker id="wf-ar" viewBox="0 0 10 10" refX="8.5" refY="5" markerWidth="9" markerHeight="9" markerUnits="userSpaceOnUse" orient="auto"><path d="M1.5 1.5 L9 5 L1.5 8.5 Z" fill="var(--line3)"/></marker>'+
+        '<marker id="wf-ar-on" viewBox="0 0 10 10" refX="8.5" refY="5" markerWidth="9" markerHeight="9" markerUnits="userSpaceOnUse" orient="auto"><path d="M1.5 1.5 L9 5 L1.5 8.5 Z" fill="var(--grn)"/></marker>'+
+      '</defs>'+
+      '<g id="wf-edges"></g><g id="wf-flow"></g><g id="wf-nodes"></g>'+
+    '</svg></div>'+
+    '<div class="wf-side" id="wf-side"></div>'+
+  '</div>'+
+  '<div class="legend">'+
+    '<span><i style="background:var(--dim)"></i>idle</span>'+
+    '<span><i style="background:var(--indigo-br)"></i>queued</span>'+
+    '<span><i style="background:var(--cyan)"></i>running</span>'+
+    '<span><i style="background:var(--grn)"></i>done</span>'+
+  '</div>'+
+  '<div class="readout">'+
+    stat('tasks','wf-total')+stat('completed','wf-done','good')+stat('running','wf-running')+
+    stat('elapsed','wf-elapsed',null,'s')+stat('critical path','wf-crit',null,'s')+
+  '</div>';
+
+  function stat(k,id,cls,u){ return '<div class="stat"><span class="k">'+k+'</span><span class="v'+(cls?' '+cls:'')+'" id="'+id+'">0'+(u?'<span class="u">'+u+'</span>':'')+'</span></div>'; }
+  function g(id){ return document.getElementById(id); }
+
+  var gEdges=g('wf-edges'), gFlow=g('wf-flow'), gNodes=g('wf-nodes'), side=g('wf-side');
+
+  // ---- build edges ----
+  var edgeEls={};
+  EDGES.forEach(function(e){
+    var a=byId[e[0]], b=byId[e[1]];
+    var x1=a.x+NW/2, y1=a.y, x2=b.x-NW/2, y2=b.y;
+    var mx=(x1+x2)/2;
+    var d='M'+x1+' '+y1+' C '+mx+' '+y1+', '+mx+' '+y2+', '+x2+' '+y2;
+    var base=document.createElementNS('http://www.w3.org/2000/svg','path');
+    base.setAttribute('d',d); base.setAttribute('fill','none'); base.setAttribute('stroke','var(--line2)');
+    base.setAttribute('stroke-width','2'); base.setAttribute('marker-end','url(#wf-ar)');
+    gEdges.appendChild(base);
+    var lit=document.createElementNS('http://www.w3.org/2000/svg','path');
+    lit.setAttribute('d',d); lit.setAttribute('fill','none'); lit.setAttribute('stroke','var(--grn)');
+    lit.setAttribute('stroke-width','2.4'); lit.setAttribute('stroke-linecap','round');
+    var len=lit.getTotalLength?lit.getTotalLength():400;
+    lit.style.strokeDasharray=len; lit.style.strokeDashoffset=len; lit.style.transition='stroke-dashoffset .5s ease';
+    gFlow.appendChild(lit);
+    edgeEls[e[0]+'>'+e[1]]={base:base,lit:lit,path:lit,len:len};
+  });
+
+  // ---- build nodes ----
+  var nodeEls={};
+  NODES.forEach(function(n){
+    var grp=document.createElementNS('http://www.w3.org/2000/svg','g');
+    grp.setAttribute('class','wf-node'); grp.setAttribute('tabindex','0'); grp.setAttribute('role','button');
+    grp.setAttribute('aria-label',n.label+' — '+n.type);
+    var rect=document.createElementNS('http://www.w3.org/2000/svg','rect');
+    rect.setAttribute('x',n.x-NW/2); rect.setAttribute('y',n.y-NH/2); rect.setAttribute('width',NW); rect.setAttribute('height',NH);
+    rect.setAttribute('rx','11'); rect.setAttribute('fill','var(--panel2)'); rect.setAttribute('stroke','var(--line2)');
+    var pip=document.createElementNS('http://www.w3.org/2000/svg','circle');
+    pip.setAttribute('cx',n.x+NW/2-14); pip.setAttribute('cy',n.y-NH/2+14); pip.setAttribute('r','4'); pip.setAttribute('fill','var(--dim)');
+    var t1=document.createElementNS('http://www.w3.org/2000/svg','text');
+    t1.setAttribute('x',n.x-NW/2+13); t1.setAttribute('y',n.y-3); t1.setAttribute('font-family','var(--sans)');
+    t1.setAttribute('font-size','12.5'); t1.setAttribute('font-weight','600'); t1.setAttribute('fill','var(--txt2)'); t1.textContent=n.label;
+    var t2=document.createElementNS('http://www.w3.org/2000/svg','text');
+    t2.setAttribute('x',n.x-NW/2+13); t2.setAttribute('y',n.y+13); t2.setAttribute('font-family','var(--code)');
+    t2.setAttribute('font-size','10'); t2.setAttribute('fill','var(--dim)'); t2.textContent=n.fn;
+    grp.appendChild(rect); grp.appendChild(pip); grp.appendChild(t1); grp.appendChild(t2);
+    gNodes.appendChild(grp);
+    nodeEls[n.id]={g:grp,rect:rect,pip:pip,t1:t1,t2:t2};
+    grp.addEventListener('click',function(){ selectNode(n.id); });
+    grp.addEventListener('keydown',function(e){ if(e.key==='Enter'||e.key===' '){ e.preventDefault(); selectNode(n.id); } });
+  });
+
+  // ---- state ----
+  var state={}, started={}, finishAt={}, selected=null, runMask=null, t0=0, raf=null, running=false;
+  function reset(full){
+    // Clear any pending frame so `raf` never lingers as a stale "running" signal.
+    if(raf){ cancelAnimationFrame(raf); raf=null; }
+    NODES.forEach(function(n){ state[n.id]='idle'; started[n.id]=0; finishAt[n.id]=0; });
+    runMask=null; running=false; t0=0;
+    Object.keys(edgeEls).forEach(function(k){ edgeEls[k].lit.style.strokeDashoffset=edgeEls[k].len; edgeEls[k].base.setAttribute('marker-end','url(#wf-ar)'); });
+    [].forEach.call(gFlow.querySelectorAll('circle.wf-dot'),function(d){ d.remove(); });
+    NODES.forEach(paintNode);
+    paintStats();
+    if(full!==false){ selected=selected||'ingest'; renderSide(); }
+  }
+
+  var COLOR={
+    idle:{fill:'var(--panel2)',stroke:'var(--line2)',pip:'var(--dim)',t1:'var(--txt2)'},
+    queued:{fill:'var(--indigo-soft)',stroke:'var(--indigo-line)',pip:'var(--indigo-br)',t1:'var(--txt)'},
+    running:{fill:'color-mix(in oklch,var(--cyan) 15%,transparent)',stroke:'color-mix(in oklch,var(--cyan) 55%,transparent)',pip:'var(--cyan)',t1:'var(--txt)'},
+    done:{fill:'color-mix(in oklch,var(--grn) 13%,transparent)',stroke:'color-mix(in oklch,var(--grn) 48%,transparent)',pip:'var(--grn)',t1:'var(--txt)'}
+  };
+  function paintNode(n){
+    var e=nodeEls[n.id], s=state[n.id], c=COLOR[s];
+    e.rect.setAttribute('fill',c.fill); e.rect.setAttribute('stroke',selected===n.id?'var(--txt2)':c.stroke);
+    e.rect.setAttribute('stroke-width',selected===n.id?'2.4':'1.6');
+    e.pip.setAttribute('fill',c.pip);
+    e.t1.setAttribute('fill',c.t1);
+    // dim non-branch nodes when a node is selected & not running
+    var dim = selected && !running && !inBranch(selected,n.id);
+    e.g.style.opacity = dim ? '0.4' : '1';
+  }
+  function repaintAll(){ NODES.forEach(paintNode); }
+
+  // downstream branch membership (selected node + all descendants)
+  function inBranch(rootId,id){
+    if(rootId===id) return true;
+    var seen={}, stack=[rootId];
+    while(stack.length){ var c=stack.pop(); byId[c].kids.forEach(function(k){ if(!seen[k]){ seen[k]=1; stack.push(k); } }); }
+    return !!seen[id];
+  }
+  function branchSet(rootId){ var set={}; set[rootId]=1; var stack=[rootId];
+    while(stack.length){ var c=stack.pop(); byId[c].kids.forEach(function(k){ if(!set[k]){ set[k]=1; stack.push(k); } }); }
+    return set; }
+
+  // ---- scheduler ----
+  function start(mask){
+    reset(false); runMask=mask||null; running=true; t0=performance.now();
+    setRunBtn(true); repaintAll();
+    if(motionOff()){ instantFinish(); return; }
+    if(raf) cancelAnimationFrame(raf);
+    raf=requestAnimationFrame(tick);
+  }
+  function eligible(id){
+    if(runMask && !runMask[id]) return false;
+    if(state[id]!=='idle') return false;
+    return byId[id].deps.every(function(d){ return (runMask && !runMask[d]) ? true : state[d]==='done'; });
+  }
+  function tick(now){
+    var t=now-t0;
+    // launch eligible
+    NODES.forEach(function(n){ if(eligible(n.id)){ state[n.id]='running'; started[n.id]=now; finishAt[n.id]=now+n.dur; paintNode(n); } });
+    // finish
+    NODES.forEach(function(n){ if(state[n.id]==='running' && now>=finishAt[n.id]){ state[n.id]='done'; paintNode(n); litOut(n); } });
+    paintStats(t);
+    var active=NODES.some(function(n){ return (runMask?runMask[n.id]:true) && state[n.id]!=='done' && state[n.id]!=='idle'; });
+    var pending=NODES.some(function(n){ return eligible(n.id); });
+    var anyRunning=NODES.some(function(n){ return state[n.id]==='running'; });
+    if(anyRunning||pending){ raf=requestAnimationFrame(tick); }
+    else { raf=null; running=false; setRunBtn(false); repaintAll(); renderSide(); }
+  }
+  function litOut(n){
+    n.kids.forEach(function(k){
+      if(runMask && !runMask[k]) return;
+      var ed=edgeEls[n.id+'>'+k]; if(!ed) return;
+      ed.lit.style.strokeDashoffset=0;
+      ed.base.setAttribute('marker-end','url(#wf-ar-on)'); // arrowhead goes green with the edge
+      if(!motionOff()) spawnDot(ed);
+    });
+  }
+  function spawnDot(ed){
+    var dot=document.createElementNS('http://www.w3.org/2000/svg','circle');
+    dot.setAttribute('r','4'); dot.setAttribute('fill','var(--grn)'); dot.setAttribute('class','wf-dot');
+    dot.style.filter='drop-shadow(0 0 5px var(--grn))';
+    gFlow.appendChild(dot);
+    var st=performance.now(), DUR=480, len=ed.len, path=ed.path;
+    (function move(now){
+      var p=Math.min(1,(now-st)/DUR);
+      var pt=path.getPointAtLength(len*p);
+      dot.setAttribute('cx',pt.x); dot.setAttribute('cy',pt.y);
+      dot.style.opacity = p<0.12?(p/0.12):(p>0.85?(1-(p-0.85)/0.15):1);
+      if(p<1) requestAnimationFrame(move); else dot.remove();
+    })(st);
+  }
+  function instantFinish(){
+    NODES.forEach(function(n){ if(!runMask||runMask[n.id]) state[n.id]='done'; });
+    Object.keys(edgeEls).forEach(function(k){ var p=k.split('>'); if(!runMask||(runMask[p[0]]&&runMask[p[1]])){ edgeEls[k].lit.style.strokeDashoffset=0; edgeEls[k].base.setAttribute('marker-end','url(#wf-ar-on)'); } });
+    running=false; setRunBtn(false); repaintAll(); paintStats(window.__wfCrit); renderSide();
+  }
+
+  function paintStats(t){
+    var scope=NODES.filter(function(n){ return !runMask||runMask[n.id]; });
+    var done=scope.filter(function(n){return state[n.id]==='done';}).length;
+    var run=scope.filter(function(n){return state[n.id]==='running';}).length;
+    setNum(g('wf-total'),scope.length);
+    setNum(g('wf-done'),done);
+    setNum(g('wf-running'),run);
+    var el=g('wf-elapsed'); el.innerHTML=((t||0)/1000).toFixed(1)+'<span class="u">s</span>';
+    var cr=g('wf-crit'); cr.innerHTML=(window.__wfCrit/1000).toFixed(1)+'<span class="u">s</span>';
+  }
+  function setNum(el,v){ el.childNodes.length>1?(el.childNodes[0].nodeValue=v):(el.textContent=v); }
+
+  function setRunBtn(on){
+    var b=g('wf-run');
+    b.innerHTML = on
+      ? '<svg viewBox="0 0 24 24" fill="currentColor" stroke="none"><rect x="6" y="5" width="4" height="14" rx="1"/><rect x="14" y="5" width="4" height="14" rx="1"/></svg>Running…'
+      : '<svg viewBox="0 0 24 24" fill="currentColor" stroke="none"><path d="M8 5v14l11-7z"/></svg>Run workflow';
+    b.toggleAttribute('disabled',on);
+  }
+
+  // ---- side panel ----
+  function selectNode(id){ selected=id; repaintAll(); renderSide(); }
+  function renderSide(){
+    var n=byId[selected||'ingest'];
+    var deps=n.deps.length? n.deps.map(function(d){return '<span class="dc">'+byId[d].label+'</span>';}).join('')
+                          : '<span class="dc none">none · root task</span>';
+    var st=state[n.id]||'idle';
+    var stColor={idle:'var(--dim)',queued:'var(--indigo-br)',running:'var(--cyan)',done:'var(--grn)'}[st];
+    var downstream=Object.keys(branchSet(n.id)).length-1;
+    side.innerHTML=
+      '<span class="sk">selected task</span>'+
+      '<span class="wf-seltype"><span style="width:7px;height:7px;border-radius:2px;background:currentColor;display:inline-block"></span>'+n.type+'</span>'+
+      '<div class="wf-selname">'+n.label+'<span class="mono">'+n.fn+'</span></div>'+
+      '<div class="wf-rows">'+
+        '<div class="wf-row"><span class="k">Status</span><span class="wf-status"><span class="sd" style="background:'+stColor+'"></span>'+st+'</span></div>'+
+        '<div class="wf-row"><span class="k">Depends on</span><div class="wf-depchips">'+deps+'</div></div>'+
+        '<div class="wf-row"><span class="k">Est. duration</span><span class="v mono">'+(n.dur/1000).toFixed(2)+'s</span></div>'+
+        '<div class="wf-row"><span class="k">Downstream tasks</span><span class="v mono">'+downstream+'</span></div>'+
+      '</div>'+
+      '<div class="wf-runbranch">'+
+        '<button class="ctl" id="wf-branch"'+(downstream===0&&n.deps.length===0?'':'')+'><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"><path d="M6 3v12"/><circle cx="6" cy="18" r="3"/><circle cx="18" cy="6" r="3"/><path d="M18 9a9 9 0 0 1-9 9"/></svg>Run from here</button>'+
+        '<div class="note">'+(downstream>0?('runs this task + '+downstream+' downstream'):'runs just this task')+'</div>'+
+      '</div>';
+    g('wf-branch').addEventListener('click',function(){ start(branchSet(n.id)); });
+  }
+
+  // ---- controls / motion ----
+  function motionOff(){ return window.__motionOff || (window.matchMedia && window.matchMedia('(prefers-reduced-motion:reduce)').matches); }
+  g('wf-run').addEventListener('click',function(){ if(running) return; selected=null; start(null); });
+  g('wf-reset').addEventListener('click',function(){ if(raf) cancelAnimationFrame(raf); reset(true); });
+
+  window.__taskitoDemos=window.__taskitoDemos||{};
+  var pm=window.__taskitoDemos.motion;
+  window.__taskitoDemos.motion=function(off){ if(pm)pm(off); if(off && raf){ cancelAnimationFrame(raf); instantFinish(); } };
+
+  // init
+  reset(true);
+  if(motionOff()){ instantFinish(); }
+  else if(document.body.hasAttribute('data-embed')){ start(null); }
+  else {
+    var io=new IntersectionObserver(function(es){ es.forEach(function(e){ if(e.isIntersecting && t0===0){ start(null); io.disconnect(); } }); },{threshold:0.3});
+    io.observe(root);
+  }
+})();
diff --git a/docs/public/demos/demo-worksteal.js b/docs/public/demos/demo-worksteal.js
new file mode 100644
index 00000000..f20154a5
--- /dev/null
+++ b/docs/public/demos/demo-worksteal.js
@@ -0,0 +1,260 @@
+/* ============================================================
+   taskito · Demo 07 — Multi-region work-stealing mesh
+   taskito runs in several regions that gossip queue depth. When
+   one region's backlog spikes, an idle peer steals a batch over
+   HTTP — load self-balances with no central broker.
+   Tier-1: SVG + requestAnimationFrame. No WebGL.
+   ============================================================ */
+(function(){
+  var root=document.getElementById('worksteal-root');
+  if(!root) return;
+  var W=940,H=540, SVGNS='http://www.w3.org/2000/svg';
+  var JOB_MS=820, STEAL_INT=620, HOT=5, COOL=2;
+
+  // equirectangular world map: lon/lat -> SVG x/y (map band centered in the viewBox)
+  var MAPH=470, MAPY=35;
+  function proj(lon,lat){ return [(lon+180)/360*W, (90-lat)/180*MAPH+MAPY]; }
+  function landPath(pts){ return 'M'+pts.map(function(c){ var p=proj(c[0],c[1]); return p[0].toFixed(1)+' '+p[1].toFixed(1); }).join(' L ')+' Z'; }
+  // simplified continent outlines (lon,lat) — geographically placed, low-poly
+  var CONTINENTS=[
+    [[-165,60],[-150,70],[-120,70],[-95,72],[-80,68],[-78,55],[-64,48],[-70,42],[-76,35],[-81,25],[-92,18],[-100,18],[-106,23],[-114,31],[-123,40],[-124,49],[-133,55],[-150,58]], // North America
+    [[-80,8],[-72,11],[-60,5],[-50,0],[-44,-2],[-40,-10],[-48,-23],[-58,-34],[-66,-44],[-72,-52],[-75,-48],[-71,-35],[-70,-18],[-76,-12],[-81,-5]], // South America
+    [[-16,14],[-12,28],[-2,35],[10,37],[20,33],[32,31],[35,24],[43,12],[51,11],[48,0],[41,-12],[35,-22],[25,-34],[18,-35],[11,-16],[9,0],[-2,5],[-12,8]], // Africa
+    [[-9,36],[-2,44],[2,50],[-4,58],[5,62],[14,66],[28,71],[55,70],[75,73],[100,73],[130,71],[155,68],[170,66],[165,60],[150,58],[142,50],[133,43],[123,40],[122,31],[112,21],[103,14],[97,8],[93,20],[88,21],[80,7],[76,8],[70,18],[63,24],[56,26],[48,30],[42,37],[30,36],[22,40],[14,45],[4,43]], // Eurasia
+    [[-5,50],[-2,51],[1,53],[-2,56],[-6,58],[-9,55],[-10,52]], // British Isles
+    [[133,32],[138,34],[143,39],[145,43],[143,45],[139,43],[136,39],[133,36],[131,33]], // Japan
+    [[114,-22],[122,-18],[131,-12],[137,-11],[143,-11],[147,-20],[150,-37],[141,-38],[131,-32],[120,-34],[114,-26]] // Australia
+  ];
+  var LAND_D=CONTINENTS.map(landPath).join(' ');
+
+  // regions placed at their real lon/lat; cards are spread out and connected to a map pin
+  var REG=[
+    {id:'us-west-2',     loc:'Oregon',     lon:-120, lat:45, cardX:44,  cardY:58,  q:2, rate:0.30},
+    {id:'us-east-1',     loc:'N. Virginia',lon:-77,  lat:38, cardX:120, cardY:214, q:2, rate:0.30},
+    {id:'eu-west',       loc:'Ireland',    lon:-7,   lat:53, cardX:386, cardY:44,  q:2, rate:1.35},
+    {id:'ap-south-1',    loc:'Mumbai',     lon:73,   lat:19, cardX:560, cardY:300, q:1, rate:0.34},
+    {id:'ap-northeast-1',loc:'Tokyo',      lon:139,  lat:36, cardX:742, cardY:66,  q:2, rate:0.34}
+  ];
+  REG.forEach(function(r){ var p=proj(r.lon,r.lat); r.gx=Math.round(p[0]); r.gy=Math.round(p[1]); r.dx=r.gx; r.dy=r.gy; r.busy=[0,0]; });
+  var byId={}; REG.forEach(function(r){ byId[r.id]=r; });
+  var LINKS=[
+    ['us-west-2','eu-west',85],['eu-west','ap-northeast-1',88],['eu-west','ap-south-1',139],
+    ['us-west-2','us-east-1',null],['us-east-1','eu-west',null],['ap-south-1','ap-northeast-1',null],
+    ['us-east-1','ap-south-1',null]
+  ];
+  var HOPS=[];
+
+  root.innerHTML=
+  '<div class="demo-bar">'+
+    '<span class="title"><span class="ld"></span>region-mesh · gossip</span>'+
+    '<div class="demo-controls">'+
+      '<button class="ctl pri" id="ws-burst"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 5v14M5 12h14"/></svg>Burst</button>'+
+      '<button class="ctl" id="ws-reset"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"><path d="M3 12a9 9 0 1 0 3-6.7L3 8"/><path d="M3 3v5h5"/></svg>Reset</button>'+
+      '<button class="ctl" id="ws-pause"><svg viewBox="0 0 24 24" fill="currentColor" stroke="none"><rect x="6" y="5" width="4" height="14" rx="1"/><rect x="14" y="5" width="4" height="14" rx="1"/></svg>Pause</button>'+
+    '</div>'+
+  '</div>'+
+  '<div class="stage"><svg id="ws-svg" viewBox="0 0 '+W+' '+H+'" role="img" aria-label="A world map with five taskito regions connected by a gossip mesh. When one region\'s queue spikes, idle regions steal batches of jobs over HTTP so load balances out.">'+
+    '<defs><pattern id="ws-grid" width="36" height="36" patternUnits="userSpaceOnUse"><circle cx="1" cy="1" r="1" fill="var(--line)"/></pattern></defs>'+
+    '<rect width="'+W+'" height="'+H+'" fill="url(#ws-grid)" opacity=".7"/>'+
+    '<g id="ws-land" opacity=".6"><path d="'+LAND_D+'" fill="var(--line)" stroke="var(--line2)" stroke-width="1" stroke-linejoin="round"/></g>'+
+    '<g id="ws-links"></g><g id="ws-leads"></g><g id="ws-pins"></g><g id="ws-hops"></g><g id="ws-tokens"></g><g id="ws-cards"></g>'+
+  '</svg></div>'+
+  '<div class="legend">'+
+    '<span><i style="background:var(--grn)"></i>region node</span>'+
+    '<span><i style="width:16px;height:0;border-top:2px dashed color-mix(in oklch,var(--grn) 50%,transparent);border-radius:0;background:none"></i>mesh link (gossip)</span>'+
+    '<span><i style="width:16px;height:0;border-top:2px solid var(--cyan);border-radius:0;background:none"></i>work-steal over HTTP</span>'+
+  '</div>'+
+  '<div class="readout">'+
+    stat('completed','ws-completed','good')+stat('steals','ws-steals')+stat('moved · HTTP','ws-moved','warn')+
+    stat('busiest queue','ws-hot')+
+  '</div>';
+
+  function stat(k,id,cls){ return '<div class="stat"><span class="k">'+k+'</span><span class="v'+(cls?' '+cls:'')+'" id="'+id+'">0</span></div>'; }
+  function el(id){ return document.getElementById(id); }
+  var gLinks=el('ws-links'), gHops=el('ws-hops'), gTok=el('ws-tokens'), gCards=el('ws-cards');
+
+  // ---- links + latency pills ----
+  var linkEls=[];
+  LINKS.forEach(function(L){
+    var a=byId[L[0]], b=byId[L[1]];
+    var p=document.createElementNS(SVGNS,'line');
+    p.setAttribute('x1',a.dx); p.setAttribute('y1',a.dy); p.setAttribute('x2',b.dx); p.setAttribute('y2',b.dy);
+    p.setAttribute('stroke','color-mix(in oklch,var(--grn) 38%,transparent)'); p.setAttribute('stroke-width','1.6');
+    p.setAttribute('stroke-dasharray','2 6'); p.setAttribute('stroke-linecap','round');
+    gLinks.appendChild(p); linkEls.push({a:a,b:b,line:p,solid:0});
+    if(L[2]!=null){
+      var mx=(a.dx+b.dx)/2, my=(a.dy+b.dy)/2;
+      var g=document.createElementNS(SVGNS,'g');
+      g.innerHTML='<rect x="'+(mx-21)+'" y="'+(my-11)+'" width="42" height="22" rx="7" fill="var(--panel)" stroke="color-mix(in oklch,var(--grn) 32%,transparent)"/>'+
+        '<text x="'+mx+'" y="'+(my+4)+'" text-anchor="middle" font-family="var(--mono)" font-size="10.5" fill="var(--mut)">'+L[2]+' ms</text>';
+      gLinks.appendChild(g);
+    }
+  });
+  HOPS.forEach(function(h){
+    var c=document.createElementNS(SVGNS,'circle');
+    c.setAttribute('cx',h[0]); c.setAttribute('cy',h[1]); c.setAttribute('r','5');
+    c.setAttribute('fill','color-mix(in oklch,var(--cyan) 60%,var(--panel))'); c.setAttribute('opacity','.85');
+    gHops.appendChild(c);
+  });
+
+  // ---- region cards ----
+  REG.forEach(function(r){
+    var x=r.cardX, y=r.cardY, w=156, h=80;
+    var g=document.createElementNS(SVGNS,'g');
+    g.innerHTML=
+      '<rect x="'+x+'" y="'+y+'" width="'+w+'" height="'+h+'" rx="13" fill="var(--panel)" stroke="var(--line2)" data-rect/>'+
+      '<circle cx="'+(x+16)+'" cy="'+(y+18)+'" r="5.5" fill="var(--grn)" data-dot/>'+
+      '<text x="'+(x+30)+'" y="'+(y+22)+'" font-family="var(--code)" font-size="12.5" font-weight="700" fill="var(--txt)">'+r.id+'</text>'+
+      '<text x="'+(x+30+labelW(r.id))+'" y="'+(y+22)+'" font-family="var(--mono)" font-size="10" fill="var(--dim)"> '+r.loc+'</text>'+
+      '<g data-workers transform="translate('+(x+16)+','+(y+36)+')"></g>'+
+      '<text x="'+(x+16)+'" y="'+(y+70)+'" font-family="var(--mono)" font-size="11" fill="var(--mut)"><tspan data-q font-weight="600" fill="var(--txt2)">'+r.q+'</tspan> queued</text>';
+    gCards.appendChild(g);
+    r.g=g; r.rect=g.querySelector('[data-rect]'); r.qEl=g.querySelector('[data-q]'); r.wkEl=g.querySelector('[data-workers]'); r.dot=g.querySelector('[data-dot]');
+    for(var i=0;i<2;i++){
+      var sq=document.createElementNS(SVGNS,'rect');
+      sq.setAttribute('x',i*18); sq.setAttribute('y',0); sq.setAttribute('width',13); sq.setAttribute('height',13); sq.setAttribute('rx',3.5);
+      sq.setAttribute('fill','var(--panel3)'); sq.setAttribute('stroke','var(--line2)'); r.wkEl.appendChild(sq);
+    }
+  });
+  function labelW(s){ return s.length*7.1+4; }
+
+  // ---- geographic pins + leader lines from each card to its real location ----
+  var gLeads=el('ws-leads'), gPins=el('ws-pins');
+  REG.forEach(function(r){
+    var ln=document.createElementNS(SVGNS,'line');
+    ln.setAttribute('x1',r.cardX+78); ln.setAttribute('y1',r.cardY+40);
+    ln.setAttribute('x2',r.gx); ln.setAttribute('y2',r.gy);
+    ln.setAttribute('stroke','var(--line2)'); ln.setAttribute('stroke-width','1.3');
+    ln.setAttribute('stroke-dasharray','1 4'); ln.setAttribute('stroke-linecap','round');
+    gLeads.appendChild(ln);
+    var pin=document.createElementNS(SVGNS,'g');
+    pin.innerHTML='<circle cx="'+r.gx+'" cy="'+r.gy+'" r="11" fill="color-mix(in oklch,var(--grn) 13%,transparent)"/>'+
+      '<circle cx="'+r.gx+'" cy="'+r.gy+'" r="4.5" fill="var(--grn)" stroke="var(--panel)" stroke-width="1.5"/>';
+    gPins.appendChild(pin);
+  });
+
+  // ---- metrics ----
+  var completed=0, steals=0, moved=0, tokens=[];
+
+  function poisson(m){ if(m<=0)return 0; var L=Math.exp(-m),k=0,p=1; do{k++;p*=Math.random();}while(p>L); return k-1; }
+
+  function stepSim(now,dt){
+    REG.forEach(function(r){
+      r.q += poisson(r.rate*dt);
+      for(var i=0;i<2;i++){
+        if(r.busy[i] && now>=r.busy[i]){ r.busy[i]=0; completed++; }
+        if(!r.busy[i] && r.q>0){ r.q--; r.busy[i]=now+JOB_MS*(0.8+Math.random()*0.5); }
+      }
+    });
+  }
+
+  var stealAcc=0;
+  function trySteal(now,dt){
+    stealAcc+=dt*1000; if(stealAcc<STEAL_INT) return; stealAcc=0;
+    // busiest region
+    var hot=REG.slice().sort(function(a,b){return b.q-a.q;})[0];
+    if(hot.q<HOT) return;
+    // an idle linked peer with a free worker
+    var peers=linkEls.filter(function(L){ return L.a===hot||L.b===hot; })
+      .map(function(L){ return L.a===hot?L.b:L.a; })
+      .filter(function(p){ return p.q<=COOL && p.busy.indexOf(0)>=0; })
+      .sort(function(a,b){ return a.q-b.q; });
+    if(!peers.length) return;
+    var dst=peers[0];
+    var batch=Math.max(1,Math.min(4,Math.floor((hot.q-dst.q)/2)));
+    hot.q-=batch;
+    steals++;
+    spawnSteal(hot,dst,batch,now);
+  }
+
+  function spawnSteal(a,b,batch,now){
+    var link=linkEls.filter(function(L){ return (L.a===a&&L.b===b)||(L.a===b&&L.b===a); })[0];
+    if(link) link.solid=now+700;
+    var g=document.createElementNS(SVGNS,'g'); g.setAttribute('class','ws-steal');
+    g.innerHTML='<circle r="8" fill="var(--cyan)" opacity=".95"/><text text-anchor="middle" y="3.5" font-family="var(--code)" font-size="9" font-weight="700" fill="#06281f">'+batch+'</text>';
+    gTok.appendChild(g);
+    var dist=Math.hypot(b.dx-a.dx,b.dy-a.dy);
+    tokens.push({ax:a.dx,ay:a.dy,bx:b.dx,by:b.dy,dst:b,batch:batch,t0:now,dur:Math.max(620,dist*1.6),g:g,done:false});
+  }
+
+  function moveTokens(now){
+    for(var i=tokens.length-1;i>=0;i--){
+      var t=tokens[i], p=Math.min(1,(now-t.t0)/t.dur);
+      var x=t.ax+(t.bx-t.ax)*p, y=t.ay+(t.by-t.ay)*p;
+      t.g.setAttribute('transform','translate('+x.toFixed(1)+','+y.toFixed(1)+')');
+      t.g.firstChild.setAttribute('opacity', (p<0.1?p/0.1:(p>0.9?(1-(p-0.9)/0.1)*0.95:0.95)).toFixed(2));
+      if(p>=1 && !t.done){ t.done=true; t.dst.q+=t.batch; moved+=t.batch; if(t.g.parentNode) t.g.parentNode.removeChild(t.g); tokens.splice(i,1); }
+    }
+  }
+
+  function paint(now){
+    var hotQ=0, hotName='—';
+    REG.forEach(function(r){
+      r.qEl.textContent=r.q;
+      if(r.q>hotQ){ hotQ=r.q; hotName=r.id; }
+      var hot=r.q>=HOT;
+      r.rect.setAttribute('stroke', hot?'color-mix(in oklch,var(--amber) 55%,transparent)':'var(--line2)');
+      r.rect.setAttribute('fill', hot?'color-mix(in oklch,var(--amber) 7%,var(--panel))':'var(--panel)');
+      // worker squares
+      [].forEach.call(r.wkEl.children,function(sq,i){
+        var busy = !!r.busy[i];
+        sq.setAttribute('fill', busy?'var(--grn)':'var(--panel3)');
+        sq.setAttribute('stroke', busy?'color-mix(in oklch,var(--grn) 55%,transparent)':'var(--line2)');
+      });
+    });
+    // link styling: solid teal briefly after a steal
+    linkEls.forEach(function(L){
+      var on = L.solid>now;
+      L.line.setAttribute('stroke', on?'var(--cyan)':'color-mix(in oklch,var(--grn) 38%,transparent)');
+      L.line.setAttribute('stroke-dasharray', on?'':'2 6');
+      L.line.setAttribute('stroke-width', on?'2.2':'1.6');
+    });
+    el('ws-completed').textContent=completed;
+    el('ws-steals').textContent=steals;
+    el('ws-moved').textContent=moved;
+    el('ws-hot').textContent=hotQ;
+  }
+
+  // ---- loop ----
+  function motionOff(){ return window.__motionOff || (window.matchMedia && window.matchMedia('(prefers-reduced-motion:reduce)').matches); }
+  var raf=null,last=0,paused=false;
+  function loop(now){
+    if(!last) last=now; var dt=Math.min((now-last)/1000,0.05); last=now;
+    stepSim(now,dt); trySteal(now,dt); moveTokens(now); paint(now);
+    raf=requestAnimationFrame(loop);
+  }
+  function start(){ if(raf||paused) return; last=0; raf=requestAnimationFrame(loop); }
+  function stop(){ if(raf){ cancelAnimationFrame(raf); raf=null; } }
+
+  function staticRender(){ var now=performance.now(); REG.forEach(function(r){ r.busy=[now+1,0]; }); paint(now); }
+
+  el('ws-burst').addEventListener('click',function(){
+    // dump load onto the already-busiest region to force a steal
+    var hot=REG.slice().sort(function(a,b){return b.q-a.q;})[0]; hot.q+=7;
+    if(motionOff()) staticRender(); else paint(performance.now());
+  });
+  el('ws-reset').addEventListener('click',function(){
+    completed=0;steals=0;moved=0; tokens.forEach(function(t){ if(t.g.parentNode) t.g.parentNode.removeChild(t.g); }); tokens=[];
+    REG.forEach(function(r){ r.q=r.id==='ap-south-1'?1:2; r.busy=[0,0]; });
+    paint(performance.now());
+  });
+  function syncPauseLabel(){
+    el('ws-pause').innerHTML = paused
+      ? '<svg viewBox="0 0 24 24" fill="currentColor" stroke="none"><path d="M8 5v14l11-7z"/></svg>Resume'
+      : '<svg viewBox="0 0 24 24" fill="currentColor" stroke="none"><rect x="6" y="5" width="4" height="14" rx="1"/><rect x="14" y="5" width="4" height="14" rx="1"/></svg>Pause';
+  }
+  el('ws-pause').addEventListener('click',function(){
+    paused=!paused;
+    syncPauseLabel();
+    if(paused) stop(); else start();
+  });
+
+  window.__taskitoDemos=window.__taskitoDemos||{};
+  var pm=window.__taskitoDemos.motion;
+  // Resuming via the motion toggle clears `paused`; keep the button label in sync.
+  window.__taskitoDemos.motion=function(off){ if(pm)pm(off); if(off){ stop(); staticRender(); } else { paused=false; syncPauseLabel(); start(); } };
+
+  paint(performance.now());
+  if(motionOff()){ staticRender(); }
+  else { start(); }
+})();
diff --git a/docs/public/demos/favicon.svg b/docs/public/demos/favicon.svg
new file mode 100644
index 00000000..0872d295
--- /dev/null
+++ b/docs/public/demos/favicon.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><rect width="32" height="32" rx="8" fill="#16a34a"></rect><g stroke="#fff" stroke-width="2.6" stroke-linecap="round"><path d="M8 11 H17"></path><path d="M8 16 H14.5"></path><path d="M8 21 H17"></path></g><path d="M19.5 16 l3 3 l5.5 -6.5" stroke="#fff" stroke-width="3" fill="none" stroke-linecap="round" stroke-linejoin="round"></path></svg>
\ No newline at end of file
diff --git a/docs/public/demos/interactive.css b/docs/public/demos/interactive.css
new file mode 100644
index 00000000..a5a8227e
--- /dev/null
+++ b/docs/public/demos/interactive.css
@@ -0,0 +1,261 @@
+/* ============================================================
+   taskito · interactive demos
+   Tier-1 universal: SVG + Canvas 2D + CSS only. No WebGL.
+   Honors prefers-reduced-motion and the [data-motion] tweak.
+   ============================================================ */
+
+/* page background fx (lighter than landing) */
+.bgfx{position:fixed;inset:0;pointer-events:none;overflow:hidden;z-index:0}
+.bgfx .grid{position:absolute;inset:0;
+  background-image:radial-gradient(circle at center, var(--line) 1px, transparent 1px);
+  background-size:34px 34px;opacity:.45;
+  -webkit-mask-image:radial-gradient(120% 60% at 60% 0%, #000 26%, transparent 72%);
+          mask-image:radial-gradient(120% 60% at 60% 0%, #000 26%, transparent 72%);}
+main{position:relative;z-index:1}
+
+/* ---------- intro hero ---------- */
+.ihero{max-width:var(--maxw);margin:0 auto;padding:60px 32px 28px;text-align:center}
+.ihero h1{font-size:clamp(38px,4.6vw,60px);line-height:1.0;letter-spacing:-.035em;font-weight:600;margin-top:18px}
+.ihero h1 .grad{background:linear-gradient(96deg,var(--indigo-br),var(--cyan));
+  -webkit-background-clip:text;background-clip:text;color:transparent}
+.ihero .sub{margin:20px auto 0;max-width:620px;font-size:18px;line-height:1.55;color:var(--mut)}
+.ihero .sub code{font-family:var(--mono);color:var(--txt);background:var(--panel2);padding:1px 6px;border-radius:5px;font-size:.85em;border:1px solid var(--line)}
+.capnote{margin:26px auto 0;display:inline-flex;align-items:center;gap:14px;flex-wrap:wrap;justify-content:center;
+  font-family:var(--mono);font-size:12.5px;color:var(--mut);
+  background:var(--panel);border:1px solid var(--line2);border-radius:100px;padding:8px 8px 8px 16px}
+.capnote .lead{display:inline-flex;align-items:center;gap:8px}
+.capnote .lead svg{width:15px;height:15px;color:var(--indigo-br)}
+.capnote .tier{display:inline-flex;align-items:center;gap:7px;background:var(--panel2);border:1px solid var(--line);
+  border-radius:100px;padding:5px 11px}
+.capnote .tier .pip{width:7px;height:7px;border-radius:50%}
+.capnote .tier.on .pip{background:var(--grn);box-shadow:0 0 8px var(--grn)}
+.capnote .tier.off .pip{background:var(--dim)}
+.capnote .tier b{color:var(--txt2);font-weight:600}
+.capnote .tier .st{color:var(--dim)}
+
+/* ---------- demo section + card frame ---------- */
+.demo-sec{padding:46px 32px}
+.demo-wrap{max-width:1080px;margin:0 auto}
+.demo-head{max-width:680px;margin:0 0 26px}
+.demo-head .num{font-family:var(--mono);font-size:12px;font-weight:600;letter-spacing:.08em;color:var(--indigo-br)}
+.demo-head h2{font-size:clamp(25px,2.9vw,34px);line-height:1.08;letter-spacing:-.025em;font-weight:600;margin-top:10px}
+.demo-head p{margin-top:12px;font-size:16.5px;line-height:1.55;color:var(--mut);max-width:600px}
+.demo-head p b{color:var(--txt2);font-weight:600}
+.demo-head p code{font-family:var(--mono);font-size:.84em;background:var(--panel3);padding:1px 6px;border-radius:5px;color:var(--txt2)}
+
+.demo-card{background:linear-gradient(180deg,var(--panel),var(--panel2));
+  border:1px solid var(--line2);border-radius:18px;overflow:hidden;
+  box-shadow:var(--shadow-md),0 0 0 1px var(--line);position:relative}
+.demo-bar{display:flex;align-items:center;gap:12px;padding:13px 18px;border-bottom:1px solid var(--line);
+  background:color-mix(in oklch,var(--panel) 60%,#000);flex-wrap:wrap}
+[data-theme="light"] .demo-bar{background:var(--panel2)}
+.demo-bar .title{font-family:var(--mono);font-size:12.5px;color:var(--txt2);font-weight:500;display:flex;align-items:center;gap:9px}
+.demo-bar .title .ld{width:7px;height:7px;border-radius:50%;background:var(--grn);box-shadow:0 0 8px var(--grn);animation:blip 1.5s infinite}
+.demo-controls{margin-left:auto;display:flex;align-items:center;gap:8px;flex-wrap:wrap}
+
+/* control atoms */
+.ctl{font-family:var(--mono);font-size:12.5px;font-weight:500;
+  display:inline-flex;align-items:center;gap:8px;padding:8px 13px;border-radius:9px;cursor:pointer;
+  border:1px solid var(--line2);background:var(--panel);color:var(--txt2);
+  transition:border-color .15s,color .15s,background .15s,transform .12s}
+.ctl:hover{border-color:var(--line3);color:var(--txt)}
+.ctl:active{transform:translateY(1px)}
+.ctl svg{width:14px;height:14px}
+.ctl.pri{background:linear-gradient(180deg,var(--indigo),var(--indigo-dk));border-color:transparent;color:#fff;
+  box-shadow:0 8px 18px -12px var(--indigo)}
+.ctl.pri:hover{color:#fff;filter:brightness(1.05)}
+.ctl[disabled]{opacity:.45;cursor:default;pointer-events:none}
+
+/* toggle (segmented) */
+.seg{display:inline-flex;border:1px solid var(--line2);border-radius:9px;overflow:hidden;background:var(--panel)}
+.seg button{appearance:none;border:0;background:transparent;cursor:pointer;
+  font-family:var(--mono);font-size:12px;font-weight:500;color:var(--mut);padding:8px 13px;
+  display:inline-flex;align-items:center;gap:7px;transition:color .15s,background .15s}
+.seg button + button{border-left:1px solid var(--line2)}
+.seg button .dot{width:7px;height:7px;border-radius:50%;background:var(--dim)}
+.seg button:hover{color:var(--txt2)}
+.seg button[data-on="1"]{color:var(--txt);background:var(--panel3)}
+.seg button[data-on="1"].good .dot{background:var(--grn);box-shadow:0 0 7px var(--grn)}
+.seg button[data-on="1"].bad .dot{background:var(--red);box-shadow:0 0 7px var(--red)}
+
+/* viz stage */
+.stage{position:relative;padding:18px 18px 6px}
+.stage svg{display:block;width:100%;height:auto;overflow:hidden}
+.stage canvas{display:block;width:100%}
+
+/* readout strip */
+.readout{display:grid;gap:1px;background:var(--line);border-top:1px solid var(--line);
+  grid-template-columns:repeat(auto-fit,minmax(120px,1fr))}
+.stat{background:var(--panel);padding:14px 16px;display:flex;flex-direction:column;gap:3px}
+.stat .k{font-family:var(--mono);font-size:10px;letter-spacing:.07em;text-transform:uppercase;color:var(--dim)}
+.stat .v{font-family:var(--code);font-size:21px;font-weight:600;color:var(--txt);line-height:1;
+  font-variant-numeric:tabular-nums;display:flex;align-items:baseline;gap:5px}
+.stat .v .u{font-size:11.5px;font-weight:500;color:var(--mut)}
+.stat .v.warn{color:var(--amber)}.stat .v.bad{color:var(--red)}.stat .v.good{color:var(--grn)}
+
+/* legend */
+.legend{display:flex;flex-wrap:wrap;gap:7px 18px;padding:0 18px 16px;
+  font-family:var(--mono);font-size:11.5px;color:var(--mut)}
+.legend span{display:inline-flex;align-items:center;gap:7px}
+.legend i{width:9px;height:9px;border-radius:50%;flex:none}
+
+/* ---------- failure recovery timeline ---------- */
+.fr-scrubwrap{padding:6px 20px 20px}
+.fr-track{position:relative;height:34px;margin:6px 0 2px;cursor:pointer;user-select:none;touch-action:none}
+.fr-rail{position:absolute;left:0;right:0;top:50%;height:8px;transform:translateY(-50%);
+  border-radius:6px;background:var(--panel3);overflow:hidden;border:1px solid var(--line)}
+.fr-seg{position:absolute;top:0;bottom:0}
+.fr-fill{position:absolute;left:0;top:50%;height:8px;transform:translateY(-50%);border-radius:6px;
+  background:color-mix(in oklch,var(--indigo) 55%,transparent);mix-blend-mode:normal;pointer-events:none;
+  box-shadow:inset 0 0 0 1px var(--indigo-line)}
+.fr-tick{position:absolute;top:50%;width:2px;height:18px;transform:translate(-1px,-50%);background:var(--line3);border-radius:2px}
+.fr-handle{position:absolute;top:50%;width:18px;height:18px;border-radius:50%;
+  transform:translate(-50%,-50%);background:var(--txt);border:3px solid var(--bg);
+  box-shadow:0 2px 8px rgba(0,0,0,.35),0 0 0 1px var(--line3);pointer-events:none;z-index:3}
+.fr-handle::after{content:"";position:absolute;left:50%;top:50%;width:5px;height:5px;border-radius:50%;
+  transform:translate(-50%,-50%);background:var(--indigo-br)}
+.fr-axis{display:flex;justify-content:space-between;font-family:var(--mono);font-size:10.5px;color:var(--dim);margin-top:7px}
+
+.fr-grid{display:grid;grid-template-columns:1.15fr 1fr;gap:0;border-top:1px solid var(--line)}
+.fr-state{padding:22px;border-right:1px solid var(--line);display:flex;flex-direction:column;gap:14px}
+.fr-pill{align-self:flex-start;display:inline-flex;align-items:center;gap:9px;font-family:var(--mono);
+  font-size:13px;font-weight:600;padding:7px 14px;border-radius:100px;border:1px solid;letter-spacing:.01em}
+.fr-pill .pd{width:8px;height:8px;border-radius:50%}
+.fr-state .big{font-size:15px;line-height:1.5;color:var(--txt2)}
+.fr-state .big b{color:var(--txt);font-weight:600}
+.fr-meta{display:flex;gap:22px;flex-wrap:wrap;margin-top:2px}
+.fr-meta .m{display:flex;flex-direction:column;gap:3px}
+.fr-meta .m .k{font-family:var(--mono);font-size:10px;letter-spacing:.06em;text-transform:uppercase;color:var(--dim)}
+.fr-meta .m .v{font-family:var(--code);font-size:17px;font-weight:600;color:var(--txt);font-variant-numeric:tabular-nums}
+.fr-attempts{display:flex;gap:7px;align-items:center;margin-top:2px}
+.fr-attempts .a{width:26px;height:26px;border-radius:7px;display:grid;place-items:center;
+  font-family:var(--code);font-size:12px;font-weight:600;border:1px solid var(--line2);background:var(--panel);color:var(--dim)}
+.fr-attempts .a.ok{border-color:var(--indigo-line);background:var(--indigo-soft);color:var(--indigo-br)}
+.fr-attempts .a.fail{border-color:color-mix(in oklch,var(--red) 40%,transparent);background:color-mix(in oklch,var(--red) 13%,transparent);color:var(--red)}
+.fr-attempts .a.dead{border-color:var(--line3);background:var(--panel3);color:var(--txt2)}
+
+.fr-log{padding:14px 6px 14px 0;max-height:268px;overflow:auto}
+.fr-log::-webkit-scrollbar{width:8px}.fr-log::-webkit-scrollbar-thumb{background:var(--line2);border-radius:8px}
+.fr-ev{display:flex;gap:12px;padding:8px 18px;align-items:flex-start;position:relative;opacity:.38;
+  transition:opacity .25s,background .25s}
+.fr-ev.on{opacity:1}
+.fr-ev.cur{background:var(--indigo-soft)}
+.fr-ev .dotcol{display:flex;flex-direction:column;align-items:center;flex:none;padding-top:3px}
+.fr-ev .ed{width:9px;height:9px;border-radius:50%;background:var(--dim);z-index:1}
+.fr-ev.on .ed{background:var(--c,var(--indigo))}
+.fr-ev .eline{width:2px;flex:1;background:var(--line2);margin:3px 0 -11px}
+.fr-ev:last-child .eline{display:none}
+.fr-ev .etxt{display:flex;flex-direction:column;gap:2px;min-width:0}
+.fr-ev .et{font-size:13.5px;font-weight:600;color:var(--txt2)}
+.fr-ev.on .et{color:var(--txt)}
+.fr-ev .ed2{font-family:var(--mono);font-size:11.5px;color:var(--mut);line-height:1.45}
+.fr-ev .ets{margin-left:auto;font-family:var(--code);font-size:11px;color:var(--dim);flex:none;padding-left:10px}
+
+/* ---------- worker scaling playground ---------- */
+.wp-grid{display:grid;grid-template-columns:268px 1fr;gap:0}
+.wp-ctl{padding:18px 20px;border-right:1px solid var(--line);display:flex;flex-direction:column;gap:18px}
+.wp-field{display:flex;flex-direction:column;gap:9px}
+.wp-field .lab{display:flex;align-items:baseline;justify-content:space-between;gap:10px}
+.wp-field .lab .n{font-size:13px;font-weight:600;color:var(--txt2);display:flex;align-items:center;gap:7px}
+.wp-field .lab .n small{font-family:var(--mono);font-size:10px;font-weight:500;color:var(--dim)}
+.wp-field .lab .val{font-family:var(--code);font-size:14px;font-weight:600;color:var(--indigo-br);font-variant-numeric:tabular-nums}
+.wp-range{appearance:none;-webkit-appearance:none;width:100%;height:6px;border-radius:5px;
+  background:var(--panel3);outline:none;cursor:pointer;border:1px solid var(--line)}
+.wp-range::-webkit-slider-thumb{appearance:none;-webkit-appearance:none;width:18px;height:18px;border-radius:50%;
+  background:var(--txt);border:3px solid var(--panel);box-shadow:0 1px 4px rgba(0,0,0,.35),0 0 0 1px var(--line3);cursor:pointer}
+.wp-range::-moz-range-thumb{width:16px;height:16px;border-radius:50%;background:var(--txt);
+  border:3px solid var(--panel);box-shadow:0 0 0 1px var(--line3);cursor:pointer}
+.wp-range:disabled{opacity:.5}
+.wp-cap{font-family:var(--mono);font-size:11px;color:var(--mut);line-height:1.5;
+  border-top:1px dashed var(--line2);padding-top:14px}
+.wp-cap b{color:var(--txt2)}
+.wp-cap .verdict{display:block;margin-top:6px;font-weight:600}
+.wp-cap .verdict.good{color:var(--grn)}.wp-cap .verdict.warn{color:var(--amber)}.wp-cap .verdict.bad{color:var(--red)}
+
+.wp-charts{display:flex;flex-direction:column}
+.wp-chart{padding:14px 18px;border-bottom:1px solid var(--line)}
+.wp-chart:last-child{border-bottom:0}
+.wp-chart .ch-hd{display:flex;align-items:baseline;justify-content:space-between;margin-bottom:6px}
+.wp-chart .ch-hd .t{font-family:var(--mono);font-size:11px;letter-spacing:.05em;text-transform:uppercase;color:var(--mut);display:flex;align-items:center;gap:8px}
+.wp-chart .ch-hd .t i{width:9px;height:9px;border-radius:2px}
+.wp-chart .ch-hd .now{font-family:var(--code);font-size:16px;font-weight:600;color:var(--txt);font-variant-numeric:tabular-nums}
+.wp-chart .ch-hd .now .u{font-size:11px;color:var(--mut);font-weight:500;margin-left:3px}
+.wp-canvas{width:100%;height:84px;display:block}
+
+/* CTA */
+.icta{max-width:760px;margin:18px auto 0;text-align:center;padding:56px 32px 8px}
+.icta h2{font-size:clamp(26px,3.2vw,38px);line-height:1.1;letter-spacing:-.03em;font-weight:600}
+.icta p{margin:14px auto 0;max-width:500px;font-size:16.5px;color:var(--mut);line-height:1.55}
+.icta .btns{display:flex;gap:12px;justify-content:center;margin-top:28px;flex-wrap:wrap}
+
+/* reveal (matches landing) */
+.reveal{opacity:0;transform:translateY(18px)}
+.reveal.in{opacity:1;transform:none;transition:opacity .7s cubic-bezier(.2,.6,.2,1),transform .7s cubic-bezier(.2,.6,.2,1)}
+
+@media (max-width:860px){
+  .fr-grid{grid-template-columns:1fr}
+  .fr-state{border-right:0;border-bottom:1px solid var(--line)}
+  .wp-grid{grid-template-columns:1fr}
+  .wp-ctl{border-right:0;border-bottom:1px solid var(--line)}
+}
+@media (max-width:600px){
+  .demo-sec{padding:38px 18px}
+  .demo-controls{width:100%;margin-left:0}
+}
+
+/* ---------- workflow DAG (demo 04) ---------- */
+.wf-grid{display:grid;grid-template-columns:1fr 246px;gap:0}
+.wf-graph{padding:14px 8px 8px 14px;position:relative}
+.wf-graph svg{display:block;width:100%;height:auto;overflow:visible}
+.wf-node{cursor:pointer}
+.wf-node rect{transition:fill .25s,stroke .25s}
+.wf-side{border-left:1px solid var(--line);padding:18px 18px 16px;display:flex;flex-direction:column;gap:14px}
+.wf-side .sk{font-family:var(--mono);font-size:10px;letter-spacing:.06em;text-transform:uppercase;color:var(--dim)}
+.wf-seltype{display:inline-flex;align-items:center;gap:8px;align-self:flex-start;font-family:var(--mono);
+  font-size:11px;font-weight:600;padding:5px 11px;border-radius:100px;border:1px solid var(--indigo-line);
+  background:var(--indigo-soft);color:var(--indigo-br)}
+.wf-selname{font-size:18px;font-weight:600;letter-spacing:-.015em;color:var(--txt);line-height:1.15}
+.wf-selname .mono{font-family:var(--code);font-size:13px;color:var(--mut);display:block;margin-top:3px;font-weight:500}
+.wf-rows{display:flex;flex-direction:column;gap:11px}
+.wf-row{display:flex;flex-direction:column;gap:3px}
+.wf-row .k{font-family:var(--mono);font-size:10px;letter-spacing:.05em;text-transform:uppercase;color:var(--dim)}
+.wf-row .v{font-size:13.5px;color:var(--txt2);line-height:1.45}
+.wf-row .v.mono{font-family:var(--code);font-variant-numeric:tabular-nums}
+.wf-depchips{display:flex;flex-wrap:wrap;gap:6px}
+.wf-depchips .dc{font-family:var(--mono);font-size:11px;color:var(--txt2);background:var(--panel);
+  border:1px solid var(--line2);border-radius:7px;padding:3px 8px}
+.wf-depchips .dc.none{color:var(--dim);border-style:dashed}
+.wf-status{display:inline-flex;align-items:center;gap:8px;font-family:var(--mono);font-size:12.5px;font-weight:600}
+.wf-status .sd{width:9px;height:9px;border-radius:50%;background:var(--dim)}
+.wf-runbranch{margin-top:auto;border-top:1px dashed var(--line2);padding-top:14px}
+.wf-runbranch .ctl{width:100%;justify-content:center}
+.wf-runbranch .note{font-family:var(--mono);font-size:11px;color:var(--dim);text-align:center;margin-top:9px;line-height:1.5}
+@media (max-width:860px){
+  .wf-grid{grid-template-columns:1fr}
+  .wf-side{border-left:0;border-top:1px solid var(--line)}
+  .wf-runbranch{margin-top:0}
+}
+
+/* ---------- embed mode (single demo inside homepage modal) ---------- */
+body[data-embed]{background:var(--bg)}
+body[data-embed] .nav,
+body[data-embed] .ihero,
+body[data-embed] .foot,
+body[data-embed] .bgfx,
+body[data-embed] #twkPanel{display:none !important}
+body[data-embed] main{position:static}
+body[data-embed] .demo-sec{display:none}
+body[data-embed] .demo-sec.embed-show{display:block;background:transparent;border:0;padding:22px 22px 30px}
+body[data-embed] .demo-head{margin-bottom:18px}
+body[data-embed] .demo-head h2{font-size:clamp(22px,2.6vw,28px)}
+
+/* ---------- mesh scheduling (demo 05) ---------- */
+.mesh-hint{display:inline-flex;align-items:center;gap:7px;font-family:var(--mono);font-size:11.5px;color:var(--dim);
+  padding-right:4px}
+.mesh-hint svg{width:14px;height:14px;color:var(--mut)}
+.mesh-node:focus-visible rect[data-rect],.mesh-node:focus-visible{outline:none}
+.mesh-node:focus-visible{outline:2px solid var(--indigo-line);outline-offset:2px;border-radius:12px}
+
+/* motion off (tweak or system pref) */
+[data-motion="off"] .demo-bar .title .ld,
+[data-motion="off"] .eyebrow .dot{animation:none}
diff --git a/docs/public/demos/interactive.html b/docs/public/demos/interactive.html
new file mode 100644
index 00000000..db01fa90
--- /dev/null
+++ b/docs/public/demos/interactive.html
@@ -0,0 +1,283 @@
+<!DOCTYPE html>
+<html lang="en" data-theme="dark">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Interactive — taskito docs</title>
+<meta name="description" content="Seven runnable simulations — rate limiting, failure recovery, worker scaling, workflows, mesh routing, sagas, and a playground — built on SVG and Canvas 2D. No WebGL required.">
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@400;500;600;700&family=IBM+Plex+Mono:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600;700&family=Fira+Code:wght@400;500;600&family=Shantell+Sans:wght@500;600;700&display=optional" rel="stylesheet">
+<link rel="stylesheet" href="theme.css">
+<link rel="stylesheet" href="interactive.css">
+<link rel="icon" type="image/svg+xml" href="favicon.svg">
+</head>
+<body data-page="interactive">
+<div class="bgfx"><div class="grid"></div></div>
+
+<!-- This file is the embed host for the homepage demo modal. It is loaded only
+     as interactive.html?embed=<demoId>; the page chrome (nav/hero/footer) was
+     removed since the modal is the sole entry point. -->
+<main>
+  <!-- DEMO 1 · RATE LIMITING -->
+  <section class="demo-sec" id="ratelimit">
+    <div class="demo-wrap">
+      <div class="demo-head reveal">
+        <div class="num">Rate limiting</div>
+        <h2>What happens when your provider says <span style="color:var(--red)">429</span>?</h2>
+        <p>Requests flow <b>your code → queue → workers → external API</b>. Flip the API to <b>Too Many Requests</b> and watch taskito hold the line: failed calls turn red, retry counters climb, an exponential <code>backoff</code> timer kicks in, and workers keep draining everything else. Nothing is dropped.</p>
+      </div>
+      <div class="demo-card reveal" id="rl-root"></div>
+    </div>
+  </section>
+
+  <!-- DEMO 2 · FAILURE RECOVERY -->
+  <section class="demo-sec" id="recovery" style="background:var(--bg-soft);border-top:1px solid var(--line);border-bottom:1px solid var(--line)">
+    <div class="demo-wrap">
+      <div class="demo-head reveal">
+        <div class="num">Failure recovery</div>
+        <h2>Scrub one job through its whole lifecycle.</h2>
+        <p>Drag the playhead across a single job's timeline — <b>queued → running → failed → retrying → running</b> — and watch the live state, attempt counter, and event log update at every step. Then switch the ending: does it <b>recover</b> on the last retry, or exhaust them and land in the <b>dead-letter queue</b>?</p>
+      </div>
+      <div class="demo-card reveal" id="fr-root"></div>
+    </div>
+  </section>
+
+  <!-- DEMO 3 · WORKER SCALING -->
+  <section class="demo-sec" id="scaling">
+    <div class="demo-wrap">
+      <div class="demo-head reveal">
+        <div class="num">Worker scaling</div>
+        <h2>Tune the pool. Watch throughput, depth, and latency react.</h2>
+        <p>A live discrete-event simulation. Move the sliders for <b>workers</b>, <b>concurrency</b>, <b>arrival rate</b>, and a per-second <b>rate limit</b> — the throughput, queue-depth, and latency charts respond in real time. Find the point where capacity meets demand, and the moment the queue runs away from you.</p>
+      </div>
+      <div class="demo-card reveal" id="wp-root"></div>
+    </div>
+  </section>
+
+  <!-- DEMO 4 · WORKFLOW DAG -->
+  <section class="demo-sec" id="workflow" style="background:var(--bg-soft);border-top:1px solid var(--line);border-bottom:1px solid var(--line)">
+    <div class="demo-wrap">
+      <div class="demo-head reveal">
+        <div class="num">Workflow execution</div>
+        <h2>Fire a DAG and watch execution propagate.</h2>
+        <p>A real dependency graph — <b>chains</b> run in sequence, <b>groups</b> fan out in parallel, a <b>chord</b> joins them back. Hit <b>Run</b> and each task lights up the moment its inputs are ready, or click any node to trace its downstream path and run just that branch.</p>
+      </div>
+      <div class="demo-card reveal" id="wf-root"></div>
+    </div>
+  </section>
+
+  <!-- DEMO 5 · MESH SCHEDULING -->
+  <section class="demo-sec" id="mesh">
+    <div class="demo-wrap">
+      <div class="demo-head reveal">
+        <div class="num">Mesh scheduling</div>
+        <h2>Route every job to the node built to run it.</h2>
+        <p>Because the queue lives in a shared store, any number of worker nodes pull from it — no broker. Each job's <b>routing key</b> sends it to the right pool (<code>gpu</code>, <code>default</code>, <code>email</code>). <b>Click any machine to drop it</b> and watch its work reroute across the rest of the mesh.</p>
+      </div>
+      <div class="demo-card reveal" id="mesh-root"></div>
+    </div>
+  </section>
+
+  <!-- DEMO 6 · SAGA / COMPENSATION -->
+  <section class="demo-sec" id="saga" style="background:var(--bg-soft);border-top:1px solid var(--line);border-bottom:1px solid var(--line)">
+    <div class="demo-wrap">
+      <div class="demo-head reveal">
+        <div class="num">Saga · compensation</div>
+        <h2>When a step fails, unwind the ones that already ran.</h2>
+        <p>A booking modeled as a saga — each step carries a compensating action. Pick where it <b>fails</b> and run it: forward steps commit one by one, then taskito fires the compensations in <b>reverse order</b> so nothing is left half-done. Either it all commits, or it all rolls back.</p>
+      </div>
+      <div class="demo-card reveal" id="saga-root"></div>
+    </div>
+  </section>
+
+  <!-- DEMO 7 · WORK-STEALING MESH -->
+  <section class="demo-sec" id="worksteal">
+    <div class="demo-wrap">
+      <div class="demo-head reveal">
+        <div class="num">Work-stealing</div>
+        <h2>Idle regions steal work from the busy ones.</h2>
+        <p>Run taskito in several regions and they gossip queue depth to each other. When one region's backlog spikes, an <b>idle peer pulls a batch over HTTP</b> and runs it — so no region drowns while another sits idle, and there's still no central broker. Hit <b>Burst</b> to overload a region and watch the mesh rebalance.</p>
+      </div>
+      <div class="demo-card reveal" id="worksteal-root"></div>
+    </div>
+  </section>
+
+</main>
+
+<script>
+/* embed mode: when loaded inside the homepage modal as
+   interactive.html?embed=<demo>&theme=<t>&accent=<hex>, strip the page
+   chrome down to a single demo and inherit the parent's theme + accent.
+   Runs before the demo scripts so only the requested demo mounts. */
+(function(){
+  var sp=new URLSearchParams(location.search);
+  var embed=sp.get('embed');
+  if(!embed) return;
+  var rootEl=document.documentElement;
+  var theme=sp.get('theme'); if(theme==='light'||theme==='dark') rootEl.setAttribute('data-theme',theme);
+  var accent=sp.get('accent');
+  if(accent && accent!=='brand'){
+    var dark=rootEl.getAttribute('data-theme')!=='light';
+    rootEl.style.setProperty('--indigo',accent);
+    rootEl.style.setProperty('--indigo-br','color-mix(in oklch,'+accent+' '+(dark?'82%':'72%')+', white)');
+    rootEl.style.setProperty('--indigo-dk','color-mix(in oklch,'+accent+' 78%, black)');
+    rootEl.style.setProperty('--indigo-soft', dark?'color-mix(in oklch,'+accent+' 15%, transparent)':'color-mix(in oklch,'+accent+' 11%, white)');
+    rootEl.style.setProperty('--indigo-line','color-mix(in oklch,'+accent+' '+(dark?'28%':'26%')+', transparent)');
+  }
+  document.body.setAttribute('data-embed',embed);
+  // keep only the requested demo: remove the other demo roots so their scripts bail
+  var MAP={ratelimit:'rl-root',recovery:'fr-root',scaling:'wp-root',workflow:'wf-root',mesh:'mesh-root',saga:'saga-root',worksteal:'worksteal-root'};
+  Object.keys(MAP).forEach(function(k){ if(k!==embed){ var r=document.getElementById(MAP[k]); if(r) r.remove(); } });
+  var sec=document.getElementById(embed);
+  if(sec){
+    sec.classList.add('embed-show');
+    // landing.js (the scroll-reveal observer) is stripped in embed mode, so
+    // reveal this demo's `.reveal` children directly — they default to opacity:0.
+    [].forEach.call(sec.querySelectorAll('.reveal'), function(el){ el.classList.add('in'); });
+  }
+})();
+</script>
+<script src="demo-ratelimit.js"></script>
+<script src="demo-recovery.js"></script>
+<script src="demo-playground.js"></script>
+<script src="demo-workflow.js"></script>
+<script src="demo-mesh.js"></script>
+<script src="demo-saga.js"></script>
+<script src="demo-worksteal.js"></script>
+
+<!-- ===== Tweaks ===== -->
+<style>
+.twk-panel{position:fixed;right:16px;bottom:16px;z-index:2147483646;width:252px;
+  display:flex;flex-direction:column;
+  background:color-mix(in oklch,var(--panel) 82%,transparent);color:var(--txt);
+  -webkit-backdrop-filter:blur(22px) saturate(150%);backdrop-filter:blur(22px) saturate(150%);
+  border:1px solid var(--line2);border-radius:14px;
+  box-shadow:var(--shadow-lg),0 0 0 1px var(--line);
+  font-family:var(--sans);overflow:hidden}
+.twk-panel[hidden]{display:none}
+.twk-hd{display:flex;align-items:center;justify-content:space-between;padding:11px 9px 11px 15px;user-select:none}
+.twk-hd b{font-size:13px;font-weight:600;letter-spacing:-.01em}
+.twk-x{appearance:none;border:0;background:transparent;color:var(--mut);width:24px;height:24px;
+  border-radius:7px;cursor:pointer;font-size:13px;line-height:1}
+.twk-x:hover{background:var(--panel3);color:var(--txt)}
+.twk-body{padding:2px 15px 16px;display:flex;flex-direction:column;gap:11px}
+.twk-sect{font-family:var(--mono);font-size:10px;font-weight:600;letter-spacing:.06em;
+  text-transform:uppercase;color:var(--dim);padding-top:4px}
+.twk-chips{display:flex;gap:7px}
+.twk-chip{position:relative;appearance:none;flex:1;min-width:0;height:38px;padding:0;border:0;
+  border-radius:9px;cursor:pointer;background:var(--c);
+  box-shadow:0 0 0 1px var(--line2),0 1px 2px rgba(0,0,0,.12);transition:transform .12s,box-shadow .12s}
+.twk-chip:hover{transform:translateY(-1px)}
+.twk-chip[data-on="1"]{box-shadow:0 0 0 2px var(--txt),0 2px 7px rgba(0,0,0,.2)}
+.twk-chip svg{position:absolute;top:50%;left:50%;width:16px;height:16px;transform:translate(-50%,-50%);filter:drop-shadow(0 1px 1px rgba(0,0,0,.35))}
+.twk-seg2{display:grid;grid-template-columns:1fr 1fr;gap:7px}
+.twk-seg2.three{grid-template-columns:1fr 1fr 1fr}
+.twk-seg2 button{appearance:none;border:1px solid var(--line2);background:var(--panel);color:var(--txt2);
+  border-radius:9px;padding:9px 8px;cursor:pointer;font-family:var(--sans);font-size:12.5px;font-weight:600;
+  transition:border-color .12s,background .12s,color .12s}
+.twk-seg2 button:hover{border-color:var(--line3)}
+.twk-seg2 button[data-on="1"]{border-color:var(--indigo);background:var(--indigo-soft);color:var(--indigo-br)}
+.twk-hint{font-size:11px;color:var(--dim);line-height:1.45}
+</style>
+<div id="twkPanel" class="twk-panel" data-omelette-chrome hidden>
+  <div class="twk-hd"><b>Tweaks</b><button class="twk-x" id="twkClose" aria-label="Close tweaks">✕</button></div>
+  <div class="twk-body">
+    <div class="twk-sect">Accent</div>
+    <div class="twk-chips" id="twkAccent"></div>
+    <div class="twk-hint">Recolors buttons, links, charts, and flow accents across every demo.</div>
+    <div class="twk-sect">Motion</div>
+    <div class="twk-seg2" id="twkMotion"></div>
+    <div class="twk-hint">“Off” freezes auto-animation — demos still respond to your input and stats stay live.</div>
+    <div class="twk-sect">Density</div>
+    <div class="twk-seg2" id="twkDensity"></div>
+  </div>
+</div>
+<script>
+var TWEAK_DEFAULTS = /*EDITMODE-BEGIN*/{
+  "accent": "brand",
+  "motion": "on",
+  "density": "spacious"
+}/*EDITMODE-END*/;
+(function(){
+  var root=document.documentElement;
+  var panel=document.getElementById('twkPanel');
+  var PRESETS=[
+    {id:'brand', color:'#1f9d54'},
+    {id:'#0fb5ae', color:'#0fb5ae'},
+    {id:'#3b82f6', color:'#3b82f6'},
+    {id:'#8b5cf6', color:'#8b5cf6'},
+    {id:'#f59e0b', color:'#f59e0b'}
+  ];
+  var ACCENT_VARS=['--indigo','--indigo-br','--indigo-dk','--indigo-soft','--indigo-line'];
+  var CHECK='<svg viewBox="0 0 14 14" fill="none" stroke="#fff" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round"><path d="M3 7.4 5.8 10 11 4.3"/></svg>';
+  var state={
+    accent:(new URLSearchParams(location.search).get('accent'))||(TWEAK_DEFAULTS&&TWEAK_DEFAULTS.accent)||'brand',
+    motion:(TWEAK_DEFAULTS&&TWEAK_DEFAULTS.motion)||'on',
+    density:(TWEAK_DEFAULTS&&TWEAK_DEFAULTS.density)||'comfortable'
+  };
+  function clearAccent(){ ACCENT_VARS.forEach(function(p){ root.style.removeProperty(p); }); }
+  function applyAccent(hex){
+    var dark=root.getAttribute('data-theme')!=='light';
+    root.style.setProperty('--indigo',hex);
+    root.style.setProperty('--indigo-br','color-mix(in oklch,'+hex+' '+(dark?'82%':'72%')+', white)');
+    root.style.setProperty('--indigo-dk','color-mix(in oklch,'+hex+' 78%, black)');
+    root.style.setProperty('--indigo-soft', dark?'color-mix(in oklch,'+hex+' 15%, transparent)':'color-mix(in oklch,'+hex+' 11%, white)');
+    root.style.setProperty('--indigo-line','color-mix(in oklch,'+hex+' '+(dark?'28%':'26%')+', transparent)');
+  }
+  var chipsEl=document.getElementById('twkAccent');
+  function paintAccent(){
+    if(state.accent==='brand') clearAccent(); else applyAccent(state.accent);
+    [].forEach.call(chipsEl.children,function(b){ b.setAttribute('data-on', b.dataset.id===state.accent?'1':'0'); b.innerHTML=b.dataset.id===state.accent?CHECK:''; });
+    if(window.__taskitoDemos&&window.__taskitoDemos.recolor) window.__taskitoDemos.recolor();
+  }
+  PRESETS.forEach(function(p){
+    var b=document.createElement('button');
+    b.type='button'; b.className='twk-chip'; b.dataset.id=p.id;
+    b.style.setProperty('--c',p.color); b.setAttribute('aria-label',p.id==='brand'?'Brand green':p.id);
+    b.addEventListener('click',function(){ state.accent=p.id; paintAccent(); persist('accent',p.id); });
+    chipsEl.appendChild(b);
+  });
+  // motion
+  var motionEl=document.getElementById('twkMotion');
+  [['on','Animated'],['off','Static']].forEach(function(o){
+    var b=document.createElement('button'); b.type='button'; b.dataset.id=o[0]; b.textContent=o[1];
+    b.addEventListener('click',function(){ state.motion=o[0]; applyMotion(); persist('motion',o[0]); });
+    motionEl.appendChild(b);
+  });
+  function applyMotion(){
+    root.setAttribute('data-motion', state.motion);
+    window.__motionOff = (state.motion==='off');
+    [].forEach.call(motionEl.children,function(b){ b.setAttribute('data-on', b.dataset.id===state.motion?'1':'0'); });
+    if(window.__taskitoDemos&&window.__taskitoDemos.motion) window.__taskitoDemos.motion(state.motion==='off');
+  }
+  // density
+  var densEl=document.getElementById('twkDensity');
+  densEl.classList.add('three');
+  [['compact','Compact'],['comfortable','Cozy'],['spacious','Roomy']].forEach(function(o){
+    var b=document.createElement('button'); b.type='button'; b.dataset.id=o[0]; b.textContent=o[1];
+    b.addEventListener('click',function(){ state.density=o[0]; applyDensity(); persist('density',o[0]); });
+    densEl.appendChild(b);
+  });
+  function applyDensity(){
+    root.setAttribute('data-density', state.density);
+    [].forEach.call(densEl.children,function(b){ b.setAttribute('data-on', b.dataset.id===state.density?'1':'0'); });
+  }
+  // Target the embedding parent's exact origin (from the referrer) instead of
+  // broadcasting to "*", and ignore inbound messages from anywhere else.
+  var parentOrigin=(function(){ try{ return new URL(document.referrer).origin; }catch(_){ return window.location.origin; } })();
+  function persist(key,val){ try{ window.parent.postMessage({type:'__edit_mode_set_keys',edits:(function(){var o={};o[key]=val;return o;})()},parentOrigin); }catch(e){} }
+
+  new MutationObserver(function(){ if(state.accent!=='brand') applyAccent(state.accent); })
+    .observe(root,{attributes:true,attributeFilter:['data-theme']});
+
+  function show(){ panel.hidden=false; } function hide(){ panel.hidden=true; }
+  document.getElementById('twkClose').addEventListener('click',function(){ hide(); try{ window.parent.postMessage({type:'__edit_mode_dismissed'},parentOrigin); }catch(e){} });
+  window.addEventListener('message',function(e){ if(e.origin!==parentOrigin||e.source!==window.parent) return; var t=e&&e.data&&e.data.type; if(t==='__activate_edit_mode') show(); else if(t==='__deactivate_edit_mode') hide(); });
+  try{ window.parent.postMessage({type:'__edit_mode_available'},parentOrigin); }catch(e){}
+
+  paintAccent(); applyMotion(); applyDensity();
+})();
+</script>
+</body>
+</html>
diff --git a/docs/public/demos/theme.css b/docs/public/demos/theme.css
new file mode 100644
index 00000000..dadc97ea
--- /dev/null
+++ b/docs/public/demos/theme.css
@@ -0,0 +1,254 @@
+/* ============================================================
+   Taskito · Midnight theme
+   Dark-first, electric indigo, IBM Plex. Light mode via [data-theme].
+   ============================================================ */
+
+:root{
+  /* dark (default) */
+  --bg:#08080c;
+  --bg-soft:#0c0c13;
+  --panel:#0f0f17;
+  --panel2:#13131d;
+  --panel3:#181824;
+  --line:rgba(255,255,255,.08);
+  --line2:rgba(255,255,255,.13);
+  --line3:rgba(255,255,255,.20);
+  --txt:#ececf4;
+  --txt2:#c3c2d4;
+  --mut:#8c8ca3;
+  --dim:#5c5c70;
+  --faint:#3a3a48;
+
+  /* Taskito brand green (matches the product/dashboard). Var names kept for compatibility. */
+  --indigo:#1f9d54;
+  --indigo-br:#3bbf72;
+  --indigo-dk:#15803d;
+  --indigo-soft:rgba(31,157,84,.12);
+  --indigo-line:rgba(31,157,84,.26);
+  --cyan:#29b8a8;
+  --grn:#4ec985;
+  --amber:#ffb86b;
+  --red:#ff6b6b;
+
+  --mono:'IBM Plex Mono',ui-monospace,'SFMono-Regular',monospace;
+  --code:'JetBrains Mono','IBM Plex Mono',ui-monospace,'SFMono-Regular',monospace;
+  --sans:'IBM Plex Sans',system-ui,-apple-system,sans-serif;
+  --hand:'Shantell Sans',cursive;
+
+  --shadow-lg:0 40px 90px -40px rgba(0,0,0,.7);
+  --shadow-md:0 20px 50px -30px rgba(0,0,0,.6);
+  --radius:14px;
+
+  --maxw:1200px;
+}
+
+[data-theme="light"]{
+  /* warm paper light mode — matches the Taskito console */
+  --bg:#f6f4ee;
+  --bg-soft:#fbf9f3;
+  --panel:#ffffff;
+  --panel2:#f2efe7;
+  --panel3:#eae5da;
+  --line:rgba(45,38,18,.10);
+  --line2:rgba(45,38,18,.15);
+  --line3:rgba(45,38,18,.22);
+  --txt:#1b1a15;
+  --txt2:#35332c;
+  --mut:#615d52;
+  --dim:#8b877a;
+  --faint:#bdb9ab;
+
+  --indigo:#10a152;
+  --indigo-br:#13a44e;
+  --indigo-dk:#0a7c3d;
+  --indigo-soft:rgba(16,161,82,.10);
+  --indigo-line:rgba(16,161,82,.26);
+  --cyan:#0d9488;
+  --grn:#15a34a;
+  --amber:#c2410c;
+  --red:#dc2626;
+
+  --shadow-lg:0 40px 90px -45px rgba(60,50,20,.20);
+  --shadow-md:0 24px 50px -34px rgba(60,50,20,.16);
+}
+
+*{box-sizing:border-box;margin:0;padding:0}
+html{scroll-behavior:smooth;-webkit-text-size-adjust:100%}
+body{
+  background:var(--bg);
+  color:var(--txt);
+  font-family:var(--sans);
+  -webkit-font-smoothing:antialiased;
+  line-height:1.5;
+  overflow-x:hidden;
+}
+body.no-anim *{animation:none!important;transition:none!important}
+a{color:inherit;text-decoration:none}
+::selection{background:var(--indigo);color:#fff}
+
+/* color theme transition */
+body, .nav, .panel, .card, .btn, .term, .foot, input, .chip{
+  transition:background-color .4s ease, border-color .4s ease, color .4s ease;
+}
+
+/* ---------- shared atoms ---------- */
+.eyebrow{
+  display:inline-flex;align-items:center;gap:9px;
+  font-family:var(--mono);font-size:12.5px;font-weight:500;letter-spacing:.02em;
+  color:var(--indigo-br);
+  background:var(--indigo-soft);
+  border:1px solid var(--indigo-line);
+  padding:6px 13px;border-radius:100px;
+}
+.eyebrow .dot{
+  width:6px;height:6px;border-radius:50%;background:var(--indigo-br);
+  box-shadow:0 0 0 4px var(--indigo-soft);
+  animation:blip 2.4s ease-in-out infinite;
+}
+@keyframes blip{0%,100%{opacity:.5}50%{opacity:1}}
+
+.btn{
+  font-family:var(--sans);font-size:14.5px;font-weight:600;
+  padding:12px 20px;border-radius:12px;
+  display:inline-flex;align-items:center;gap:8px;
+  border:1px solid transparent;cursor:pointer;
+  transition:transform .15s, box-shadow .2s, background .2s, border-color .2s, color .2s;
+  white-space:nowrap;
+}
+.btn svg{width:16px;height:16px}
+.btn.pri{
+  background:linear-gradient(180deg,var(--indigo),var(--indigo-dk));color:#fff;
+  box-shadow:0 10px 22px -14px var(--indigo),inset 0 1px 0 rgba(255,255,255,.16);
+}
+.btn.pri:hover{transform:translateY(-2px);box-shadow:0 14px 30px -16px var(--indigo),inset 0 1px 0 rgba(255,255,255,.2)}
+.btn.sec{background:var(--panel);border-color:var(--line2);color:var(--txt)}
+.btn.sec:hover{transform:translateY(-2px);border-color:var(--indigo)}
+.btn.gho{color:var(--mut);background:transparent}
+.btn.gho:hover{color:var(--txt)}
+
+.kicker{
+  font-family:var(--mono);font-size:13px;font-weight:500;letter-spacing:.04em;
+  color:var(--indigo-br);text-transform:uppercase;
+}
+
+/* section scaffolding */
+.section{padding:96px 32px;position:relative}
+.wrap{max-width:var(--maxw);margin:0 auto}
+.section-head{max-width:640px;margin:0 auto 56px;text-align:center}
+.section-head h2{
+  font-size:clamp(30px,3.6vw,44px);line-height:1.05;letter-spacing:-.03em;font-weight:600;
+  margin-top:14px;
+}
+.section-head p{margin-top:16px;font-size:18px;line-height:1.55;color:var(--mut)}
+
+/* code tokens */
+.cmt{color:var(--dim)}.kw{color:#c98bff}.def{color:var(--cyan)}.fn{color:var(--indigo-br)}
+.str{color:#9ce08a}.num{color:var(--amber)}.pn{color:var(--mut)}.var{color:var(--txt)}
+[data-theme="light"] .kw{color:#8b3cf0}[data-theme="light"] .str{color:#1a8f3a}
+[data-theme="light"] .def{color:#0e9b91}
+
+/* ---------- nav ---------- */
+.nav{
+  position:sticky;top:0;z-index:50;
+  display:flex;align-items:center;gap:28px;
+  padding:16px 32px;
+  background:color-mix(in oklch,var(--bg) 78%, transparent);
+  backdrop-filter:blur(16px);-webkit-backdrop-filter:blur(16px);
+  border-bottom:1px solid var(--line);
+}
+.brand{display:flex;align-items:center;gap:10px;font-family:var(--mono);font-weight:700;letter-spacing:-.02em;font-size:17px}
+.logo{
+  width:27px;height:27px;border-radius:8px;position:relative;flex:none;
+  background:linear-gradient(135deg,var(--indigo-br),var(--indigo-dk));
+  box-shadow:0 0 0 1px var(--line2),0 6px 18px -6px var(--indigo);
+  display:grid;place-items:center;
+}
+/* real logo mark (tile) */
+.logo-mark{display:inline-flex;align-items:center;flex:none}
+.logo-mark svg{height:26px;width:auto;display:block;border-radius:7px;box-shadow:0 4px 12px -4px color-mix(in oklch,var(--indigo) 55%, transparent)}
+.logo-mark rect{fill:var(--indigo)}
+.brand .bto{color:var(--indigo-br)}
+.navlinks{display:flex;gap:22px;font-size:14px;color:var(--mut);font-weight:500}
+.navlinks a{transition:color .15s;position:relative}
+.navlinks a:hover{color:var(--txt)}
+.navlinks a.active{color:var(--txt)}
+.navright{margin-left:auto;display:flex;align-items:center;gap:12px}
+.kbar{
+  display:flex;align-items:center;gap:8px;padding:8px 12px;border:1px solid var(--line2);
+  border-radius:10px;color:var(--dim);font-size:12.5px;font-family:var(--mono);background:var(--panel);cursor:pointer;
+  transition:border-color .2s;
+}
+.kbar:hover{border-color:var(--line3)}
+.kbar kbd{font-family:var(--mono);border:1px solid var(--line2);border-radius:4px;padding:0 5px;font-size:11px;color:var(--mut)}
+.icon-btn{
+  width:36px;height:36px;border:1px solid var(--line2);border-radius:10px;
+  display:grid;place-items:center;color:var(--mut);background:var(--panel);cursor:pointer;
+  transition:color .2s,border-color .2s;
+}
+.icon-btn:hover{color:var(--txt);border-color:var(--line3)}
+.icon-btn svg{width:17px;height:17px}
+.theme-toggle .sun{display:none}
+[data-theme="light"] .theme-toggle .sun{display:block}
+[data-theme="light"] .theme-toggle .moon{display:none}
+
+/* ---------- footer ---------- */
+.foot{
+  border-top:1px solid var(--line);
+  background:var(--bg-soft);
+  padding:64px 32px 40px;
+}
+.foot-grid{max-width:var(--maxw);margin:0 auto;display:grid;grid-template-columns:1.6fr 1fr 1fr 1fr;gap:40px}
+.foot-brand .brand{margin-bottom:14px}
+.foot-brand p{color:var(--mut);font-size:14px;line-height:1.6;max-width:280px}
+.foot-col h4{font-size:13px;font-family:var(--mono);text-transform:uppercase;letter-spacing:.06em;color:var(--dim);margin-bottom:16px;font-weight:600}
+.foot-col a{display:block;color:var(--mut);font-size:14px;padding:5px 0;transition:color .15s}
+.foot-col a:hover{color:var(--txt)}
+.foot-bottom{
+  max-width:var(--maxw);margin:48px auto 0;padding-top:24px;border-top:1px solid var(--line);
+  display:flex;align-items:center;justify-content:space-between;color:var(--dim);font-size:13px;font-family:var(--mono);
+}
+
+@media (max-width:880px){
+  .navlinks,.kbar{display:none}
+  .foot-grid{grid-template-columns:1fr 1fr}
+  .section{padding:72px 22px}
+}
+@media (prefers-reduced-motion:reduce){*{animation:none!important;scroll-behavior:auto}}
+
+/* ============================================================
+   ⌘K command palette (shared, all pages)
+   ============================================================ */
+.cmdk{position:fixed;inset:0;z-index:200;display:none;align-items:flex-start;justify-content:center}
+.cmdk.show{display:flex}
+.cmdk-backdrop{position:absolute;inset:0;background:color-mix(in oklch,var(--bg) 55%,transparent);backdrop-filter:blur(6px);-webkit-backdrop-filter:blur(6px)}
+.cmdk-panel{position:relative;margin-top:11vh;width:min(620px,92vw);background:var(--panel);border:1px solid var(--line2);
+  border-radius:16px;box-shadow:0 40px 100px -30px rgba(0,0,0,.6),0 0 0 1px var(--line);overflow:hidden;opacity:1;
+  animation:cmdkpop .18s cubic-bezier(.2,.7,.3,1)}
+@keyframes cmdkpop{from{transform:translateY(-8px) scale(.98)}to{transform:none}}
+.cmdk-inputrow{display:flex;align-items:center;gap:11px;padding:15px 17px;border-bottom:1px solid var(--line)}
+.cmdk-ic{width:19px;height:19px;color:var(--mut);flex:none}
+.cmdk-input{flex:1;background:transparent;border:none;outline:none;color:var(--txt);font-family:var(--sans);font-size:16.5px}
+.cmdk-input::placeholder{color:var(--dim)}
+.cmdk-esc{font-family:var(--mono);font-size:11px;color:var(--mut);border:1px solid var(--line2);border-radius:5px;padding:2px 7px;cursor:pointer}
+.cmdk-results{max-height:min(420px,56vh);overflow-y:auto;padding:8px}
+.cmdk-results::-webkit-scrollbar{width:8px}.cmdk-results::-webkit-scrollbar-thumb{background:var(--line2);border-radius:8px}
+.cmdk-group{font-family:var(--mono);font-size:10.5px;text-transform:uppercase;letter-spacing:.07em;color:var(--dim);
+  padding:12px 12px 6px;font-weight:600}
+.cmdk-item{display:flex;align-items:center;gap:13px;padding:10px 12px;border-radius:11px;text-decoration:none;cursor:pointer}
+.cmdk-item.active{background:var(--indigo-soft)}
+.cmdk-it-ic{width:34px;height:34px;border-radius:9px;flex:none;display:grid;place-items:center;
+  background:var(--panel2);border:1px solid var(--line2);color:var(--mut)}
+.cmdk-item.active .cmdk-it-ic{background:var(--panel);border-color:var(--indigo-line);color:var(--indigo-br)}
+.cmdk-it-ic svg{width:17px;height:17px}
+.cmdk-it-body{display:flex;flex-direction:column;gap:2px;min-width:0;flex:1}
+.cmdk-it-t{font-size:14.5px;font-weight:600;color:var(--txt);display:flex;align-items:center;gap:8px}
+.cmdk-it-t em{font-style:normal;font-family:var(--mono);font-size:10px;font-weight:500;color:var(--indigo-br);
+  background:var(--indigo-soft);border:1px solid var(--indigo-line);border-radius:5px;padding:1px 6px}
+.cmdk-it-d{font-size:12.5px;color:var(--mut);white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
+.cmdk-it-go{font-family:var(--mono);font-size:13px;color:var(--dim);opacity:0;flex:none}
+.cmdk-item.active .cmdk-it-go{opacity:1;color:var(--indigo-br)}
+.cmdk-empty{padding:34px 16px;text-align:center;color:var(--mut);font-size:14px}
+.cmdk-foot{display:flex;gap:18px;padding:11px 16px;border-top:1px solid var(--line);color:var(--dim);font-size:11.5px;font-family:var(--mono)}
+.cmdk-foot kbd{font-family:var(--mono);border:1px solid var(--line2);border-radius:4px;padding:0 5px;margin-right:3px;color:var(--mut)}
+.cmdk-foot span{display:flex;align-items:center;gap:3px}
+.kbar,.side-search{cursor:pointer}