docs: rebuild site on React Router v7 (polyglot SDK docs)

.github/workflows/docs.yml

@@ -44,7 +44,7 @@ jobs:
         run: pnpm install --frozen-lockfile
 
       - name: Type check
-        run: pnpm types:check
+        run: pnpm typecheck
 
       - name: Lint
         run: pnpm lint
@@ -54,11 +54,14 @@ jobs:
           DOCS_BASE_PATH: /taskito
         run: pnpm build
 
+      - name: SPA fallback for client-side routes
+        run: cp build/client/__spa-fallback.html build/client/404.html
+
       - name: Upload Pages artifact
         if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
         uses: actions/upload-pages-artifact@v5
         with:
-          path: docs/out
+          path: docs/build/client
 
   deploy:
     needs: build

docs/.gitignore

@@ -23,4 +23,7 @@ yarn-error.log*
 # others
 .env*.local
 .vercel
-next-env.d.ts
+next-env.d.ts
+# React Router
+.react-router/
+build/

docs/README.md

@@ -1,47 +1,49 @@
-# docs
+# Taskito docs
 
-This is a Next.js application generated with
-[Create Fumadocs](https://github.com/fuma-nama/fumadocs).
+The Taskito documentation site — a polyglot (Python + Node.js) docs site built with
+[React Router v7](https://reactrouter.com) in framework mode, statically prerendered
+to HTML for GitHub Pages.
 
-It is a Next.js app with [Static Export](https://nextjs.org/docs/app/guides/static-exports) configured.
+## Stack
 
-Run development server:
+- **React Router v7** (framework mode, `ssr: false` + `prerender`) — static export to
+  `build/client/`.
+- **MDX** via `@mdx-js/rollup` — the content under `content/docs/**/*.mdx` is the source,
+  compiled at build and rendered through the component map in `app/components/mdx/`.
+- **Shiki** for build-time code highlighting; **Mermaid** (client-side) for diagrams.
+- **Tailwind v4** + a ported design system in `app/app.css` (dark + warm-light themes).
+- **MiniSearch** for the client-side ⌘K search index.
+
+## Develop
 
 ```bash
-npm run dev
-# or
-pnpm dev
-# or
-yarn dev
+pnpm install
+pnpm dev          # local dev server
+pnpm typecheck    # react-router typegen + tsc
+pnpm lint         # biome
+pnpm build        # static prerender → build/client/
+pnpm start        # serve the built output
 ```
 
-Open http://localhost:3000 with your browser to see the result.
-
-## Explore
-
-In the project, you can see:
-
-- `lib/source.ts`: Code for content source adapter, [`loader()`](https://fumadocs.dev/docs/headless/source-api) provides the interface to access your content.
-- `lib/layout.shared.tsx`: Shared options for layouts, optional but preferred to keep.
-
-| Route                     | Description                                            |
-| ------------------------- | ------------------------------------------------------ |
-| `app/(home)`              | The route group for your landing page and other pages. |
-| `app/docs`                | The documentation layout and pages.                    |
-| `app/api/search/route.ts` | The Route Handler for search.                          |
+Set `DOCS_BASE_PATH=/taskito` to build under the GitHub Pages base path (CI does this).
 
-### Fumadocs MDX
+## Layout
 
-A `source.config.ts` config file has been included, you can customise different options like frontmatter schema.
-
-Read the [Introduction](https://fumadocs.dev/docs/mdx) for further details.
-
-## Learn More
-
-To learn more about Next.js and Fumadocs, take a look at the following
-resources:
+```
+content/docs/**/*.mdx     the documentation source (+ meta.json nav)
+app/
+  root.tsx                document shell, fonts, no-flash theme
+  routes.ts               route config (landing, llms.txt, docs catch-all)
+  routes/                 home, docs-layout, docs.$ (MDX page), llms[.txt]
+  components/
+    landing/              polyglot landing sections
+    docs/                 sidebar, SDK switch, TOC, prev/next, search modal
+    mdx/                  Callout/Tabs/Card shims + MDX component map
+    ui/                   nav, theme toggle, RawHtml
+    animated/             diagram components (reused in MDX)
+  lib/                    content glob, nav tree, search index, theme, highlighters
+```
 
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js
-  features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
-- [Fumadocs](https://fumadocs.dev) - learn about Fumadocs
+Adding a page: drop an `.mdx` file under `content/docs/`, add it to the directory's
+`meta.json`. It is picked up, prerendered, indexed for search, and slotted into the
+sidebar automatically.

docs/app/app.css

@@ -0,0 +1,12 @@
+@import "tailwindcss";
+
+/* Design system, split by concern. tokens first — every module uses var(--*). */
+@import "./styles/tokens.css";
+@import "./styles/atoms.css";
+@import "./styles/cmdk.css";
+@import "./styles/docs.css";
+@import "./styles/changelog.css";
+@import "./styles/diagrams.css";
+@import "./styles/landing.css";
+@import "./styles/shiki.css";
+@import "./styles/sdk.css";

docs/app/components/diagrams/arch-stack.tsx

@@ -0,0 +1,166 @@
+import { type CSSProperties, Fragment, type ReactNode } from "react";
+
+// Layered architecture stack — exact port of the prototype's `.archstack` HTML
+// (semantic layers + PyO3/store boundaries as direct children).
+
+type Kind = "py" | "rust" | "store" | "";
+
+interface Layer {
+  tag: string;
+  /** Pill colour: `.ltag t-*`. */
+  tagKind?: Kind;
+  /** `.layer` modifier; defaults to `tagKind`. The prototype sometimes pairs a
+   *  `rust` layer surface with a `py` pill (e.g. the resource-proxy layer). */
+  layerKind?: Kind;
+  style?: CSSProperties;
+  title: string;
+  body: ReactNode;
+  role?: string;
+}
+
+function ArchStack({
+  layers,
+  bounds,
+  legend,
+}: {
+  layers: Layer[];
+  bounds: ReactNode[]; // one fewer than layers
+  legend?: ReactNode;
+}) {
+  return (
+    <div className="archstack">
+      {legend ? <div className="arch-legend">{legend}</div> : null}
+      {layers.map((l, i) => (
+        <Fragment key={l.title}>
+          <div
+            className={`layer ${l.layerKind ?? l.tagKind ?? ""}`.trim()}
+            style={l.style}
+          >
+            <span className={`ltag t-${l.tagKind ?? "store"}`}>{l.tag}</span>
+            <div className="lbody">
+              <div className="lt">{l.title}</div>
+              <div className="ld">{l.body}</div>
+            </div>
+            {l.role ? <span className="lrole">{l.role}</span> : null}
+          </div>
+          {i < bounds.length ? <div className="bound">{bounds[i]}</div> : null}
+        </Fragment>
+      ))}
+    </div>
+  );
+}
+
+/** `architecture/overview.mdx` — the Python / Rust / Store stack. */
+export function ArchitectureStack() {
+  return (
+    <ArchStack
+      legend={
+        <>
+          <span className="al-item">
+            <span className="al-arrow down">↓</span> you call down — enqueue
+            jobs
+          </span>
+          <span className="al-item">
+            <span className="al-arrow up">↑</span> results &amp; state flow back
+            up
+          </span>
+        </>
+      }
+      layers={[
+        {
+          tag: "Python",
+          tagKind: "py",
+          title: "User-facing API",
+          body: (
+            <>
+              <code>Queue</code>, <code>@task</code>, <code>.delay()</code>,
+              results, workflows, resources — the surface you write against.
+            </>
+          ),
+          role: "what you write",
+        },
+        {
+          tag: "Rust",
+          tagKind: "rust",
+          title: "Engine",
+          body: "Scheduler, dispatcher, worker pool, rate limiter — Tokio runtime, OS-thread pool, near-zero Python overhead.",
+          role: "where the work runs",
+        },
+        {
+          tag: "Store",
+          tagKind: "store",
+          title: "Storage layer",
+          body: "SQLite (bundled) or Postgres — jobs, results, schedules, rate-limit state, all in one place.",
+          role: "where state lives",
+        },
+      ]}
+      bounds={[
+        <>
+          <span className="bdir">↓</span>
+          <span className="pyo3">PyO3 boundary</span>
+          <span className="bdir">↑</span>
+        </>,
+        <>
+          <span className="bdir">↓</span>reads &amp; writes
+          <span className="bdir">↑</span>
+        </>,
+      ]}
+    />
+  );
+}
+
+/** `architecture/resources.mdx` — the 3-layer resource pipeline. */
+export function ResourcePipeline() {
+  return (
+    <ArchStack
+      layers={[
+        {
+          tag: "Layer 1",
+          tagKind: "py",
+          title: "Argument interception",
+          body: (
+            <>
+              The <code>ArgumentInterceptor</code> walks every argument before
+              serialization. CONVERT types become JSON-safe markers, REDIRECT
+              types become DI placeholders, PROXY types are deconstructed,
+              REJECT types raise in strict mode.
+            </>
+          ),
+        },
+        {
+          tag: "Layer 2",
+          tagKind: "py",
+          title: "Worker resource runtime",
+          body: (
+            <>
+              <code>ResourceRuntime</code> initializes resources at worker
+              startup in topological order, then injects requested ones (via{" "}
+              <code>inject=</code> or <code>Inject["name"]</code>) as kwargs.
+              Task-scoped resources come from a semaphore pool.
+            </>
+          ),
+        },
+        {
+          tag: "Layer 3",
+          tagKind: "py",
+          layerKind: "rust",
+          style: {
+            borderColor: "var(--indigo-line)",
+            background:
+              "linear-gradient(100deg,var(--indigo-soft),var(--panel))",
+          },
+          title: "Resource proxies",
+          body: (
+            <>
+              <code>ProxyHandler</code>s deconstruct live objects (file handles,
+              HTTP sessions, cloud clients) into a JSON recipe and reconstruct
+              them on the worker. Recipes are optionally HMAC-signed for tamper
+              detection.
+            </>
+          ),
+        },
+      ]}
+      bounds={["enqueue → worker", "before task()"]}
+    />
+  );
+}

docs/app/components/diagrams/failure-timeline.tsx

@@ -0,0 +1,54 @@
+import type { ReactNode } from "react";
+
+// Crash-recovery timeline — ports the prototype's `.timeline` (`.tl`/`.tt`/`.tb`).
+// `architecture/failure-model.mdx`.
+const STEPS: { at: string; body: ReactNode }[] = [
+  {
+    at: "t = 0s",
+    body: (
+      <>
+        Worker claims a job — status <b>pending → running</b>,{" "}
+        <code>started_at</code> recorded.
+      </>
+    ),
+  },
+  {
+    at: "t = crash",
+    body: (
+      <>
+        Worker dies mid-task. The row is left in <b>running</b> with no result.
+      </>
+    ),
+  },
+  {
+    at: "t = timeout_ms",
+    body: (
+      <>
+        The stale reaper (runs ~every 5s) finds the job has exceeded{" "}
+        <code>timeout_ms</code> and marks it <b>failed</b>.
+      </>
+    ),
+  },
+  {
+    at: "t + retry",
+    body: (
+      <>
+        If retries remain → re-enqueued as <b>pending</b> with backoff.
+        Otherwise → <b>dead-letter</b>.
+      </>
+    ),
+  },
+];
+
+export function CrashRecoveryTimeline() {
+  return (
+    <div className="timeline">
+      {STEPS.map((s) => (
+        <div className="tl" key={s.at}>
+          <div className="tt">{s.at}</div>
+          <div className="tb">{s.body}</div>
+        </div>
+      ))}
+    </div>
+  );
+}

docs/app/components/diagrams/index.ts

@@ -0,0 +1,12 @@
+// Single barrel for every diagram component used in MDX. All architecture
+// diagrams below are prototype-faithful ports (arch.js + arch-*.html).
+
+export { Mermaid } from "@/components/mermaid";
+export { ArchitectureStack, ResourcePipeline } from "./arch-stack";
+export { CrashRecoveryTimeline } from "./failure-timeline";
+export { JobStateMachine } from "./lifecycle-graph";
+export { MeshDemo } from "./mesh-demo";
+export { SchedulerPollLoop } from "./poll-cycle";
+export { SchemaGrid } from "./schema-grid";
+export { Seq } from "./seq";
+export { WorkerDispatch } from "./worker-fork";