Page not found
+No documentation page matches this URL.
+One queue. Python and Node.
+| - Property - | -- {COMPARISON.taskito.label} - | -- {COMPARISON.celery.label} - | -
|---|---|---|
| - {row.label} - | -- {row.taskito} - | -- {row.celery} - | -
- {CTA_CONTENT.description} -
-
- {part.slice(1, -1)}
-
- );
- }
- return part;
- });
-}
diff --git a/docs/src/app/(home)/_sections/features.tsx b/docs/src/app/(home)/_sections/features.tsx
deleted file mode 100644
index 98a70c74..00000000
--- a/docs/src/app/(home)/_sections/features.tsx
+++ /dev/null
@@ -1,36 +0,0 @@
-import { SectionHeader } from "@/components/ui";
-import {
- FEATURES,
- FEATURES_DESCRIPTION,
- FEATURES_TITLE,
- type LandingFeature,
-} from "@/lib/landing-content";
-
-export function Features() {
- return (
- {body}
-- {HERO.description} -
-- {section.description} -
-- {body} -
-- {caption} -
- ) : null} -
- Your code calls{" "}
- .delay() · the
- job durably queues · a Rust scheduler routes it · a worker returns the
- result.
-
- Jobs stream in, workers pick them up, results stream out. No broker - between them. -
-Mermaid render error: ${(err as Error).message}`);
- }
- }
- })();
- return () => {
- cancelled = true;
- };
- }, [chart, id, resolvedTheme]);
-
- return (
-
- );
-}
diff --git a/docs/src/components/provider.tsx b/docs/src/components/provider.tsx
deleted file mode 100644
index de8ad125..00000000
--- a/docs/src/components/provider.tsx
+++ /dev/null
@@ -1,8 +0,0 @@
-"use client";
-import { RootProvider } from "fumadocs-ui/provider/next";
-import type { ReactNode } from "react";
-import SearchDialog from "@/components/search";
-
-export function Provider({ children }: { children: ReactNode }) {
- return {description}
- ) : null} -
- {children}
-
- ),
- },
- });
-}
diff --git a/docs/src/lib/landing-content.tsx b/docs/src/lib/landing-content.tsx
deleted file mode 100644
index 0229467a..00000000
--- a/docs/src/lib/landing-content.tsx
+++ /dev/null
@@ -1,325 +0,0 @@
-import {
- Activity,
- BookOpen,
- Clock,
- Code2,
- Cpu,
- Database,
- Layers,
- type LucideIcon,
- Mail,
- Shield,
- Sparkles,
- Workflow,
- Zap,
-} from "lucide-react";
-import { RELEASE_BADGE } from "./release";
-
-export type CtaTarget = {
- href: string;
- label: string;
-};
-
-export type LandingHero = {
- badge: string;
- headline: string[];
- description: string;
- primaryCta: CtaTarget;
- secondaryCta: CtaTarget;
- ghostCta: CtaTarget;
- preview: {
- filename: string;
- code: string;
- };
-};
-
-export type LandingFeature = {
- icon: LucideIcon;
- title: string;
- body: string;
-};
-
-export type DocSectionCard = {
- icon: LucideIcon;
- title: string;
- description: string;
- href: string;
-};
-
-export const DOC_SECTIONS: DocSectionCard[] = [
- {
- icon: BookOpen,
- title: "Guides",
- description:
- "Recipes for tasks, queues, workers, retries, workflows, observability, and integrations.",
- href: "/guides",
- },
- {
- icon: Layers,
- title: "Architecture",
- description:
- "How the Rust core, scheduler, worker pool, storage, and resource graph fit together.",
- href: "/architecture/overview",
- },
- {
- icon: Code2,
- title: "API Reference",
- description:
- "Queues, tasks, results, contexts, the canvas, workflows, testing helpers, and the CLI.",
- href: "/api-reference/overview",
- },
- {
- icon: Sparkles,
- title: "More",
- description:
- "Worked examples, the Celery comparison, FAQ, and the per-release changelog.",
- href: "/more/examples",
- },
-];
-
-export type ComparisonRow = {
- label: string;
- taskito: string;
- celery: string;
-};
-
-export type ComparisonStack = {
- label: string;
- caption: string;
- code: string;
-};
-
-export type LandingComparison = {
- title: string;
- description: string;
- taskito: ComparisonStack;
- celery: ComparisonStack;
- rows: ComparisonRow[];
-};
-
-export type LandingCta = {
- title: string;
- description: string;
- primary: CtaTarget;
- secondary: CtaTarget;
-};
-
-export const HERO: LandingHero = {
- badge: RELEASE_BADGE,
- headline: ["Task queue", "without the broker."],
- description:
- "Rust-powered task queue for Python. Replace Celery without Redis or RabbitMQ. Start with SQLite, scale to Postgres.",
- primaryCta: {
- href: "/getting-started/quickstart",
- label: "Quickstart",
- },
- secondaryCta: {
- href: "/getting-started/installation",
- label: "Install",
- },
- ghostCta: {
- href: "https://github.com/ByteVeda/taskito",
- label: "GitHub →",
- },
- preview: {
- filename: "tasks.py",
- code: `# pip install taskito
-from taskito import Queue
-
-queue = Queue(db_path="tasks.db")
-
-@queue.task()
-def add(a, b):
- return a + b
-
-job = add.delay(2, 3)
-print(job.result()) # 5`,
- },
-};
-
-export const FEATURES_TITLE = "What you get";
-export const FEATURES_DESCRIPTION =
- "The convenience of Celery, the performance of Rust, the simplicity of SQLite.";
-
-export const FEATURES: LandingFeature[] = [
- {
- icon: Zap,
- title: "Brokerless",
- body: "No Redis, no RabbitMQ. Everything in a single SQLite file — queue, results, rate limits, schedules. Just `pip install` and go.",
- },
- {
- icon: Cpu,
- title: "Rust-powered",
- body: "The scheduler, dispatcher, and storage engine are all Rust. Tokio runtime, OS-thread worker pool, thin PyO3 boundary keeps the Python overhead negligible.",
- },
- {
- icon: Activity,
- title: "Async-first",
- body: "`async def` tasks dispatch onto a dedicated event loop — no `asyncio.run()` wrapping, no thread-pool bridging. Sync and async tasks coexist transparently.",
- },
- {
- icon: Workflow,
- title: "DAG workflows",
- body: "Multi-step pipelines as directed acyclic graphs. Fan-out, fan-in, conditions, approval gates, sub-workflows, incremental re-runs, Mermaid visualization.",
- },
- {
- icon: Layers,
- title: "Resource system",
- body: "Inject database connections, HTTP clients, and cloud SDKs by name. Three-layer pipeline: argument interception, worker DI, transparent proxy reconstruction.",
- },
- {
- icon: Shield,
- title: "Production-ready",
- body: "Retries with exponential backoff, dead letter queue, rate limits, circuit breakers, distributed locks, structured logs, OTel/Sentry/Prometheus middleware.",
- },
-];
-
-export const COMPARISON: LandingComparison = {
- title: "Less to operate",
- description:
- "The same task, two stacks. Side by side, with the operational delta.",
- taskito: {
- label: "taskito",
- caption: "Brokerless · single process",
- code: `from taskito import Queue
-
-queue = Queue(db_path="tasks.db")
-
-@queue.task(max_retries=3, rate_limit="100/m")
-def send_email(to, subject, body):
- smtp.send(to, subject, body)
-
-# Enqueue
-send_email.delay("alice@example.com", "Hi", "Body")
-
-# Run the worker
-# $ taskito worker --app tasks:queue`,
- },
- celery: {
- label: "Celery + Redis",
- caption: "Requires Redis · 3 processes",
- code: `from celery import Celery
-
-app = Celery(
- "myapp",
- broker="redis://localhost:6379/0",
- backend="redis://localhost:6379/1",
-)
-app.conf.task_default_rate_limit = "100/m"
-
-@app.task(bind=True, max_retries=3)
-def send_email(self, to, subject, body):
- try:
- smtp.send(to, subject, body)
- except SMTPError as exc:
- raise self.retry(exc=exc, countdown=60)
-
-# Enqueue
-send_email.delay("alice@example.com", "Hi", "Body")
-
-# Run the worker (in a separate terminal, plus Redis)
-# $ celery -A myapp worker --loglevel=info`,
- },
- rows: [
- {
- label: "Install",
- taskito: "pip install taskito",
- celery: "pip install celery[redis] + run Redis daemon",
- },
- {
- label: "Background services",
- taskito: "1 (worker)",
- celery: "3 (worker, beat, Redis)",
- },
- {
- label: "Default storage",
- taskito: "SQLite file (built-in)",
- celery: "Redis (separate daemon)",
- },
- {
- label: "Retry config in the example above",
- taskito: "max_retries=3 decorator arg",
- celery: "try/except + self.retry(exc=…)",
- },
- ],
-};
-
-export type UseCase = {
- icon: LucideIcon;
- title: string;
- body: string;
- href: string;
-};
-
-export const USE_CASES_TITLE = "Built for the jobs you actually have";
-export const USE_CASES_DESCRIPTION =
- "Pick the workload — taskito ships the primitives.";
-
-export const USE_CASES: UseCase[] = [
- {
- icon: Database,
- title: "ETL pipelines",
- body: "Chain extract → transform → load as a DAG. Fan out across workers, fan in to aggregate, restart from any node on failure.",
- href: "/guides/workflows",
- },
- {
- icon: Mail,
- title: "Email & notifications",
- body: "Bursty SMTP, push, or webhook delivery. Per-task rate limits keep providers happy; retries with backoff handle transient failures.",
- href: "/guides/reliability/retries",
- },
- {
- icon: Cpu,
- title: "ML inference & batch",
- body: "Long-running model jobs with progress tracking, soft timeouts, and prefork pools for true CPU parallelism without GIL contention.",
- href: "/guides/advanced-execution/prefork",
- },
- {
- icon: Clock,
- title: "Scheduled jobs",
- body: "Six-field cron syntax down to the second. Periodic tasks live in the scheduler — no separate beat daemon to babysit.",
- href: "/guides/core/scheduling",
- },
-];
-
-export const INTEGRATIONS_TITLE = "Slots into your stack";
-export const INTEGRATIONS_DESCRIPTION =
- "First-class support for the tools you already run.";
-
-export type IntegrationGroup = {
- group: string;
- items: string[];
-};
-
-export const INTEGRATIONS: IntegrationGroup[] = [
- {
- group: "Frameworks",
- items: ["Django", "FastAPI", "Flask"],
- },
- {
- group: "Storage",
- items: ["Postgres", "SQLite", "Redis"],
- },
- {
- group: "Observability",
- items: ["OpenTelemetry", "Sentry", "Prometheus"],
- },
- {
- group: "Serialization",
- items: ["JSON", "MsgPack", "Cloudpickle"],
- },
-];
-
-export const CTA: LandingCta = {
- title: "Five minutes from `pip install` to your first job.",
- description:
- "The quickstart walks you through defining a task, enqueuing it, and watching the worker run it — no Redis, no broker, no config.",
- primary: {
- href: "/getting-started/quickstart",
- label: "Start the quickstart",
- },
- secondary: {
- href: "/more/comparison",
- label: "See the full comparison",
- },
-};
diff --git a/docs/src/lib/layout.shared.tsx b/docs/src/lib/layout.shared.tsx
deleted file mode 100644
index 7d4402fc..00000000
--- a/docs/src/lib/layout.shared.tsx
+++ /dev/null
@@ -1,41 +0,0 @@
-import type { BaseLayoutProps } from "fumadocs-ui/layouts/shared";
-import { appName, gitConfig } from "./shared";
-
-const PRIMARY_NAV_LINKS = [
- {
- text: "Getting Started",
- url: "/getting-started/installation",
- },
- {
- text: "Guides",
- url: "/guides",
- },
- {
- text: "Architecture",
- url: "/architecture/overview",
- },
- {
- text: "API",
- url: "/api-reference/overview",
- },
- {
- text: "Changelog",
- url: "/more/changelog",
- },
-];
-
-export function baseOptions(): BaseLayoutProps {
- return {
- nav: {
- title: appName,
- },
- githubUrl: `https://github.com/${gitConfig.user}/${gitConfig.repo}`,
- };
-}
-
-export function homeOptions(): BaseLayoutProps {
- return {
- ...baseOptions(),
- links: PRIMARY_NAV_LINKS,
- };
-}
diff --git a/docs/src/lib/release.ts b/docs/src/lib/release.ts
deleted file mode 100644
index ce20ecf6..00000000
--- a/docs/src/lib/release.ts
+++ /dev/null
@@ -1,4 +0,0 @@
-export const RELEASE_VERSION = "0.16.2";
-export const RELEASE_TAGLINE =
- "mesh scheduling, DLQ policies, dashboard redesign";
-export const RELEASE_BADGE = `v${RELEASE_VERSION.replace(/\.\d+$/, "")} — ${RELEASE_TAGLINE}`;
diff --git a/docs/src/lib/shared.ts b/docs/src/lib/shared.ts
deleted file mode 100644
index fe5750f6..00000000
--- a/docs/src/lib/shared.ts
+++ /dev/null
@@ -1,15 +0,0 @@
-export const appName = "Taskito";
-export const docsRoute = "/";
-export const docsImageRoute = "/og";
-export const docsContentRoute = "/llms.mdx";
-
-// Raw href strings (markdown/OG routes) are not run through Next's router,
-// so basePath is not auto-applied — prepend it ourselves when deployed under
-// a sub-path (e.g. /taskito on GitHub Pages).
-export const basePath = process.env.NEXT_PUBLIC_DOCS_BASE_PATH ?? "";
-
-export const gitConfig = {
- user: "ByteVeda",
- repo: "taskito",
- branch: "master",
-};
diff --git a/docs/src/lib/source.ts b/docs/src/lib/source.ts
deleted file mode 100644
index bbd1cee7..00000000
--- a/docs/src/lib/source.ts
+++ /dev/null
@@ -1,41 +0,0 @@
-import { docs } from "collections/server";
-import { loader } from "fumadocs-core/source";
-import {
- basePath,
- docsContentRoute,
- docsImageRoute,
- docsRoute,
-} from "./shared";
-
-// See https://fumadocs.dev/docs/headless/source-api for more info
-export const source = loader({
- baseUrl: docsRoute,
- source: docs.toFumadocsSource(),
- plugins: [],
-});
-
-export function getPageImage(page: (typeof source)["$inferPage"]) {
- const segments = [...page.slugs, "image.png"];
-
- return {
- segments,
- url: `${basePath}${docsImageRoute}/${segments.join("/")}`,
- };
-}
-
-export function getPageMarkdownUrl(page: (typeof source)["$inferPage"]) {
- const segments = [...page.slugs, "content.md"];
-
- return {
- segments,
- url: `${basePath}${docsContentRoute}/${segments.join("/")}`,
- };
-}
-
-export async function getLLMText(page: (typeof source)["$inferPage"]) {
- const processed = await page.data.getText("processed");
-
- return `# ${page.data.title} (${page.url})
-
-${processed}`;
-}
diff --git a/docs/tsconfig.json b/docs/tsconfig.json
index f43f8735..d3533f57 100644
--- a/docs/tsconfig.json
+++ b/docs/tsconfig.json
@@ -1,35 +1,30 @@
{
+ "include": [
+ "app/**/*.ts",
+ "app/**/*.tsx",
+ "*.ts",
+ "*.tsx",
+ ".react-router/types/**/*"
+ ],
"compilerOptions": {
- "target": "ESNext",
- "lib": ["dom", "dom.iterable", "esnext"],
- "allowJs": true,
- "skipLibCheck": true,
- "strict": true,
- "forceConsistentCasingInFileNames": true,
- "noEmit": true,
- "esModuleInterop": true,
- "module": "esnext",
+ "lib": ["DOM", "DOM.Iterable", "ES2022"],
+ "types": ["@react-router/node", "vite/client"],
+ "target": "ES2022",
+ "module": "ESNext",
"moduleResolution": "bundler",
+ "jsx": "react-jsx",
+ "strict": true,
+ "skipLibCheck": true,
"resolveJsonModule": true,
+ "esModuleInterop": true,
+ "noEmit": true,
+ "allowJs": true,
"isolatedModules": true,
- "jsx": "react-jsx",
- "incremental": true,
+ "verbatimModuleSyntax": true,
+ "rootDirs": [".", "./.react-router/types"],
"paths": {
- "@/*": ["./src/*"],
- "collections/*": ["./.source/*"]
- },
- "plugins": [
- {
- "name": "next"
- }
- ]
+ "@/*": ["./app/*"]
+ }
},
- "include": [
- "next-env.d.ts",
- "**/*.ts",
- "**/*.tsx",
- ".next/types/**/*.ts",
- ".next/dev/types/**/*.ts"
- ],
- "exclude": ["node_modules"]
+ "exclude": ["node_modules", "build"]
}
diff --git a/docs/vite.config.ts b/docs/vite.config.ts
new file mode 100644
index 00000000..993bd4db
--- /dev/null
+++ b/docs/vite.config.ts
@@ -0,0 +1,58 @@
+import { fileURLToPath } from "node:url";
+import mdx from "@mdx-js/rollup";
+import { reactRouter } from "@react-router/dev/vite";
+import rehypeShiki from "@shikijs/rehype";
+import tailwindcss from "@tailwindcss/vite";
+import rehypeAutolinkHeadings from "rehype-autolink-headings";
+import rehypeSlug from "rehype-slug";
+import remarkFrontmatter from "remark-frontmatter";
+import remarkGfm from "remark-gfm";
+import remarkMdxFrontmatter from "remark-mdx-frontmatter";
+import { defineConfig } from "vite";
+import tsconfigPaths from "vite-tsconfig-paths";
+
+// Deploy under /taskito on GitHub Pages; serve from root locally.
+const base = process.env.DOCS_BASE_PATH
+ ? `${process.env.DOCS_BASE_PATH}/`
+ : "/";
+
+const mdxComponentDir = (name: string) =>
+ fileURLToPath(new URL(`./app/components/mdx/${name}.tsx`, import.meta.url));
+
+export default defineConfig({
+ base,
+ resolve: {
+ alias: {
+ // The reused content MDX imports Fumadocs components; map those paths to
+ // our own design-matched shims so the content compiles unchanged.
+ "fumadocs-ui/components/callout": mdxComponentDir("callout"),
+ "fumadocs-ui/components/tabs": mdxComponentDir("tabs"),
+ "fumadocs-ui/components/card": mdxComponentDir("card"),
+ },
+ },
+ plugins: [
+ tailwindcss(),
+ // MDX must transform `.mdx` before React Router's plugin processes routes.
+ {
+ enforce: "pre",
+ ...mdx({
+ remarkPlugins: [
+ remarkGfm,
+ remarkFrontmatter,
+ [remarkMdxFrontmatter, { name: "frontmatter" }],
+ ],
+ rehypePlugins: [
+ rehypeSlug,
+ [
+ rehypeShiki,
+ { themes: { light: "github-light", dark: "github-dark" } },
+ ],
+ [rehypeAutolinkHeadings, { behavior: "wrap" }],
+ ],
+ providerImportSource: "@mdx-js/react",
+ }),
+ },
+ reactRouter(),
+ tsconfigPaths(),
+ ],
+});
From 6666875a4f75d680700e2bff88bdee7f2ba31a84 Mon Sep 17 00:00:00 2001
From: Pratyush Sharma <56130065+pratyush618@users.noreply.github.com>
Date: Sun, 21 Jun 2026 11:19:15 +0530
Subject: [PATCH 02/48] docs: port prototype design system (dark + warm-light
theme)
---
docs/app/app.css | 2975 +++++++++++++++++++++++++++++++++++++++++++++-
docs/biome.json | 13 +-
2 files changed, 2972 insertions(+), 16 deletions(-)
diff --git a/docs/app/app.css b/docs/app/app.css
index fff94dcb..da2e2bba 100644
--- a/docs/app/app.css
+++ b/docs/app/app.css
@@ -1,35 +1,2980 @@
@import "tailwindcss";
-/* Minimal theme tokens for Phase 1; the full design system (theme.css + docs.css
- port) lands in Phase 2. */
+/* ============================================================
+ Design system ported 1:1 from the approved prototype
+ (theme.css + docs.css). Components in app/ reuse these classes.
+ ============================================================ */
+
+/* ============================================================
+ 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, 0.08);
+ --line2: rgba(255, 255, 255, 0.13);
+ --line3: rgba(255, 255, 255, 0.2);
--txt: #ececf4;
- --accent: #3bbf72;
+ --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, 0.12);
+ --indigo-line: rgba(31, 157, 84, 0.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, 0.7);
+ --shadow-md: 0 20px 50px -30px rgba(0, 0, 0, 0.6);
+ --radius: 14px;
+
+ --maxw: 1200px;
}
-html[data-theme="light"] {
+
+[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, 0.1);
+ --line2: rgba(45, 38, 18, 0.15);
+ --line3: rgba(45, 38, 18, 0.22);
--txt: #1b1a15;
- --accent: #13a44e;
+ --txt2: #35332c;
+ --mut: #615d52;
+ --dim: #8b877a;
+ --faint: #bdb9ab;
+
+ --indigo: #10a152;
+ --indigo-br: #13a44e;
+ --indigo-dk: #0a7c3d;
+ --indigo-soft: rgba(16, 161, 82, 0.1);
+ --indigo-line: rgba(16, 161, 82, 0.26);
+ --cyan: #0d9488;
+ --grn: #15a34a;
+ --amber: #c2410c;
+ --red: #dc2626;
+
+ --shadow-lg: 0 40px 90px -45px rgba(60, 50, 20, 0.2);
+ --shadow-md: 0 24px 50px -34px rgba(60, 50, 20, 0.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: "IBM Plex Sans", system-ui, sans-serif;
- margin: 0;
+ 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 0.4s ease,
+ border-color 0.4s ease,
+ color 0.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: 0.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: 0.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 0.15s,
+ box-shadow 0.2s,
+ background 0.2s,
+ border-color 0.2s,
+ color 0.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, 0.16);
+}
+.btn.pri:hover {
+ transform: translateY(-2px);
+ box-shadow:
+ 0 14px 30px -16px var(--indigo),
+ inset 0 1px 0 rgba(255, 255, 255, 0.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: 0.04em;
+ color: var(--indigo-br);
+ text-transform: uppercase;
}
-.landing-stub {
- max-width: 880px;
+/* section scaffolding */
+.section {
+ padding: 96px 32px;
+ position: relative;
+}
+.wrap {
+ max-width: var(--maxw);
margin: 0 auto;
- padding: 120px 32px;
}
-.landing-stub h1 {
- font-size: 48px;
+.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: -0.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: -0.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 0.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 0.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 0.2s,
+ border-color 0.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: 0.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 0.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, 0.6),
+ 0 0 0 1px var(--line);
+ overflow: hidden;
+ opacity: 1;
+ animation: cmdkpop 0.18s cubic-bezier(0.2, 0.7, 0.3, 1);
+}
+@keyframes cmdkpop {
+ from {
+ transform: translateY(-8px) scale(0.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: 0.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;
+}
+
+/* ============================================================
+ taskito docs — shared page styles (sidebar / article / toc)
+ Loaded after theme.css on every docs page.
+ ============================================================ */
+body {
+ overflow-x: hidden;
+}
+.docs-shell {
+ display: grid;
+ grid-template-columns: 282px minmax(0, 1fr) 240px;
+ max-width: 1500px;
+ margin: 0 auto;
+ align-items: start;
+}
+
+/* ---------- sidebar ---------- */
+.sidebar {
+ position: sticky;
+ top: 65px;
+ height: calc(100vh - 65px);
+ overflow-y: auto;
+ padding: 28px 18px 40px 32px;
+ border-right: 1px solid var(--line);
+}
+.sidebar::-webkit-scrollbar {
+ width: 7px;
+}
+.sidebar::-webkit-scrollbar-thumb {
+ background: var(--line2);
+ border-radius: 8px;
+}
+.side-search {
+ display: flex;
+ align-items: center;
+ gap: 9px;
+ width: 100%;
+ padding: 9px 12px;
+ border: 1px solid var(--line2);
+ border-radius: 10px;
+ background: var(--panel);
+ color: var(--dim);
+ font-size: 13px;
+ font-family: var(--mono);
+ cursor: pointer;
+ margin-bottom: 22px;
+ transition: border-color 0.2s;
+}
+.side-search:hover {
+ border-color: var(--line3);
+}
+.side-search .sk {
+ margin-left: auto;
+ display: flex;
+ gap: 4px;
+}
+.side-search kbd {
+ font-family: var(--mono);
+ border: 1px solid var(--line2);
+ border-radius: 4px;
+ padding: 0 5px;
+ font-size: 11px;
+}
+/* SDK switcher (Python | Node) — sits above the nav tree */
+.sdk-switch {
+ display: grid;
+ grid-template-columns: 1fr 1fr;
+ gap: 4px;
+ padding: 4px;
+ margin-bottom: 20px;
+ background: var(--panel2);
+ border: 1px solid var(--line2);
+ border-radius: 11px;
+}
+.sdk-opt {
+ display: flex;
+ align-items: center;
+ justify-content: center;
+ gap: 7px;
+ padding: 8px 6px;
+ border-radius: 8px;
+ font-size: 13px;
+ font-weight: 500;
+ color: var(--mut);
+ text-decoration: none;
+ transition:
+ background 0.15s,
+ color 0.15s,
+ box-shadow 0.15s;
+}
+.sdk-opt svg {
+ width: 15px;
+ height: 15px;
+ flex: none;
+}
+.sdk-opt:hover {
+ color: var(--txt);
+}
+.sdk-opt.active {
+ color: var(--indigo-br);
+ background: var(--panel);
+ box-shadow:
+ 0 1px 3px rgba(0, 0, 0, 0.12),
+ 0 0 0 1px var(--indigo-line);
+}
+.nav-group {
+ margin-bottom: 22px;
+}
+.nav-group > .gt {
+ display: flex;
+ align-items: center;
+ gap: 8px;
+ font-family: var(--mono);
+ font-size: 11px;
+ font-weight: 600;
+ letter-spacing: 0.07em;
+ text-transform: uppercase;
+ color: var(--dim);
+ margin-bottom: 9px;
+ padding: 0 4px;
+}
+.nav-group > .gt svg {
+ width: 14px;
+ height: 14px;
+ color: var(--indigo-br);
+}
+.nav-item {
+ display: flex;
+ align-items: center;
+ gap: 9px;
+ padding: 7px 11px;
+ border-radius: 9px;
+ color: var(--mut);
+ font-size: 14px;
+ cursor: pointer;
+ transition:
+ background 0.15s,
+ color 0.15s;
+ position: relative;
+ text-decoration: none;
+}
+.nav-item:hover {
+ background: var(--panel2);
+ color: var(--txt);
+}
+.nav-item.active {
+ color: var(--indigo-br);
+ background: var(--indigo-soft);
+ font-weight: 500;
+}
+.nav-item.active::before {
+ content: "";
+ position: absolute;
+ left: -32px;
+ top: 6px;
+ bottom: 6px;
+ width: 2px;
+ background: var(--indigo);
+ border-radius: 2px;
+}
+.nav-sub {
+ margin-left: 6px;
+ border-left: 1px solid var(--line2);
+ padding-left: 10px;
+ display: flex;
+ flex-direction: column;
+ gap: 1px;
+}
+
+/* ---------- article ---------- */
+.article {
+ padding: 40px 56px 96px;
+ min-width: 0;
+ max-width: 840px;
+}
+.crumb {
+ display: flex;
+ align-items: center;
+ gap: 8px;
+ font-size: 13px;
+ color: var(--dim);
+ font-family: var(--mono);
+ margin-bottom: 22px;
+}
+.crumb a:hover {
+ color: var(--mut);
+}
+.crumb .sep {
+ opacity: 0.5;
+}
+.article h1 {
+ font-size: 40px;
+ line-height: 1.08;
letter-spacing: -0.03em;
+ font-weight: 600;
+ margin-bottom: 12px;
+}
+.lead {
+ font-size: 18px;
+ line-height: 1.55;
+ color: var(--mut);
+ margin-bottom: 14px;
+}
+.article h2 {
+ font-size: 24px;
+ font-weight: 600;
+ letter-spacing: -0.02em;
+ margin: 48px 0 14px;
+ scroll-margin-top: 90px;
+ display: flex;
+ align-items: center;
+ gap: 11px;
+}
+.article h2 .nbadge {
+ font-family: var(--mono);
+ font-size: 13px;
+ font-weight: 600;
+ color: var(--indigo-br);
+ background: var(--indigo-soft);
+ border: 1px solid var(--indigo-line);
+ width: 28px;
+ height: 28px;
+ border-radius: 8px;
+ display: grid;
+ place-items: center;
+ flex: none;
+}
+.article h3 {
+ font-size: 18px;
+ font-weight: 600;
+ margin: 32px 0 10px;
+ scroll-margin-top: 90px;
+}
+.article p {
+ font-size: 15.5px;
+ line-height: 1.7;
+ color: var(--txt2);
+ margin: 12px 0;
+}
+.article p code,
+.article li code,
+.article td code {
+ font-family: var(--mono);
+ font-size: 0.85em;
+ background: var(--panel2);
+ border: 1px solid var(--line);
+ padding: 1.5px 6px;
+ border-radius: 5px;
+ color: var(--txt);
+}
+.article a {
+ color: var(--indigo-br);
+ text-decoration: none;
+ border-bottom: 1px solid var(--indigo-line);
+ transition: border-color 0.15s;
+}
+.article a:hover {
+ border-color: var(--indigo-br);
+}
+.article ul {
+ margin: 14px 0;
+ padding-left: 4px;
+ list-style: none;
+ display: flex;
+ flex-direction: column;
+ gap: 9px;
+}
+.article ul li {
+ font-size: 15px;
+ line-height: 1.6;
+ color: var(--txt2);
+ padding-left: 22px;
+ position: relative;
+}
+.article ul li::before {
+ content: "";
+ position: absolute;
+ left: 4px;
+ top: 9px;
+ width: 6px;
+ height: 6px;
+ border-radius: 50%;
+ background: var(--indigo);
+ opacity: 0.6;
+}
+
+/* code block */
+.codeblock {
+ margin: 18px 0;
+ border: 1px solid var(--line2);
+ border-radius: 13px;
+ overflow: hidden;
+ background: var(--panel);
+ box-shadow: var(--shadow-md);
+}
+.cb-bar {
+ display: flex;
+ align-items: center;
+ gap: 9px;
+ padding: 10px 14px;
+ border-bottom: 1px solid var(--line);
+ background: color-mix(in oklch, var(--panel) 60%, #000);
+}
+[data-theme="light"] .cb-bar {
+ background: var(--panel2);
+}
+.cb-bar .lang {
+ font-family: var(--mono);
+ font-size: 11.5px;
+ color: var(--mut);
+ text-transform: lowercase;
+}
+.cb-bar .fname {
+ font-family: var(--mono);
+ font-size: 12px;
+ color: var(--txt2);
+}
+.cb-copy {
+ margin-left: auto;
+ background: transparent;
+ border: none;
+ color: var(--dim);
+ cursor: pointer;
+ display: grid;
+ place-items: center;
+ padding: 5px;
+ border-radius: 6px;
+ transition:
+ color 0.15s,
+ background 0.15s;
+}
+.cb-copy:hover {
+ color: var(--txt);
+ background: var(--panel3);
+}
+.cb-copy svg {
+ width: 15px;
+ height: 15px;
+}
+.codeblock pre {
+ margin: 0;
+ padding: 16px 18px;
+ overflow-x: auto;
+ font-family: var(--mono);
+ font-size: 13.5px;
+ line-height: 1.7;
+ color: var(--txt);
+}
+.codeblock pre::-webkit-scrollbar {
+ height: 8px;
+}
+.codeblock pre::-webkit-scrollbar-thumb {
+ background: var(--line3);
+ border-radius: 8px;
+}
+.tok-flag {
+ color: var(--cyan);
+}
+.tok-cmd {
+ color: var(--indigo-br);
+ font-weight: 600;
+}
+.tok-comment {
+ color: var(--dim);
+}
+.tok-str {
+ color: #9ce08a;
+}
+[data-theme="light"] .tok-str {
+ color: #1a8f3a;
+}
+
+/* tabs */
+.tabs {
+ margin: 18px 0;
+}
+.tablist {
+ display: flex;
+ gap: 4px;
+ border-bottom: 1px solid var(--line);
+ margin-bottom: 0;
+}
+.tab {
+ padding: 9px 15px;
+ font-size: 13.5px;
+ font-weight: 500;
+ color: var(--mut);
+ cursor: pointer;
+ border-bottom: 2px solid transparent;
+ transition:
+ color 0.15s,
+ border-color 0.15s;
+ font-family: var(--sans);
+}
+.tab:hover {
+ color: var(--txt);
+}
+.tab.active {
+ color: var(--indigo-br);
+ border-bottom-color: var(--indigo);
+}
+.tabpanel {
+ display: none;
+}
+.tabpanel.active {
+ display: block;
+}
+.tabpanel .codeblock {
+ margin-top: 14px;
+}
+
+/* callout (+ variants) */
+.callout {
+ display: flex;
+ gap: 13px;
+ margin: 20px 0;
+ padding: 15px 17px;
+ border-radius: 12px;
+ border: 1px solid var(--indigo-line);
+ background: var(--indigo-soft);
+}
+.callout .ci {
+ flex: none;
+ width: 22px;
+ height: 22px;
+ color: var(--indigo-br);
+}
+.callout .cc {
+ font-size: 14.5px;
+ line-height: 1.6;
+ color: var(--txt2);
+}
+.callout .cc strong {
+ color: var(--txt);
+ font-weight: 600;
+}
+.callout .ctitle {
+ display: block;
+ font-weight: 600;
+ color: var(--txt);
+ margin-bottom: 3px;
+ font-size: 14.5px;
+}
+.callout.info {
+ border-color: color-mix(in oklch, var(--cyan) 40%, transparent);
+ background: color-mix(in oklch, var(--cyan) 9%, transparent);
+}
+.callout.info .ci {
+ color: var(--cyan);
+}
+.callout.warn {
+ border-color: color-mix(in oklch, var(--amber) 45%, transparent);
+ background: color-mix(in oklch, var(--amber) 10%, transparent);
+}
+.callout.warn .ci {
+ color: var(--amber);
+}
+
+/* doc cards (concept / next-steps) */
+.next-grid {
+ display: grid;
+ grid-template-columns: 1fr 1fr;
+ gap: 12px;
+ margin-top: 18px;
+}
+
+/* icon card grid (index pages) */
+.icard-grid {
+ display: grid;
+ grid-template-columns: repeat(2, 1fr);
+ gap: 14px;
+ margin: 24px 0;
+}
+.icard {
+ display: block;
+ padding: 20px;
+ border: 1px solid var(--line2);
+ border-radius: 15px;
+ background: var(--panel);
+ transition:
+ border-color 0.2s,
+ transform 0.2s,
+ box-shadow 0.2s;
+ position: relative;
+ overflow: hidden;
+}
+.icard:hover {
+ border-color: var(--indigo-line);
+ transform: translateY(-3px);
+ box-shadow: var(--shadow-md);
+}
+.icard .ic {
+ width: 40px;
+ height: 40px;
+ border-radius: 11px;
+ display: grid;
+ place-items: center;
+ margin-bottom: 14px;
+ background: var(--indigo-soft);
+ border: 1px solid var(--indigo-line);
+ color: var(--indigo-br);
+}
+.icard .ic svg {
+ width: 20px;
+ height: 20px;
+}
+.icard .it {
+ font-size: 16px;
+ font-weight: 600;
+ color: var(--txt);
+ display: flex;
+ align-items: center;
+ gap: 7px;
+}
+.icard .it .arr {
+ color: var(--dim);
+ transition:
+ transform 0.2s,
+ color 0.2s;
+ font-size: 14px;
+}
+.icard:hover .it .arr {
+ transform: translateX(3px);
+ color: var(--indigo-br);
+}
+.icard .id {
+ font-size: 13.5px;
+ color: var(--mut);
+ margin-top: 6px;
+ line-height: 1.55;
+}
+@media (max-width: 860px) {
+ .icard-grid {
+ grid-template-columns: 1fr;
+ }
+}
+
+.next-card {
+ display: block;
+ padding: 16px 18px;
+ border: 1px solid var(--line2);
+ border-radius: 13px;
+ background: var(--panel);
+ transition:
+ border-color 0.2s,
+ transform 0.2s;
+}
+.next-card:hover {
+ border-color: var(--indigo-line);
+ transform: translateY(-2px);
+}
+.next-card .nt {
+ font-size: 14.5px;
+ font-weight: 600;
+ color: var(--txt);
+ display: flex;
+ align-items: center;
+ gap: 7px;
+}
+.next-card .nt .arr {
+ color: var(--dim);
+ transition: transform 0.2s;
+}
+.next-card:hover .nt .arr {
+ transform: translateX(3px);
+ color: var(--indigo-br);
+}
+.next-card .nd {
+ font-size: 13px;
+ color: var(--mut);
+ margin-top: 5px;
+ line-height: 1.5;
+}
+
+/* markdown table */
+.md-table {
+ margin: 20px 0;
+ border: 1px solid var(--line2);
+ border-radius: 13px;
+ overflow-x: auto;
+ background: var(--panel);
+}
+.md-table table {
+ width: 100%;
+ border-collapse: collapse;
+ font-size: 14.5px;
+}
+.md-table th {
+ text-align: left;
+ font-family: var(--mono);
+ font-size: 11px;
+ text-transform: uppercase;
+ letter-spacing: 0.05em;
+ color: var(--dim);
+ font-weight: 600;
+ padding: 13px 18px;
+ background: var(--panel2);
+ border-bottom: 1px solid var(--line);
+ white-space: nowrap;
+}
+.md-table td {
+ padding: 13px 18px;
+ border-top: 1px solid var(--line);
+ color: var(--txt2);
+ vertical-align: top;
+}
+.md-table tr td:first-child {
+ white-space: nowrap;
+}
+.md-table a {
+ color: var(--indigo-br);
+ border-bottom: 1px solid var(--indigo-line);
+}
+.md-table td b,
+.md-table .yes {
+ color: var(--grn);
+ font-weight: 600;
+}
+.md-table .no {
+ color: var(--mut);
+}
+/* feature-matrix taskito column highlight */
+.md-table.matrix th:nth-child(2),
+.md-table.matrix td:nth-child(2) {
+ background: var(--indigo-soft);
+}
+.md-table.matrix th:nth-child(2) {
+ color: var(--indigo-br);
+}
+
+/* when-to-use split */
+.use-split {
+ display: grid;
+ grid-template-columns: 1fr 1fr;
+ gap: 16px;
+ margin: 22px 0;
+}
+.use-card {
+ border: 1px solid var(--line2);
+ border-radius: 14px;
+ padding: 20px;
+ background: var(--panel);
+}
+.use-card.yes {
+ border-color: color-mix(in oklch, var(--grn) 35%, transparent);
+}
+.use-card.no {
+ border-color: color-mix(in oklch, var(--amber) 30%, transparent);
+}
+.use-card h3 {
+ font-size: 15px;
+ font-weight: 600;
+ margin: 0 0 12px;
+ display: flex;
+ align-items: center;
+ gap: 8px;
+}
+.use-card.yes h3 {
+ color: var(--grn);
+}
+.use-card.no h3 {
+ color: var(--amber);
+}
+.use-card ul {
+ margin: 0;
+ padding: 0;
+ list-style: none;
+ display: flex;
+ flex-direction: column;
+ gap: 10px;
+}
+.use-card li {
+ font-size: 14px;
+ line-height: 1.55;
+ color: var(--txt2);
+ padding-left: 20px;
+ position: relative;
+}
+.use-card li::before {
+ content: "";
+ position: absolute;
+ left: 3px;
+ top: 8px;
+ width: 6px;
+ height: 6px;
+ border-radius: 50%;
+}
+.use-card.yes li::before {
+ background: var(--grn);
+}
+.use-card.no li::before {
+ background: var(--amber);
+}
+.use-card li b {
+ color: var(--txt);
+ font-weight: 600;
+}
+@media (max-width: 760px) {
+ .use-split {
+ grid-template-columns: 1fr;
+ }
+}
+
+/* FAQ accordion */
+.faq-list {
+ margin: 16px 0;
+ display: flex;
+ flex-direction: column;
+ gap: 10px;
+}
+.faq-item {
+ border: 1px solid var(--line2);
+ border-radius: 13px;
+ background: var(--panel);
+ overflow: hidden;
+ transition: border-color 0.2s;
+}
+.faq-item.open {
+ border-color: var(--indigo-line);
+}
+.faq-q {
+ width: 100%;
+ display: flex;
+ align-items: center;
+ gap: 13px;
+ padding: 16px 18px;
+ background: transparent;
+ border: none;
+ cursor: pointer;
+ text-align: left;
+ font-family: var(--sans);
+ font-size: 15.5px;
+ font-weight: 600;
+ color: var(--txt);
+}
+.faq-q .faq-chevron {
+ margin-left: auto;
+ flex: none;
+ color: var(--mut);
+ transition: transform 0.22s;
+}
+.faq-item.open .faq-q .faq-chevron {
+ transform: rotate(180deg);
+ color: var(--indigo-br);
+}
+.faq-q .faq-qmark {
+ flex: none;
+ width: 26px;
+ height: 26px;
+ border-radius: 8px;
+ display: grid;
+ place-items: center;
+ font-family: var(--mono);
+ font-size: 13px;
+ font-weight: 600;
+ background: var(--indigo-soft);
+ border: 1px solid var(--indigo-line);
+ color: var(--indigo-br);
+}
+.faq-a {
+ display: none;
+ padding: 0 18px 18px 57px;
+}
+.faq-item.open .faq-a {
+ display: block;
+}
+.faq-a p {
+ margin: 6px 0;
+ font-size: 14.5px;
+ line-height: 1.65;
+ color: var(--txt2);
+}
+.faq-a p code,
+.faq-a li code {
+ font-family: var(--mono);
+ font-size: 0.85em;
+ background: var(--panel2);
+ border: 1px solid var(--line);
+ padding: 1.5px 6px;
+ border-radius: 5px;
+ color: var(--txt);
+}
+.faq-a .codeblock {
+ margin: 12px 0;
+}
+.faq-a ul {
+ margin: 10px 0;
+ padding: 0;
+ list-style: none;
+ display: flex;
+ flex-direction: column;
+ gap: 8px;
+}
+.faq-a ul li {
+ font-size: 14px;
+ line-height: 1.55;
+ color: var(--txt2);
+ padding-left: 20px;
+ position: relative;
+}
+.faq-a ul li::before {
+ content: "";
+ position: absolute;
+ left: 4px;
+ top: 9px;
+ width: 5px;
+ height: 5px;
+ border-radius: 50%;
+ background: var(--indigo);
+ opacity: 0.6;
+}
+@media (max-width: 760px) {
+ .faq-a {
+ padding-left: 18px;
+ }
+}
+
+/* when-to / general */
+.use-split + h2 {
+ margin-top: 40px;
+}
+
+/* architecture stack diagram */
+.archstack {
+ margin: 26px 0;
+ display: flex;
+ flex-direction: column;
+ gap: 0;
+ border: 1px solid var(--line2);
+ border-radius: 16px;
+ padding: 22px;
+ background: linear-gradient(180deg, var(--bg-soft), var(--panel));
+ position: relative;
+ overflow: hidden;
+}
+.archstack .layer {
+ display: flex;
+ align-items: center;
+ gap: 16px;
+ padding: 16px 18px;
+ border-radius: 13px;
+ border: 1px solid var(--line2);
+ background: var(--panel);
+ position: relative;
+ z-index: 1;
+}
+.archstack .layer.py {
+ border-color: var(--indigo-line);
+ background: linear-gradient(100deg, var(--indigo-soft), var(--panel));
+}
+.archstack .layer.rust {
+ border-color: color-mix(in oklch, var(--amber) 35%, transparent);
+ background: linear-gradient(
+ 100deg,
+ color-mix(in oklch, var(--amber) 8%, transparent),
+ var(--panel)
+ );
+}
+.archstack .ltag {
+ flex: none;
+ font-family: var(--mono);
+ font-size: 11px;
+ font-weight: 600;
+ letter-spacing: 0.06em;
+ text-transform: uppercase;
+ padding: 5px 10px;
+ border-radius: 7px;
+ color: #fff;
+}
+.archstack .ltag.t-py {
+ background: var(--indigo);
+}
+.archstack .ltag.t-rust {
+ background: var(--amber);
+ color: #1a1206;
+}
+.archstack .ltag.t-store {
+ background: var(--mut);
+}
+.archstack .lbody {
+ min-width: 0;
+}
+.archstack .lt {
+ font-size: 15px;
+ font-weight: 600;
+ color: var(--txt);
+}
+.archstack .ld {
+ font-size: 13px;
+ color: var(--mut);
+ margin-top: 2px;
+ line-height: 1.5;
+}
+.archstack .bound {
+ display: flex;
+ align-items: center;
+ justify-content: center;
+ gap: 9px;
+ padding: 8px 0;
+ font-family: var(--mono);
+ font-size: 11px;
+ color: var(--dim);
+ position: relative;
+}
+.archstack .bound::before,
+.archstack .bound::after {
+ content: "";
+ height: 1px;
+ flex: 1;
+ max-width: 120px;
+ background: linear-gradient(90deg, transparent, var(--line2), transparent);
+}
+.archstack .pyo3 {
+ color: var(--indigo-br);
+ border: 1px solid var(--indigo-line);
+ border-radius: 100px;
+ padding: 2px 10px;
+ background: var(--indigo-soft);
+}
+.archstack .pulse {
+ position: absolute;
+ left: 50%;
+ top: 0;
+ width: 8px;
+ height: 8px;
+ border-radius: 50%;
+ background: var(--indigo);
+ box-shadow: 0 0 12px var(--indigo);
+ transform: translateX(-50%);
+ opacity: 0;
+}
+@media (prefers-reduced-motion: no-preference) {
+ .archstack .pulse {
+ animation: archflow 3.2s ease-in-out infinite;
+ }
+}
+@keyframes archflow {
+ 0% {
+ top: 8%;
+ opacity: 0;
+ }
+ 10% {
+ opacity: 1;
+ }
+ 50% {
+ opacity: 1;
+ }
+ 90% {
+ opacity: 1;
+ }
+ 100% {
+ top: 92%;
+ opacity: 0;
+ }
+}
+
+/* ===== release / changelog ===== */
+.changelog {
+ margin-top: 10px;
+}
+.release {
+ padding: 30px 0;
+ border-bottom: 1px solid var(--line);
+}
+.release:first-child {
+ padding-top: 8px;
+}
+.rel-top {
+ display: flex;
+ align-items: center;
+ gap: 12px;
+ flex-wrap: wrap;
+}
+.rel-v {
+ font-family: var(--mono);
+ font-size: 23px;
+ font-weight: 600;
+ letter-spacing: -0.02em;
+ color: var(--txt);
+ scroll-margin-top: 90px;
+}
+.rel-badge {
+ font-family: var(--mono);
+ font-size: 11px;
+ font-weight: 600;
+ padding: 3px 9px;
+ border-radius: 7px;
+ text-transform: uppercase;
+ letter-spacing: 0.04em;
+}
+.rel-badge.feature {
+ color: var(--indigo-br);
+ background: var(--indigo-soft);
+ border: 1px solid var(--indigo-line);
+}
+.rel-badge.patch {
+ color: var(--mut);
+ background: var(--panel2);
+ border: 1px solid var(--line2);
+}
+.rel-badge.security {
+ color: var(--cyan);
+ background: color-mix(in oklch, var(--cyan) 10%, transparent);
+ border: 1px solid color-mix(in oklch, var(--cyan) 35%, transparent);
+}
+.rel-badge.current {
+ color: var(--grn);
+ background: color-mix(in oklch, var(--grn) 12%, transparent);
+ border: 1px solid color-mix(in oklch, var(--grn) 40%, transparent);
+}
+.rel-tagline {
+ flex-basis: 100%;
+ margin-top: 4px;
+ color: var(--mut);
+ font-size: 15px;
+ line-height: 1.55;
+}
+.rel-section {
+ margin-top: 18px;
+}
+.rel-cat {
+ display: inline-block;
+ font-family: var(--mono);
+ font-size: 10.5px;
+ font-weight: 600;
+ text-transform: uppercase;
+ letter-spacing: 0.05em;
+ padding: 2px 9px;
+ border-radius: 6px;
+ margin-bottom: 9px;
+}
+.cat-added {
+ color: var(--grn);
+ background: color-mix(in oklch, var(--grn) 11%, transparent);
+}
+.cat-fixed {
+ color: var(--amber);
+ background: color-mix(in oklch, var(--amber) 11%, transparent);
+}
+.cat-changed {
+ color: var(--indigo-br);
+ background: var(--indigo-soft);
+}
+.cat-breaking {
+ color: var(--red);
+ background: color-mix(in oklch, var(--red) 11%, transparent);
+}
+.cat-security {
+ color: var(--cyan);
+ background: color-mix(in oklch, var(--cyan) 11%, transparent);
+}
+.cat-notes {
+ color: var(--mut);
+ background: var(--panel2);
+}
+.rel-list {
+ margin: 0 0 4px;
+ padding: 0;
+ list-style: none;
+ display: flex;
+ flex-direction: column;
+ gap: 8px;
+}
+.rel-list li {
+ font-size: 14.5px;
+ line-height: 1.6;
+ color: var(--txt2);
+ padding-left: 20px;
+ position: relative;
+}
+.rel-list li::before {
+ content: "";
+ position: absolute;
+ left: 4px;
+ top: 9px;
+ width: 5px;
+ height: 5px;
+ border-radius: 50%;
+ background: var(--faint);
+}
+.rel-list li b {
+ color: var(--txt);
+ font-weight: 600;
+}
+.rel-list li code {
+ font-family: var(--mono);
+ font-size: 0.84em;
+ background: var(--panel2);
+ border: 1px solid var(--line);
+ padding: 1px 5px;
+ border-radius: 5px;
+ color: var(--txt);
+}
+.rel-earlier {
+ margin-top: 6px;
+}
+.rel-earlier .release {
+ padding: 18px 0;
+}
+.rel-earlier .rel-tagline {
+ margin-top: 2px;
+ font-size: 14px;
+}
+
+/* ===== diagram components (architecture) ===== */
+/* --- job lifecycle state graph --- */
+.lc {
+ position: relative;
+ margin: 24px 0;
+ border: 1px solid var(--line2);
+ border-radius: 16px;
+ padding: 20px 16px;
+ background: linear-gradient(180deg, var(--bg-soft), var(--panel));
+ overflow: hidden;
+}
+.lc svg {
+ width: 100%;
+ height: auto;
+ display: block;
+ overflow: visible;
+}
+.lc-node rect {
+ fill: var(--panel);
+ stroke: var(--line2);
+ stroke-width: 1.5;
+}
+.lc-nt {
+ fill: var(--txt);
+ font-size: 16px;
+ font-weight: 600;
+ font-family: var(--sans);
+}
+.lc-nc {
+ fill: var(--dim);
+ font-size: 11px;
+ font-family: var(--mono);
+}
+.lc-elabel {
+ fill: var(--mut);
+ font-size: 11.5px;
+ font-family: var(--mono);
+}
+.lc-node.s-pending rect {
+ stroke: var(--line3);
+}
+.lc-node.s-pending .lc-sd {
+ fill: var(--dim);
+}
+.lc-node.s-running rect {
+ stroke: var(--indigo-line);
+ fill: var(--indigo-soft);
+}
+.lc-node.s-running .lc-sd {
+ fill: var(--indigo);
+}
+.lc-node.s-complete rect {
+ stroke: color-mix(in oklch, var(--grn) 50%, transparent);
+}
+.lc-node.s-complete .lc-sd {
+ fill: var(--grn);
+}
+.lc-node.s-failed rect {
+ stroke: color-mix(in oklch, var(--amber) 50%, transparent);
+}
+.lc-node.s-failed .lc-sd {
+ fill: var(--amber);
+}
+.lc-node.s-dead rect {
+ stroke: color-mix(in oklch, var(--red) 50%, transparent);
+}
+.lc-node.s-dead .lc-sd {
+ fill: var(--red);
+}
+.lc-node.s-cancel rect {
+ stroke: var(--line3);
+ stroke-dasharray: 4 4;
+}
+.lc-node.s-cancel .lc-sd {
+ fill: var(--mut);
+}
+.lc-token {
+ position: absolute;
+ top: 21.4%;
+ left: 15%;
+ width: 11px;
+ height: 11px;
+ border-radius: 50%;
+ margin: -5.5px 0 0 -5.5px;
+ background: var(--indigo);
+ box-shadow: 0 0 12px var(--indigo);
+ z-index: 2;
+}
+@media (prefers-reduced-motion: no-preference) {
+ .lc-node.s-running .lc-sd {
+ animation: blip 1.4s infinite;
+ }
+ .lc-token {
+ animation: lctravel 4.4s cubic-bezier(0.5, 0, 0.4, 1) infinite;
+ }
+}
+@keyframes lctravel {
+ 0% {
+ left: 15%;
+ opacity: 0;
+ }
+ 6% {
+ opacity: 1;
+ }
+ 34% {
+ left: 50%;
+ opacity: 1;
+ }
+ 46% {
+ left: 50%;
+ opacity: 1;
+ }
+ 74% {
+ left: 84.5%;
+ opacity: 1;
+ }
+ 86% {
+ left: 84.5%;
+ opacity: 1;
+ }
+ 100% {
+ left: 84.5%;
+ opacity: 0;
+ }
+}
+
+/* --- scheduler poll cycle --- */
+.pc-wrap {
+ display: flex;
+ align-items: center;
+ gap: 30px;
+ flex-wrap: wrap;
+ justify-content: center;
+ margin: 24px 0;
+ border: 1px solid var(--line2);
+ border-radius: 16px;
+ padding: 26px;
+ background: linear-gradient(180deg, var(--bg-soft), var(--panel));
+}
+.pc-svg {
+ width: 230px;
+ height: 230px;
+ flex: none;
+}
+.pc-center {
+ fill: var(--txt);
+ font-size: 30px;
+ font-weight: 600;
+ font-family: var(--mono);
+ letter-spacing: -0.02em;
+}
+.pc-centersub {
+ fill: var(--dim);
+ font-size: 12px;
+ font-family: var(--mono);
+ text-transform: uppercase;
+ letter-spacing: 0.1em;
+}
+.pc-sweep {
+ transform-origin: 180px 180px;
+}
+@media (prefers-reduced-motion: no-preference) {
+ .pc-sweep {
+ animation: pcspin 3.4s linear infinite;
+ }
+}
+@keyframes pcspin {
+ to {
+ transform: rotate(360deg);
+ }
+}
+.pc-legend {
+ display: flex;
+ flex-direction: column;
+ gap: 12px;
+ min-width: 220px;
+}
+.pc-leg {
+ display: flex;
+ align-items: center;
+ gap: 11px;
+ font-size: 14px;
+}
+.pc-leg .pc-dot {
+ width: 10px;
+ height: 10px;
+ border-radius: 50%;
+ flex: none;
+}
+.pc-leg .pc-name {
+ font-family: var(--mono);
+ font-size: 13.5px;
+ color: var(--txt);
+ font-weight: 500;
+}
+.pc-leg .pc-cad {
+ margin-left: auto;
+ font-family: var(--mono);
+ font-size: 11.5px;
+ color: var(--dim);
+}
+
+/* --- mesh live demo --- */
+.mesh-demo {
+ position: relative;
+ margin: 24px 0;
+ border: 1px solid var(--line2);
+ border-radius: 18px;
+ overflow: hidden;
+ background: radial-gradient(
+ 120% 90% at 50% 40%,
+ var(--bg-soft),
+ var(--panel)
+ );
+}
+.mesh-demo .mesh-toolbar {
+ position: absolute;
+ top: 0;
+ left: 0;
+ right: 0;
+ z-index: 5;
+ display: flex;
+ align-items: center;
+ justify-content: space-between;
+ gap: 12px;
+ padding: 13px 16px;
+ flex-wrap: wrap;
+}
+.mesh-stats {
+ display: flex;
+ gap: 18px;
+ font-size: 12.5px;
+ color: var(--mut);
+ font-family: var(--mono);
+}
+.mesh-stats .mstat b {
+ color: var(--indigo-br);
+ font-weight: 600;
+ font-size: 14px;
+}
+.mesh-btns {
+ display: flex;
+ gap: 8px;
+}
+.mesh-btn {
+ font-family: var(--mono);
+ font-size: 12px;
+ font-weight: 500;
+ padding: 7px 13px;
+ border-radius: 9px;
+ cursor: pointer;
+ white-space: nowrap;
+ background: var(--panel);
+ border: 1px solid var(--line2);
+ color: var(--txt);
+ transition:
+ border-color 0.15s,
+ background 0.15s;
+}
+.mesh-btn:hover {
+ border-color: var(--indigo);
+ color: var(--indigo-br);
+}
+.mesh-stepper {
+ display: inline-flex;
+ align-items: center;
+ gap: 0;
+ border: 1px solid var(--line2);
+ border-radius: 9px;
+ background: var(--panel);
+ overflow: hidden;
+}
+.mesh-stepper button {
+ width: 30px;
+ height: 32px;
+ border: none;
+ background: transparent;
+ color: var(--txt);
+ font-size: 17px;
+ cursor: pointer;
+ display: grid;
+ place-items: center;
+ transition:
+ background 0.15s,
+ color 0.15s;
+ font-family: var(--mono);
+ line-height: 1;
+}
+.mesh-stepper button:hover:not(:disabled) {
+ background: var(--indigo-soft);
+ color: var(--indigo-br);
+}
+.mesh-stepper button:disabled {
+ opacity: 0.35;
+ cursor: not-allowed;
+}
+.mesh-count {
+ font-family: var(--mono);
+ font-size: 11.5px;
+ color: var(--mut);
+ padding: 0 10px;
+ border-left: 1px solid var(--line2);
+ border-right: 1px solid var(--line2);
+ white-space: nowrap;
+}
+.mesh-count b {
+ color: var(--txt);
+ font-weight: 600;
+}
+/* world-map backdrop */
+.mesh-map {
+ position: absolute;
+ inset: 0;
+ z-index: 0;
+ width: 100%;
+ height: 100%;
+ pointer-events: none;
+}
+.mesh-map .grat {
+ stroke: var(--line);
+ stroke-width: 1;
+ fill: none;
+}
+.mesh-map .land {
+ fill: var(--line);
+ opacity: 0.55;
+}
+[data-theme="light"] .mesh-map .land {
+ opacity: 0.7;
+}
+.mesh-map .link {
+ stroke: var(--line2);
+ stroke-width: 1.2;
+ fill: none;
+ stroke-dasharray: 2 6;
+ stroke-linecap: round;
+ opacity: 0.6;
+ transition:
+ opacity 0.2s,
+ stroke 0.2s;
+}
+.mesh-map .link.on {
+ stroke: var(--indigo-line);
+ opacity: 1;
+ stroke-dasharray: none;
+}
+.mesh-map.focus .link {
+ opacity: 0.12;
+}
+.mesh-map.focus .link.lit {
+ opacity: 1;
+ stroke: var(--indigo);
+ stroke-dasharray: none;
+}
+.mesh-map .ping {
+ stroke: var(--cyan);
+ stroke-width: 2;
+ fill: none;
+ opacity: 0;
+}
+
+/* latency labels on links (shown on focus) */
+.mlat {
+ position: absolute;
+ z-index: 3;
+ transform: translate(-50%, -50%);
+ font-family: var(--mono);
+ font-size: 10px;
+ color: var(--cyan);
+ background: color-mix(in oklch, var(--panel) 88%, transparent);
+ border: 1px solid color-mix(in oklch, var(--cyan) 32%, transparent);
+ border-radius: 6px;
+ padding: 1px 6px;
+ white-space: nowrap;
+ pointer-events: none;
+ opacity: 0;
+ transition: opacity 0.18s;
+}
+.mlat.show {
+ opacity: 1;
+}
+
+/* region node (callout card offset from its geo pin) */
+.mw {
+ position: absolute;
+ transform: translate(-50%, -50%);
+ z-index: 2;
+ width: 140px;
+ cursor: pointer;
+ background: var(--panel);
+ border: 1px solid var(--line2);
+ border-radius: 12px;
+ padding: 9px 11px;
+ box-shadow: var(--shadow-md);
+ transition:
+ border-color 0.25s,
+ box-shadow 0.25s;
+}
+.mw:hover {
+ z-index: 6;
+ border-color: var(--indigo-line);
+}
+.mw.idle {
+ opacity: 0.85;
+}
+.mw.hot {
+ border-color: color-mix(in oklch, var(--amber) 55%, transparent);
+ box-shadow:
+ 0 0 0 1px color-mix(in oklch, var(--amber) 30%, transparent),
+ var(--shadow-md);
+}
+.mw.thief {
+ border-color: var(--indigo-line);
+ box-shadow:
+ 0 0 0 2px var(--indigo-line),
+ var(--shadow-md);
+}
+.mw-head {
+ display: flex;
+ align-items: center;
+ gap: 7px;
+ margin-bottom: 6px;
+}
+.mw-id {
+ font-family: var(--mono);
+ font-size: 12px;
+ font-weight: 600;
+ color: var(--txt);
+ letter-spacing: -0.01em;
+ white-space: nowrap;
+}
+.mw-city {
+ font-family: var(--mono);
+ font-size: 9.5px;
+ color: var(--dim);
+ white-space: nowrap;
+ margin-left: auto;
+}
+.mw-pulse {
+ width: 8px;
+ height: 8px;
+ border-radius: 50%;
+ background: var(--dim);
+ flex: none;
+}
+.mw-pulse.go {
+ background: var(--grn);
+ box-shadow: 0 0 10px var(--grn);
+ animation: mwpulse 0.6s ease-out;
+}
+@keyframes mwpulse {
+ 0% {
+ transform: scale(0.6);
+ opacity: 1;
+ }
+ 100% {
+ transform: scale(1.4);
+ opacity: 0.4;
+ }
+}
+.mw-q {
+ display: flex;
+ flex-wrap: wrap;
+ gap: 3px;
+ min-height: 24px;
+ align-content: flex-start;
+}
+.mw-q i {
+ width: 10px;
+ height: 10px;
+ border-radius: 3px;
+ background: linear-gradient(180deg, var(--indigo-br), var(--indigo));
+ display: block;
+ animation: mwjob 0.3s ease-out;
+}
+.mw.hot .mw-q i {
+ background: linear-gradient(
+ 180deg,
+ var(--amber),
+ color-mix(in oklch, var(--amber) 70%, #000)
+ );
+}
+@keyframes mwjob {
+ from {
+ transform: scale(0);
+ }
+ to {
+ transform: scale(1);
+ }
+}
+.mw-q u {
+ font-family: var(--mono);
+ font-size: 10px;
+ color: var(--mut);
+ font-style: normal;
+ align-self: center;
+ margin-left: 2px;
+}
+.mw-load {
+ margin-top: 6px;
+ font-family: var(--mono);
+ font-size: 10px;
+ color: var(--dim);
+}
+.mw-load .mw-n {
+ color: var(--txt2);
+ font-weight: 600;
+}
+
+/* geo pin + callout connector */
+.mnode {
+ position: absolute;
+ z-index: 1;
+ width: 10px;
+ height: 10px;
+ border-radius: 50%;
+ transform: translate(-50%, -50%);
+ background: var(--indigo);
+ box-shadow:
+ 0 0 0 4px var(--indigo-soft),
+ 0 0 10px var(--indigo);
+ transition:
+ background 0.25s,
+ box-shadow 0.25s;
+}
+.mnode.hot {
+ background: var(--amber);
+ box-shadow:
+ 0 0 0 4px color-mix(in oklch, var(--amber) 16%, transparent),
+ 0 0 10px var(--amber);
+}
+.mesh-map .callout {
+ stroke: var(--line3);
+ stroke-width: 1;
+ stroke-dasharray: 2 4;
+ fill: none;
+ opacity: 0.7;
+}
+
+/* traveling packets */
+.mjob {
+ position: absolute;
+ z-index: 4;
+ width: 11px;
+ height: 11px;
+ border-radius: 3px;
+ left: 0;
+ top: 0;
+ background: linear-gradient(180deg, var(--indigo-br), var(--indigo));
+ box-shadow: 0 0 10px var(--indigo);
+ pointer-events: none;
+}
+.mjob.steal {
+ background: linear-gradient(
+ 180deg,
+ var(--cyan),
+ color-mix(in oklch, var(--cyan) 60%, #000)
+ );
+ box-shadow: 0 0 12px var(--cyan);
+ border-radius: 50%;
+}
+.mjob.gos {
+ width: 7px;
+ height: 7px;
+ border-radius: 50%;
+ background: var(--indigo-br);
+ box-shadow: 0 0 9px var(--indigo);
+}
+
+/* legend */
+.mesh-legend {
+ position: absolute;
+ left: 16px;
+ bottom: 13px;
+ z-index: 5;
+ display: flex;
+ gap: 15px;
+ flex-wrap: wrap;
+ font-family: var(--mono);
+ font-size: 10.5px;
+ color: var(--mut);
+}
+.mesh-legend span {
+ display: flex;
+ align-items: center;
+ gap: 6px;
+}
+.mesh-legend i {
+ width: 16px;
+ height: 0;
+ border-top: 2px dashed var(--line3);
+ display: inline-block;
+}
+.mesh-legend i.http {
+ border-top: 2px solid var(--indigo);
+}
+.mesh-legend i.steal {
+ border-top: 2px solid var(--cyan);
+}
+.mesh-legend i.dot {
+ width: 8px;
+ height: 8px;
+ border: 0;
+ border-radius: 50%;
+ background: var(--indigo);
+ box-shadow: 0 0 8px var(--indigo);
+}
+@media (max-width: 640px) {
+ .mw {
+ width: 118px;
+ }
+ .mesh-stats {
+ gap: 11px;
+ font-size: 11px;
+ }
+ .mw-city {
+ display: none;
+ }
+ .mesh-legend {
+ display: none;
+ }
+}
+
+/* --- layered stack (overview/worker/resources/mesh) --- */
+.archstack {
+ margin: 24px 0;
+ display: flex;
+ flex-direction: column;
+ gap: 0;
+ border: 1px solid var(--line2);
+ border-radius: 16px;
+ padding: 22px;
+ background: linear-gradient(180deg, var(--bg-soft), var(--panel));
+ position: relative;
+ overflow: hidden;
+}
+
+/* self-explanatory annotations (overview stack) */
+.arch-legend {
+ display: flex;
+ flex-wrap: wrap;
+ gap: 18px;
+ justify-content: center;
+ margin-bottom: 16px;
+ font-family: var(--mono);
+ font-size: 12px;
+ color: var(--mut);
+}
+.al-item {
+ display: inline-flex;
+ align-items: center;
+ gap: 7px;
+}
+.al-arrow {
+ display: inline-grid;
+ place-items: center;
+ width: 20px;
+ height: 20px;
+ border-radius: 6px;
+ font-size: 13px;
+ font-weight: 700;
+ line-height: 1;
+}
+.al-arrow.down {
+ background: var(--indigo-soft);
+ border: 1px solid var(--indigo-line);
+ color: var(--indigo-br);
+}
+.al-arrow.up {
+ background: color-mix(in oklch, var(--cyan) 12%, transparent);
+ border: 1px solid color-mix(in oklch, var(--cyan) 38%, transparent);
+ color: var(--cyan);
+}
+.archstack .lrole {
+ margin-left: auto;
+ flex: none;
+ font-family: var(--mono);
+ font-size: 11px;
+ color: var(--dim);
+ border: 1px dashed var(--line3);
+ border-radius: 100px;
+ padding: 3px 11px;
+ white-space: nowrap;
+}
+.archstack .bound .bdir {
+ color: var(--indigo-br);
+ font-weight: 700;
+ margin: 0 2px;
+}
+@media (max-width: 620px) {
+ .archstack .lrole {
+ display: none;
+ }
+}
+
+/* --- branching fork: scheduler routes to parallel pools --- */
+.archfork {
+ position: relative;
+ display: grid;
+ grid-template-columns: 1fr 1fr;
+ gap: 16px;
+ margin-top: 30px;
+}
+.archfork::after {
+ content: "";
+ position: absolute;
+ top: -22px;
+ left: 50%;
+ width: 2px;
+ height: 8px;
+ background: var(--line3);
+ transform: translateX(-50%);
+}
+.archfork::before {
+ content: "";
+ position: absolute;
+ top: -14px;
+ left: 25%;
+ right: 25%;
+ height: 14px;
+ border: 2px solid var(--line3);
+ border-bottom: none;
+ border-radius: 9px 9px 0 0;
+}
+.fork-route {
+ display: flex;
+ align-items: center;
+ justify-content: center;
+ gap: 9px;
+ margin-top: 14px;
+ font-family: var(--mono);
+ font-size: 11px;
+ color: var(--dim);
+ position: relative;
+}
+.fork-route::before,
+.fork-route::after {
+ content: "";
+ height: 1px;
+ flex: 1;
+ max-width: 120px;
+ background: linear-gradient(90deg, transparent, var(--line2), transparent);
+}
+.forkcol {
+ display: flex;
+ flex-direction: column;
+ gap: 8px;
+ min-width: 0;
+}
+.forkcol .forktag {
+ display: flex;
+ justify-content: center;
+ font-family: var(--mono);
+ font-size: 10.5px;
+ color: var(--indigo-br);
+ border: 1px dashed var(--indigo-line);
+ border-radius: 100px;
+ padding: 3px 11px;
+ background: var(--indigo-soft);
+ align-self: center;
+}
+.forkcol .layer {
+ flex: 1;
+}
+@media (max-width: 620px) {
+ .archfork {
+ grid-template-columns: 1fr;
+ gap: 22px;
+ margin-top: 22px;
+ }
+ .archfork::before,
+ .archfork::after {
+ display: none;
+ }
+}
+
+/* flow steps (dispatch / ordered) */
+.flowsteps {
+ margin: 20px 0;
+ list-style: none;
+ padding: 0;
+ display: flex;
+ flex-direction: column;
+ gap: 0;
+}
+.flowsteps li {
+ position: relative;
+ padding: 0 0 20px 44px;
+ font-size: 15px;
+ line-height: 1.6;
+ color: var(--txt2);
+}
+.flowsteps li::before {
+ content: counter(fs);
+ counter-increment: fs;
+ position: absolute;
+ left: 0;
+ top: -2px;
+ width: 28px;
+ height: 28px;
+ border-radius: 8px;
+ background: var(--indigo-soft);
+ border: 1px solid var(--indigo-line);
+ color: var(--indigo-br);
+ font-family: var(--mono);
+ font-weight: 600;
+ font-size: 13px;
+ display: grid;
+ place-items: center;
+}
+.flowsteps li::after {
+ content: "";
+ position: absolute;
+ left: 13.5px;
+ top: 28px;
+ bottom: 2px;
+ width: 1px;
+ background: var(--line2);
+}
+.flowsteps li:last-child {
+ padding-bottom: 0;
+}
+.flowsteps li:last-child::after {
+ display: none;
+}
+.flowsteps {
+ counter-reset: fs;
+}
+.flowsteps li code {
+ font-family: var(--mono);
+ font-size: 0.85em;
+ background: var(--panel2);
+ border: 1px solid var(--line);
+ padding: 1.5px 6px;
+ border-radius: 5px;
+ color: var(--txt);
+}
+.flowsteps li b {
+ color: var(--txt);
+ font-weight: 600;
+}
+
+/* sequence diagram */
+.seq {
+ margin: 22px 0;
+ border: 1px solid var(--line2);
+ border-radius: 16px;
+ padding: 22px;
+ background: var(--panel);
+ overflow-x: auto;
+}
+.seq-heads {
+ display: flex;
+ justify-content: space-around;
+ gap: 12px;
+ margin-bottom: 6px;
+ min-width: 420px;
+}
+.seq-head {
+ font-family: var(--mono);
+ font-size: 12px;
+ font-weight: 600;
+ color: var(--txt);
+ background: var(--panel2);
+ border: 1px solid var(--line2);
+ padding: 7px 14px;
+ border-radius: 9px;
+ flex: 1;
+ text-align: center;
+ max-width: 160px;
+}
+.seq-msgs {
+ display: flex;
+ flex-direction: column;
+ gap: 9px;
+ margin-top: 14px;
+ min-width: 420px;
+}
+.seq-msg {
+ display: flex;
+ align-items: center;
+ gap: 10px;
+ font-size: 13px;
+ color: var(--txt2);
+}
+.seq-msg .ln {
+ flex: 1;
+ height: 2px;
+ border-radius: 2px;
+ background: linear-gradient(
+ 90deg,
+ color-mix(in oklch, var(--indigo) 35%, transparent),
+ var(--indigo)
+ );
+ position: relative;
+}
+.seq-msg .ln::after {
+ content: "";
+ position: absolute;
+ right: -1px;
+ top: -4px;
+ border-left: 10px solid var(--indigo);
+ border-top: 5px solid transparent;
+ border-bottom: 5px solid transparent;
+}
+.seq-msg.rev .ln {
+ background: linear-gradient(
+ 90deg,
+ var(--cyan),
+ color-mix(in oklch, var(--cyan) 35%, transparent)
+ );
+}
+.seq-msg.rev .ln::after {
+ right: auto;
+ left: -1px;
+ border-left: none;
+ border-right: 10px solid var(--cyan);
+}
+.seq-msg .lbl {
+ font-family: var(--mono);
+ font-size: 11.5px;
+ color: var(--txt2);
+ white-space: nowrap;
+}
+.seq-msg .self {
+ font-family: var(--mono);
+ font-size: 11.5px;
+ color: var(--dim);
+ font-style: italic;
+ padding-left: 8px;
+}
+
+/* schema entity grid */
+.schema-grid {
+ display: grid;
+ grid-template-columns: repeat(2, 1fr);
+ gap: 14px;
+ margin: 22px 0;
+}
+.entity {
+ border: 1px solid var(--line2);
+ border-radius: 13px;
+ overflow: hidden;
+ background: var(--panel);
+}
+.entity .ehead {
+ display: flex;
+ align-items: center;
+ gap: 8px;
+ padding: 11px 15px;
+ background: var(--panel2);
+ border-bottom: 1px solid var(--line);
+ font-family: var(--mono);
+ font-size: 13px;
+ font-weight: 600;
+ color: var(--txt);
+}
+.entity .ehead .ekey {
+ margin-left: auto;
+ font-size: 10px;
+ color: var(--indigo-br);
+ background: var(--indigo-soft);
+ border: 1px solid var(--indigo-line);
+ padding: 1px 7px;
+ border-radius: 5px;
+}
+.entity .erow {
+ display: flex;
+ align-items: center;
+ gap: 10px;
+ padding: 7px 15px;
+ font-family: var(--mono);
+ font-size: 12px;
+ border-top: 1px solid var(--line);
+}
+.entity .erow:first-of-type {
+ border-top: none;
+}
+.entity .erow .fn {
+ color: var(--txt2);
+}
+.entity .erow .ft {
+ margin-left: auto;
+ color: var(--dim);
+ font-size: 11px;
+}
+.entity .erow .pk {
+ color: var(--amber);
+ font-size: 10px;
+ font-weight: 600;
+}
+.entity .erow .fk {
+ color: var(--cyan);
+ font-size: 10px;
+ font-weight: 600;
+}
+@media (max-width: 860px) {
+ .schema-grid {
+ grid-template-columns: 1fr;
+ }
+}
+
+/* recovery timeline */
+.timeline {
+ margin: 22px 0;
+ border-left: 2px solid var(--line2);
+ padding-left: 0;
+ margin-left: 8px;
+}
+.timeline .tl {
+ position: relative;
+ padding: 0 0 22px 28px;
+}
+.timeline .tl::before {
+ content: "";
+ position: absolute;
+ left: -7px;
+ top: 2px;
+ width: 12px;
+ height: 12px;
+ border-radius: 50%;
+ background: var(--panel);
+ border: 2px solid var(--indigo);
+ box-shadow: 0 0 0 4px var(--bg);
+}
+.timeline .tl:last-child {
+ padding-bottom: 0;
+}
+.timeline .tt {
+ font-family: var(--mono);
+ font-size: 11.5px;
+ color: var(--indigo-br);
+ font-weight: 600;
+}
+.timeline .tb {
+ font-size: 14.5px;
+ color: var(--txt2);
+ margin-top: 3px;
+ line-height: 1.55;
+}
+.timeline .tb b {
+ color: var(--txt);
+ font-weight: 600;
+}
+
+/* page nav (prev/next) */
+.pagenav {
+ display: flex;
+ justify-content: space-between;
+ gap: 14px;
+ margin-top: 56px;
+ padding-top: 28px;
+ border-top: 1px solid var(--line);
+}
+.pagenav a {
+ flex: 1;
+ padding: 16px 18px;
+ border: 1px solid var(--line2);
+ border-radius: 13px;
+ transition: border-color 0.2s;
+ text-decoration: none;
+}
+.pagenav a:hover {
+ border-color: var(--indigo-line);
+}
+.pagenav .dir {
+ font-family: var(--mono);
+ font-size: 11.5px;
+ color: var(--dim);
+ text-transform: uppercase;
+ letter-spacing: 0.05em;
+}
+.pagenav .ttl {
+ font-size: 15px;
+ font-weight: 600;
+ color: var(--txt);
+ margin-top: 4px;
+}
+.pagenav .nx {
+ text-align: right;
+}
+
+/* ---------- TOC ---------- */
+.toc {
+ position: sticky;
+ top: 65px;
+ height: calc(100vh - 65px);
+ overflow-y: auto;
+ padding: 40px 24px 40px 8px;
+}
+.toc h4 {
+ font-family: var(--mono);
+ font-size: 11px;
+ font-weight: 600;
+ letter-spacing: 0.07em;
+ text-transform: uppercase;
+ color: var(--dim);
+ margin-bottom: 14px;
+ display: flex;
+ align-items: center;
+ gap: 8px;
+}
+.toc h4 svg {
+ width: 14px;
+ height: 14px;
+}
+.toc-link {
+ display: block;
+ font-size: 13px;
+ color: var(--mut);
+ padding: 5px 0 5px 14px;
+ border-left: 2px solid var(--line2);
+ transition:
+ color 0.15s,
+ border-color 0.15s;
+ cursor: pointer;
+}
+.toc-link:hover {
+ color: var(--txt);
+}
+.toc-link.sub {
+ padding-left: 26px;
+ font-size: 12.5px;
+}
+.toc-link.active {
+ color: var(--indigo-br);
+ border-left-color: var(--indigo);
+}
+
+/* mobile */
+.menu-btn {
+ display: none;
+}
+@media (max-width: 1180px) {
+ .docs-shell {
+ grid-template-columns: 262px minmax(0, 1fr);
+ }
+ .toc {
+ display: none;
+ }
+}
+@media (max-width: 860px) {
+ .docs-shell {
+ grid-template-columns: 1fr;
+ }
+ .sidebar {
+ display: none;
+ }
+ .article {
+ padding: 32px 22px 72px;
+ }
+ .menu-btn {
+ display: grid;
+ }
+ .next-grid {
+ grid-template-columns: 1fr;
+ }
+}
+
+/* Error boundary fallback */
+.error-page {
+ max-width: 680px;
+ margin: 0 auto;
+ padding: 120px 32px;
+ text-align: center;
+}
+.error-page h1 {
+ font-size: 32px;
+ letter-spacing: -0.02em;
+ margin-bottom: 16px;
}
-.landing-stub p {
- color: var(--accent);
- font-family: "IBM Plex Mono", monospace;
+.error-page a {
+ color: var(--indigo-br);
+ border-bottom: 1px solid var(--indigo-line);
}
diff --git a/docs/biome.json b/docs/biome.json
index ae0b5928..5932a5d0 100644
--- a/docs/biome.json
+++ b/docs/biome.json
@@ -29,5 +29,16 @@
"organizeImports": "on"
}
}
- }
+ },
+ "overrides": [
+ {
+ "includes": ["**/*.css"],
+ "linter": {
+ "rules": {
+ "complexity": { "noImportantStyles": "off" },
+ "style": { "noDescendingSpecificity": "off" }
+ }
+ }
+ }
+ ]
}
From 9504bb78c449d2a78bbc96db72c5d00934676401 Mon Sep 17 00:00:00 2001
From: Pratyush Sharma <56130065+pratyush618@users.noreply.github.com>
Date: Sun, 21 Jun 2026 11:19:15 +0530
Subject: [PATCH 03/48] =?UTF-8?q?docs:=20MDX=20content=20pipeline=20?=
=?UTF-8?q?=E2=80=94=20render=20+=20prerender=20all=20pages?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
docs/app/components/animated/_primitives.tsx | 457 ++++++++++++++++++
.../animated/architecture-stack.tsx | 148 ++++++
.../animated/crash-recovery-timeline.tsx | 287 +++++++++++
.../components/animated/dispatch-sequence.tsx | 200 ++++++++
.../app/components/animated/entity-schema.tsx | 246 ++++++++++
docs/app/components/animated/how-it-works.tsx | 317 ++++++++++++
docs/app/components/animated/index.ts | 10 +
.../components/animated/job-state-machine.tsx | 204 ++++++++
.../components/animated/resource-pipeline.tsx | 251 ++++++++++
.../animated/scheduler-poll-loop.tsx | 291 +++++++++++
.../components/animated/worker-dispatch.tsx | 336 +++++++++++++
docs/app/components/animated/worker-pool.tsx | 312 ++++++++++++
docs/app/components/diagram-carousel.tsx | 149 ++++++
docs/app/components/mdx/callout.tsx | 38 ++
docs/app/components/mdx/card.tsx | 46 ++
docs/app/components/mdx/index.tsx | 46 ++
docs/app/components/mdx/tabs.tsx | 57 +++
docs/app/components/mermaid.tsx | 174 +++++++
docs/app/lib/cn.ts | 6 +
docs/app/lib/content.ts | 53 ++
docs/app/lib/theme.ts | 39 ++
docs/app/routes.ts | 10 +-
docs/app/routes/docs.$.tsx | 41 ++
docs/react-router.config.ts | 4 +-
24 files changed, 3716 insertions(+), 6 deletions(-)
create mode 100644 docs/app/components/animated/_primitives.tsx
create mode 100644 docs/app/components/animated/architecture-stack.tsx
create mode 100644 docs/app/components/animated/crash-recovery-timeline.tsx
create mode 100644 docs/app/components/animated/dispatch-sequence.tsx
create mode 100644 docs/app/components/animated/entity-schema.tsx
create mode 100644 docs/app/components/animated/how-it-works.tsx
create mode 100644 docs/app/components/animated/index.ts
create mode 100644 docs/app/components/animated/job-state-machine.tsx
create mode 100644 docs/app/components/animated/resource-pipeline.tsx
create mode 100644 docs/app/components/animated/scheduler-poll-loop.tsx
create mode 100644 docs/app/components/animated/worker-dispatch.tsx
create mode 100644 docs/app/components/animated/worker-pool.tsx
create mode 100644 docs/app/components/diagram-carousel.tsx
create mode 100644 docs/app/components/mdx/callout.tsx
create mode 100644 docs/app/components/mdx/card.tsx
create mode 100644 docs/app/components/mdx/index.tsx
create mode 100644 docs/app/components/mdx/tabs.tsx
create mode 100644 docs/app/components/mermaid.tsx
create mode 100644 docs/app/lib/cn.ts
create mode 100644 docs/app/lib/content.ts
create mode 100644 docs/app/lib/theme.ts
create mode 100644 docs/app/routes/docs.$.tsx
diff --git a/docs/app/components/animated/_primitives.tsx b/docs/app/components/animated/_primitives.tsx
new file mode 100644
index 00000000..2cfca6c2
--- /dev/null
+++ b/docs/app/components/animated/_primitives.tsx
@@ -0,0 +1,457 @@
+import type { ReactNode } from "react";
+
+const FILTER_ID = "taskito-sketch-filter";
+const ARROW_ID = "taskito-sketch-arrow";
+const ARROW_SOFT_ID = "taskito-sketch-arrow-soft";
+
+export const SKETCH_FILTER = `url(#${FILTER_ID})`;
+export const SKETCH_ARROW = `url(#${ARROW_ID})`;
+export const SKETCH_ARROW_SOFT = `url(#${ARROW_SOFT_ID})`;
+
+const FONT_MONO =
+ 'var(--font-mono), "IBM Plex Mono", ui-monospace, SFMono-Regular, monospace';
+
+/**
+ * Sketch defs (filter + arrow markers). Render once inside each diagram's
+ * `+ {caption} +
+ ) : null} +
+ Your code calls{" "}
+ .delay() · the
+ job durably queues · a Rust scheduler routes it · a worker returns the
+ result.
+
+ Jobs stream in, workers pick them up, results stream out. No broker + between them. +
+Mermaid render error: ${(err as Error).message}`);
+ }
+ }
+ })();
+ return () => {
+ cancelled = true;
+ };
+ }, [chart, id, resolvedTheme]);
+
+ return (
+
+ );
+}
diff --git a/docs/app/lib/cn.ts b/docs/app/lib/cn.ts
new file mode 100644
index 00000000..a70ebb68
--- /dev/null
+++ b/docs/app/lib/cn.ts
@@ -0,0 +1,6 @@
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]): string {
+ return twMerge(clsx(inputs));
+}
diff --git a/docs/app/lib/content.ts b/docs/app/lib/content.ts
new file mode 100644
index 00000000..b481b146
--- /dev/null
+++ b/docs/app/lib/content.ts
@@ -0,0 +1,53 @@
+import type { ComponentType } from "react";
+
+export interface DocFrontmatter {
+ title?: string;
+ description?: string;
+}
+
+interface MdxModule {
+ default: ComponentType;
+ frontmatter?: DocFrontmatter;
+}
+
+// Compile every content MDX into the bundle (the doc source — reused unchanged).
+// Eager so page lookup + prerender are synchronous; vite still splits assets.
+const MODULES = import.meta.globNo documentation page matches this URL.
+{frontmatter.description}
+ ) : null} ++ A brokerless, Rust-powered task queue with first-class Python and + Node.js SDKs over one core and store. No Redis, no RabbitMQ — just a + file and a worker. +
++ The Rust scheduler polls the store, dispatches to a worker pool, and + writes results back — the same loop whether you enqueue from Python + or Node. +
+| + | taskito | +Celery | +
|---|---|---|
| {d.label} | +
One file, one worker. Pick your runtime:
+pip install or pnpm add and go.",
+ },
+ {
+ icon: "M9 2v3M15 2v3M9 19v3M15 19v3M2 9h3M2 15h3M19 9h3M19 15h3",
+ rect: true,
+ title: "Rust-powered",
+ body: "The scheduler, dispatcher, and storage engine are all Rust. Tokio runtime, OS-thread worker pool; thin PyO3 and napi-rs boundaries keep Python and Node overhead negligible.",
+ },
+ {
+ icon: "M22 12h-4l-3 9L9 3l-3 9H2",
+ title: "One core, two SDKs",
+ body: "First-class Python and Node.js clients are peers over the same Rust core and store — enqueue in one runtime, run workers in the other. Zero cross-language dependency.",
+ },
+ {
+ icon: "M6 3v12M18 9a3 3 0 1 0 0 6 3 3 0 0 0 0-6zM6 21a3 3 0 1 0 0-6 3 3 0 0 0 0 6zM15 6a9 9 0 0 0-9 9",
+ title: "DAG workflows",
+ body: "Multi-step pipelines as directed acyclic graphs. Fan-out, fan-in, conditions, approval gates, sub-workflows, incremental re-runs, Mermaid viz.",
+ },
+ {
+ icon: "M12 2L2 7l10 5 10-5-10-5zM2 17l10 5 10-5M2 12l10 5 10-5",
+ title: "Resource system",
+ body: "Inject database connections, HTTP clients, and cloud SDKs by name. Three-layer pipeline: argument interception, worker DI, transparent proxy.",
+ },
+ {
+ icon: "M12 22s8-4 8-10V5l-8-3-8 3v7c0 6 8 10 8 10z",
+ title: "Production-ready",
+ body: "Retries with exponential backoff, dead letter queue, rate limits, circuit breakers, distributed locks, structured logs, OTel/Sentry/Prometheus.",
+ },
+];
+
+export const USE_CASES: IconCard[] = [
+ {
+ icon: "M12 2C6.48 2 2 4.02 2 6.5v11C2 19.98 6.48 22 12 22s10-2.02 10-4.5v-11C22 4.02 17.52 2 12 2zM2 6.5C2 8.43 6.48 10 12 10s10-1.57 10-3.5M2 12c0 1.93 4.48 3.5 10 3.5s10-1.57 10-3.5",
+ title: "ETL pipelines",
+ body: "Chain extract → transform → load as a DAG. Fan out across workers, fan in to aggregate, restart from any node on failure.",
+ },
+ {
+ icon: "M4 4h16a2 2 0 0 1 2 2v12a2 2 0 0 1-2 2H4a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2zM22 6l-10 7L2 6",
+ title: "Email & notifications",
+ body: "Bursty SMTP, push, or webhook delivery. Per-task rate limits keep providers happy; retries with backoff handle transient failures.",
+ },
+ {
+ icon: "M9 2v3M15 2v3M9 19v3M15 19v3M2 9h3M2 15h3M19 9h3M19 15h3",
+ rect: true,
+ title: "ML inference & batch",
+ body: "Long-running model jobs with progress tracking, soft timeouts, and prefork pools for true CPU parallelism without GIL contention.",
+ },
+ {
+ icon: "M12 6v6l4 2M12 22a10 10 0 1 1 0-20 10 10 0 0 1 0 20z",
+ title: "Scheduled jobs",
+ body: "Six-field cron syntax down to the second. Periodic tasks live in the scheduler — no separate beat daemon to babysit.",
+ },
+];
+
+export interface DeltaRow {
+ label: string;
+ taskito: string;
+ celery: string;
+}
+
+export const DELTA: DeltaRow[] = [
+ {
+ label: "Install",
+ taskito: "pip install taskito",
+ celery: "pip install celery[redis] + run Redis daemon",
+ },
+ {
+ label: "Background services",
+ taskito: "1 (worker)",
+ celery: "3 (worker, beat, Redis)",
+ },
+ {
+ label: "Default storage",
+ taskito: "SQLite file (built-in)",
+ celery: "Redis (separate daemon)",
+ },
+ {
+ label: "Retry config above",
+ taskito: "max_retries=3 decorator arg",
+ celery: "try/except + self.retry(exc=…)",
+ },
+];
+
+export interface IntegrationGroup {
+ group: string;
+ items: string[];
+}
+
+export const INTEGRATIONS: IntegrationGroup[] = [
+ { group: "Python frameworks", items: ["Django", "FastAPI", "Flask"] },
+ { group: "Node frameworks", items: ["Express", "Fastify", "NestJS"] },
+ { group: "Storage", items: ["Postgres", "SQLite", "Redis"] },
+ { group: "Observability", items: ["OpenTelemetry", "Sentry", "Prometheus"] },
+];
+
+export const CODE_TASKITO = HERO_PANES[0].code;
+
+export const CODE_CELERY = `from celery import Celery
+
+app = Celery(
+ "myapp",
+ broker="redis://localhost:6379/0",
+ backend="redis://localhost:6379/1",
+)
+app.conf.task_default_rate_limit = "100/m"
+
+@app.task(bind=True, max_retries=3)
+def send_email(self, to, subject, body):
+ try:
+ smtp.send(to, subject, body)
+ except SMTPError as exc:
+ raise self.retry(exc=exc, countdown=60)
+
+# Enqueue
+send_email.delay("alice@x.com", "Hi", "Body")
+
+# Run the worker (separate terminal + Redis)
+# $ celery -A myapp worker --loglevel=info`;
diff --git a/docs/app/routes/home.tsx b/docs/app/routes/home.tsx
index b32c8a69..3524deae 100644
--- a/docs/app/routes/home.tsx
+++ b/docs/app/routes/home.tsx
@@ -1,3 +1,14 @@
+import {
+ Comparison,
+ CTA,
+ Features,
+ Hero,
+ HowItWorks,
+ Integrations,
+ UseCases,
+ useReveal,
+} from "@/components/landing";
+import { SiteNav } from "@/components/ui";
import type { Route } from "./+types/home";
export function meta(_: Route.MetaArgs) {
@@ -12,10 +23,19 @@ export function meta(_: Route.MetaArgs) {
}
export default function Home() {
+ useReveal();
return (
- One queue. Python and Node.
- sits inside the .codeblock panel (CodeBlock component); keep it
+ flat — the panel gives border/radius/shadow, .codeblock pre the padding/font. */
+.codeblock pre.shiki {
+ margin: 0;
+ border: 0;
+ border-radius: 0;
+ box-shadow: none;
+ background: transparent;
overflow-x: auto;
tab-size: 2;
}
-.article pre.shiki code {
+.codeblock pre.shiki code {
background: none;
border: none;
padding: 0;
diff --git a/docs/app/components/mdx/code-block.tsx b/docs/app/components/mdx/code-block.tsx
new file mode 100644
index 00000000..fed8ac3b
--- /dev/null
+++ b/docs/app/components/mdx/code-block.tsx
@@ -0,0 +1,39 @@
+import { Check, Copy } from "lucide-react";
+import { type ComponentProps, useRef, useState } from "react";
+
+/** Wraps a shiki-highlighted `` in the design's `.codeblock` panel with a
+ * header bar (language label + copy button). Mapped as the MDX `pre` element. */
+export function CodeBlock(
+ props: ComponentProps<"pre"> & { "data-language"?: string },
+) {
+ const { children, ...preProps } = props;
+ const lang = props["data-language"] || "code";
+ const ref = useRef(null);
+ const [copied, setCopied] = useState(false);
+
+ const copy = () => {
+ const text = ref.current?.textContent ?? "";
+ navigator.clipboard?.writeText(text);
+ setCopied(true);
+ setTimeout(() => setCopied(false), 1400);
+ };
+
+ return (
+
+
+ {lang}
+
+
+
+ {children}
+
+
+ );
+}
diff --git a/docs/app/components/mdx/index.tsx b/docs/app/components/mdx/index.tsx
index 23c8ac45..fcb31663 100644
--- a/docs/app/components/mdx/index.tsx
+++ b/docs/app/components/mdx/index.tsx
@@ -6,6 +6,7 @@ import { DiagramCarousel, DiagramSlide } from "@/components/diagram-carousel";
import { Mermaid } from "@/components/mermaid";
import { Callout } from "./callout";
import { Card, Cards } from "./card";
+import { CodeBlock } from "./code-block";
import { Tab, Tabs } from "./tabs";
// Internal links use the router for client navigation; external/anchor links
@@ -34,6 +35,7 @@ function Anchor({ href, children, ...rest }: ComponentProps<"a">) {
/** Components made available to every MDX page via ``. */
export const mdxComponents: MDXComponents = {
a: Anchor,
+ pre: CodeBlock,
Callout,
Tabs,
Tab,
diff --git a/docs/vite.config.ts b/docs/vite.config.ts
index cfe202df..341929e0 100644
--- a/docs/vite.config.ts
+++ b/docs/vite.config.ts
@@ -50,6 +50,19 @@ export default defineConfig({
// Emit only --shiki-light/--shiki-dark CSS vars (no inline color/bg),
// so app.css can switch them on our [data-theme] selector.
defaultColor: false,
+ // Tag each with its language so the CodeBlock wrapper can
+ // render the design's header bar.
+ transformers: [
+ {
+ name: "code-language",
+ pre(
+ this: { options: { lang: string } },
+ node: { properties: Record },
+ ) {
+ node.properties["data-language"] = this.options.lang;
+ },
+ },
+ ],
},
],
[rehypeAutolinkHeadings, { behavior: "wrap" }],
From bea8fc8f27f324b3fd984ccc1d9307f07aba46f9 Mon Sep 17 00:00:00 2001
From: Pratyush Sharma <56130065+pratyush618@users.noreply.github.com>
Date: Sun, 21 Jun 2026 11:19:16 +0530
Subject: [PATCH 12/48] docs(perf): lazy per-route MDX + build-time manifest
(kill 3.9MB search chunk)
---
docs/app/lib/content.ts | 44 +++++------------
docs/app/lib/manifest.ts | 26 ++++++++++
docs/app/lib/nav.ts | 8 +--
docs/app/lib/search.ts | 22 ++++-----
docs/app/routes/docs.$.tsx | 34 ++++++++-----
docs/app/virtual-docs-manifest.d.ts | 3 ++
docs/vite-plugin-docs-manifest.ts | 76 +++++++++++++++++++++++++++++
docs/vite.config.ts | 2 +
8 files changed, 154 insertions(+), 61 deletions(-)
create mode 100644 docs/app/lib/manifest.ts
create mode 100644 docs/app/virtual-docs-manifest.d.ts
create mode 100644 docs/vite-plugin-docs-manifest.ts
diff --git a/docs/app/lib/content.ts b/docs/app/lib/content.ts
index b481b146..ac4e4529 100644
--- a/docs/app/lib/content.ts
+++ b/docs/app/lib/content.ts
@@ -1,23 +1,14 @@
import type { ComponentType } from "react";
-export interface DocFrontmatter {
- title?: string;
- description?: string;
-}
-
interface MdxModule {
default: ComponentType;
- frontmatter?: DocFrontmatter;
}
-// Compile every content MDX into the bundle (the doc source — reused unchanged).
-// Eager so page lookup + prerender are synchronous; vite still splits assets.
-const MODULES = import.meta.glob("../../content/docs/**/*.mdx", {
- eager: true,
-});
+// LAZY glob: each MDX compiles to its own chunk, loaded on demand by the route
+// (React.lazy). Page metadata lives in the build-time manifest (manifest.ts), so
+// nav/search never pull these heavy (shiki-inflated) modules into a shared chunk.
+const LOADERS = import.meta.glob("../../content/docs/**/*.mdx");
-/** `…/content/docs/getting-started/installation.mdx` → `/getting-started/installation`;
- * `…/node/index.mdx` → `/node`. Mirrors app/lib/doc-paths.ts (build-time prerender list). */
function keyToSlug(key: string): string {
const rel = key.replace(/^.*\/content\/docs\//, "").replace(/\.mdx$/, "");
const parts = rel.split("/");
@@ -27,27 +18,18 @@ function keyToSlug(key: string): string {
return `/${parts.join("/")}`.replace(/\/$/, "") || "/";
}
-export interface DocPage {
- slug: string;
- Component: ComponentType;
- frontmatter: DocFrontmatter;
-}
-
-const PAGES = new Map();
-for (const [key, mod] of Object.entries(MODULES)) {
- const slug = keyToSlug(key);
- PAGES.set(slug, {
- slug,
- Component: mod.default,
- frontmatter: mod.frontmatter ?? {},
- });
+const BY_SLUG = new Map Promise>();
+for (const [key, loader] of Object.entries(LOADERS)) {
+ BY_SLUG.set(keyToSlug(key), loader);
}
-/** Resolve a URL path (e.g. `/node/workflows/saga`) to its rendered MDX page. */
-export function getDocPage(path: string): DocPage | undefined {
- return PAGES.get(path.replace(/\/$/, "") || "/");
+/** The dynamic import for a doc page's compiled component, or undefined if unknown. */
+export function getDocLoader(
+ path: string,
+): (() => Promise) | undefined {
+ return BY_SLUG.get(path.replace(/\/$/, "") || "/");
}
export function allDocSlugs(): string[] {
- return [...PAGES.keys()];
+ return [...BY_SLUG.keys()];
}
diff --git a/docs/app/lib/manifest.ts b/docs/app/lib/manifest.ts
new file mode 100644
index 00000000..7752e730
--- /dev/null
+++ b/docs/app/lib/manifest.ts
@@ -0,0 +1,26 @@
+// Lightweight page metadata (slug/title/description) from the build-time manifest
+// (vite-plugin-docs-manifest). No compiled MDX here — keeps nav/search/llms out of
+// the heavy component graph.
+import { DOCS } from "virtual:docs-manifest";
+
+export interface DocMeta {
+ slug: string;
+ title: string;
+ description: string;
+}
+
+export const DOC_METAS: DocMeta[] = DOCS;
+
+const BY_SLUG = new Map(DOC_METAS.map((d) => [d.slug, d]));
+
+export function docMeta(slug: string): DocMeta | undefined {
+ return BY_SLUG.get(slug.replace(/\/$/, "") || "/");
+}
+
+export function docTitle(slug: string): string | undefined {
+ return BY_SLUG.get(slug)?.title;
+}
+
+export function hasDoc(slug: string): boolean {
+ return BY_SLUG.has(slug);
+}
diff --git a/docs/app/lib/nav.ts b/docs/app/lib/nav.ts
index fb27fc5e..3ed5083a 100644
--- a/docs/app/lib/nav.ts
+++ b/docs/app/lib/nav.ts
@@ -1,4 +1,4 @@
-import { getDocPage } from "./content";
+import { docTitle, hasDoc } from "./manifest";
interface Meta {
title?: string;
@@ -31,7 +31,7 @@ function humanize(name: string): string {
function titleFor(slug: string, fallback: string): string {
return (
- getDocPage(slug)?.frontmatter.title ??
+ docTitle(slug) ??
metaFor(slug.replace(/^\//, "")).title ??
humanize(fallback)
);
@@ -59,7 +59,7 @@ function nodesForDir(dir: string): NavNode[] {
const indexSlug = `/${childDir}`;
nodes.push({
title: childMeta.title ?? humanize(name),
- href: getDocPage(indexSlug) ? indexSlug : undefined,
+ href: hasDoc(indexSlug) ? indexSlug : undefined,
children: nodesForDir(childDir),
});
} else {
@@ -76,7 +76,7 @@ function buildTree(sections: string[]): NavNode[] {
const indexSlug = `/${dir}`;
return {
title: metaFor(dir).title ?? humanize(dir),
- href: getDocPage(indexSlug) ? indexSlug : undefined,
+ href: hasDoc(indexSlug) ? indexSlug : undefined,
children: nodesForDir(dir),
};
});
diff --git a/docs/app/lib/search.ts b/docs/app/lib/search.ts
index cc42d97f..eea15f7c 100644
--- a/docs/app/lib/search.ts
+++ b/docs/app/lib/search.ts
@@ -1,5 +1,5 @@
import MiniSearch from "minisearch";
-import { allDocSlugs, getDocPage } from "./content";
+import { DOC_METAS } from "./manifest";
export interface SearchDoc {
id: string; // slug
@@ -19,18 +19,14 @@ function humanizeSlug(slug: string): string {
return slug.split("/").filter(Boolean).join(" ").replace(/-/g, " ");
}
-// Index built from each page's frontmatter (title + description) plus its slug
-// words. Curated and reliable — derived from the same compiled-module glob the
-// router uses, so it never drifts from the rendered pages.
-export const SEARCH_DOCS: SearchDoc[] = allDocSlugs().map((slug) => {
- const fm = getDocPage(slug)?.frontmatter ?? {};
- return {
- id: slug,
- title: fm.title || slug,
- section: sectionOf(slug),
- text: `${fm.description ?? ""} ${humanizeSlug(slug)}`.trim(),
- };
-});
+// Index built from the build-time manifest (title + description + slug words).
+// No compiled MDX pulled in — keeps the search chunk tiny.
+export const SEARCH_DOCS: SearchDoc[] = DOC_METAS.map((d) => ({
+ id: d.slug,
+ title: d.title,
+ section: sectionOf(d.slug),
+ text: `${d.description} ${humanizeSlug(d.slug)}`.trim(),
+}));
let index: MiniSearch | null = null;
diff --git a/docs/app/routes/docs.$.tsx b/docs/app/routes/docs.$.tsx
index d06153ff..458ae302 100644
--- a/docs/app/routes/docs.$.tsx
+++ b/docs/app/routes/docs.$.tsx
@@ -1,7 +1,9 @@
import { MDXProvider } from "@mdx-js/react";
+import { lazy, Suspense, useMemo } from "react";
import { PrevNext } from "@/components/docs";
import { mdxComponents } from "@/components/mdx";
-import { getDocPage } from "@/lib/content";
+import { getDocLoader } from "@/lib/content";
+import { docMeta } from "@/lib/manifest";
import type { Route } from "./+types/docs.$";
function pathOf(params: { "*"?: string }): string {
@@ -9,17 +11,23 @@ function pathOf(params: { "*"?: string }): string {
}
export function meta({ params }: Route.MetaArgs) {
- const page = getDocPage(pathOf(params));
- const title = page?.frontmatter.title;
+ const meta = docMeta(pathOf(params));
return [
- { title: title ? `${title} | Taskito` : "Taskito" },
- { name: "description", content: page?.frontmatter.description ?? "" },
+ { title: meta?.title ? `${meta.title} | Taskito` : "Taskito" },
+ { name: "description", content: meta?.description ?? "" },
];
}
export default function DocRoute({ params }: Route.ComponentProps) {
- const page = getDocPage(pathOf(params));
- if (!page) {
+ const path = pathOf(params);
+ const loader = getDocLoader(path);
+ const meta = docMeta(path);
+
+ // Each page is its own lazily-loaded chunk; React.lazy is resolved during
+ // prerender (Suspense) so the static HTML still carries the full content.
+ const Page = useMemo(() => (loader ? lazy(loader) : null), [loader]);
+
+ if (!Page) {
return (
Page not found
@@ -27,15 +35,15 @@ export default function DocRoute({ params }: Route.ComponentProps) {
);
}
- const { Component, frontmatter } = page;
+
return (
- {frontmatter.title ? {frontmatter.title}
: null}
- {frontmatter.description ? (
- {frontmatter.description}
- ) : null}
+ {meta?.title ? {meta.title}
: null}
+ {meta?.description ? {meta.description}
: null}
-
+
diff --git a/docs/app/virtual-docs-manifest.d.ts b/docs/app/virtual-docs-manifest.d.ts
new file mode 100644
index 00000000..46929372
--- /dev/null
+++ b/docs/app/virtual-docs-manifest.d.ts
@@ -0,0 +1,3 @@
+declare module "virtual:docs-manifest" {
+ export const DOCS: { slug: string; title: string; description: string }[];
+}
diff --git a/docs/vite-plugin-docs-manifest.ts b/docs/vite-plugin-docs-manifest.ts
new file mode 100644
index 00000000..b5d766bd
--- /dev/null
+++ b/docs/vite-plugin-docs-manifest.ts
@@ -0,0 +1,76 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { Plugin } from "vite";
+
+// Build-time manifest of doc pages: { slug, title, description } only — NO compiled
+// components. nav/search/llms import this (via `virtual:docs-manifest`) instead of the
+// component glob, so they never pull the 128 shiki-inflated MDX modules into a chunk.
+
+const CONTENT_DIR = fileURLToPath(new URL("./content/docs", import.meta.url));
+const VIRTUAL_ID = "virtual:docs-manifest";
+const RESOLVED_ID = `\0${VIRTUAL_ID}`;
+
+export interface DocMeta {
+ slug: string;
+ title: string;
+ description: string;
+}
+
+function slugOf(absFile: string): string {
+ const rel = relative(CONTENT_DIR, absFile).replace(/\.mdx$/, "");
+ const parts = rel.split(sep);
+ if (parts[parts.length - 1] === "index") {
+ parts.pop();
+ }
+ return `/${parts.join("/")}`.replace(/\/$/, "") || "/";
+}
+
+function parseFrontmatter(raw: string): { title: string; description: string } {
+ const fm = raw.match(/^---\n([\s\S]*?)\n---/);
+ const block = fm?.[1] ?? "";
+ const field = (name: string) =>
+ block.match(new RegExp(`^${name}:\\s*"?(.+?)"?\\s*$`, "m"))?.[1] ?? "";
+ return { title: field("title"), description: field("description") };
+}
+
+function walk(dir: string, out: string[]): void {
+ for (const entry of readdirSync(dir, { withFileTypes: true })) {
+ const full = join(dir, entry.name);
+ if (entry.isDirectory()) {
+ walk(full, out);
+ } else if (entry.name.endsWith(".mdx")) {
+ out.push(full);
+ }
+ }
+}
+
+function buildManifest(): DocMeta[] {
+ const files: string[] = [];
+ walk(CONTENT_DIR, files);
+ return files
+ .map((file) => {
+ const { title, description } = parseFrontmatter(
+ readFileSync(file, "utf8"),
+ );
+ const slug = slugOf(file);
+ return { slug, title: title || slug, description };
+ })
+ .sort((a, b) => a.slug.localeCompare(b.slug));
+}
+
+export function docsManifest(): Plugin {
+ return {
+ name: "docs-manifest",
+ resolveId(id) {
+ if (id === VIRTUAL_ID) {
+ return RESOLVED_ID;
+ }
+ },
+ load(id) {
+ if (id === RESOLVED_ID) {
+ return `export const DOCS = ${JSON.stringify(buildManifest())};`;
+ }
+ },
+ };
+}
diff --git a/docs/vite.config.ts b/docs/vite.config.ts
index 341929e0..45ff004c 100644
--- a/docs/vite.config.ts
+++ b/docs/vite.config.ts
@@ -10,6 +10,7 @@ import remarkGfm from "remark-gfm";
import remarkMdxFrontmatter from "remark-mdx-frontmatter";
import { defineConfig } from "vite";
import tsconfigPaths from "vite-tsconfig-paths";
+import { docsManifest } from "./vite-plugin-docs-manifest";
// Deploy under /taskito on GitHub Pages; serve from root locally.
const base = process.env.DOCS_BASE_PATH
@@ -32,6 +33,7 @@ export default defineConfig({
},
plugins: [
tailwindcss(),
+ docsManifest(),
// MDX must transform `.mdx` before React Router's plugin processes routes.
{
enforce: "pre",
From b95fa6109a1a6d4c726e6b25150bf7e686dc4ba2 Mon Sep 17 00:00:00 2001
From: Pratyush Sharma <56130065+pratyush618@users.noreply.github.com>
Date: Sun, 21 Jun 2026 11:19:16 +0530
Subject: [PATCH 13/48] docs: split app.css into modular style files
---
docs/app/app.css | 3628 +--------------------------------
docs/app/styles/atoms.css | 366 ++++
docs/app/styles/changelog.css | 147 ++
docs/app/styles/cmdk.css | 234 +++
docs/app/styles/diagrams.css | 1081 ++++++++++
docs/app/styles/docs.css | 1095 ++++++++++
docs/app/styles/landing.css | 531 +++++
docs/app/styles/shiki.css | 33 +
docs/app/styles/tokens.css | 120 ++
9 files changed, 3616 insertions(+), 3619 deletions(-)
create mode 100644 docs/app/styles/atoms.css
create mode 100644 docs/app/styles/changelog.css
create mode 100644 docs/app/styles/cmdk.css
create mode 100644 docs/app/styles/diagrams.css
create mode 100644 docs/app/styles/docs.css
create mode 100644 docs/app/styles/landing.css
create mode 100644 docs/app/styles/shiki.css
create mode 100644 docs/app/styles/tokens.css
diff --git a/docs/app/app.css b/docs/app/app.css
index 39e9797c..766ccd5a 100644
--- a/docs/app/app.css
+++ b/docs/app/app.css
@@ -1,3621 +1,11 @@
@import "tailwindcss";
-/* ============================================================
- Design system ported 1:1 from the approved prototype
- (theme.css + docs.css). Components in app/ reuse these classes.
- ============================================================ */
-
-/* ============================================================
- 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, 0.08);
- --line2: rgba(255, 255, 255, 0.13);
- --line3: rgba(255, 255, 255, 0.2);
- --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, 0.12);
- --indigo-line: rgba(31, 157, 84, 0.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, 0.7);
- --shadow-md: 0 20px 50px -30px rgba(0, 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, 0.1);
- --line2: rgba(45, 38, 18, 0.15);
- --line3: rgba(45, 38, 18, 0.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, 0.1);
- --indigo-line: rgba(16, 161, 82, 0.26);
- --cyan: #0d9488;
- --grn: #15a34a;
- --amber: #c2410c;
- --red: #dc2626;
-
- --shadow-lg: 0 40px 90px -45px rgba(60, 50, 20, 0.2);
- --shadow-md: 0 24px 50px -34px rgba(60, 50, 20, 0.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 0.4s ease,
- border-color 0.4s ease,
- color 0.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: 0.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: 0.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 0.15s,
- box-shadow 0.2s,
- background 0.2s,
- border-color 0.2s,
- color 0.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, 0.16);
-}
-.btn.pri:hover {
- transform: translateY(-2px);
- box-shadow:
- 0 14px 30px -16px var(--indigo),
- inset 0 1px 0 rgba(255, 255, 255, 0.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: 0.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: -0.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: -0.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 0.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 0.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 0.2s,
- border-color 0.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: 0.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 0.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, 0.6),
- 0 0 0 1px var(--line);
- overflow: hidden;
- opacity: 1;
- animation: cmdkpop 0.18s cubic-bezier(0.2, 0.7, 0.3, 1);
-}
-@keyframes cmdkpop {
- from {
- transform: translateY(-8px) scale(0.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: 0.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;
-}
-
-/* ============================================================
- taskito docs — shared page styles (sidebar / article / toc)
- Loaded after theme.css on every docs page.
- ============================================================ */
-body {
- overflow-x: hidden;
-}
-.docs-shell {
- display: grid;
- grid-template-columns: 282px minmax(0, 1fr) 240px;
- max-width: 1500px;
- margin: 0 auto;
- align-items: start;
-}
-
-/* ---------- sidebar ---------- */
-.sidebar {
- position: sticky;
- top: 65px;
- height: calc(100vh - 65px);
- overflow-y: auto;
- padding: 28px 18px 40px 32px;
- border-right: 1px solid var(--line);
-}
-.sidebar::-webkit-scrollbar {
- width: 7px;
-}
-.sidebar::-webkit-scrollbar-thumb {
- background: var(--line2);
- border-radius: 8px;
-}
-.side-search {
- display: flex;
- align-items: center;
- gap: 9px;
- width: 100%;
- padding: 9px 12px;
- border: 1px solid var(--line2);
- border-radius: 10px;
- background: var(--panel);
- color: var(--dim);
- font-size: 13px;
- font-family: var(--mono);
- cursor: pointer;
- margin-bottom: 22px;
- transition: border-color 0.2s;
-}
-.side-search:hover {
- border-color: var(--line3);
-}
-.side-search .sk {
- margin-left: auto;
- display: flex;
- gap: 4px;
-}
-.side-search kbd {
- font-family: var(--mono);
- border: 1px solid var(--line2);
- border-radius: 4px;
- padding: 0 5px;
- font-size: 11px;
-}
-/* SDK switcher (Python | Node) — sits above the nav tree */
-.sdk-switch {
- display: grid;
- grid-template-columns: 1fr 1fr;
- gap: 4px;
- padding: 4px;
- margin-bottom: 20px;
- background: var(--panel2);
- border: 1px solid var(--line2);
- border-radius: 11px;
-}
-.sdk-opt {
- display: flex;
- align-items: center;
- justify-content: center;
- gap: 7px;
- padding: 8px 6px;
- border-radius: 8px;
- font-size: 13px;
- font-weight: 500;
- color: var(--mut);
- text-decoration: none;
- transition:
- background 0.15s,
- color 0.15s,
- box-shadow 0.15s;
-}
-.sdk-opt svg {
- width: 15px;
- height: 15px;
- flex: none;
-}
-.sdk-opt:hover {
- color: var(--txt);
-}
-.sdk-opt.active {
- color: var(--indigo-br);
- background: var(--panel);
- box-shadow:
- 0 1px 3px rgba(0, 0, 0, 0.12),
- 0 0 0 1px var(--indigo-line);
-}
-.nav-group {
- margin-bottom: 22px;
-}
-.nav-group > .gt {
- display: flex;
- align-items: center;
- gap: 8px;
- font-family: var(--mono);
- font-size: 11px;
- font-weight: 600;
- letter-spacing: 0.07em;
- text-transform: uppercase;
- color: var(--dim);
- margin-bottom: 9px;
- padding: 0 4px;
-}
-.nav-group > .gt svg {
- width: 14px;
- height: 14px;
- color: var(--indigo-br);
-}
-.nav-item {
- display: flex;
- align-items: center;
- gap: 9px;
- padding: 7px 11px;
- border-radius: 9px;
- color: var(--mut);
- font-size: 14px;
- cursor: pointer;
- transition:
- background 0.15s,
- color 0.15s;
- position: relative;
- text-decoration: none;
-}
-.nav-item:hover {
- background: var(--panel2);
- color: var(--txt);
-}
-.nav-item.active {
- color: var(--indigo-br);
- background: var(--indigo-soft);
- font-weight: 500;
-}
-.nav-item.active::before {
- content: "";
- position: absolute;
- left: -32px;
- top: 6px;
- bottom: 6px;
- width: 2px;
- background: var(--indigo);
- border-radius: 2px;
-}
-.nav-sub {
- margin-left: 6px;
- border-left: 1px solid var(--line2);
- padding-left: 10px;
- display: flex;
- flex-direction: column;
- gap: 1px;
-}
-
-/* ---------- article ---------- */
-.article {
- padding: 40px 56px 96px;
- min-width: 0;
- max-width: 840px;
-}
-.crumb {
- display: flex;
- align-items: center;
- gap: 8px;
- font-size: 13px;
- color: var(--dim);
- font-family: var(--mono);
- margin-bottom: 22px;
-}
-.crumb a:hover {
- color: var(--mut);
-}
-.crumb .sep {
- opacity: 0.5;
-}
-.article h1 {
- font-size: 40px;
- line-height: 1.08;
- letter-spacing: -0.03em;
- font-weight: 600;
- margin-bottom: 12px;
-}
-.lead {
- font-size: 18px;
- line-height: 1.55;
- color: var(--mut);
- margin-bottom: 14px;
-}
-.article h2 {
- font-size: 24px;
- font-weight: 600;
- letter-spacing: -0.02em;
- margin: 48px 0 14px;
- scroll-margin-top: 90px;
- display: flex;
- align-items: center;
- gap: 11px;
-}
-.article h2 .nbadge {
- font-family: var(--mono);
- font-size: 13px;
- font-weight: 600;
- color: var(--indigo-br);
- background: var(--indigo-soft);
- border: 1px solid var(--indigo-line);
- width: 28px;
- height: 28px;
- border-radius: 8px;
- display: grid;
- place-items: center;
- flex: none;
-}
-.article h3 {
- font-size: 18px;
- font-weight: 600;
- margin: 32px 0 10px;
- scroll-margin-top: 90px;
-}
-.article p {
- font-size: 15.5px;
- line-height: 1.7;
- color: var(--txt2);
- margin: 12px 0;
-}
-.article p code,
-.article li code,
-.article td code {
- font-family: var(--mono);
- font-size: 0.85em;
- background: var(--panel2);
- border: 1px solid var(--line);
- padding: 1.5px 6px;
- border-radius: 5px;
- color: var(--txt);
-}
-.article a {
- color: var(--indigo-br);
- text-decoration: none;
- border-bottom: 1px solid var(--indigo-line);
- transition: border-color 0.15s;
-}
-.article a:hover {
- border-color: var(--indigo-br);
-}
-.article ul {
- margin: 14px 0;
- padding-left: 4px;
- list-style: none;
- display: flex;
- flex-direction: column;
- gap: 9px;
-}
-.article ul li {
- font-size: 15px;
- line-height: 1.6;
- color: var(--txt2);
- padding-left: 22px;
- position: relative;
-}
-.article ul li::before {
- content: "";
- position: absolute;
- left: 4px;
- top: 9px;
- width: 6px;
- height: 6px;
- border-radius: 50%;
- background: var(--indigo);
- opacity: 0.6;
-}
-
-/* code block */
-.codeblock {
- margin: 18px 0;
- border: 1px solid var(--line2);
- border-radius: 13px;
- overflow: hidden;
- background: var(--panel);
- box-shadow: var(--shadow-md);
-}
-.cb-bar {
- display: flex;
- align-items: center;
- gap: 9px;
- padding: 10px 14px;
- border-bottom: 1px solid var(--line);
- background: color-mix(in oklch, var(--panel) 60%, #000);
-}
-[data-theme="light"] .cb-bar {
- background: var(--panel2);
-}
-.cb-bar .lang {
- font-family: var(--mono);
- font-size: 11.5px;
- color: var(--mut);
- text-transform: lowercase;
-}
-.cb-bar .fname {
- font-family: var(--mono);
- font-size: 12px;
- color: var(--txt2);
-}
-.cb-copy {
- margin-left: auto;
- background: transparent;
- border: none;
- color: var(--dim);
- cursor: pointer;
- display: grid;
- place-items: center;
- padding: 5px;
- border-radius: 6px;
- transition:
- color 0.15s,
- background 0.15s;
-}
-.cb-copy:hover {
- color: var(--txt);
- background: var(--panel3);
-}
-.cb-copy svg {
- width: 15px;
- height: 15px;
-}
-.codeblock pre {
- margin: 0;
- padding: 16px 18px;
- overflow-x: auto;
- font-family: var(--mono);
- font-size: 13.5px;
- line-height: 1.7;
- color: var(--txt);
-}
-.codeblock pre::-webkit-scrollbar {
- height: 8px;
-}
-.codeblock pre::-webkit-scrollbar-thumb {
- background: var(--line3);
- border-radius: 8px;
-}
-.tok-flag {
- color: var(--cyan);
-}
-.tok-cmd {
- color: var(--indigo-br);
- font-weight: 600;
-}
-.tok-comment {
- color: var(--dim);
-}
-.tok-str {
- color: #9ce08a;
-}
-[data-theme="light"] .tok-str {
- color: #1a8f3a;
-}
-
-/* tabs */
-.tabs {
- margin: 18px 0;
-}
-.tablist {
- display: flex;
- gap: 4px;
- border-bottom: 1px solid var(--line);
- margin-bottom: 0;
-}
-.tab {
- padding: 9px 15px;
- font-size: 13.5px;
- font-weight: 500;
- color: var(--mut);
- cursor: pointer;
- border-bottom: 2px solid transparent;
- transition:
- color 0.15s,
- border-color 0.15s;
- font-family: var(--sans);
-}
-.tab:hover {
- color: var(--txt);
-}
-.tab.active {
- color: var(--indigo-br);
- border-bottom-color: var(--indigo);
-}
-.tabpanel {
- display: none;
-}
-.tabpanel.active {
- display: block;
-}
-.tabpanel .codeblock {
- margin-top: 14px;
-}
-
-/* callout (+ variants) */
-.callout {
- display: flex;
- gap: 13px;
- margin: 20px 0;
- padding: 15px 17px;
- border-radius: 12px;
- border: 1px solid var(--indigo-line);
- background: var(--indigo-soft);
-}
-.callout .ci {
- flex: none;
- width: 22px;
- height: 22px;
- color: var(--indigo-br);
-}
-.callout .cc {
- font-size: 14.5px;
- line-height: 1.6;
- color: var(--txt2);
-}
-.callout .cc strong {
- color: var(--txt);
- font-weight: 600;
-}
-.callout .ctitle {
- display: block;
- font-weight: 600;
- color: var(--txt);
- margin-bottom: 3px;
- font-size: 14.5px;
-}
-.callout.info {
- border-color: color-mix(in oklch, var(--cyan) 40%, transparent);
- background: color-mix(in oklch, var(--cyan) 9%, transparent);
-}
-.callout.info .ci {
- color: var(--cyan);
-}
-.callout.warn {
- border-color: color-mix(in oklch, var(--amber) 45%, transparent);
- background: color-mix(in oklch, var(--amber) 10%, transparent);
-}
-.callout.warn .ci {
- color: var(--amber);
-}
-
-/* doc cards (concept / next-steps) */
-.next-grid {
- display: grid;
- grid-template-columns: 1fr 1fr;
- gap: 12px;
- margin-top: 18px;
-}
-
-/* icon card grid (index pages) */
-.icard-grid {
- display: grid;
- grid-template-columns: repeat(2, 1fr);
- gap: 14px;
- margin: 24px 0;
-}
-.icard {
- display: block;
- padding: 20px;
- border: 1px solid var(--line2);
- border-radius: 15px;
- background: var(--panel);
- transition:
- border-color 0.2s,
- transform 0.2s,
- box-shadow 0.2s;
- position: relative;
- overflow: hidden;
-}
-.icard:hover {
- border-color: var(--indigo-line);
- transform: translateY(-3px);
- box-shadow: var(--shadow-md);
-}
-.icard .ic {
- width: 40px;
- height: 40px;
- border-radius: 11px;
- display: grid;
- place-items: center;
- margin-bottom: 14px;
- background: var(--indigo-soft);
- border: 1px solid var(--indigo-line);
- color: var(--indigo-br);
-}
-.icard .ic svg {
- width: 20px;
- height: 20px;
-}
-.icard .it {
- font-size: 16px;
- font-weight: 600;
- color: var(--txt);
- display: flex;
- align-items: center;
- gap: 7px;
-}
-.icard .it .arr {
- color: var(--dim);
- transition:
- transform 0.2s,
- color 0.2s;
- font-size: 14px;
-}
-.icard:hover .it .arr {
- transform: translateX(3px);
- color: var(--indigo-br);
-}
-.icard .id {
- font-size: 13.5px;
- color: var(--mut);
- margin-top: 6px;
- line-height: 1.55;
-}
-@media (max-width: 860px) {
- .icard-grid {
- grid-template-columns: 1fr;
- }
-}
-
-.next-card {
- display: block;
- padding: 16px 18px;
- border: 1px solid var(--line2);
- border-radius: 13px;
- background: var(--panel);
- transition:
- border-color 0.2s,
- transform 0.2s;
-}
-.next-card:hover {
- border-color: var(--indigo-line);
- transform: translateY(-2px);
-}
-.next-card .nt {
- font-size: 14.5px;
- font-weight: 600;
- color: var(--txt);
- display: flex;
- align-items: center;
- gap: 7px;
-}
-.next-card .nt .arr {
- color: var(--dim);
- transition: transform 0.2s;
-}
-.next-card:hover .nt .arr {
- transform: translateX(3px);
- color: var(--indigo-br);
-}
-.next-card .nd {
- font-size: 13px;
- color: var(--mut);
- margin-top: 5px;
- line-height: 1.5;
-}
-
-/* markdown table */
-.md-table {
- margin: 20px 0;
- border: 1px solid var(--line2);
- border-radius: 13px;
- overflow-x: auto;
- background: var(--panel);
-}
-.md-table table {
- width: 100%;
- border-collapse: collapse;
- font-size: 14.5px;
-}
-.md-table th {
- text-align: left;
- font-family: var(--mono);
- font-size: 11px;
- text-transform: uppercase;
- letter-spacing: 0.05em;
- color: var(--dim);
- font-weight: 600;
- padding: 13px 18px;
- background: var(--panel2);
- border-bottom: 1px solid var(--line);
- white-space: nowrap;
-}
-.md-table td {
- padding: 13px 18px;
- border-top: 1px solid var(--line);
- color: var(--txt2);
- vertical-align: top;
-}
-.md-table tr td:first-child {
- white-space: nowrap;
-}
-.md-table a {
- color: var(--indigo-br);
- border-bottom: 1px solid var(--indigo-line);
-}
-.md-table td b,
-.md-table .yes {
- color: var(--grn);
- font-weight: 600;
-}
-.md-table .no {
- color: var(--mut);
-}
-/* feature-matrix taskito column highlight */
-.md-table.matrix th:nth-child(2),
-.md-table.matrix td:nth-child(2) {
- background: var(--indigo-soft);
-}
-.md-table.matrix th:nth-child(2) {
- color: var(--indigo-br);
-}
-
-/* when-to-use split */
-.use-split {
- display: grid;
- grid-template-columns: 1fr 1fr;
- gap: 16px;
- margin: 22px 0;
-}
-.use-card {
- border: 1px solid var(--line2);
- border-radius: 14px;
- padding: 20px;
- background: var(--panel);
-}
-.use-card.yes {
- border-color: color-mix(in oklch, var(--grn) 35%, transparent);
-}
-.use-card.no {
- border-color: color-mix(in oklch, var(--amber) 30%, transparent);
-}
-.use-card h3 {
- font-size: 15px;
- font-weight: 600;
- margin: 0 0 12px;
- display: flex;
- align-items: center;
- gap: 8px;
-}
-.use-card.yes h3 {
- color: var(--grn);
-}
-.use-card.no h3 {
- color: var(--amber);
-}
-.use-card ul {
- margin: 0;
- padding: 0;
- list-style: none;
- display: flex;
- flex-direction: column;
- gap: 10px;
-}
-.use-card li {
- font-size: 14px;
- line-height: 1.55;
- color: var(--txt2);
- padding-left: 20px;
- position: relative;
-}
-.use-card li::before {
- content: "";
- position: absolute;
- left: 3px;
- top: 8px;
- width: 6px;
- height: 6px;
- border-radius: 50%;
-}
-.use-card.yes li::before {
- background: var(--grn);
-}
-.use-card.no li::before {
- background: var(--amber);
-}
-.use-card li b {
- color: var(--txt);
- font-weight: 600;
-}
-@media (max-width: 760px) {
- .use-split {
- grid-template-columns: 1fr;
- }
-}
-
-/* FAQ accordion */
-.faq-list {
- margin: 16px 0;
- display: flex;
- flex-direction: column;
- gap: 10px;
-}
-.faq-item {
- border: 1px solid var(--line2);
- border-radius: 13px;
- background: var(--panel);
- overflow: hidden;
- transition: border-color 0.2s;
-}
-.faq-item.open {
- border-color: var(--indigo-line);
-}
-.faq-q {
- width: 100%;
- display: flex;
- align-items: center;
- gap: 13px;
- padding: 16px 18px;
- background: transparent;
- border: none;
- cursor: pointer;
- text-align: left;
- font-family: var(--sans);
- font-size: 15.5px;
- font-weight: 600;
- color: var(--txt);
-}
-.faq-q .faq-chevron {
- margin-left: auto;
- flex: none;
- color: var(--mut);
- transition: transform 0.22s;
-}
-.faq-item.open .faq-q .faq-chevron {
- transform: rotate(180deg);
- color: var(--indigo-br);
-}
-.faq-q .faq-qmark {
- flex: none;
- width: 26px;
- height: 26px;
- border-radius: 8px;
- display: grid;
- place-items: center;
- font-family: var(--mono);
- font-size: 13px;
- font-weight: 600;
- background: var(--indigo-soft);
- border: 1px solid var(--indigo-line);
- color: var(--indigo-br);
-}
-.faq-a {
- display: none;
- padding: 0 18px 18px 57px;
-}
-.faq-item.open .faq-a {
- display: block;
-}
-.faq-a p {
- margin: 6px 0;
- font-size: 14.5px;
- line-height: 1.65;
- color: var(--txt2);
-}
-.faq-a p code,
-.faq-a li code {
- font-family: var(--mono);
- font-size: 0.85em;
- background: var(--panel2);
- border: 1px solid var(--line);
- padding: 1.5px 6px;
- border-radius: 5px;
- color: var(--txt);
-}
-.faq-a .codeblock {
- margin: 12px 0;
-}
-.faq-a ul {
- margin: 10px 0;
- padding: 0;
- list-style: none;
- display: flex;
- flex-direction: column;
- gap: 8px;
-}
-.faq-a ul li {
- font-size: 14px;
- line-height: 1.55;
- color: var(--txt2);
- padding-left: 20px;
- position: relative;
-}
-.faq-a ul li::before {
- content: "";
- position: absolute;
- left: 4px;
- top: 9px;
- width: 5px;
- height: 5px;
- border-radius: 50%;
- background: var(--indigo);
- opacity: 0.6;
-}
-@media (max-width: 760px) {
- .faq-a {
- padding-left: 18px;
- }
-}
-
-/* when-to / general */
-.use-split + h2 {
- margin-top: 40px;
-}
-
-/* architecture stack diagram */
-.archstack {
- margin: 26px 0;
- display: flex;
- flex-direction: column;
- gap: 0;
- border: 1px solid var(--line2);
- border-radius: 16px;
- padding: 22px;
- background: linear-gradient(180deg, var(--bg-soft), var(--panel));
- position: relative;
- overflow: hidden;
-}
-.archstack .layer {
- display: flex;
- align-items: center;
- gap: 16px;
- padding: 16px 18px;
- border-radius: 13px;
- border: 1px solid var(--line2);
- background: var(--panel);
- position: relative;
- z-index: 1;
-}
-.archstack .layer.py {
- border-color: var(--indigo-line);
- background: linear-gradient(100deg, var(--indigo-soft), var(--panel));
-}
-.archstack .layer.rust {
- border-color: color-mix(in oklch, var(--amber) 35%, transparent);
- background: linear-gradient(
- 100deg,
- color-mix(in oklch, var(--amber) 8%, transparent),
- var(--panel)
- );
-}
-.archstack .ltag {
- flex: none;
- font-family: var(--mono);
- font-size: 11px;
- font-weight: 600;
- letter-spacing: 0.06em;
- text-transform: uppercase;
- padding: 5px 10px;
- border-radius: 7px;
- color: #fff;
-}
-.archstack .ltag.t-py {
- background: var(--indigo);
-}
-.archstack .ltag.t-rust {
- background: var(--amber);
- color: #1a1206;
-}
-.archstack .ltag.t-store {
- background: var(--mut);
-}
-.archstack .lbody {
- min-width: 0;
-}
-.archstack .lt {
- font-size: 15px;
- font-weight: 600;
- color: var(--txt);
-}
-.archstack .ld {
- font-size: 13px;
- color: var(--mut);
- margin-top: 2px;
- line-height: 1.5;
-}
-.archstack .bound {
- display: flex;
- align-items: center;
- justify-content: center;
- gap: 9px;
- padding: 8px 0;
- font-family: var(--mono);
- font-size: 11px;
- color: var(--dim);
- position: relative;
-}
-.archstack .bound::before,
-.archstack .bound::after {
- content: "";
- height: 1px;
- flex: 1;
- max-width: 120px;
- background: linear-gradient(90deg, transparent, var(--line2), transparent);
-}
-.archstack .pyo3 {
- color: var(--indigo-br);
- border: 1px solid var(--indigo-line);
- border-radius: 100px;
- padding: 2px 10px;
- background: var(--indigo-soft);
-}
-.archstack .pulse {
- position: absolute;
- left: 50%;
- top: 0;
- width: 8px;
- height: 8px;
- border-radius: 50%;
- background: var(--indigo);
- box-shadow: 0 0 12px var(--indigo);
- transform: translateX(-50%);
- opacity: 0;
-}
-@media (prefers-reduced-motion: no-preference) {
- .archstack .pulse {
- animation: archflow 3.2s ease-in-out infinite;
- }
-}
-@keyframes archflow {
- 0% {
- top: 8%;
- opacity: 0;
- }
- 10% {
- opacity: 1;
- }
- 50% {
- opacity: 1;
- }
- 90% {
- opacity: 1;
- }
- 100% {
- top: 92%;
- opacity: 0;
- }
-}
-
-/* ===== release / changelog ===== */
-.changelog {
- margin-top: 10px;
-}
-.release {
- padding: 30px 0;
- border-bottom: 1px solid var(--line);
-}
-.release:first-child {
- padding-top: 8px;
-}
-.rel-top {
- display: flex;
- align-items: center;
- gap: 12px;
- flex-wrap: wrap;
-}
-.rel-v {
- font-family: var(--mono);
- font-size: 23px;
- font-weight: 600;
- letter-spacing: -0.02em;
- color: var(--txt);
- scroll-margin-top: 90px;
-}
-.rel-badge {
- font-family: var(--mono);
- font-size: 11px;
- font-weight: 600;
- padding: 3px 9px;
- border-radius: 7px;
- text-transform: uppercase;
- letter-spacing: 0.04em;
-}
-.rel-badge.feature {
- color: var(--indigo-br);
- background: var(--indigo-soft);
- border: 1px solid var(--indigo-line);
-}
-.rel-badge.patch {
- color: var(--mut);
- background: var(--panel2);
- border: 1px solid var(--line2);
-}
-.rel-badge.security {
- color: var(--cyan);
- background: color-mix(in oklch, var(--cyan) 10%, transparent);
- border: 1px solid color-mix(in oklch, var(--cyan) 35%, transparent);
-}
-.rel-badge.current {
- color: var(--grn);
- background: color-mix(in oklch, var(--grn) 12%, transparent);
- border: 1px solid color-mix(in oklch, var(--grn) 40%, transparent);
-}
-.rel-tagline {
- flex-basis: 100%;
- margin-top: 4px;
- color: var(--mut);
- font-size: 15px;
- line-height: 1.55;
-}
-.rel-section {
- margin-top: 18px;
-}
-.rel-cat {
- display: inline-block;
- font-family: var(--mono);
- font-size: 10.5px;
- font-weight: 600;
- text-transform: uppercase;
- letter-spacing: 0.05em;
- padding: 2px 9px;
- border-radius: 6px;
- margin-bottom: 9px;
-}
-.cat-added {
- color: var(--grn);
- background: color-mix(in oklch, var(--grn) 11%, transparent);
-}
-.cat-fixed {
- color: var(--amber);
- background: color-mix(in oklch, var(--amber) 11%, transparent);
-}
-.cat-changed {
- color: var(--indigo-br);
- background: var(--indigo-soft);
-}
-.cat-breaking {
- color: var(--red);
- background: color-mix(in oklch, var(--red) 11%, transparent);
-}
-.cat-security {
- color: var(--cyan);
- background: color-mix(in oklch, var(--cyan) 11%, transparent);
-}
-.cat-notes {
- color: var(--mut);
- background: var(--panel2);
-}
-.rel-list {
- margin: 0 0 4px;
- padding: 0;
- list-style: none;
- display: flex;
- flex-direction: column;
- gap: 8px;
-}
-.rel-list li {
- font-size: 14.5px;
- line-height: 1.6;
- color: var(--txt2);
- padding-left: 20px;
- position: relative;
-}
-.rel-list li::before {
- content: "";
- position: absolute;
- left: 4px;
- top: 9px;
- width: 5px;
- height: 5px;
- border-radius: 50%;
- background: var(--faint);
-}
-.rel-list li b {
- color: var(--txt);
- font-weight: 600;
-}
-.rel-list li code {
- font-family: var(--mono);
- font-size: 0.84em;
- background: var(--panel2);
- border: 1px solid var(--line);
- padding: 1px 5px;
- border-radius: 5px;
- color: var(--txt);
-}
-.rel-earlier {
- margin-top: 6px;
-}
-.rel-earlier .release {
- padding: 18px 0;
-}
-.rel-earlier .rel-tagline {
- margin-top: 2px;
- font-size: 14px;
-}
-
-/* ===== diagram components (architecture) ===== */
-/* --- job lifecycle state graph --- */
-.lc {
- position: relative;
- margin: 24px 0;
- border: 1px solid var(--line2);
- border-radius: 16px;
- padding: 20px 16px;
- background: linear-gradient(180deg, var(--bg-soft), var(--panel));
- overflow: hidden;
-}
-.lc svg {
- width: 100%;
- height: auto;
- display: block;
- overflow: visible;
-}
-.lc-node rect {
- fill: var(--panel);
- stroke: var(--line2);
- stroke-width: 1.5;
-}
-.lc-nt {
- fill: var(--txt);
- font-size: 16px;
- font-weight: 600;
- font-family: var(--sans);
-}
-.lc-nc {
- fill: var(--dim);
- font-size: 11px;
- font-family: var(--mono);
-}
-.lc-elabel {
- fill: var(--mut);
- font-size: 11.5px;
- font-family: var(--mono);
-}
-.lc-node.s-pending rect {
- stroke: var(--line3);
-}
-.lc-node.s-pending .lc-sd {
- fill: var(--dim);
-}
-.lc-node.s-running rect {
- stroke: var(--indigo-line);
- fill: var(--indigo-soft);
-}
-.lc-node.s-running .lc-sd {
- fill: var(--indigo);
-}
-.lc-node.s-complete rect {
- stroke: color-mix(in oklch, var(--grn) 50%, transparent);
-}
-.lc-node.s-complete .lc-sd {
- fill: var(--grn);
-}
-.lc-node.s-failed rect {
- stroke: color-mix(in oklch, var(--amber) 50%, transparent);
-}
-.lc-node.s-failed .lc-sd {
- fill: var(--amber);
-}
-.lc-node.s-dead rect {
- stroke: color-mix(in oklch, var(--red) 50%, transparent);
-}
-.lc-node.s-dead .lc-sd {
- fill: var(--red);
-}
-.lc-node.s-cancel rect {
- stroke: var(--line3);
- stroke-dasharray: 4 4;
-}
-.lc-node.s-cancel .lc-sd {
- fill: var(--mut);
-}
-.lc-token {
- position: absolute;
- top: 21.4%;
- left: 15%;
- width: 11px;
- height: 11px;
- border-radius: 50%;
- margin: -5.5px 0 0 -5.5px;
- background: var(--indigo);
- box-shadow: 0 0 12px var(--indigo);
- z-index: 2;
-}
-@media (prefers-reduced-motion: no-preference) {
- .lc-node.s-running .lc-sd {
- animation: blip 1.4s infinite;
- }
- .lc-token {
- animation: lctravel 4.4s cubic-bezier(0.5, 0, 0.4, 1) infinite;
- }
-}
-@keyframes lctravel {
- 0% {
- left: 15%;
- opacity: 0;
- }
- 6% {
- opacity: 1;
- }
- 34% {
- left: 50%;
- opacity: 1;
- }
- 46% {
- left: 50%;
- opacity: 1;
- }
- 74% {
- left: 84.5%;
- opacity: 1;
- }
- 86% {
- left: 84.5%;
- opacity: 1;
- }
- 100% {
- left: 84.5%;
- opacity: 0;
- }
-}
-
-/* --- scheduler poll cycle --- */
-.pc-wrap {
- display: flex;
- align-items: center;
- gap: 30px;
- flex-wrap: wrap;
- justify-content: center;
- margin: 24px 0;
- border: 1px solid var(--line2);
- border-radius: 16px;
- padding: 26px;
- background: linear-gradient(180deg, var(--bg-soft), var(--panel));
-}
-.pc-svg {
- width: 230px;
- height: 230px;
- flex: none;
-}
-.pc-center {
- fill: var(--txt);
- font-size: 30px;
- font-weight: 600;
- font-family: var(--mono);
- letter-spacing: -0.02em;
-}
-.pc-centersub {
- fill: var(--dim);
- font-size: 12px;
- font-family: var(--mono);
- text-transform: uppercase;
- letter-spacing: 0.1em;
-}
-.pc-sweep {
- transform-origin: 180px 180px;
-}
-@media (prefers-reduced-motion: no-preference) {
- .pc-sweep {
- animation: pcspin 3.4s linear infinite;
- }
-}
-@keyframes pcspin {
- to {
- transform: rotate(360deg);
- }
-}
-.pc-legend {
- display: flex;
- flex-direction: column;
- gap: 12px;
- min-width: 220px;
-}
-.pc-leg {
- display: flex;
- align-items: center;
- gap: 11px;
- font-size: 14px;
-}
-.pc-leg .pc-dot {
- width: 10px;
- height: 10px;
- border-radius: 50%;
- flex: none;
-}
-.pc-leg .pc-name {
- font-family: var(--mono);
- font-size: 13.5px;
- color: var(--txt);
- font-weight: 500;
-}
-.pc-leg .pc-cad {
- margin-left: auto;
- font-family: var(--mono);
- font-size: 11.5px;
- color: var(--dim);
-}
-
-/* --- mesh live demo --- */
-.mesh-demo {
- position: relative;
- margin: 24px 0;
- border: 1px solid var(--line2);
- border-radius: 18px;
- overflow: hidden;
- background: radial-gradient(
- 120% 90% at 50% 40%,
- var(--bg-soft),
- var(--panel)
- );
-}
-.mesh-demo .mesh-toolbar {
- position: absolute;
- top: 0;
- left: 0;
- right: 0;
- z-index: 5;
- display: flex;
- align-items: center;
- justify-content: space-between;
- gap: 12px;
- padding: 13px 16px;
- flex-wrap: wrap;
-}
-.mesh-stats {
- display: flex;
- gap: 18px;
- font-size: 12.5px;
- color: var(--mut);
- font-family: var(--mono);
-}
-.mesh-stats .mstat b {
- color: var(--indigo-br);
- font-weight: 600;
- font-size: 14px;
-}
-.mesh-btns {
- display: flex;
- gap: 8px;
-}
-.mesh-btn {
- font-family: var(--mono);
- font-size: 12px;
- font-weight: 500;
- padding: 7px 13px;
- border-radius: 9px;
- cursor: pointer;
- white-space: nowrap;
- background: var(--panel);
- border: 1px solid var(--line2);
- color: var(--txt);
- transition:
- border-color 0.15s,
- background 0.15s;
-}
-.mesh-btn:hover {
- border-color: var(--indigo);
- color: var(--indigo-br);
-}
-.mesh-stepper {
- display: inline-flex;
- align-items: center;
- gap: 0;
- border: 1px solid var(--line2);
- border-radius: 9px;
- background: var(--panel);
- overflow: hidden;
-}
-.mesh-stepper button {
- width: 30px;
- height: 32px;
- border: none;
- background: transparent;
- color: var(--txt);
- font-size: 17px;
- cursor: pointer;
- display: grid;
- place-items: center;
- transition:
- background 0.15s,
- color 0.15s;
- font-family: var(--mono);
- line-height: 1;
-}
-.mesh-stepper button:hover:not(:disabled) {
- background: var(--indigo-soft);
- color: var(--indigo-br);
-}
-.mesh-stepper button:disabled {
- opacity: 0.35;
- cursor: not-allowed;
-}
-.mesh-count {
- font-family: var(--mono);
- font-size: 11.5px;
- color: var(--mut);
- padding: 0 10px;
- border-left: 1px solid var(--line2);
- border-right: 1px solid var(--line2);
- white-space: nowrap;
-}
-.mesh-count b {
- color: var(--txt);
- font-weight: 600;
-}
-/* world-map backdrop */
-.mesh-map {
- position: absolute;
- inset: 0;
- z-index: 0;
- width: 100%;
- height: 100%;
- pointer-events: none;
-}
-.mesh-map .grat {
- stroke: var(--line);
- stroke-width: 1;
- fill: none;
-}
-.mesh-map .land {
- fill: var(--line);
- opacity: 0.55;
-}
-[data-theme="light"] .mesh-map .land {
- opacity: 0.7;
-}
-.mesh-map .link {
- stroke: var(--line2);
- stroke-width: 1.2;
- fill: none;
- stroke-dasharray: 2 6;
- stroke-linecap: round;
- opacity: 0.6;
- transition:
- opacity 0.2s,
- stroke 0.2s;
-}
-.mesh-map .link.on {
- stroke: var(--indigo-line);
- opacity: 1;
- stroke-dasharray: none;
-}
-.mesh-map.focus .link {
- opacity: 0.12;
-}
-.mesh-map.focus .link.lit {
- opacity: 1;
- stroke: var(--indigo);
- stroke-dasharray: none;
-}
-.mesh-map .ping {
- stroke: var(--cyan);
- stroke-width: 2;
- fill: none;
- opacity: 0;
-}
-
-/* latency labels on links (shown on focus) */
-.mlat {
- position: absolute;
- z-index: 3;
- transform: translate(-50%, -50%);
- font-family: var(--mono);
- font-size: 10px;
- color: var(--cyan);
- background: color-mix(in oklch, var(--panel) 88%, transparent);
- border: 1px solid color-mix(in oklch, var(--cyan) 32%, transparent);
- border-radius: 6px;
- padding: 1px 6px;
- white-space: nowrap;
- pointer-events: none;
- opacity: 0;
- transition: opacity 0.18s;
-}
-.mlat.show {
- opacity: 1;
-}
-
-/* region node (callout card offset from its geo pin) */
-.mw {
- position: absolute;
- transform: translate(-50%, -50%);
- z-index: 2;
- width: 140px;
- cursor: pointer;
- background: var(--panel);
- border: 1px solid var(--line2);
- border-radius: 12px;
- padding: 9px 11px;
- box-shadow: var(--shadow-md);
- transition:
- border-color 0.25s,
- box-shadow 0.25s;
-}
-.mw:hover {
- z-index: 6;
- border-color: var(--indigo-line);
-}
-.mw.idle {
- opacity: 0.85;
-}
-.mw.hot {
- border-color: color-mix(in oklch, var(--amber) 55%, transparent);
- box-shadow:
- 0 0 0 1px color-mix(in oklch, var(--amber) 30%, transparent),
- var(--shadow-md);
-}
-.mw.thief {
- border-color: var(--indigo-line);
- box-shadow:
- 0 0 0 2px var(--indigo-line),
- var(--shadow-md);
-}
-.mw-head {
- display: flex;
- align-items: center;
- gap: 7px;
- margin-bottom: 6px;
-}
-.mw-id {
- font-family: var(--mono);
- font-size: 12px;
- font-weight: 600;
- color: var(--txt);
- letter-spacing: -0.01em;
- white-space: nowrap;
-}
-.mw-city {
- font-family: var(--mono);
- font-size: 9.5px;
- color: var(--dim);
- white-space: nowrap;
- margin-left: auto;
-}
-.mw-pulse {
- width: 8px;
- height: 8px;
- border-radius: 50%;
- background: var(--dim);
- flex: none;
-}
-.mw-pulse.go {
- background: var(--grn);
- box-shadow: 0 0 10px var(--grn);
- animation: mwpulse 0.6s ease-out;
-}
-@keyframes mwpulse {
- 0% {
- transform: scale(0.6);
- opacity: 1;
- }
- 100% {
- transform: scale(1.4);
- opacity: 0.4;
- }
-}
-.mw-q {
- display: flex;
- flex-wrap: wrap;
- gap: 3px;
- min-height: 24px;
- align-content: flex-start;
-}
-.mw-q i {
- width: 10px;
- height: 10px;
- border-radius: 3px;
- background: linear-gradient(180deg, var(--indigo-br), var(--indigo));
- display: block;
- animation: mwjob 0.3s ease-out;
-}
-.mw.hot .mw-q i {
- background: linear-gradient(
- 180deg,
- var(--amber),
- color-mix(in oklch, var(--amber) 70%, #000)
- );
-}
-@keyframes mwjob {
- from {
- transform: scale(0);
- }
- to {
- transform: scale(1);
- }
-}
-.mw-q u {
- font-family: var(--mono);
- font-size: 10px;
- color: var(--mut);
- font-style: normal;
- align-self: center;
- margin-left: 2px;
-}
-.mw-load {
- margin-top: 6px;
- font-family: var(--mono);
- font-size: 10px;
- color: var(--dim);
-}
-.mw-load .mw-n {
- color: var(--txt2);
- font-weight: 600;
-}
-
-/* geo pin + callout connector */
-.mnode {
- position: absolute;
- z-index: 1;
- width: 10px;
- height: 10px;
- border-radius: 50%;
- transform: translate(-50%, -50%);
- background: var(--indigo);
- box-shadow:
- 0 0 0 4px var(--indigo-soft),
- 0 0 10px var(--indigo);
- transition:
- background 0.25s,
- box-shadow 0.25s;
-}
-.mnode.hot {
- background: var(--amber);
- box-shadow:
- 0 0 0 4px color-mix(in oklch, var(--amber) 16%, transparent),
- 0 0 10px var(--amber);
-}
-.mesh-map .callout {
- stroke: var(--line3);
- stroke-width: 1;
- stroke-dasharray: 2 4;
- fill: none;
- opacity: 0.7;
-}
-
-/* traveling packets */
-.mjob {
- position: absolute;
- z-index: 4;
- width: 11px;
- height: 11px;
- border-radius: 3px;
- left: 0;
- top: 0;
- background: linear-gradient(180deg, var(--indigo-br), var(--indigo));
- box-shadow: 0 0 10px var(--indigo);
- pointer-events: none;
-}
-.mjob.steal {
- background: linear-gradient(
- 180deg,
- var(--cyan),
- color-mix(in oklch, var(--cyan) 60%, #000)
- );
- box-shadow: 0 0 12px var(--cyan);
- border-radius: 50%;
-}
-.mjob.gos {
- width: 7px;
- height: 7px;
- border-radius: 50%;
- background: var(--indigo-br);
- box-shadow: 0 0 9px var(--indigo);
-}
-
-/* legend */
-.mesh-legend {
- position: absolute;
- left: 16px;
- bottom: 13px;
- z-index: 5;
- display: flex;
- gap: 15px;
- flex-wrap: wrap;
- font-family: var(--mono);
- font-size: 10.5px;
- color: var(--mut);
-}
-.mesh-legend span {
- display: flex;
- align-items: center;
- gap: 6px;
-}
-.mesh-legend i {
- width: 16px;
- height: 0;
- border-top: 2px dashed var(--line3);
- display: inline-block;
-}
-.mesh-legend i.http {
- border-top: 2px solid var(--indigo);
-}
-.mesh-legend i.steal {
- border-top: 2px solid var(--cyan);
-}
-.mesh-legend i.dot {
- width: 8px;
- height: 8px;
- border: 0;
- border-radius: 50%;
- background: var(--indigo);
- box-shadow: 0 0 8px var(--indigo);
-}
-@media (max-width: 640px) {
- .mw {
- width: 118px;
- }
- .mesh-stats {
- gap: 11px;
- font-size: 11px;
- }
- .mw-city {
- display: none;
- }
- .mesh-legend {
- display: none;
- }
-}
-
-/* --- layered stack (overview/worker/resources/mesh) --- */
-.archstack {
- margin: 24px 0;
- display: flex;
- flex-direction: column;
- gap: 0;
- border: 1px solid var(--line2);
- border-radius: 16px;
- padding: 22px;
- background: linear-gradient(180deg, var(--bg-soft), var(--panel));
- position: relative;
- overflow: hidden;
-}
-
-/* self-explanatory annotations (overview stack) */
-.arch-legend {
- display: flex;
- flex-wrap: wrap;
- gap: 18px;
- justify-content: center;
- margin-bottom: 16px;
- font-family: var(--mono);
- font-size: 12px;
- color: var(--mut);
-}
-.al-item {
- display: inline-flex;
- align-items: center;
- gap: 7px;
-}
-.al-arrow {
- display: inline-grid;
- place-items: center;
- width: 20px;
- height: 20px;
- border-radius: 6px;
- font-size: 13px;
- font-weight: 700;
- line-height: 1;
-}
-.al-arrow.down {
- background: var(--indigo-soft);
- border: 1px solid var(--indigo-line);
- color: var(--indigo-br);
-}
-.al-arrow.up {
- background: color-mix(in oklch, var(--cyan) 12%, transparent);
- border: 1px solid color-mix(in oklch, var(--cyan) 38%, transparent);
- color: var(--cyan);
-}
-.archstack .lrole {
- margin-left: auto;
- flex: none;
- font-family: var(--mono);
- font-size: 11px;
- color: var(--dim);
- border: 1px dashed var(--line3);
- border-radius: 100px;
- padding: 3px 11px;
- white-space: nowrap;
-}
-.archstack .bound .bdir {
- color: var(--indigo-br);
- font-weight: 700;
- margin: 0 2px;
-}
-@media (max-width: 620px) {
- .archstack .lrole {
- display: none;
- }
-}
-
-/* --- branching fork: scheduler routes to parallel pools --- */
-.archfork {
- position: relative;
- display: grid;
- grid-template-columns: 1fr 1fr;
- gap: 16px;
- margin-top: 30px;
-}
-.archfork::after {
- content: "";
- position: absolute;
- top: -22px;
- left: 50%;
- width: 2px;
- height: 8px;
- background: var(--line3);
- transform: translateX(-50%);
-}
-.archfork::before {
- content: "";
- position: absolute;
- top: -14px;
- left: 25%;
- right: 25%;
- height: 14px;
- border: 2px solid var(--line3);
- border-bottom: none;
- border-radius: 9px 9px 0 0;
-}
-.fork-route {
- display: flex;
- align-items: center;
- justify-content: center;
- gap: 9px;
- margin-top: 14px;
- font-family: var(--mono);
- font-size: 11px;
- color: var(--dim);
- position: relative;
-}
-.fork-route::before,
-.fork-route::after {
- content: "";
- height: 1px;
- flex: 1;
- max-width: 120px;
- background: linear-gradient(90deg, transparent, var(--line2), transparent);
-}
-.forkcol {
- display: flex;
- flex-direction: column;
- gap: 8px;
- min-width: 0;
-}
-.forkcol .forktag {
- display: flex;
- justify-content: center;
- font-family: var(--mono);
- font-size: 10.5px;
- color: var(--indigo-br);
- border: 1px dashed var(--indigo-line);
- border-radius: 100px;
- padding: 3px 11px;
- background: var(--indigo-soft);
- align-self: center;
-}
-.forkcol .layer {
- flex: 1;
-}
-@media (max-width: 620px) {
- .archfork {
- grid-template-columns: 1fr;
- gap: 22px;
- margin-top: 22px;
- }
- .archfork::before,
- .archfork::after {
- display: none;
- }
-}
-
-/* flow steps (dispatch / ordered) */
-.flowsteps {
- margin: 20px 0;
- list-style: none;
- padding: 0;
- display: flex;
- flex-direction: column;
- gap: 0;
-}
-.flowsteps li {
- position: relative;
- padding: 0 0 20px 44px;
- font-size: 15px;
- line-height: 1.6;
- color: var(--txt2);
-}
-.flowsteps li::before {
- content: counter(fs);
- counter-increment: fs;
- position: absolute;
- left: 0;
- top: -2px;
- width: 28px;
- height: 28px;
- border-radius: 8px;
- background: var(--indigo-soft);
- border: 1px solid var(--indigo-line);
- color: var(--indigo-br);
- font-family: var(--mono);
- font-weight: 600;
- font-size: 13px;
- display: grid;
- place-items: center;
-}
-.flowsteps li::after {
- content: "";
- position: absolute;
- left: 13.5px;
- top: 28px;
- bottom: 2px;
- width: 1px;
- background: var(--line2);
-}
-.flowsteps li:last-child {
- padding-bottom: 0;
-}
-.flowsteps li:last-child::after {
- display: none;
-}
-.flowsteps {
- counter-reset: fs;
-}
-.flowsteps li code {
- font-family: var(--mono);
- font-size: 0.85em;
- background: var(--panel2);
- border: 1px solid var(--line);
- padding: 1.5px 6px;
- border-radius: 5px;
- color: var(--txt);
-}
-.flowsteps li b {
- color: var(--txt);
- font-weight: 600;
-}
-
-/* sequence diagram */
-.seq {
- margin: 22px 0;
- border: 1px solid var(--line2);
- border-radius: 16px;
- padding: 22px;
- background: var(--panel);
- overflow-x: auto;
-}
-.seq-heads {
- display: flex;
- justify-content: space-around;
- gap: 12px;
- margin-bottom: 6px;
- min-width: 420px;
-}
-.seq-head {
- font-family: var(--mono);
- font-size: 12px;
- font-weight: 600;
- color: var(--txt);
- background: var(--panel2);
- border: 1px solid var(--line2);
- padding: 7px 14px;
- border-radius: 9px;
- flex: 1;
- text-align: center;
- max-width: 160px;
-}
-.seq-msgs {
- display: flex;
- flex-direction: column;
- gap: 9px;
- margin-top: 14px;
- min-width: 420px;
-}
-.seq-msg {
- display: flex;
- align-items: center;
- gap: 10px;
- font-size: 13px;
- color: var(--txt2);
-}
-.seq-msg .ln {
- flex: 1;
- height: 2px;
- border-radius: 2px;
- background: linear-gradient(
- 90deg,
- color-mix(in oklch, var(--indigo) 35%, transparent),
- var(--indigo)
- );
- position: relative;
-}
-.seq-msg .ln::after {
- content: "";
- position: absolute;
- right: -1px;
- top: -4px;
- border-left: 10px solid var(--indigo);
- border-top: 5px solid transparent;
- border-bottom: 5px solid transparent;
-}
-.seq-msg.rev .ln {
- background: linear-gradient(
- 90deg,
- var(--cyan),
- color-mix(in oklch, var(--cyan) 35%, transparent)
- );
-}
-.seq-msg.rev .ln::after {
- right: auto;
- left: -1px;
- border-left: none;
- border-right: 10px solid var(--cyan);
-}
-.seq-msg .lbl {
- font-family: var(--mono);
- font-size: 11.5px;
- color: var(--txt2);
- white-space: nowrap;
-}
-.seq-msg .self {
- font-family: var(--mono);
- font-size: 11.5px;
- color: var(--dim);
- font-style: italic;
- padding-left: 8px;
-}
-
-/* schema entity grid */
-.schema-grid {
- display: grid;
- grid-template-columns: repeat(2, 1fr);
- gap: 14px;
- margin: 22px 0;
-}
-.entity {
- border: 1px solid var(--line2);
- border-radius: 13px;
- overflow: hidden;
- background: var(--panel);
-}
-.entity .ehead {
- display: flex;
- align-items: center;
- gap: 8px;
- padding: 11px 15px;
- background: var(--panel2);
- border-bottom: 1px solid var(--line);
- font-family: var(--mono);
- font-size: 13px;
- font-weight: 600;
- color: var(--txt);
-}
-.entity .ehead .ekey {
- margin-left: auto;
- font-size: 10px;
- color: var(--indigo-br);
- background: var(--indigo-soft);
- border: 1px solid var(--indigo-line);
- padding: 1px 7px;
- border-radius: 5px;
-}
-.entity .erow {
- display: flex;
- align-items: center;
- gap: 10px;
- padding: 7px 15px;
- font-family: var(--mono);
- font-size: 12px;
- border-top: 1px solid var(--line);
-}
-.entity .erow:first-of-type {
- border-top: none;
-}
-.entity .erow .fn {
- color: var(--txt2);
-}
-.entity .erow .ft {
- margin-left: auto;
- color: var(--dim);
- font-size: 11px;
-}
-.entity .erow .pk {
- color: var(--amber);
- font-size: 10px;
- font-weight: 600;
-}
-.entity .erow .fk {
- color: var(--cyan);
- font-size: 10px;
- font-weight: 600;
-}
-@media (max-width: 860px) {
- .schema-grid {
- grid-template-columns: 1fr;
- }
-}
-
-/* recovery timeline */
-.timeline {
- margin: 22px 0;
- border-left: 2px solid var(--line2);
- padding-left: 0;
- margin-left: 8px;
-}
-.timeline .tl {
- position: relative;
- padding: 0 0 22px 28px;
-}
-.timeline .tl::before {
- content: "";
- position: absolute;
- left: -7px;
- top: 2px;
- width: 12px;
- height: 12px;
- border-radius: 50%;
- background: var(--panel);
- border: 2px solid var(--indigo);
- box-shadow: 0 0 0 4px var(--bg);
-}
-.timeline .tl:last-child {
- padding-bottom: 0;
-}
-.timeline .tt {
- font-family: var(--mono);
- font-size: 11.5px;
- color: var(--indigo-br);
- font-weight: 600;
-}
-.timeline .tb {
- font-size: 14.5px;
- color: var(--txt2);
- margin-top: 3px;
- line-height: 1.55;
-}
-.timeline .tb b {
- color: var(--txt);
- font-weight: 600;
-}
-
-/* page nav (prev/next) */
-.pagenav {
- display: flex;
- justify-content: space-between;
- gap: 14px;
- margin-top: 56px;
- padding-top: 28px;
- border-top: 1px solid var(--line);
-}
-.pagenav a {
- flex: 1;
- padding: 16px 18px;
- border: 1px solid var(--line2);
- border-radius: 13px;
- transition: border-color 0.2s;
- text-decoration: none;
-}
-.pagenav a:hover {
- border-color: var(--indigo-line);
-}
-.pagenav .dir {
- font-family: var(--mono);
- font-size: 11.5px;
- color: var(--dim);
- text-transform: uppercase;
- letter-spacing: 0.05em;
-}
-.pagenav .ttl {
- font-size: 15px;
- font-weight: 600;
- color: var(--txt);
- margin-top: 4px;
-}
-.pagenav .nx {
- text-align: right;
-}
-
-/* ---------- TOC ---------- */
-.toc {
- position: sticky;
- top: 65px;
- height: calc(100vh - 65px);
- overflow-y: auto;
- padding: 40px 24px 40px 8px;
-}
-.toc h4 {
- font-family: var(--mono);
- font-size: 11px;
- font-weight: 600;
- letter-spacing: 0.07em;
- text-transform: uppercase;
- color: var(--dim);
- margin-bottom: 14px;
- display: flex;
- align-items: center;
- gap: 8px;
-}
-.toc h4 svg {
- width: 14px;
- height: 14px;
-}
-.toc-link {
- display: block;
- font-size: 13px;
- color: var(--mut);
- padding: 5px 0 5px 14px;
- border-left: 2px solid var(--line2);
- transition:
- color 0.15s,
- border-color 0.15s;
- cursor: pointer;
-}
-.toc-link:hover {
- color: var(--txt);
-}
-.toc-link.sub {
- padding-left: 26px;
- font-size: 12.5px;
-}
-.toc-link.active {
- color: var(--indigo-br);
- border-left-color: var(--indigo);
-}
-
-/* mobile */
-.menu-btn {
- display: none;
-}
-@media (max-width: 1180px) {
- .docs-shell {
- grid-template-columns: 262px minmax(0, 1fr);
- }
- .toc {
- display: none;
- }
-}
-@media (max-width: 860px) {
- .docs-shell {
- grid-template-columns: 1fr;
- }
- .sidebar {
- display: none;
- }
- .article {
- padding: 32px 22px 72px;
- }
- .menu-btn {
- display: grid;
- }
- .next-grid {
- grid-template-columns: 1fr;
- }
-}
-
-/* Error boundary fallback */
-.error-page {
- max-width: 680px;
- margin: 0 auto;
- padding: 120px 32px;
- text-align: center;
-}
-.error-page h1 {
- font-size: 32px;
- letter-spacing: -0.02em;
- margin-bottom: 16px;
-}
-.error-page a {
- color: var(--indigo-br);
- border-bottom: 1px solid var(--indigo-line);
-}
-
-/* ---------- React port additions (nested nav, link-group headers, prev/next blocks) ---------- */
-.gt.gt-link {
- color: var(--dim);
- transition: color 0.15s;
-}
-.gt.gt-link:hover {
- color: var(--txt);
-}
-.nav-subsection {
- margin: 2px 0;
-}
-.nav-subsection .nav-sub {
- margin-left: 11px;
- padding-left: 9px;
- border-left: 1px solid var(--line);
-}
-.nav-item-label {
- color: var(--dim);
- font-weight: 600;
- cursor: default;
-}
-.nav-item-label:hover {
- background: transparent;
- color: var(--dim);
-}
-.pagenav .dir,
-.pagenav .ttl {
- display: block;
-}
-.next-card .nt svg {
- width: 16px;
- height: 16px;
- color: var(--indigo-br);
-}
-/* search modal (Phase 6 swaps the body in) */
-.cmdk-panel {
- width: min(620px, 92vw);
- margin: 11vh auto 0;
- padding: 22px 20px;
- border: 1px solid var(--line2);
- border-radius: 16px;
- background: var(--panel);
- color: var(--mut);
- font-family: var(--mono);
- font-size: 13px;
-}
-
-/* ---------- search palette (React renders only when open) ---------- */
-.cmdk {
- display: flex;
-}
-.cmdk-title {
- font-size: 14px;
- color: var(--txt);
- font-weight: 500;
-}
-.cmdk-section {
- margin-left: auto;
- font-family: var(--mono);
- font-size: 11.5px;
- color: var(--dim);
- text-transform: uppercase;
- letter-spacing: 0.04em;
-}
-.cmdk-item {
- display: flex;
- align-items: center;
- gap: 10px;
- width: 100%;
- text-align: left;
- background: transparent;
- border: none;
- cursor: pointer;
-}
-
-/* ============================================================
- Landing page layout — reconstructed from the design tokens.
- (The prototype's hero/sections CSS was inline in index.html.)
- ============================================================ */
-
-/* hero */
-.hero {
- display: grid;
- grid-template-columns: 1fr 1.05fr;
- gap: 48px;
- align-items: center;
- max-width: 1240px;
- margin: 0 auto;
- padding: 64px 32px 88px;
-}
-.hero-left {
- display: flex;
- flex-direction: column;
- align-items: flex-start;
- gap: 22px;
-}
-.hero h1 {
- font-size: clamp(40px, 5vw, 62px);
- line-height: 1.02;
- letter-spacing: -0.035em;
- font-weight: 600;
- color: var(--txt);
- text-wrap: balance;
- margin: 0;
-}
-.hero .sub {
- font-size: 18px;
- line-height: 1.6;
- color: var(--mut);
- max-width: 520px;
- margin: 0;
-}
-.btns {
- display: flex;
- gap: 12px;
- flex-wrap: wrap;
-}
-.metarow {
- display: flex;
- gap: 18px;
- flex-wrap: wrap;
- font-family: var(--mono);
- font-size: 12.5px;
- color: var(--dim);
-}
-.metarow span {
- display: inline-flex;
- align-items: center;
- gap: 7px;
-}
-.metarow span + span::before {
- content: "·";
- margin-right: 18px;
- color: var(--faint);
-}
-.hero-right {
- display: flex;
- flex-direction: column;
- gap: 12px;
- min-width: 0;
-}
-.hero-doclink {
- align-self: flex-start;
- font-family: var(--mono);
- font-size: 13px;
- color: var(--indigo-br);
- border-bottom: 1px solid var(--indigo-line);
-}
-.hero-doclink:hover {
- border-color: var(--indigo-br);
-}
-
-/* code terminal (hero + comparison) */
-.term {
- border: 1px solid var(--line2);
- border-radius: 14px;
- background: var(--panel);
- box-shadow: var(--shadow-md);
- overflow: hidden;
- min-width: 0;
-}
-.langtabs {
- display: flex;
- align-items: center;
- gap: 4px;
- padding: 9px 12px;
- border-bottom: 1px solid var(--line);
- background: color-mix(in oklch, var(--panel) 55%, #000);
-}
-[data-theme="light"] .langtabs {
- background: var(--panel2);
-}
-.langtab {
- font-family: var(--mono);
- font-size: 12.5px;
- font-weight: 500;
- color: var(--mut);
- background: transparent;
- border: none;
- padding: 5px 11px;
- border-radius: 8px;
- cursor: pointer;
- transition:
- color 0.15s,
- background 0.15s;
-}
-.langtab:hover {
- color: var(--txt);
-}
-.langtab.active {
- color: var(--indigo-br);
- background: var(--indigo-soft);
-}
-.langtab.dis {
- color: var(--faint);
- cursor: default;
- display: inline-flex;
- align-items: center;
- gap: 6px;
-}
-.tag.soon {
- font-size: 9.5px;
- text-transform: uppercase;
- letter-spacing: 0.05em;
- padding: 1px 5px;
- border-radius: 5px;
- border: 1px solid var(--line2);
- color: var(--dim);
-}
-.tabname {
- margin-left: auto;
- font-family: var(--mono);
- font-size: 12px;
- color: var(--dim);
-}
-.hcopy {
- font-family: var(--mono);
- font-size: 12px;
- color: var(--mut);
- background: transparent;
- border: 1px solid var(--line2);
- border-radius: 7px;
- padding: 3px 9px;
- cursor: pointer;
- transition:
- border-color 0.15s,
- color 0.15s;
-}
-.hcopy:hover {
- color: var(--txt);
- border-color: var(--line3);
-}
-.term .code {
- margin: 0;
- padding: 18px 20px;
- font-family: var(--code);
- font-size: 13.5px;
- line-height: 1.7;
- color: var(--txt2);
- overflow-x: auto;
- white-space: pre;
- tab-size: 2;
-}
-.outset {
- border-top: 1px solid var(--line);
- background: var(--bg-soft);
- padding: 13px 20px;
- font-family: var(--mono);
- font-size: 12.5px;
- display: flex;
- flex-direction: column;
- gap: 5px;
-}
-.oline {
- color: var(--mut);
- opacity: 0;
- transform: translateY(4px);
- transition:
- opacity 0.3s ease,
- transform 0.3s ease;
-}
-.oline.show {
- opacity: 1;
- transform: none;
-}
-
-/* how it works */
-.how {
- background: var(--bg-soft);
- border-block: 1px solid var(--line);
-}
-.flowdiag {
- display: flex;
- align-items: stretch;
- justify-content: center;
- gap: 0;
- flex-wrap: wrap;
-}
-.station {
- flex: 1 1 0;
- min-width: 180px;
- border: 1px solid var(--line2);
- border-radius: 13px;
- background: var(--panel);
- padding: 18px 18px;
-}
-.station.accent {
- border-color: var(--indigo-line);
- background: color-mix(in oklch, var(--indigo) 5%, var(--panel));
-}
-.srow {
- display: flex;
- align-items: center;
- gap: 13px;
-}
-.dicon {
- width: 38px;
- height: 38px;
- border-radius: 10px;
- background: var(--indigo-soft);
- border: 1px solid var(--indigo-line);
- flex: none;
-}
-.dpool {
- display: grid;
- grid-template-columns: repeat(3, 1fr);
- gap: 4px;
- width: 38px;
- flex: none;
-}
-.dpool span {
- width: 100%;
- aspect-ratio: 1;
- border-radius: 3px;
- background: var(--indigo-br);
- opacity: 0.45;
- animation: poolpulse 2.4s ease-in-out infinite;
- animation-delay: calc(var(--k) * 0.2s);
-}
-@keyframes poolpulse {
- 0%,
- 100% {
- opacity: 0.3;
- }
- 50% {
- opacity: 0.9;
- }
-}
-.smeta {
- display: flex;
- flex-direction: column;
- gap: 2px;
- min-width: 0;
-}
-.slabel {
- font-family: var(--mono);
- font-size: 10.5px;
- letter-spacing: 0.07em;
- color: var(--dim);
-}
-.stitle {
- font-size: 15px;
- font-weight: 600;
- color: var(--txt);
-}
-.shint {
- font-family: var(--mono);
- font-size: 11.5px;
- color: var(--mut);
-}
-.wire {
- flex: 0 0 40px;
- align-self: center;
- height: 2px;
- position: relative;
- background: linear-gradient(90deg, var(--line2), var(--indigo-line));
- overflow: hidden;
-}
-.wire .spark {
- position: absolute;
- top: -2px;
- left: 0;
- width: 6px;
- height: 6px;
- border-radius: 50%;
- background: var(--indigo-br);
- box-shadow: 0 0 8px var(--indigo-br);
- animation: sparkmove 2.4s linear infinite;
- animation-delay: var(--wd);
-}
-@keyframes sparkmove {
- 0% {
- left: -6px;
- opacity: 0;
- }
- 20% {
- opacity: 1;
- }
- 80% {
- opacity: 1;
- }
- 100% {
- left: 100%;
- opacity: 0;
- }
-}
-.returnlane {
- display: flex;
- align-items: center;
- justify-content: center;
- gap: 10px;
- margin-top: 28px;
- font-family: var(--mono);
- font-size: 12px;
- color: var(--dim);
-}
-.returnlane .rspark {
- width: 6px;
- height: 6px;
- border-radius: 50%;
- background: var(--cyan);
- box-shadow: 0 0 8px var(--cyan);
-}
-
-/* feature + use-case grids */
-.feat-grid {
- display: grid;
- grid-template-columns: repeat(3, 1fr);
- gap: 18px;
-}
-.uc-grid {
- display: grid;
- grid-template-columns: repeat(2, 1fr);
- gap: 18px;
-}
-.feat-grid .card,
-.uc-grid .card {
- position: relative;
- border: 1px solid var(--line2);
- border-radius: 15px;
- background: var(--panel);
- padding: 22px 22px 24px;
- overflow: hidden;
- transition:
- transform 0.2s,
- border-color 0.2s;
-}
-.feat-grid .card:hover,
-.uc-grid .card:hover {
- transform: translateY(-3px);
- border-color: var(--indigo-line);
-}
-.card .sheen {
- position: absolute;
- inset: 0;
- background: radial-gradient(
- circle at 70% -20%,
- var(--indigo-soft),
- transparent 60%
- );
- opacity: 0;
- transition: opacity 0.3s;
- pointer-events: none;
-}
-.card:hover .sheen {
- opacity: 1;
-}
-.card .ic {
- width: 42px;
- height: 42px;
- border-radius: 11px;
- background: var(--indigo-soft);
- border: 1px solid var(--indigo-line);
- color: var(--indigo-br);
- display: grid;
- place-items: center;
- margin-bottom: 15px;
-}
-.card .ic svg {
- width: 20px;
- height: 20px;
-}
-.card h3 {
- font-size: 16px;
- font-weight: 600;
- color: var(--txt);
- margin: 0 0 7px;
-}
-.card p {
- font-size: 14px;
- line-height: 1.6;
- color: var(--mut);
- margin: 0;
-}
-.card p code {
- font-family: var(--mono);
- font-size: 0.85em;
- background: var(--panel2);
- border: 1px solid var(--line);
- padding: 1px 5px;
- border-radius: 5px;
- color: var(--txt2);
-}
-
-/* comparison + delta table */
-.cmp-term {
- max-width: 720px;
- margin: 0 auto 28px;
-}
-.delta {
- max-width: 720px;
- margin: 0 auto;
-}
-.delta .tk {
- color: var(--txt);
-}
-.delta .ce {
- color: var(--mut);
-}
-.delta .tk b,
-.delta .ce b {
- color: var(--txt);
-}
-
-/* integrations */
-.int-grid {
- display: grid;
- grid-template-columns: repeat(4, 1fr);
- gap: 18px;
-}
-.int-col h4 {
- font-family: var(--mono);
- font-size: 11px;
- letter-spacing: 0.06em;
- text-transform: uppercase;
- color: var(--dim);
- margin: 0 0 14px;
-}
-.int-col .chips {
- display: flex;
- flex-direction: column;
- gap: 8px;
-}
-
-/* cta */
-.cta-wrap {
- max-width: 880px;
- margin: 0 auto;
- text-align: center;
- border: 1px solid var(--indigo-line);
- border-radius: 24px;
- background:
- radial-gradient(circle at 50% 0%, var(--indigo-soft), transparent 70%),
- var(--panel);
- padding: 56px 32px 52px;
-}
-.cta-wrap h2 {
- font-size: clamp(26px, 3vw, 36px);
- letter-spacing: -0.02em;
- font-weight: 600;
- color: var(--txt);
- margin: 0 0 10px;
-}
-.cta-wrap > p {
- color: var(--mut);
- margin: 0 0 24px;
-}
-.install-row {
- display: flex;
- gap: 12px;
- justify-content: center;
- flex-wrap: wrap;
- margin-bottom: 26px;
-}
-.install-pill {
- display: inline-flex;
- align-items: center;
- gap: 12px;
- background: var(--bg-soft);
- border: 1px solid var(--line2);
- border-radius: 11px;
- padding: 10px 14px;
- cursor: pointer;
- font-family: var(--mono);
-}
-.install-pill code {
- font-size: 13px;
- color: var(--txt);
-}
-.install-pill .copyInstall {
- font-size: 11px;
- color: var(--indigo-br);
- text-transform: uppercase;
- letter-spacing: 0.04em;
-}
-.cta-wrap .btns {
- justify-content: center;
-}
-
-/* responsive */
-@media (max-width: 900px) {
- .hero {
- grid-template-columns: 1fr;
- gap: 36px;
- padding: 40px 24px 64px;
- }
- .feat-grid,
- .int-grid {
- grid-template-columns: repeat(2, 1fr);
- }
- .uc-grid {
- grid-template-columns: 1fr;
- }
- .station {
- flex-basis: 100%;
- }
- .wire {
- display: none;
- }
-}
-@media (max-width: 560px) {
- .feat-grid,
- .int-grid {
- grid-template-columns: 1fr;
- }
-}
-
-/* ============================================================
- MDX code blocks (shiki dual-theme). defaultColor:false emits
- --shiki-light/--shiki-dark vars; we pick by [data-theme] and
- wrap in the design's code panel (not shiki's github background).
- ============================================================ */
-/* shiki sits inside the .codeblock panel (CodeBlock component); keep it
- flat — the panel gives border/radius/shadow, .codeblock pre the padding/font. */
-.codeblock pre.shiki {
- margin: 0;
- border: 0;
- border-radius: 0;
- box-shadow: none;
- background: transparent;
- overflow-x: auto;
- tab-size: 2;
-}
-.codeblock pre.shiki code {
- background: none;
- border: none;
- padding: 0;
- font-size: inherit;
- font-family: inherit;
- color: inherit;
-}
-/* light (default) → dark under [data-theme="dark"] */
-.shiki,
-.shiki span {
- color: var(--shiki-light);
-}
-html[data-theme="dark"] .shiki,
-html[data-theme="dark"] .shiki span {
- color: var(--shiki-dark);
-}
+/* 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";
diff --git a/docs/app/styles/atoms.css b/docs/app/styles/atoms.css
new file mode 100644
index 00000000..9503a6cd
--- /dev/null
+++ b/docs/app/styles/atoms.css
@@ -0,0 +1,366 @@
+/* ---------- shared atoms ---------- */
+.eyebrow {
+ display: inline-flex;
+ align-items: center;
+ gap: 9px;
+ font-family: var(--mono);
+ font-size: 12.5px;
+ font-weight: 500;
+ letter-spacing: 0.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: 0.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 0.15s,
+ box-shadow 0.2s,
+ background 0.2s,
+ border-color 0.2s,
+ color 0.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, 0.16);
+}
+.btn.pri:hover {
+ transform: translateY(-2px);
+ box-shadow:
+ 0 14px 30px -16px var(--indigo),
+ inset 0 1px 0 rgba(255, 255, 255, 0.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: 0.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: -0.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: -0.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 0.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 0.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 0.2s,
+ border-color 0.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: 0.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 0.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;
+ }
+}
diff --git a/docs/app/styles/changelog.css b/docs/app/styles/changelog.css
new file mode 100644
index 00000000..57210657
--- /dev/null
+++ b/docs/app/styles/changelog.css
@@ -0,0 +1,147 @@
+/* ===== release / changelog ===== */
+.changelog {
+ margin-top: 10px;
+}
+.release {
+ padding: 30px 0;
+ border-bottom: 1px solid var(--line);
+}
+.release:first-child {
+ padding-top: 8px;
+}
+.rel-top {
+ display: flex;
+ align-items: center;
+ gap: 12px;
+ flex-wrap: wrap;
+}
+.rel-v {
+ font-family: var(--mono);
+ font-size: 23px;
+ font-weight: 600;
+ letter-spacing: -0.02em;
+ color: var(--txt);
+ scroll-margin-top: 90px;
+}
+.rel-badge {
+ font-family: var(--mono);
+ font-size: 11px;
+ font-weight: 600;
+ padding: 3px 9px;
+ border-radius: 7px;
+ text-transform: uppercase;
+ letter-spacing: 0.04em;
+}
+.rel-badge.feature {
+ color: var(--indigo-br);
+ background: var(--indigo-soft);
+ border: 1px solid var(--indigo-line);
+}
+.rel-badge.patch {
+ color: var(--mut);
+ background: var(--panel2);
+ border: 1px solid var(--line2);
+}
+.rel-badge.security {
+ color: var(--cyan);
+ background: color-mix(in oklch, var(--cyan) 10%, transparent);
+ border: 1px solid color-mix(in oklch, var(--cyan) 35%, transparent);
+}
+.rel-badge.current {
+ color: var(--grn);
+ background: color-mix(in oklch, var(--grn) 12%, transparent);
+ border: 1px solid color-mix(in oklch, var(--grn) 40%, transparent);
+}
+.rel-tagline {
+ flex-basis: 100%;
+ margin-top: 4px;
+ color: var(--mut);
+ font-size: 15px;
+ line-height: 1.55;
+}
+.rel-section {
+ margin-top: 18px;
+}
+.rel-cat {
+ display: inline-block;
+ font-family: var(--mono);
+ font-size: 10.5px;
+ font-weight: 600;
+ text-transform: uppercase;
+ letter-spacing: 0.05em;
+ padding: 2px 9px;
+ border-radius: 6px;
+ margin-bottom: 9px;
+}
+.cat-added {
+ color: var(--grn);
+ background: color-mix(in oklch, var(--grn) 11%, transparent);
+}
+.cat-fixed {
+ color: var(--amber);
+ background: color-mix(in oklch, var(--amber) 11%, transparent);
+}
+.cat-changed {
+ color: var(--indigo-br);
+ background: var(--indigo-soft);
+}
+.cat-breaking {
+ color: var(--red);
+ background: color-mix(in oklch, var(--red) 11%, transparent);
+}
+.cat-security {
+ color: var(--cyan);
+ background: color-mix(in oklch, var(--cyan) 11%, transparent);
+}
+.cat-notes {
+ color: var(--mut);
+ background: var(--panel2);
+}
+.rel-list {
+ margin: 0 0 4px;
+ padding: 0;
+ list-style: none;
+ display: flex;
+ flex-direction: column;
+ gap: 8px;
+}
+.rel-list li {
+ font-size: 14.5px;
+ line-height: 1.6;
+ color: var(--txt2);
+ padding-left: 20px;
+ position: relative;
+}
+.rel-list li::before {
+ content: "";
+ position: absolute;
+ left: 4px;
+ top: 9px;
+ width: 5px;
+ height: 5px;
+ border-radius: 50%;
+ background: var(--faint);
+}
+.rel-list li b {
+ color: var(--txt);
+ font-weight: 600;
+}
+.rel-list li code {
+ font-family: var(--mono);
+ font-size: 0.84em;
+ background: var(--panel2);
+ border: 1px solid var(--line);
+ padding: 1px 5px;
+ border-radius: 5px;
+ color: var(--txt);
+}
+.rel-earlier {
+ margin-top: 6px;
+}
+.rel-earlier .release {
+ padding: 18px 0;
+}
+.rel-earlier .rel-tagline {
+ margin-top: 2px;
+ font-size: 14px;
+}
diff --git a/docs/app/styles/cmdk.css b/docs/app/styles/cmdk.css
new file mode 100644
index 00000000..aba5d910
--- /dev/null
+++ b/docs/app/styles/cmdk.css
@@ -0,0 +1,234 @@
+/* ============================================================
+ ⌘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, 0.6),
+ 0 0 0 1px var(--line);
+ overflow: hidden;
+ opacity: 1;
+ animation: cmdkpop 0.18s cubic-bezier(0.2, 0.7, 0.3, 1);
+}
+@keyframes cmdkpop {
+ from {
+ transform: translateY(-8px) scale(0.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: 0.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;
+}
+
+/* ---------- search palette (React renders only when open) ---------- */
+.cmdk {
+ display: flex;
+}
+.cmdk-title {
+ font-size: 14px;
+ color: var(--txt);
+ font-weight: 500;
+}
+.cmdk-section {
+ margin-left: auto;
+ font-family: var(--mono);
+ font-size: 11.5px;
+ color: var(--dim);
+ text-transform: uppercase;
+ letter-spacing: 0.04em;
+}
+.cmdk-item {
+ display: flex;
+ align-items: center;
+ gap: 10px;
+ width: 100%;
+ text-align: left;
+ background: transparent;
+ border: none;
+ cursor: pointer;
+}
diff --git a/docs/app/styles/diagrams.css b/docs/app/styles/diagrams.css
new file mode 100644
index 00000000..950f5cdb
--- /dev/null
+++ b/docs/app/styles/diagrams.css
@@ -0,0 +1,1081 @@
+/* ===== diagram components (architecture) ===== */
+/* --- job lifecycle state graph --- */
+.lc {
+ position: relative;
+ margin: 24px 0;
+ border: 1px solid var(--line2);
+ border-radius: 16px;
+ padding: 20px 16px;
+ background: linear-gradient(180deg, var(--bg-soft), var(--panel));
+ overflow: hidden;
+}
+.lc svg {
+ width: 100%;
+ height: auto;
+ display: block;
+ overflow: visible;
+}
+.lc-node rect {
+ fill: var(--panel);
+ stroke: var(--line2);
+ stroke-width: 1.5;
+}
+.lc-nt {
+ fill: var(--txt);
+ font-size: 16px;
+ font-weight: 600;
+ font-family: var(--sans);
+}
+.lc-nc {
+ fill: var(--dim);
+ font-size: 11px;
+ font-family: var(--mono);
+}
+.lc-elabel {
+ fill: var(--mut);
+ font-size: 11.5px;
+ font-family: var(--mono);
+}
+.lc-node.s-pending rect {
+ stroke: var(--line3);
+}
+.lc-node.s-pending .lc-sd {
+ fill: var(--dim);
+}
+.lc-node.s-running rect {
+ stroke: var(--indigo-line);
+ fill: var(--indigo-soft);
+}
+.lc-node.s-running .lc-sd {
+ fill: var(--indigo);
+}
+.lc-node.s-complete rect {
+ stroke: color-mix(in oklch, var(--grn) 50%, transparent);
+}
+.lc-node.s-complete .lc-sd {
+ fill: var(--grn);
+}
+.lc-node.s-failed rect {
+ stroke: color-mix(in oklch, var(--amber) 50%, transparent);
+}
+.lc-node.s-failed .lc-sd {
+ fill: var(--amber);
+}
+.lc-node.s-dead rect {
+ stroke: color-mix(in oklch, var(--red) 50%, transparent);
+}
+.lc-node.s-dead .lc-sd {
+ fill: var(--red);
+}
+.lc-node.s-cancel rect {
+ stroke: var(--line3);
+ stroke-dasharray: 4 4;
+}
+.lc-node.s-cancel .lc-sd {
+ fill: var(--mut);
+}
+.lc-token {
+ position: absolute;
+ top: 21.4%;
+ left: 15%;
+ width: 11px;
+ height: 11px;
+ border-radius: 50%;
+ margin: -5.5px 0 0 -5.5px;
+ background: var(--indigo);
+ box-shadow: 0 0 12px var(--indigo);
+ z-index: 2;
+}
+@media (prefers-reduced-motion: no-preference) {
+ .lc-node.s-running .lc-sd {
+ animation: blip 1.4s infinite;
+ }
+ .lc-token {
+ animation: lctravel 4.4s cubic-bezier(0.5, 0, 0.4, 1) infinite;
+ }
+}
+@keyframes lctravel {
+ 0% {
+ left: 15%;
+ opacity: 0;
+ }
+ 6% {
+ opacity: 1;
+ }
+ 34% {
+ left: 50%;
+ opacity: 1;
+ }
+ 46% {
+ left: 50%;
+ opacity: 1;
+ }
+ 74% {
+ left: 84.5%;
+ opacity: 1;
+ }
+ 86% {
+ left: 84.5%;
+ opacity: 1;
+ }
+ 100% {
+ left: 84.5%;
+ opacity: 0;
+ }
+}
+
+/* --- scheduler poll cycle --- */
+.pc-wrap {
+ display: flex;
+ align-items: center;
+ gap: 30px;
+ flex-wrap: wrap;
+ justify-content: center;
+ margin: 24px 0;
+ border: 1px solid var(--line2);
+ border-radius: 16px;
+ padding: 26px;
+ background: linear-gradient(180deg, var(--bg-soft), var(--panel));
+}
+.pc-svg {
+ width: 230px;
+ height: 230px;
+ flex: none;
+}
+.pc-center {
+ fill: var(--txt);
+ font-size: 30px;
+ font-weight: 600;
+ font-family: var(--mono);
+ letter-spacing: -0.02em;
+}
+.pc-centersub {
+ fill: var(--dim);
+ font-size: 12px;
+ font-family: var(--mono);
+ text-transform: uppercase;
+ letter-spacing: 0.1em;
+}
+.pc-sweep {
+ transform-origin: 180px 180px;
+}
+@media (prefers-reduced-motion: no-preference) {
+ .pc-sweep {
+ animation: pcspin 3.4s linear infinite;
+ }
+}
+@keyframes pcspin {
+ to {
+ transform: rotate(360deg);
+ }
+}
+.pc-legend {
+ display: flex;
+ flex-direction: column;
+ gap: 12px;
+ min-width: 220px;
+}
+.pc-leg {
+ display: flex;
+ align-items: center;
+ gap: 11px;
+ font-size: 14px;
+}
+.pc-leg .pc-dot {
+ width: 10px;
+ height: 10px;
+ border-radius: 50%;
+ flex: none;
+}
+.pc-leg .pc-name {
+ font-family: var(--mono);
+ font-size: 13.5px;
+ color: var(--txt);
+ font-weight: 500;
+}
+.pc-leg .pc-cad {
+ margin-left: auto;
+ font-family: var(--mono);
+ font-size: 11.5px;
+ color: var(--dim);
+}
+
+/* --- mesh live demo --- */
+.mesh-demo {
+ position: relative;
+ margin: 24px 0;
+ border: 1px solid var(--line2);
+ border-radius: 18px;
+ overflow: hidden;
+ background: radial-gradient(
+ 120% 90% at 50% 40%,
+ var(--bg-soft),
+ var(--panel)
+ );
+}
+.mesh-demo .mesh-toolbar {
+ position: absolute;
+ top: 0;
+ left: 0;
+ right: 0;
+ z-index: 5;
+ display: flex;
+ align-items: center;
+ justify-content: space-between;
+ gap: 12px;
+ padding: 13px 16px;
+ flex-wrap: wrap;
+}
+.mesh-stats {
+ display: flex;
+ gap: 18px;
+ font-size: 12.5px;
+ color: var(--mut);
+ font-family: var(--mono);
+}
+.mesh-stats .mstat b {
+ color: var(--indigo-br);
+ font-weight: 600;
+ font-size: 14px;
+}
+.mesh-btns {
+ display: flex;
+ gap: 8px;
+}
+.mesh-btn {
+ font-family: var(--mono);
+ font-size: 12px;
+ font-weight: 500;
+ padding: 7px 13px;
+ border-radius: 9px;
+ cursor: pointer;
+ white-space: nowrap;
+ background: var(--panel);
+ border: 1px solid var(--line2);
+ color: var(--txt);
+ transition:
+ border-color 0.15s,
+ background 0.15s;
+}
+.mesh-btn:hover {
+ border-color: var(--indigo);
+ color: var(--indigo-br);
+}
+.mesh-stepper {
+ display: inline-flex;
+ align-items: center;
+ gap: 0;
+ border: 1px solid var(--line2);
+ border-radius: 9px;
+ background: var(--panel);
+ overflow: hidden;
+}
+.mesh-stepper button {
+ width: 30px;
+ height: 32px;
+ border: none;
+ background: transparent;
+ color: var(--txt);
+ font-size: 17px;
+ cursor: pointer;
+ display: grid;
+ place-items: center;
+ transition:
+ background 0.15s,
+ color 0.15s;
+ font-family: var(--mono);
+ line-height: 1;
+}
+.mesh-stepper button:hover:not(:disabled) {
+ background: var(--indigo-soft);
+ color: var(--indigo-br);
+}
+.mesh-stepper button:disabled {
+ opacity: 0.35;
+ cursor: not-allowed;
+}
+.mesh-count {
+ font-family: var(--mono);
+ font-size: 11.5px;
+ color: var(--mut);
+ padding: 0 10px;
+ border-left: 1px solid var(--line2);
+ border-right: 1px solid var(--line2);
+ white-space: nowrap;
+}
+.mesh-count b {
+ color: var(--txt);
+ font-weight: 600;
+}
+/* world-map backdrop */
+.mesh-map {
+ position: absolute;
+ inset: 0;
+ z-index: 0;
+ width: 100%;
+ height: 100%;
+ pointer-events: none;
+}
+.mesh-map .grat {
+ stroke: var(--line);
+ stroke-width: 1;
+ fill: none;
+}
+.mesh-map .land {
+ fill: var(--line);
+ opacity: 0.55;
+}
+[data-theme="light"] .mesh-map .land {
+ opacity: 0.7;
+}
+.mesh-map .link {
+ stroke: var(--line2);
+ stroke-width: 1.2;
+ fill: none;
+ stroke-dasharray: 2 6;
+ stroke-linecap: round;
+ opacity: 0.6;
+ transition:
+ opacity 0.2s,
+ stroke 0.2s;
+}
+.mesh-map .link.on {
+ stroke: var(--indigo-line);
+ opacity: 1;
+ stroke-dasharray: none;
+}
+.mesh-map.focus .link {
+ opacity: 0.12;
+}
+.mesh-map.focus .link.lit {
+ opacity: 1;
+ stroke: var(--indigo);
+ stroke-dasharray: none;
+}
+.mesh-map .ping {
+ stroke: var(--cyan);
+ stroke-width: 2;
+ fill: none;
+ opacity: 0;
+}
+
+/* latency labels on links (shown on focus) */
+.mlat {
+ position: absolute;
+ z-index: 3;
+ transform: translate(-50%, -50%);
+ font-family: var(--mono);
+ font-size: 10px;
+ color: var(--cyan);
+ background: color-mix(in oklch, var(--panel) 88%, transparent);
+ border: 1px solid color-mix(in oklch, var(--cyan) 32%, transparent);
+ border-radius: 6px;
+ padding: 1px 6px;
+ white-space: nowrap;
+ pointer-events: none;
+ opacity: 0;
+ transition: opacity 0.18s;
+}
+.mlat.show {
+ opacity: 1;
+}
+
+/* region node (callout card offset from its geo pin) */
+.mw {
+ position: absolute;
+ transform: translate(-50%, -50%);
+ z-index: 2;
+ width: 140px;
+ cursor: pointer;
+ background: var(--panel);
+ border: 1px solid var(--line2);
+ border-radius: 12px;
+ padding: 9px 11px;
+ box-shadow: var(--shadow-md);
+ transition:
+ border-color 0.25s,
+ box-shadow 0.25s;
+}
+.mw:hover {
+ z-index: 6;
+ border-color: var(--indigo-line);
+}
+.mw.idle {
+ opacity: 0.85;
+}
+.mw.hot {
+ border-color: color-mix(in oklch, var(--amber) 55%, transparent);
+ box-shadow:
+ 0 0 0 1px color-mix(in oklch, var(--amber) 30%, transparent),
+ var(--shadow-md);
+}
+.mw.thief {
+ border-color: var(--indigo-line);
+ box-shadow:
+ 0 0 0 2px var(--indigo-line),
+ var(--shadow-md);
+}
+.mw-head {
+ display: flex;
+ align-items: center;
+ gap: 7px;
+ margin-bottom: 6px;
+}
+.mw-id {
+ font-family: var(--mono);
+ font-size: 12px;
+ font-weight: 600;
+ color: var(--txt);
+ letter-spacing: -0.01em;
+ white-space: nowrap;
+}
+.mw-city {
+ font-family: var(--mono);
+ font-size: 9.5px;
+ color: var(--dim);
+ white-space: nowrap;
+ margin-left: auto;
+}
+.mw-pulse {
+ width: 8px;
+ height: 8px;
+ border-radius: 50%;
+ background: var(--dim);
+ flex: none;
+}
+.mw-pulse.go {
+ background: var(--grn);
+ box-shadow: 0 0 10px var(--grn);
+ animation: mwpulse 0.6s ease-out;
+}
+@keyframes mwpulse {
+ 0% {
+ transform: scale(0.6);
+ opacity: 1;
+ }
+ 100% {
+ transform: scale(1.4);
+ opacity: 0.4;
+ }
+}
+.mw-q {
+ display: flex;
+ flex-wrap: wrap;
+ gap: 3px;
+ min-height: 24px;
+ align-content: flex-start;
+}
+.mw-q i {
+ width: 10px;
+ height: 10px;
+ border-radius: 3px;
+ background: linear-gradient(180deg, var(--indigo-br), var(--indigo));
+ display: block;
+ animation: mwjob 0.3s ease-out;
+}
+.mw.hot .mw-q i {
+ background: linear-gradient(
+ 180deg,
+ var(--amber),
+ color-mix(in oklch, var(--amber) 70%, #000)
+ );
+}
+@keyframes mwjob {
+ from {
+ transform: scale(0);
+ }
+ to {
+ transform: scale(1);
+ }
+}
+.mw-q u {
+ font-family: var(--mono);
+ font-size: 10px;
+ color: var(--mut);
+ font-style: normal;
+ align-self: center;
+ margin-left: 2px;
+}
+.mw-load {
+ margin-top: 6px;
+ font-family: var(--mono);
+ font-size: 10px;
+ color: var(--dim);
+}
+.mw-load .mw-n {
+ color: var(--txt2);
+ font-weight: 600;
+}
+
+/* geo pin + callout connector */
+.mnode {
+ position: absolute;
+ z-index: 1;
+ width: 10px;
+ height: 10px;
+ border-radius: 50%;
+ transform: translate(-50%, -50%);
+ background: var(--indigo);
+ box-shadow:
+ 0 0 0 4px var(--indigo-soft),
+ 0 0 10px var(--indigo);
+ transition:
+ background 0.25s,
+ box-shadow 0.25s;
+}
+.mnode.hot {
+ background: var(--amber);
+ box-shadow:
+ 0 0 0 4px color-mix(in oklch, var(--amber) 16%, transparent),
+ 0 0 10px var(--amber);
+}
+.mesh-map .callout {
+ stroke: var(--line3);
+ stroke-width: 1;
+ stroke-dasharray: 2 4;
+ fill: none;
+ opacity: 0.7;
+}
+
+/* traveling packets */
+.mjob {
+ position: absolute;
+ z-index: 4;
+ width: 11px;
+ height: 11px;
+ border-radius: 3px;
+ left: 0;
+ top: 0;
+ background: linear-gradient(180deg, var(--indigo-br), var(--indigo));
+ box-shadow: 0 0 10px var(--indigo);
+ pointer-events: none;
+}
+.mjob.steal {
+ background: linear-gradient(
+ 180deg,
+ var(--cyan),
+ color-mix(in oklch, var(--cyan) 60%, #000)
+ );
+ box-shadow: 0 0 12px var(--cyan);
+ border-radius: 50%;
+}
+.mjob.gos {
+ width: 7px;
+ height: 7px;
+ border-radius: 50%;
+ background: var(--indigo-br);
+ box-shadow: 0 0 9px var(--indigo);
+}
+
+/* legend */
+.mesh-legend {
+ position: absolute;
+ left: 16px;
+ bottom: 13px;
+ z-index: 5;
+ display: flex;
+ gap: 15px;
+ flex-wrap: wrap;
+ font-family: var(--mono);
+ font-size: 10.5px;
+ color: var(--mut);
+}
+.mesh-legend span {
+ display: flex;
+ align-items: center;
+ gap: 6px;
+}
+.mesh-legend i {
+ width: 16px;
+ height: 0;
+ border-top: 2px dashed var(--line3);
+ display: inline-block;
+}
+.mesh-legend i.http {
+ border-top: 2px solid var(--indigo);
+}
+.mesh-legend i.steal {
+ border-top: 2px solid var(--cyan);
+}
+.mesh-legend i.dot {
+ width: 8px;
+ height: 8px;
+ border: 0;
+ border-radius: 50%;
+ background: var(--indigo);
+ box-shadow: 0 0 8px var(--indigo);
+}
+@media (max-width: 640px) {
+ .mw {
+ width: 118px;
+ }
+ .mesh-stats {
+ gap: 11px;
+ font-size: 11px;
+ }
+ .mw-city {
+ display: none;
+ }
+ .mesh-legend {
+ display: none;
+ }
+}
+
+/* --- layered stack (overview/worker/resources/mesh) --- */
+.archstack {
+ margin: 24px 0;
+ display: flex;
+ flex-direction: column;
+ gap: 0;
+ border: 1px solid var(--line2);
+ border-radius: 16px;
+ padding: 22px;
+ background: linear-gradient(180deg, var(--bg-soft), var(--panel));
+ position: relative;
+ overflow: hidden;
+}
+
+/* self-explanatory annotations (overview stack) */
+.arch-legend {
+ display: flex;
+ flex-wrap: wrap;
+ gap: 18px;
+ justify-content: center;
+ margin-bottom: 16px;
+ font-family: var(--mono);
+ font-size: 12px;
+ color: var(--mut);
+}
+.al-item {
+ display: inline-flex;
+ align-items: center;
+ gap: 7px;
+}
+.al-arrow {
+ display: inline-grid;
+ place-items: center;
+ width: 20px;
+ height: 20px;
+ border-radius: 6px;
+ font-size: 13px;
+ font-weight: 700;
+ line-height: 1;
+}
+.al-arrow.down {
+ background: var(--indigo-soft);
+ border: 1px solid var(--indigo-line);
+ color: var(--indigo-br);
+}
+.al-arrow.up {
+ background: color-mix(in oklch, var(--cyan) 12%, transparent);
+ border: 1px solid color-mix(in oklch, var(--cyan) 38%, transparent);
+ color: var(--cyan);
+}
+.archstack .lrole {
+ margin-left: auto;
+ flex: none;
+ font-family: var(--mono);
+ font-size: 11px;
+ color: var(--dim);
+ border: 1px dashed var(--line3);
+ border-radius: 100px;
+ padding: 3px 11px;
+ white-space: nowrap;
+}
+.archstack .bound .bdir {
+ color: var(--indigo-br);
+ font-weight: 700;
+ margin: 0 2px;
+}
+@media (max-width: 620px) {
+ .archstack .lrole {
+ display: none;
+ }
+}
+
+/* --- branching fork: scheduler routes to parallel pools --- */
+.archfork {
+ position: relative;
+ display: grid;
+ grid-template-columns: 1fr 1fr;
+ gap: 16px;
+ margin-top: 30px;
+}
+.archfork::after {
+ content: "";
+ position: absolute;
+ top: -22px;
+ left: 50%;
+ width: 2px;
+ height: 8px;
+ background: var(--line3);
+ transform: translateX(-50%);
+}
+.archfork::before {
+ content: "";
+ position: absolute;
+ top: -14px;
+ left: 25%;
+ right: 25%;
+ height: 14px;
+ border: 2px solid var(--line3);
+ border-bottom: none;
+ border-radius: 9px 9px 0 0;
+}
+.fork-route {
+ display: flex;
+ align-items: center;
+ justify-content: center;
+ gap: 9px;
+ margin-top: 14px;
+ font-family: var(--mono);
+ font-size: 11px;
+ color: var(--dim);
+ position: relative;
+}
+.fork-route::before,
+.fork-route::after {
+ content: "";
+ height: 1px;
+ flex: 1;
+ max-width: 120px;
+ background: linear-gradient(90deg, transparent, var(--line2), transparent);
+}
+.forkcol {
+ display: flex;
+ flex-direction: column;
+ gap: 8px;
+ min-width: 0;
+}
+.forkcol .forktag {
+ display: flex;
+ justify-content: center;
+ font-family: var(--mono);
+ font-size: 10.5px;
+ color: var(--indigo-br);
+ border: 1px dashed var(--indigo-line);
+ border-radius: 100px;
+ padding: 3px 11px;
+ background: var(--indigo-soft);
+ align-self: center;
+}
+.forkcol .layer {
+ flex: 1;
+}
+@media (max-width: 620px) {
+ .archfork {
+ grid-template-columns: 1fr;
+ gap: 22px;
+ margin-top: 22px;
+ }
+ .archfork::before,
+ .archfork::after {
+ display: none;
+ }
+}
+
+/* flow steps (dispatch / ordered) */
+.flowsteps {
+ margin: 20px 0;
+ list-style: none;
+ padding: 0;
+ display: flex;
+ flex-direction: column;
+ gap: 0;
+}
+.flowsteps li {
+ position: relative;
+ padding: 0 0 20px 44px;
+ font-size: 15px;
+ line-height: 1.6;
+ color: var(--txt2);
+}
+.flowsteps li::before {
+ content: counter(fs);
+ counter-increment: fs;
+ position: absolute;
+ left: 0;
+ top: -2px;
+ width: 28px;
+ height: 28px;
+ border-radius: 8px;
+ background: var(--indigo-soft);
+ border: 1px solid var(--indigo-line);
+ color: var(--indigo-br);
+ font-family: var(--mono);
+ font-weight: 600;
+ font-size: 13px;
+ display: grid;
+ place-items: center;
+}
+.flowsteps li::after {
+ content: "";
+ position: absolute;
+ left: 13.5px;
+ top: 28px;
+ bottom: 2px;
+ width: 1px;
+ background: var(--line2);
+}
+.flowsteps li:last-child {
+ padding-bottom: 0;
+}
+.flowsteps li:last-child::after {
+ display: none;
+}
+.flowsteps {
+ counter-reset: fs;
+}
+.flowsteps li code {
+ font-family: var(--mono);
+ font-size: 0.85em;
+ background: var(--panel2);
+ border: 1px solid var(--line);
+ padding: 1.5px 6px;
+ border-radius: 5px;
+ color: var(--txt);
+}
+.flowsteps li b {
+ color: var(--txt);
+ font-weight: 600;
+}
+
+/* sequence diagram */
+.seq {
+ margin: 22px 0;
+ border: 1px solid var(--line2);
+ border-radius: 16px;
+ padding: 22px;
+ background: var(--panel);
+ overflow-x: auto;
+}
+.seq-heads {
+ display: flex;
+ justify-content: space-around;
+ gap: 12px;
+ margin-bottom: 6px;
+ min-width: 420px;
+}
+.seq-head {
+ font-family: var(--mono);
+ font-size: 12px;
+ font-weight: 600;
+ color: var(--txt);
+ background: var(--panel2);
+ border: 1px solid var(--line2);
+ padding: 7px 14px;
+ border-radius: 9px;
+ flex: 1;
+ text-align: center;
+ max-width: 160px;
+}
+.seq-msgs {
+ display: flex;
+ flex-direction: column;
+ gap: 9px;
+ margin-top: 14px;
+ min-width: 420px;
+}
+.seq-msg {
+ display: flex;
+ align-items: center;
+ gap: 10px;
+ font-size: 13px;
+ color: var(--txt2);
+}
+.seq-msg .ln {
+ flex: 1;
+ height: 2px;
+ border-radius: 2px;
+ background: linear-gradient(
+ 90deg,
+ color-mix(in oklch, var(--indigo) 35%, transparent),
+ var(--indigo)
+ );
+ position: relative;
+}
+.seq-msg .ln::after {
+ content: "";
+ position: absolute;
+ right: -1px;
+ top: -4px;
+ border-left: 10px solid var(--indigo);
+ border-top: 5px solid transparent;
+ border-bottom: 5px solid transparent;
+}
+.seq-msg.rev .ln {
+ background: linear-gradient(
+ 90deg,
+ var(--cyan),
+ color-mix(in oklch, var(--cyan) 35%, transparent)
+ );
+}
+.seq-msg.rev .ln::after {
+ right: auto;
+ left: -1px;
+ border-left: none;
+ border-right: 10px solid var(--cyan);
+}
+.seq-msg .lbl {
+ font-family: var(--mono);
+ font-size: 11.5px;
+ color: var(--txt2);
+ white-space: nowrap;
+}
+.seq-msg .self {
+ font-family: var(--mono);
+ font-size: 11.5px;
+ color: var(--dim);
+ font-style: italic;
+ padding-left: 8px;
+}
+
+/* schema entity grid */
+.schema-grid {
+ display: grid;
+ grid-template-columns: repeat(2, 1fr);
+ gap: 14px;
+ margin: 22px 0;
+}
+.entity {
+ border: 1px solid var(--line2);
+ border-radius: 13px;
+ overflow: hidden;
+ background: var(--panel);
+}
+.entity .ehead {
+ display: flex;
+ align-items: center;
+ gap: 8px;
+ padding: 11px 15px;
+ background: var(--panel2);
+ border-bottom: 1px solid var(--line);
+ font-family: var(--mono);
+ font-size: 13px;
+ font-weight: 600;
+ color: var(--txt);
+}
+.entity .ehead .ekey {
+ margin-left: auto;
+ font-size: 10px;
+ color: var(--indigo-br);
+ background: var(--indigo-soft);
+ border: 1px solid var(--indigo-line);
+ padding: 1px 7px;
+ border-radius: 5px;
+}
+.entity .erow {
+ display: flex;
+ align-items: center;
+ gap: 10px;
+ padding: 7px 15px;
+ font-family: var(--mono);
+ font-size: 12px;
+ border-top: 1px solid var(--line);
+}
+.entity .erow:first-of-type {
+ border-top: none;
+}
+.entity .erow .fn {
+ color: var(--txt2);
+}
+.entity .erow .ft {
+ margin-left: auto;
+ color: var(--dim);
+ font-size: 11px;
+}
+.entity .erow .pk {
+ color: var(--amber);
+ font-size: 10px;
+ font-weight: 600;
+}
+.entity .erow .fk {
+ color: var(--cyan);
+ font-size: 10px;
+ font-weight: 600;
+}
+@media (max-width: 860px) {
+ .schema-grid {
+ grid-template-columns: 1fr;
+ }
+}
+
+/* recovery timeline */
+.timeline {
+ margin: 22px 0;
+ border-left: 2px solid var(--line2);
+ padding-left: 0;
+ margin-left: 8px;
+}
+.timeline .tl {
+ position: relative;
+ padding: 0 0 22px 28px;
+}
+.timeline .tl::before {
+ content: "";
+ position: absolute;
+ left: -7px;
+ top: 2px;
+ width: 12px;
+ height: 12px;
+ border-radius: 50%;
+ background: var(--panel);
+ border: 2px solid var(--indigo);
+ box-shadow: 0 0 0 4px var(--bg);
+}
+.timeline .tl:last-child {
+ padding-bottom: 0;
+}
+.timeline .tt {
+ font-family: var(--mono);
+ font-size: 11.5px;
+ color: var(--indigo-br);
+ font-weight: 600;
+}
+.timeline .tb {
+ font-size: 14.5px;
+ color: var(--txt2);
+ margin-top: 3px;
+ line-height: 1.55;
+}
+.timeline .tb b {
+ color: var(--txt);
+ font-weight: 600;
+}
+
+/* page nav (prev/next) */
+.pagenav {
+ display: flex;
+ justify-content: space-between;
+ gap: 14px;
+ margin-top: 56px;
+ padding-top: 28px;
+ border-top: 1px solid var(--line);
+}
+.pagenav a {
+ flex: 1;
+ padding: 16px 18px;
+ border: 1px solid var(--line2);
+ border-radius: 13px;
+ transition: border-color 0.2s;
+ text-decoration: none;
+}
+.pagenav a:hover {
+ border-color: var(--indigo-line);
+}
+.pagenav .dir {
+ font-family: var(--mono);
+ font-size: 11.5px;
+ color: var(--dim);
+ text-transform: uppercase;
+ letter-spacing: 0.05em;
+}
+.pagenav .ttl {
+ font-size: 15px;
+ font-weight: 600;
+ color: var(--txt);
+ margin-top: 4px;
+}
+.pagenav .nx {
+ text-align: right;
+}
diff --git a/docs/app/styles/docs.css b/docs/app/styles/docs.css
new file mode 100644
index 00000000..d8a6e292
--- /dev/null
+++ b/docs/app/styles/docs.css
@@ -0,0 +1,1095 @@
+/* ============================================================
+ taskito docs — shared page styles (sidebar / article / toc)
+ Loaded after theme.css on every docs page.
+ ============================================================ */
+body {
+ overflow-x: hidden;
+}
+.docs-shell {
+ display: grid;
+ grid-template-columns: 282px minmax(0, 1fr) 240px;
+ max-width: 1500px;
+ margin: 0 auto;
+ align-items: start;
+}
+
+/* ---------- sidebar ---------- */
+.sidebar {
+ position: sticky;
+ top: 65px;
+ height: calc(100vh - 65px);
+ overflow-y: auto;
+ padding: 28px 18px 40px 32px;
+ border-right: 1px solid var(--line);
+}
+.sidebar::-webkit-scrollbar {
+ width: 7px;
+}
+.sidebar::-webkit-scrollbar-thumb {
+ background: var(--line2);
+ border-radius: 8px;
+}
+.side-search {
+ display: flex;
+ align-items: center;
+ gap: 9px;
+ width: 100%;
+ padding: 9px 12px;
+ border: 1px solid var(--line2);
+ border-radius: 10px;
+ background: var(--panel);
+ color: var(--dim);
+ font-size: 13px;
+ font-family: var(--mono);
+ cursor: pointer;
+ margin-bottom: 22px;
+ transition: border-color 0.2s;
+}
+.side-search:hover {
+ border-color: var(--line3);
+}
+.side-search .sk {
+ margin-left: auto;
+ display: flex;
+ gap: 4px;
+}
+.side-search kbd {
+ font-family: var(--mono);
+ border: 1px solid var(--line2);
+ border-radius: 4px;
+ padding: 0 5px;
+ font-size: 11px;
+}
+/* SDK switcher (Python | Node) — sits above the nav tree */
+.sdk-switch {
+ display: grid;
+ grid-template-columns: 1fr 1fr;
+ gap: 4px;
+ padding: 4px;
+ margin-bottom: 20px;
+ background: var(--panel2);
+ border: 1px solid var(--line2);
+ border-radius: 11px;
+}
+.sdk-opt {
+ display: flex;
+ align-items: center;
+ justify-content: center;
+ gap: 7px;
+ padding: 8px 6px;
+ border-radius: 8px;
+ font-size: 13px;
+ font-weight: 500;
+ color: var(--mut);
+ text-decoration: none;
+ transition:
+ background 0.15s,
+ color 0.15s,
+ box-shadow 0.15s;
+}
+.sdk-opt svg {
+ width: 15px;
+ height: 15px;
+ flex: none;
+}
+.sdk-opt:hover {
+ color: var(--txt);
+}
+.sdk-opt.active {
+ color: var(--indigo-br);
+ background: var(--panel);
+ box-shadow:
+ 0 1px 3px rgba(0, 0, 0, 0.12),
+ 0 0 0 1px var(--indigo-line);
+}
+.nav-group {
+ margin-bottom: 22px;
+}
+.nav-group > .gt {
+ display: flex;
+ align-items: center;
+ gap: 8px;
+ font-family: var(--mono);
+ font-size: 11px;
+ font-weight: 600;
+ letter-spacing: 0.07em;
+ text-transform: uppercase;
+ color: var(--dim);
+ margin-bottom: 9px;
+ padding: 0 4px;
+}
+.nav-group > .gt svg {
+ width: 14px;
+ height: 14px;
+ color: var(--indigo-br);
+}
+.nav-item {
+ display: flex;
+ align-items: center;
+ gap: 9px;
+ padding: 7px 11px;
+ border-radius: 9px;
+ color: var(--mut);
+ font-size: 14px;
+ cursor: pointer;
+ transition:
+ background 0.15s,
+ color 0.15s;
+ position: relative;
+ text-decoration: none;
+}
+.nav-item:hover {
+ background: var(--panel2);
+ color: var(--txt);
+}
+.nav-item.active {
+ color: var(--indigo-br);
+ background: var(--indigo-soft);
+ font-weight: 500;
+}
+.nav-item.active::before {
+ content: "";
+ position: absolute;
+ left: -32px;
+ top: 6px;
+ bottom: 6px;
+ width: 2px;
+ background: var(--indigo);
+ border-radius: 2px;
+}
+.nav-sub {
+ margin-left: 6px;
+ border-left: 1px solid var(--line2);
+ padding-left: 10px;
+ display: flex;
+ flex-direction: column;
+ gap: 1px;
+}
+
+/* ---------- article ---------- */
+.article {
+ padding: 40px 56px 96px;
+ min-width: 0;
+ max-width: 840px;
+}
+.crumb {
+ display: flex;
+ align-items: center;
+ gap: 8px;
+ font-size: 13px;
+ color: var(--dim);
+ font-family: var(--mono);
+ margin-bottom: 22px;
+}
+.crumb a:hover {
+ color: var(--mut);
+}
+.crumb .sep {
+ opacity: 0.5;
+}
+.article h1 {
+ font-size: 40px;
+ line-height: 1.08;
+ letter-spacing: -0.03em;
+ font-weight: 600;
+ margin-bottom: 12px;
+}
+.lead {
+ font-size: 18px;
+ line-height: 1.55;
+ color: var(--mut);
+ margin-bottom: 14px;
+}
+.article h2 {
+ font-size: 24px;
+ font-weight: 600;
+ letter-spacing: -0.02em;
+ margin: 48px 0 14px;
+ scroll-margin-top: 90px;
+ display: flex;
+ align-items: center;
+ gap: 11px;
+}
+.article h2 .nbadge {
+ font-family: var(--mono);
+ font-size: 13px;
+ font-weight: 600;
+ color: var(--indigo-br);
+ background: var(--indigo-soft);
+ border: 1px solid var(--indigo-line);
+ width: 28px;
+ height: 28px;
+ border-radius: 8px;
+ display: grid;
+ place-items: center;
+ flex: none;
+}
+.article h3 {
+ font-size: 18px;
+ font-weight: 600;
+ margin: 32px 0 10px;
+ scroll-margin-top: 90px;
+}
+.article p {
+ font-size: 15.5px;
+ line-height: 1.7;
+ color: var(--txt2);
+ margin: 12px 0;
+}
+.article p code,
+.article li code,
+.article td code {
+ font-family: var(--mono);
+ font-size: 0.85em;
+ background: var(--panel2);
+ border: 1px solid var(--line);
+ padding: 1.5px 6px;
+ border-radius: 5px;
+ color: var(--txt);
+}
+.article a {
+ color: var(--indigo-br);
+ text-decoration: none;
+ border-bottom: 1px solid var(--indigo-line);
+ transition: border-color 0.15s;
+}
+.article a:hover {
+ border-color: var(--indigo-br);
+}
+.article ul {
+ margin: 14px 0;
+ padding-left: 4px;
+ list-style: none;
+ display: flex;
+ flex-direction: column;
+ gap: 9px;
+}
+.article ul li {
+ font-size: 15px;
+ line-height: 1.6;
+ color: var(--txt2);
+ padding-left: 22px;
+ position: relative;
+}
+.article ul li::before {
+ content: "";
+ position: absolute;
+ left: 4px;
+ top: 9px;
+ width: 6px;
+ height: 6px;
+ border-radius: 50%;
+ background: var(--indigo);
+ opacity: 0.6;
+}
+
+/* code block */
+.codeblock {
+ margin: 18px 0;
+ border: 1px solid var(--line2);
+ border-radius: 13px;
+ overflow: hidden;
+ background: var(--panel);
+ box-shadow: var(--shadow-md);
+}
+.cb-bar {
+ display: flex;
+ align-items: center;
+ gap: 9px;
+ padding: 10px 14px;
+ border-bottom: 1px solid var(--line);
+ background: color-mix(in oklch, var(--panel) 60%, #000);
+}
+[data-theme="light"] .cb-bar {
+ background: var(--panel2);
+}
+.cb-bar .lang {
+ font-family: var(--mono);
+ font-size: 11.5px;
+ color: var(--mut);
+ text-transform: lowercase;
+}
+.cb-bar .fname {
+ font-family: var(--mono);
+ font-size: 12px;
+ color: var(--txt2);
+}
+.cb-copy {
+ margin-left: auto;
+ background: transparent;
+ border: none;
+ color: var(--dim);
+ cursor: pointer;
+ display: grid;
+ place-items: center;
+ padding: 5px;
+ border-radius: 6px;
+ transition:
+ color 0.15s,
+ background 0.15s;
+}
+.cb-copy:hover {
+ color: var(--txt);
+ background: var(--panel3);
+}
+.cb-copy svg {
+ width: 15px;
+ height: 15px;
+}
+.codeblock pre {
+ margin: 0;
+ padding: 16px 18px;
+ overflow-x: auto;
+ font-family: var(--mono);
+ font-size: 13.5px;
+ line-height: 1.7;
+ color: var(--txt);
+}
+.codeblock pre::-webkit-scrollbar {
+ height: 8px;
+}
+.codeblock pre::-webkit-scrollbar-thumb {
+ background: var(--line3);
+ border-radius: 8px;
+}
+.tok-flag {
+ color: var(--cyan);
+}
+.tok-cmd {
+ color: var(--indigo-br);
+ font-weight: 600;
+}
+.tok-comment {
+ color: var(--dim);
+}
+.tok-str {
+ color: #9ce08a;
+}
+[data-theme="light"] .tok-str {
+ color: #1a8f3a;
+}
+
+/* tabs */
+.tabs {
+ margin: 18px 0;
+}
+.tablist {
+ display: flex;
+ gap: 4px;
+ border-bottom: 1px solid var(--line);
+ margin-bottom: 0;
+}
+.tab {
+ padding: 9px 15px;
+ font-size: 13.5px;
+ font-weight: 500;
+ color: var(--mut);
+ cursor: pointer;
+ border-bottom: 2px solid transparent;
+ transition:
+ color 0.15s,
+ border-color 0.15s;
+ font-family: var(--sans);
+}
+.tab:hover {
+ color: var(--txt);
+}
+.tab.active {
+ color: var(--indigo-br);
+ border-bottom-color: var(--indigo);
+}
+.tabpanel {
+ display: none;
+}
+.tabpanel.active {
+ display: block;
+}
+.tabpanel .codeblock {
+ margin-top: 14px;
+}
+
+/* callout (+ variants) */
+.callout {
+ display: flex;
+ gap: 13px;
+ margin: 20px 0;
+ padding: 15px 17px;
+ border-radius: 12px;
+ border: 1px solid var(--indigo-line);
+ background: var(--indigo-soft);
+}
+.callout .ci {
+ flex: none;
+ width: 22px;
+ height: 22px;
+ color: var(--indigo-br);
+}
+.callout .cc {
+ font-size: 14.5px;
+ line-height: 1.6;
+ color: var(--txt2);
+}
+.callout .cc strong {
+ color: var(--txt);
+ font-weight: 600;
+}
+.callout .ctitle {
+ display: block;
+ font-weight: 600;
+ color: var(--txt);
+ margin-bottom: 3px;
+ font-size: 14.5px;
+}
+.callout.info {
+ border-color: color-mix(in oklch, var(--cyan) 40%, transparent);
+ background: color-mix(in oklch, var(--cyan) 9%, transparent);
+}
+.callout.info .ci {
+ color: var(--cyan);
+}
+.callout.warn {
+ border-color: color-mix(in oklch, var(--amber) 45%, transparent);
+ background: color-mix(in oklch, var(--amber) 10%, transparent);
+}
+.callout.warn .ci {
+ color: var(--amber);
+}
+
+/* doc cards (concept / next-steps) */
+.next-grid {
+ display: grid;
+ grid-template-columns: 1fr 1fr;
+ gap: 12px;
+ margin-top: 18px;
+}
+
+/* icon card grid (index pages) */
+.icard-grid {
+ display: grid;
+ grid-template-columns: repeat(2, 1fr);
+ gap: 14px;
+ margin: 24px 0;
+}
+.icard {
+ display: block;
+ padding: 20px;
+ border: 1px solid var(--line2);
+ border-radius: 15px;
+ background: var(--panel);
+ transition:
+ border-color 0.2s,
+ transform 0.2s,
+ box-shadow 0.2s;
+ position: relative;
+ overflow: hidden;
+}
+.icard:hover {
+ border-color: var(--indigo-line);
+ transform: translateY(-3px);
+ box-shadow: var(--shadow-md);
+}
+.icard .ic {
+ width: 40px;
+ height: 40px;
+ border-radius: 11px;
+ display: grid;
+ place-items: center;
+ margin-bottom: 14px;
+ background: var(--indigo-soft);
+ border: 1px solid var(--indigo-line);
+ color: var(--indigo-br);
+}
+.icard .ic svg {
+ width: 20px;
+ height: 20px;
+}
+.icard .it {
+ font-size: 16px;
+ font-weight: 600;
+ color: var(--txt);
+ display: flex;
+ align-items: center;
+ gap: 7px;
+}
+.icard .it .arr {
+ color: var(--dim);
+ transition:
+ transform 0.2s,
+ color 0.2s;
+ font-size: 14px;
+}
+.icard:hover .it .arr {
+ transform: translateX(3px);
+ color: var(--indigo-br);
+}
+.icard .id {
+ font-size: 13.5px;
+ color: var(--mut);
+ margin-top: 6px;
+ line-height: 1.55;
+}
+@media (max-width: 860px) {
+ .icard-grid {
+ grid-template-columns: 1fr;
+ }
+}
+
+.next-card {
+ display: block;
+ padding: 16px 18px;
+ border: 1px solid var(--line2);
+ border-radius: 13px;
+ background: var(--panel);
+ transition:
+ border-color 0.2s,
+ transform 0.2s;
+}
+.next-card:hover {
+ border-color: var(--indigo-line);
+ transform: translateY(-2px);
+}
+.next-card .nt {
+ font-size: 14.5px;
+ font-weight: 600;
+ color: var(--txt);
+ display: flex;
+ align-items: center;
+ gap: 7px;
+}
+.next-card .nt .arr {
+ color: var(--dim);
+ transition: transform 0.2s;
+}
+.next-card:hover .nt .arr {
+ transform: translateX(3px);
+ color: var(--indigo-br);
+}
+.next-card .nd {
+ font-size: 13px;
+ color: var(--mut);
+ margin-top: 5px;
+ line-height: 1.5;
+}
+
+/* markdown table */
+.md-table {
+ margin: 20px 0;
+ border: 1px solid var(--line2);
+ border-radius: 13px;
+ overflow-x: auto;
+ background: var(--panel);
+}
+.md-table table {
+ width: 100%;
+ border-collapse: collapse;
+ font-size: 14.5px;
+}
+.md-table th {
+ text-align: left;
+ font-family: var(--mono);
+ font-size: 11px;
+ text-transform: uppercase;
+ letter-spacing: 0.05em;
+ color: var(--dim);
+ font-weight: 600;
+ padding: 13px 18px;
+ background: var(--panel2);
+ border-bottom: 1px solid var(--line);
+ white-space: nowrap;
+}
+.md-table td {
+ padding: 13px 18px;
+ border-top: 1px solid var(--line);
+ color: var(--txt2);
+ vertical-align: top;
+}
+.md-table tr td:first-child {
+ white-space: nowrap;
+}
+.md-table a {
+ color: var(--indigo-br);
+ border-bottom: 1px solid var(--indigo-line);
+}
+.md-table td b,
+.md-table .yes {
+ color: var(--grn);
+ font-weight: 600;
+}
+.md-table .no {
+ color: var(--mut);
+}
+/* feature-matrix taskito column highlight */
+.md-table.matrix th:nth-child(2),
+.md-table.matrix td:nth-child(2) {
+ background: var(--indigo-soft);
+}
+.md-table.matrix th:nth-child(2) {
+ color: var(--indigo-br);
+}
+
+/* when-to-use split */
+.use-split {
+ display: grid;
+ grid-template-columns: 1fr 1fr;
+ gap: 16px;
+ margin: 22px 0;
+}
+.use-card {
+ border: 1px solid var(--line2);
+ border-radius: 14px;
+ padding: 20px;
+ background: var(--panel);
+}
+.use-card.yes {
+ border-color: color-mix(in oklch, var(--grn) 35%, transparent);
+}
+.use-card.no {
+ border-color: color-mix(in oklch, var(--amber) 30%, transparent);
+}
+.use-card h3 {
+ font-size: 15px;
+ font-weight: 600;
+ margin: 0 0 12px;
+ display: flex;
+ align-items: center;
+ gap: 8px;
+}
+.use-card.yes h3 {
+ color: var(--grn);
+}
+.use-card.no h3 {
+ color: var(--amber);
+}
+.use-card ul {
+ margin: 0;
+ padding: 0;
+ list-style: none;
+ display: flex;
+ flex-direction: column;
+ gap: 10px;
+}
+.use-card li {
+ font-size: 14px;
+ line-height: 1.55;
+ color: var(--txt2);
+ padding-left: 20px;
+ position: relative;
+}
+.use-card li::before {
+ content: "";
+ position: absolute;
+ left: 3px;
+ top: 8px;
+ width: 6px;
+ height: 6px;
+ border-radius: 50%;
+}
+.use-card.yes li::before {
+ background: var(--grn);
+}
+.use-card.no li::before {
+ background: var(--amber);
+}
+.use-card li b {
+ color: var(--txt);
+ font-weight: 600;
+}
+@media (max-width: 760px) {
+ .use-split {
+ grid-template-columns: 1fr;
+ }
+}
+
+/* FAQ accordion */
+.faq-list {
+ margin: 16px 0;
+ display: flex;
+ flex-direction: column;
+ gap: 10px;
+}
+.faq-item {
+ border: 1px solid var(--line2);
+ border-radius: 13px;
+ background: var(--panel);
+ overflow: hidden;
+ transition: border-color 0.2s;
+}
+.faq-item.open {
+ border-color: var(--indigo-line);
+}
+.faq-q {
+ width: 100%;
+ display: flex;
+ align-items: center;
+ gap: 13px;
+ padding: 16px 18px;
+ background: transparent;
+ border: none;
+ cursor: pointer;
+ text-align: left;
+ font-family: var(--sans);
+ font-size: 15.5px;
+ font-weight: 600;
+ color: var(--txt);
+}
+.faq-q .faq-chevron {
+ margin-left: auto;
+ flex: none;
+ color: var(--mut);
+ transition: transform 0.22s;
+}
+.faq-item.open .faq-q .faq-chevron {
+ transform: rotate(180deg);
+ color: var(--indigo-br);
+}
+.faq-q .faq-qmark {
+ flex: none;
+ width: 26px;
+ height: 26px;
+ border-radius: 8px;
+ display: grid;
+ place-items: center;
+ font-family: var(--mono);
+ font-size: 13px;
+ font-weight: 600;
+ background: var(--indigo-soft);
+ border: 1px solid var(--indigo-line);
+ color: var(--indigo-br);
+}
+.faq-a {
+ display: none;
+ padding: 0 18px 18px 57px;
+}
+.faq-item.open .faq-a {
+ display: block;
+}
+.faq-a p {
+ margin: 6px 0;
+ font-size: 14.5px;
+ line-height: 1.65;
+ color: var(--txt2);
+}
+.faq-a p code,
+.faq-a li code {
+ font-family: var(--mono);
+ font-size: 0.85em;
+ background: var(--panel2);
+ border: 1px solid var(--line);
+ padding: 1.5px 6px;
+ border-radius: 5px;
+ color: var(--txt);
+}
+.faq-a .codeblock {
+ margin: 12px 0;
+}
+.faq-a ul {
+ margin: 10px 0;
+ padding: 0;
+ list-style: none;
+ display: flex;
+ flex-direction: column;
+ gap: 8px;
+}
+.faq-a ul li {
+ font-size: 14px;
+ line-height: 1.55;
+ color: var(--txt2);
+ padding-left: 20px;
+ position: relative;
+}
+.faq-a ul li::before {
+ content: "";
+ position: absolute;
+ left: 4px;
+ top: 9px;
+ width: 5px;
+ height: 5px;
+ border-radius: 50%;
+ background: var(--indigo);
+ opacity: 0.6;
+}
+@media (max-width: 760px) {
+ .faq-a {
+ padding-left: 18px;
+ }
+}
+
+/* when-to / general */
+.use-split + h2 {
+ margin-top: 40px;
+}
+
+/* architecture stack diagram */
+.archstack {
+ margin: 26px 0;
+ display: flex;
+ flex-direction: column;
+ gap: 0;
+ border: 1px solid var(--line2);
+ border-radius: 16px;
+ padding: 22px;
+ background: linear-gradient(180deg, var(--bg-soft), var(--panel));
+ position: relative;
+ overflow: hidden;
+}
+.archstack .layer {
+ display: flex;
+ align-items: center;
+ gap: 16px;
+ padding: 16px 18px;
+ border-radius: 13px;
+ border: 1px solid var(--line2);
+ background: var(--panel);
+ position: relative;
+ z-index: 1;
+}
+.archstack .layer.py {
+ border-color: var(--indigo-line);
+ background: linear-gradient(100deg, var(--indigo-soft), var(--panel));
+}
+.archstack .layer.rust {
+ border-color: color-mix(in oklch, var(--amber) 35%, transparent);
+ background: linear-gradient(
+ 100deg,
+ color-mix(in oklch, var(--amber) 8%, transparent),
+ var(--panel)
+ );
+}
+.archstack .ltag {
+ flex: none;
+ font-family: var(--mono);
+ font-size: 11px;
+ font-weight: 600;
+ letter-spacing: 0.06em;
+ text-transform: uppercase;
+ padding: 5px 10px;
+ border-radius: 7px;
+ color: #fff;
+}
+.archstack .ltag.t-py {
+ background: var(--indigo);
+}
+.archstack .ltag.t-rust {
+ background: var(--amber);
+ color: #1a1206;
+}
+.archstack .ltag.t-store {
+ background: var(--mut);
+}
+.archstack .lbody {
+ min-width: 0;
+}
+.archstack .lt {
+ font-size: 15px;
+ font-weight: 600;
+ color: var(--txt);
+}
+.archstack .ld {
+ font-size: 13px;
+ color: var(--mut);
+ margin-top: 2px;
+ line-height: 1.5;
+}
+.archstack .bound {
+ display: flex;
+ align-items: center;
+ justify-content: center;
+ gap: 9px;
+ padding: 8px 0;
+ font-family: var(--mono);
+ font-size: 11px;
+ color: var(--dim);
+ position: relative;
+}
+.archstack .bound::before,
+.archstack .bound::after {
+ content: "";
+ height: 1px;
+ flex: 1;
+ max-width: 120px;
+ background: linear-gradient(90deg, transparent, var(--line2), transparent);
+}
+.archstack .pyo3 {
+ color: var(--indigo-br);
+ border: 1px solid var(--indigo-line);
+ border-radius: 100px;
+ padding: 2px 10px;
+ background: var(--indigo-soft);
+}
+.archstack .pulse {
+ position: absolute;
+ left: 50%;
+ top: 0;
+ width: 8px;
+ height: 8px;
+ border-radius: 50%;
+ background: var(--indigo);
+ box-shadow: 0 0 12px var(--indigo);
+ transform: translateX(-50%);
+ opacity: 0;
+}
+@media (prefers-reduced-motion: no-preference) {
+ .archstack .pulse {
+ animation: archflow 3.2s ease-in-out infinite;
+ }
+}
+@keyframes archflow {
+ 0% {
+ top: 8%;
+ opacity: 0;
+ }
+ 10% {
+ opacity: 1;
+ }
+ 50% {
+ opacity: 1;
+ }
+ 90% {
+ opacity: 1;
+ }
+ 100% {
+ top: 92%;
+ opacity: 0;
+ }
+}
+
+/* ---------- TOC ---------- */
+.toc {
+ position: sticky;
+ top: 65px;
+ height: calc(100vh - 65px);
+ overflow-y: auto;
+ padding: 40px 24px 40px 8px;
+}
+.toc h4 {
+ font-family: var(--mono);
+ font-size: 11px;
+ font-weight: 600;
+ letter-spacing: 0.07em;
+ text-transform: uppercase;
+ color: var(--dim);
+ margin-bottom: 14px;
+ display: flex;
+ align-items: center;
+ gap: 8px;
+}
+.toc h4 svg {
+ width: 14px;
+ height: 14px;
+}
+.toc-link {
+ display: block;
+ font-size: 13px;
+ color: var(--mut);
+ padding: 5px 0 5px 14px;
+ border-left: 2px solid var(--line2);
+ transition:
+ color 0.15s,
+ border-color 0.15s;
+ cursor: pointer;
+}
+.toc-link:hover {
+ color: var(--txt);
+}
+.toc-link.sub {
+ padding-left: 26px;
+ font-size: 12.5px;
+}
+.toc-link.active {
+ color: var(--indigo-br);
+ border-left-color: var(--indigo);
+}
+
+/* mobile */
+.menu-btn {
+ display: none;
+}
+@media (max-width: 1180px) {
+ .docs-shell {
+ grid-template-columns: 262px minmax(0, 1fr);
+ }
+ .toc {
+ display: none;
+ }
+}
+@media (max-width: 860px) {
+ .docs-shell {
+ grid-template-columns: 1fr;
+ }
+ .sidebar {
+ display: none;
+ }
+ .article {
+ padding: 32px 22px 72px;
+ }
+ .menu-btn {
+ display: grid;
+ }
+ .next-grid {
+ grid-template-columns: 1fr;
+ }
+}
+
+/* Error boundary fallback */
+.error-page {
+ max-width: 680px;
+ margin: 0 auto;
+ padding: 120px 32px;
+ text-align: center;
+}
+.error-page h1 {
+ font-size: 32px;
+ letter-spacing: -0.02em;
+ margin-bottom: 16px;
+}
+.error-page a {
+ color: var(--indigo-br);
+ border-bottom: 1px solid var(--indigo-line);
+}
+
+/* ---------- React port additions (nested nav, link-group headers, prev/next blocks) ---------- */
+.gt.gt-link {
+ color: var(--dim);
+ transition: color 0.15s;
+}
+.gt.gt-link:hover {
+ color: var(--txt);
+}
+.nav-subsection {
+ margin: 2px 0;
+}
+.nav-subsection .nav-sub {
+ margin-left: 11px;
+ padding-left: 9px;
+ border-left: 1px solid var(--line);
+}
+.nav-item-label {
+ color: var(--dim);
+ font-weight: 600;
+ cursor: default;
+}
+.nav-item-label:hover {
+ background: transparent;
+ color: var(--dim);
+}
+.pagenav .dir,
+.pagenav .ttl {
+ display: block;
+}
+.next-card .nt svg {
+ width: 16px;
+ height: 16px;
+ color: var(--indigo-br);
+}
+/* search modal (Phase 6 swaps the body in) */
+.cmdk-panel {
+ width: min(620px, 92vw);
+ margin: 11vh auto 0;
+ padding: 22px 20px;
+ border: 1px solid var(--line2);
+ border-radius: 16px;
+ background: var(--panel);
+ color: var(--mut);
+ font-family: var(--mono);
+ font-size: 13px;
+}
diff --git a/docs/app/styles/landing.css b/docs/app/styles/landing.css
new file mode 100644
index 00000000..e45c33b6
--- /dev/null
+++ b/docs/app/styles/landing.css
@@ -0,0 +1,531 @@
+/* ============================================================
+ Landing page layout — reconstructed from the design tokens.
+ (The prototype's hero/sections CSS was inline in index.html.)
+ ============================================================ */
+
+/* hero */
+.hero {
+ display: grid;
+ grid-template-columns: 1fr 1.05fr;
+ gap: 48px;
+ align-items: center;
+ max-width: 1240px;
+ margin: 0 auto;
+ padding: 64px 32px 88px;
+}
+.hero-left {
+ display: flex;
+ flex-direction: column;
+ align-items: flex-start;
+ gap: 22px;
+}
+.hero h1 {
+ font-size: clamp(40px, 5vw, 62px);
+ line-height: 1.02;
+ letter-spacing: -0.035em;
+ font-weight: 600;
+ color: var(--txt);
+ text-wrap: balance;
+ margin: 0;
+}
+.hero .sub {
+ font-size: 18px;
+ line-height: 1.6;
+ color: var(--mut);
+ max-width: 520px;
+ margin: 0;
+}
+.btns {
+ display: flex;
+ gap: 12px;
+ flex-wrap: wrap;
+}
+.metarow {
+ display: flex;
+ gap: 18px;
+ flex-wrap: wrap;
+ font-family: var(--mono);
+ font-size: 12.5px;
+ color: var(--dim);
+}
+.metarow span {
+ display: inline-flex;
+ align-items: center;
+ gap: 7px;
+}
+.metarow span + span::before {
+ content: "·";
+ margin-right: 18px;
+ color: var(--faint);
+}
+.hero-right {
+ display: flex;
+ flex-direction: column;
+ gap: 12px;
+ min-width: 0;
+}
+.hero-doclink {
+ align-self: flex-start;
+ font-family: var(--mono);
+ font-size: 13px;
+ color: var(--indigo-br);
+ border-bottom: 1px solid var(--indigo-line);
+}
+.hero-doclink:hover {
+ border-color: var(--indigo-br);
+}
+
+/* code terminal (hero + comparison) */
+.term {
+ border: 1px solid var(--line2);
+ border-radius: 14px;
+ background: var(--panel);
+ box-shadow: var(--shadow-md);
+ overflow: hidden;
+ min-width: 0;
+}
+.langtabs {
+ display: flex;
+ align-items: center;
+ gap: 4px;
+ padding: 9px 12px;
+ border-bottom: 1px solid var(--line);
+ background: color-mix(in oklch, var(--panel) 55%, #000);
+}
+[data-theme="light"] .langtabs {
+ background: var(--panel2);
+}
+.langtab {
+ font-family: var(--mono);
+ font-size: 12.5px;
+ font-weight: 500;
+ color: var(--mut);
+ background: transparent;
+ border: none;
+ padding: 5px 11px;
+ border-radius: 8px;
+ cursor: pointer;
+ transition:
+ color 0.15s,
+ background 0.15s;
+}
+.langtab:hover {
+ color: var(--txt);
+}
+.langtab.active {
+ color: var(--indigo-br);
+ background: var(--indigo-soft);
+}
+.langtab.dis {
+ color: var(--faint);
+ cursor: default;
+ display: inline-flex;
+ align-items: center;
+ gap: 6px;
+}
+.tag.soon {
+ font-size: 9.5px;
+ text-transform: uppercase;
+ letter-spacing: 0.05em;
+ padding: 1px 5px;
+ border-radius: 5px;
+ border: 1px solid var(--line2);
+ color: var(--dim);
+}
+.tabname {
+ margin-left: auto;
+ font-family: var(--mono);
+ font-size: 12px;
+ color: var(--dim);
+}
+.hcopy {
+ font-family: var(--mono);
+ font-size: 12px;
+ color: var(--mut);
+ background: transparent;
+ border: 1px solid var(--line2);
+ border-radius: 7px;
+ padding: 3px 9px;
+ cursor: pointer;
+ transition:
+ border-color 0.15s,
+ color 0.15s;
+}
+.hcopy:hover {
+ color: var(--txt);
+ border-color: var(--line3);
+}
+.term .code {
+ margin: 0;
+ padding: 18px 20px;
+ font-family: var(--code);
+ font-size: 13.5px;
+ line-height: 1.7;
+ color: var(--txt2);
+ overflow-x: auto;
+ white-space: pre;
+ tab-size: 2;
+}
+.outset {
+ border-top: 1px solid var(--line);
+ background: var(--bg-soft);
+ padding: 13px 20px;
+ font-family: var(--mono);
+ font-size: 12.5px;
+ display: flex;
+ flex-direction: column;
+ gap: 5px;
+}
+.oline {
+ color: var(--mut);
+ opacity: 0;
+ transform: translateY(4px);
+ transition:
+ opacity 0.3s ease,
+ transform 0.3s ease;
+}
+.oline.show {
+ opacity: 1;
+ transform: none;
+}
+
+/* how it works */
+.how {
+ background: var(--bg-soft);
+ border-block: 1px solid var(--line);
+}
+.flowdiag {
+ display: flex;
+ align-items: stretch;
+ justify-content: center;
+ gap: 0;
+ flex-wrap: wrap;
+}
+.station {
+ flex: 1 1 0;
+ min-width: 180px;
+ border: 1px solid var(--line2);
+ border-radius: 13px;
+ background: var(--panel);
+ padding: 18px 18px;
+}
+.station.accent {
+ border-color: var(--indigo-line);
+ background: color-mix(in oklch, var(--indigo) 5%, var(--panel));
+}
+.srow {
+ display: flex;
+ align-items: center;
+ gap: 13px;
+}
+.dicon {
+ width: 38px;
+ height: 38px;
+ border-radius: 10px;
+ background: var(--indigo-soft);
+ border: 1px solid var(--indigo-line);
+ flex: none;
+}
+.dpool {
+ display: grid;
+ grid-template-columns: repeat(3, 1fr);
+ gap: 4px;
+ width: 38px;
+ flex: none;
+}
+.dpool span {
+ width: 100%;
+ aspect-ratio: 1;
+ border-radius: 3px;
+ background: var(--indigo-br);
+ opacity: 0.45;
+ animation: poolpulse 2.4s ease-in-out infinite;
+ animation-delay: calc(var(--k) * 0.2s);
+}
+@keyframes poolpulse {
+ 0%,
+ 100% {
+ opacity: 0.3;
+ }
+ 50% {
+ opacity: 0.9;
+ }
+}
+.smeta {
+ display: flex;
+ flex-direction: column;
+ gap: 2px;
+ min-width: 0;
+}
+.slabel {
+ font-family: var(--mono);
+ font-size: 10.5px;
+ letter-spacing: 0.07em;
+ color: var(--dim);
+}
+.stitle {
+ font-size: 15px;
+ font-weight: 600;
+ color: var(--txt);
+}
+.shint {
+ font-family: var(--mono);
+ font-size: 11.5px;
+ color: var(--mut);
+}
+.wire {
+ flex: 0 0 40px;
+ align-self: center;
+ height: 2px;
+ position: relative;
+ background: linear-gradient(90deg, var(--line2), var(--indigo-line));
+ overflow: hidden;
+}
+.wire .spark {
+ position: absolute;
+ top: -2px;
+ left: 0;
+ width: 6px;
+ height: 6px;
+ border-radius: 50%;
+ background: var(--indigo-br);
+ box-shadow: 0 0 8px var(--indigo-br);
+ animation: sparkmove 2.4s linear infinite;
+ animation-delay: var(--wd);
+}
+@keyframes sparkmove {
+ 0% {
+ left: -6px;
+ opacity: 0;
+ }
+ 20% {
+ opacity: 1;
+ }
+ 80% {
+ opacity: 1;
+ }
+ 100% {
+ left: 100%;
+ opacity: 0;
+ }
+}
+.returnlane {
+ display: flex;
+ align-items: center;
+ justify-content: center;
+ gap: 10px;
+ margin-top: 28px;
+ font-family: var(--mono);
+ font-size: 12px;
+ color: var(--dim);
+}
+.returnlane .rspark {
+ width: 6px;
+ height: 6px;
+ border-radius: 50%;
+ background: var(--cyan);
+ box-shadow: 0 0 8px var(--cyan);
+}
+
+/* feature + use-case grids */
+.feat-grid {
+ display: grid;
+ grid-template-columns: repeat(3, 1fr);
+ gap: 18px;
+}
+.uc-grid {
+ display: grid;
+ grid-template-columns: repeat(2, 1fr);
+ gap: 18px;
+}
+.feat-grid .card,
+.uc-grid .card {
+ position: relative;
+ border: 1px solid var(--line2);
+ border-radius: 15px;
+ background: var(--panel);
+ padding: 22px 22px 24px;
+ overflow: hidden;
+ transition:
+ transform 0.2s,
+ border-color 0.2s;
+}
+.feat-grid .card:hover,
+.uc-grid .card:hover {
+ transform: translateY(-3px);
+ border-color: var(--indigo-line);
+}
+.card .sheen {
+ position: absolute;
+ inset: 0;
+ background: radial-gradient(
+ circle at 70% -20%,
+ var(--indigo-soft),
+ transparent 60%
+ );
+ opacity: 0;
+ transition: opacity 0.3s;
+ pointer-events: none;
+}
+.card:hover .sheen {
+ opacity: 1;
+}
+.card .ic {
+ width: 42px;
+ height: 42px;
+ border-radius: 11px;
+ background: var(--indigo-soft);
+ border: 1px solid var(--indigo-line);
+ color: var(--indigo-br);
+ display: grid;
+ place-items: center;
+ margin-bottom: 15px;
+}
+.card .ic svg {
+ width: 20px;
+ height: 20px;
+}
+.card h3 {
+ font-size: 16px;
+ font-weight: 600;
+ color: var(--txt);
+ margin: 0 0 7px;
+}
+.card p {
+ font-size: 14px;
+ line-height: 1.6;
+ color: var(--mut);
+ margin: 0;
+}
+.card p code {
+ font-family: var(--mono);
+ font-size: 0.85em;
+ background: var(--panel2);
+ border: 1px solid var(--line);
+ padding: 1px 5px;
+ border-radius: 5px;
+ color: var(--txt2);
+}
+
+/* comparison + delta table */
+.cmp-term {
+ max-width: 720px;
+ margin: 0 auto 28px;
+}
+.delta {
+ max-width: 720px;
+ margin: 0 auto;
+}
+.delta .tk {
+ color: var(--txt);
+}
+.delta .ce {
+ color: var(--mut);
+}
+.delta .tk b,
+.delta .ce b {
+ color: var(--txt);
+}
+
+/* integrations */
+.int-grid {
+ display: grid;
+ grid-template-columns: repeat(4, 1fr);
+ gap: 18px;
+}
+.int-col h4 {
+ font-family: var(--mono);
+ font-size: 11px;
+ letter-spacing: 0.06em;
+ text-transform: uppercase;
+ color: var(--dim);
+ margin: 0 0 14px;
+}
+.int-col .chips {
+ display: flex;
+ flex-direction: column;
+ gap: 8px;
+}
+
+/* cta */
+.cta-wrap {
+ max-width: 880px;
+ margin: 0 auto;
+ text-align: center;
+ border: 1px solid var(--indigo-line);
+ border-radius: 24px;
+ background:
+ radial-gradient(circle at 50% 0%, var(--indigo-soft), transparent 70%),
+ var(--panel);
+ padding: 56px 32px 52px;
+}
+.cta-wrap h2 {
+ font-size: clamp(26px, 3vw, 36px);
+ letter-spacing: -0.02em;
+ font-weight: 600;
+ color: var(--txt);
+ margin: 0 0 10px;
+}
+.cta-wrap > p {
+ color: var(--mut);
+ margin: 0 0 24px;
+}
+.install-row {
+ display: flex;
+ gap: 12px;
+ justify-content: center;
+ flex-wrap: wrap;
+ margin-bottom: 26px;
+}
+.install-pill {
+ display: inline-flex;
+ align-items: center;
+ gap: 12px;
+ background: var(--bg-soft);
+ border: 1px solid var(--line2);
+ border-radius: 11px;
+ padding: 10px 14px;
+ cursor: pointer;
+ font-family: var(--mono);
+}
+.install-pill code {
+ font-size: 13px;
+ color: var(--txt);
+}
+.install-pill .copyInstall {
+ font-size: 11px;
+ color: var(--indigo-br);
+ text-transform: uppercase;
+ letter-spacing: 0.04em;
+}
+.cta-wrap .btns {
+ justify-content: center;
+}
+
+/* responsive */
+@media (max-width: 900px) {
+ .hero {
+ grid-template-columns: 1fr;
+ gap: 36px;
+ padding: 40px 24px 64px;
+ }
+ .feat-grid,
+ .int-grid {
+ grid-template-columns: repeat(2, 1fr);
+ }
+ .uc-grid {
+ grid-template-columns: 1fr;
+ }
+ .station {
+ flex-basis: 100%;
+ }
+ .wire {
+ display: none;
+ }
+}
+@media (max-width: 560px) {
+ .feat-grid,
+ .int-grid {
+ grid-template-columns: 1fr;
+ }
+}
diff --git a/docs/app/styles/shiki.css b/docs/app/styles/shiki.css
new file mode 100644
index 00000000..62594335
--- /dev/null
+++ b/docs/app/styles/shiki.css
@@ -0,0 +1,33 @@
+/* ============================================================
+ MDX code blocks (shiki dual-theme). defaultColor:false emits
+ --shiki-light/--shiki-dark vars; we pick by [data-theme] and
+ wrap in the design's code panel (not shiki's github background).
+ ============================================================ */
+/* shiki sits inside the .codeblock panel (CodeBlock component); keep it
+ flat — the panel gives border/radius/shadow, .codeblock pre the padding/font. */
+.codeblock pre.shiki {
+ margin: 0;
+ border: 0;
+ border-radius: 0;
+ box-shadow: none;
+ background: transparent;
+ overflow-x: auto;
+ tab-size: 2;
+}
+.codeblock pre.shiki code {
+ background: none;
+ border: none;
+ padding: 0;
+ font-size: inherit;
+ font-family: inherit;
+ color: inherit;
+}
+/* light (default) → dark under [data-theme="dark"] */
+.shiki,
+.shiki span {
+ color: var(--shiki-light);
+}
+html[data-theme="dark"] .shiki,
+html[data-theme="dark"] .shiki span {
+ color: var(--shiki-dark);
+}
diff --git a/docs/app/styles/tokens.css b/docs/app/styles/tokens.css
new file mode 100644
index 00000000..75f1660c
--- /dev/null
+++ b/docs/app/styles/tokens.css
@@ -0,0 +1,120 @@
+/* ============================================================
+ 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, 0.08);
+ --line2: rgba(255, 255, 255, 0.13);
+ --line3: rgba(255, 255, 255, 0.2);
+ --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, 0.12);
+ --indigo-line: rgba(31, 157, 84, 0.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, 0.7);
+ --shadow-md: 0 20px 50px -30px rgba(0, 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, 0.1);
+ --line2: rgba(45, 38, 18, 0.15);
+ --line3: rgba(45, 38, 18, 0.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, 0.1);
+ --indigo-line: rgba(16, 161, 82, 0.26);
+ --cyan: #0d9488;
+ --grn: #15a34a;
+ --amber: #c2410c;
+ --red: #dc2626;
+
+ --shadow-lg: 0 40px 90px -45px rgba(60, 50, 20, 0.2);
+ --shadow-md: 0 24px 50px -34px rgba(60, 50, 20, 0.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 0.4s ease,
+ border-color 0.4s ease,
+ color 0.4s ease;
+}
From b9a39d194e608538ff84cc39caa0ca3ea5ed2f3a Mon Sep 17 00:00:00 2001
From: Pratyush Sharma <56130065+pratyush618@users.noreply.github.com>
Date: Sun, 21 Jun 2026 11:19:16 +0530
Subject: [PATCH 14/48] docs: rebuild landing to authentic prototype CSS + DOM
---
docs/app/components/landing/footer.tsx | 88 ++
docs/app/components/landing/hero.tsx | 140 ++-
docs/app/components/landing/index.ts | 1 +
docs/app/components/landing/sections.tsx | 291 +++--
docs/app/lib/landing-content.ts | 102 +-
docs/app/routes/home.tsx | 7 +
docs/app/styles/landing.css | 1333 +++++++++++++++++-----
7 files changed, 1511 insertions(+), 451 deletions(-)
create mode 100644 docs/app/components/landing/footer.tsx
diff --git a/docs/app/components/landing/footer.tsx b/docs/app/components/landing/footer.tsx
new file mode 100644
index 00000000..d71d552f
--- /dev/null
+++ b/docs/app/components/landing/footer.tsx
@@ -0,0 +1,88 @@
+import { Link } from "react-router";
+
+const COLS = [
+ {
+ title: "Docs",
+ links: [
+ { label: "Getting Started", href: "/getting-started/installation" },
+ { label: "Guides", href: "/guides" },
+ { label: "Architecture", href: "/architecture" },
+ { label: "API Reference", href: "/api-reference" },
+ ],
+ },
+ {
+ title: "More",
+ links: [
+ { label: "Examples", href: "/more/examples" },
+ { label: "Celery comparison", href: "/more/comparison" },
+ { label: "FAQ", href: "/more/faq" },
+ { label: "Changelog", href: "/more/changelog" },
+ ],
+ },
+ {
+ title: "Project",
+ links: [
+ {
+ label: "GitHub",
+ href: "https://github.com/ByteVeda/taskito",
+ external: true,
+ },
+ {
+ label: "Releases",
+ href: "https://github.com/ByteVeda/taskito/releases",
+ external: true,
+ },
+ {
+ label: "Issues",
+ href: "https://github.com/ByteVeda/taskito/issues",
+ external: true,
+ },
+ {
+ label: "PyPI",
+ href: "https://pypi.org/project/taskito/",
+ external: true,
+ },
+ ],
+ },
+];
+
+export function Footer() {
+ return (
+
+ );
+}
diff --git a/docs/app/components/landing/hero.tsx b/docs/app/components/landing/hero.tsx
index 04bb27a0..687acdfc 100644
--- a/docs/app/components/landing/hero.tsx
+++ b/docs/app/components/landing/hero.tsx
@@ -2,7 +2,9 @@ import { useState } from "react";
import { Link } from "react-router";
import { RawHtml } from "@/components/ui";
import { highlightPython, highlightTs } from "@/lib/highlight-lite";
-import { HERO_PANES, SOON_LANGS } from "@/lib/landing-content";
+import { HERO_PANES, SOON_PANES, type SoonLang } from "@/lib/landing-content";
+
+type Lang = "py" | "ts" | "go" | "java";
function CopyButton({ text }: { text: string }) {
const [copied, setCopied] = useState(false);
@@ -16,52 +18,79 @@ function CopyButton({ text }: { text: string }) {
setTimeout(() => setCopied(false), 1300);
}}
>
- {copied ? "Copied" : "Copy"}
+ {copied ? "Copied" : "Copy"}
);
}
+function SoonBox({ pane }: { pane: SoonLang }) {
+ return (
+
+
+ {pane.heading}
+ {pane.body}
+ github.com/ByteVeda/taskito
+
+ );
+}
+
export function Hero() {
- const [lang, setLang] = useState<"py" | "ts">("py");
- const pane = HERO_PANES.find((p) => p.id === lang) ?? HERO_PANES[0];
- const codeHtml =
- lang === "py" ? highlightPython(pane.code) : highlightTs(pane.code);
+ const [lang, setLang] = useState("py");
+ const pane = HERO_PANES.find((p) => p.id === lang);
+ const codeHtml = pane
+ ? lang === "py"
+ ? highlightPython(pane.code)
+ : highlightTs(pane.code)
+ : "";
+ const active = pane ?? HERO_PANES[0];
return (
-
-
- Rust-powered · Python & Node.js
-
- One queue. Python and Node.
+
+
+ One queue.Python and Node.
+
- A brokerless, Rust-powered task queue with first-class Python and
- Node.js SDKs over one core and store. No Redis, no RabbitMQ — just a
- file and a worker.
+ A Rust-powered task queue with first-class Python and{" "}
+ Node.js SDKs over one core and one store — no broker. Start on{" "}
+ SQLite, scale to Postgres.
-
- Get started →
+
+ Quickstart →
-
- GitHub
+
+ Install
+
+
+ GitHub ↗
- MIT licensed
- SQLite · Postgres · Redis
- v0.16
+ Brokerless
+ Rust core
+ Python & Node
+ DAG workflows
-
+
-
+
+
+
+
+
+
+
+ {active.filename}
+
+
+
+ worker · live
+
+
+
{HERO_PANES.map((p) => (
- p.id === lang) ?? SOON_PANES[0]}
+ />
+ )}
-
- {pane.docLabel} →
+
+ {pane ? (
+
+
+ {pane.output.map((line) => (
+
+ {line.glyph}
+ {line.text}
+ {line.value ? {line.value} : null}
+ {line.timing ? (
+ {line.timing}
+ ) : null}
+
+ ))}
+
+
+ ) : null}
+
+
+ {active.docLabel} →
diff --git a/docs/app/components/landing/index.ts b/docs/app/components/landing/index.ts
index d7bd79f3..1991a1b3 100644
--- a/docs/app/components/landing/index.ts
+++ b/docs/app/components/landing/index.ts
@@ -1,3 +1,4 @@
+export { Footer } from "./footer";
export { Hero } from "./hero";
export { useReveal } from "./reveal";
export {
diff --git a/docs/app/components/landing/sections.tsx b/docs/app/components/landing/sections.tsx
index 213bc835..70da8c23 100644
--- a/docs/app/components/landing/sections.tsx
+++ b/docs/app/components/landing/sections.tsx
@@ -29,6 +29,24 @@ function Icon({ d, rect }: { d: string; rect?: boolean }) {
);
}
+function SectionHead({
+ kicker,
+ title,
+ lead,
+}: {
+ kicker: string;
+ title: string;
+ lead?: string;
+}) {
+ return (
+
+ {kicker}
+ {title}
+ {lead ? {lead}
: null}
+
+ );
+}
+
const STATIONS = [
{ label: "YOUR CODE", title: "enqueue", hint: ".delay()" },
{ label: "QUEUE", title: "store", hint: "SQLite · PG" },
@@ -46,28 +64,26 @@ export function HowItWorks() {
return (
-
- How it works
- Enqueue here, execute there.
-
- The Rust scheduler polls the store, dispatches to a worker pool, and
- writes results back — the same loop whether you enqueue from Python
- or Node.
-
-
-
- {STATIONS.map((s, i) => (
- {c.title}
-
-
- Features
- Everything a queue needs, nothing it doesn't.
+ {c.title}
+
+
-
- Use cases
- Built for real workloads.
+
+ {c.title} →
+
+
+
-
- vs Celery
- One dependency, not three.
-
-
-
-
-
+
-
-
-
- taskito
- Celery
-
-
-
- {DELTA.map((d) => (
-
- {d.label}
-
+
+
+
+ taskito
+ Celery + Redis
- ))}
-
-
+
+
+ {DELTA.map((d) => (
+
+ {d.label}
+
+ ))}
+
+
+
);
@@ -221,13 +250,20 @@ export function Comparison() {
export function Integrations() {
return (
-
+
-
- Integrations
- Fits your stack.
-
-
+ {g.group}
@@ -250,37 +286,48 @@ export function Integrations() {
function InstallPill({ cmd }: { cmd: string }) {
const [copied, setCopied] = useState(false);
return (
-
+
+ $
+ {cmd}
+
+
);
}
export function CTA() {
return (
-
-
- Ship background work in minutes.
- One file, one worker. Pick your runtime:
+
+
+
+ Get started
+
+ Five minutes from install to your first job.
+
+ The quickstart walks you through defining a task, enqueuing it, and
+ watching the worker run it — in Python or Node, no Redis, no broker,
+ no config.
+
+
);
}
diff --git a/docs/app/styles/landing.css b/docs/app/styles/landing.css
index e45c33b6..ad83bccb 100644
--- a/docs/app/styles/landing.css
+++ b/docs/app/styles/landing.css
@@ -1,9 +1,67 @@
-/* ============================================================
- Landing page layout — reconstructed from the design tokens.
- (The prototype's hero/sections CSS was inline in index.html.)
- ============================================================ */
+/* Landing page — authentic CSS, verbatim from the prototype index.html
- );
-}
diff --git a/docs/app/components/animated/architecture-stack.tsx b/docs/app/components/animated/architecture-stack.tsx
deleted file mode 100644
index a55c1c13..00000000
--- a/docs/app/components/animated/architecture-stack.tsx
+++ /dev/null
@@ -1,148 +0,0 @@
-import {
- Arrow,
- DiagramFrame,
- MotionStyles,
- NodeBox,
- Panel,
-} from "./_primitives";
-
-const VIEW_W = 640;
-const VIEW_H = 296;
-
-const PANELS = [
- { id: "python", label: "python layer", y: 24, h: 76, cy: 62 },
- { id: "rust", label: "rust core", y: 110, h: 76, cy: 148 },
- { id: "storage", label: "storage", y: 196, h: 76, cy: 234 },
-] as const;
-
-type NodeData = {
- id: string;
- label: string;
- hint?: string;
- cx: number;
- cy: number;
- variant?: "primary";
-};
-
-const NODES: NodeData[] = [
- { id: "queue", label: "Queue", hint: ".delay()", cx: 150, cy: 62 },
- { id: "task", label: "@task fn", hint: "Python", cx: 490, cy: 62 },
- { id: "pyqueue", label: "PyQueue", hint: "PyO3", cx: 150, cy: 148 },
- {
- id: "scheduler",
- label: "Scheduler",
- hint: "Tokio · 50ms",
- cx: 320,
- cy: 148,
- variant: "primary",
- },
- {
- id: "workerpool",
- label: "Worker Pool",
- hint: "Rust threads",
- cx: 490,
- cy: 148,
- },
- { id: "sqlite", label: "SQLite", hint: "default", cx: 260, cy: 234 },
- { id: "postgres", label: "PostgreSQL", hint: "scale-out", cx: 420, cy: 234 },
-];
-
-const ARROWS = [
- { id: "enqueue", d: "M 150 85 L 150 125" },
- { id: "insert", d: "M 205 148 L 265 148" },
- { id: "dispatch", d: "M 375 148 L 435 148" },
- { id: "gil", d: "M 490 125 L 490 85" },
- {
- id: "persist",
- d: "M 320 172 Q 320 188 340 200",
- variant: "muted" as const,
- },
-];
-
-export function ArchitectureStack() {
- return (
-
- {PANELS.map((p) => (
-
- acquire GIL
-
-
-
- );
-}
diff --git a/docs/app/components/animated/crash-recovery-timeline.tsx b/docs/app/components/animated/crash-recovery-timeline.tsx
deleted file mode 100644
index d33f2045..00000000
--- a/docs/app/components/animated/crash-recovery-timeline.tsx
+++ /dev/null
@@ -1,287 +0,0 @@
-import {
- Arrow,
- Caption,
- DiagramFrame,
- MotionStyles,
- NodeBox,
- SKETCH_FILTER,
-} from "./_primitives";
-
-const VIEW_W = 760;
-const VIEW_H = 260;
-const TRACK_Y = 150;
-const TRACK_LEFT = 50;
-const TRACK_RIGHT = 730;
-const WORKER_Y = 60;
-
-type Marker = {
- id: string;
- x: number;
- time: string;
- label: string;
- variant?: "primary" | "danger" | "success";
-};
-
-const MARKERS: Marker[] = [
- { id: "enqueue", x: 80, time: "T=0", label: "enqueue", variant: "primary" },
- {
- id: "dispatch",
- x: 170,
- time: "T=1s",
- label: "dispatch",
- variant: "primary",
- },
- { id: "crash", x: 250, time: "T=5s", label: "crash", variant: "danger" },
- {
- id: "reap",
- x: 510,
- time: "T=300s",
- label: "reap_stale",
- variant: "primary",
- },
- { id: "retry", x: 600, time: "T=301s", label: "retry", variant: "primary" },
- { id: "done", x: 690, time: "T=302s", label: "complete", variant: "success" },
-];
-
-const POLLING_LEFT = 280;
-const POLLING_RIGHT = 480;
-
-export function CrashRecoveryTimeline() {
- return (
-
- {/* Worker boxes (above timeline) */}
-
- );
-}
-
-function MarkerPin({ marker }: { marker: Marker }) {
- const color =
- marker.variant === "danger"
- ? "var(--color-fd-muted-foreground)"
- : marker.variant === "success" || marker.variant === "primary"
- ? "var(--color-fd-primary)"
- : "var(--color-fd-muted-foreground)";
- return (
-
-
- {marker.time}
-
-
- {marker.label}
-
-
- );
-}
-
-function CrashBurst({ cx, cy }: { cx: number; cy: number }) {
- return (
-
-
- );
-}
-
-function PollingRegion({ x1, x2, y }: { x1: number; x2: number; y: number }) {
- const count = Math.floor((x2 - x1) / 14);
- return (
-
- {Array.from({ length: count }, (_, i) => (
-
- );
-}
diff --git a/docs/app/components/animated/dispatch-sequence.tsx b/docs/app/components/animated/dispatch-sequence.tsx
deleted file mode 100644
index 1434d2eb..00000000
--- a/docs/app/components/animated/dispatch-sequence.tsx
+++ /dev/null
@@ -1,200 +0,0 @@
-import {
- Arrow,
- Caption,
- DiagramFrame,
- Lifeline,
- MotionStyles,
- NodeBox,
-} from "./_primitives";
-
-const VIEW_W = 760;
-const VIEW_H = 380;
-
-type Lane = { id: string; label: string; cx: number };
-
-const LANES: Lane[] = [
- { id: "scheduler", label: "Scheduler", cx: 90 },
- { id: "db", label: "Storage", cx: 240 },
- { id: "rl", label: "RateLimiter", cx: 380 },
- { id: "wp", label: "WorkerPool", cx: 520 },
- { id: "worker", label: "Worker", cx: 660 },
-];
-
-const HEADER_Y = 24;
-const HEADER_H = 36;
-const LIFELINE_TOP = HEADER_Y + HEADER_H + 4;
-const LIFELINE_BOTTOM = 358;
-
-type Msg = {
- num: number;
- fromLane: string;
- toLane: string;
- label: string;
- y: number;
- reply?: boolean;
-};
-
-const MSGS: Msg[] = [
- {
- num: 1,
- fromLane: "scheduler",
- toLane: "db",
- label: "dequeue_from()",
- y: 88,
- },
- {
- num: 2,
- fromLane: "db",
- toLane: "scheduler",
- label: "pending job",
- y: 124,
- reply: true,
- },
- { num: 3, fromLane: "scheduler", toLane: "rl", label: "check(task)", y: 160 },
- {
- num: 4,
- fromLane: "rl",
- toLane: "scheduler",
- label: "ok",
- y: 196,
- reply: true,
- },
- {
- num: 5,
- fromLane: "scheduler",
- toLane: "wp",
- label: "mpsc.send(job)",
- y: 232,
- },
- { num: 6, fromLane: "wp", toLane: "worker", label: "execute()", y: 268 },
- {
- num: 7,
- fromLane: "worker",
- toLane: "scheduler",
- label: "result",
- y: 304,
- reply: true,
- },
- {
- num: 8,
- fromLane: "scheduler",
- toLane: "db",
- label: "handle_result()",
- y: 340,
- },
-];
-
-const TOTAL_DURATION = 14;
-const SLOT_PERCENT = 8;
-const TRAVEL_PERCENT = 6.5;
-const FADE_IN_PERCENT = 0.5;
-const FADE_OUT_PERCENT = TRAVEL_PERCENT + 0.5;
-
-function laneCx(id: string): number {
- const lane = LANES.find((l) => l.id === id);
- if (!lane) throw new Error(`unknown lane: ${id}`);
- return lane.cx;
-}
-
-export function DispatchSequence() {
- return (
-
- {LANES.map((lane) => (
-
-
- ))}
-
- {MSGS.map((msg) => {
- const x1 = laneCx(msg.fromLane);
- const x2 = laneCx(msg.toLane);
- const dir = x2 > x1 ? 1 : -1;
- const startX = x1 + dir * 6;
- const endX = x2 - dir * 6;
- return (
-
-
-
- {`${msg.num} `}
-
- {msg.label}
-
-
- );
- })}
-
- keyframeFor(m)).join("\n")}
-`}
- animations={`
-${MSGS.map(
- (m) => `.taskito-seq .tok-${m.num} {
- animation: taskito-seq-msg-${m.num} ${TOTAL_DURATION}s linear infinite;
- filter: drop-shadow(0 0 6px var(--color-fd-primary));
-}`,
-).join("\n")}
-`}
- />
-
- );
-}
-
-function keyframeFor(msg: Msg): string {
- const startX = laneCx(msg.fromLane);
- const endX = laneCx(msg.toLane);
- return `
-@keyframes taskito-seq-msg-${msg.num} {
- 0% { cx: ${startX}px; cy: ${msg.y}px; opacity: 0; }
- ${FADE_IN_PERCENT}% { cx: ${startX}px; cy: ${msg.y}px; opacity: 1; }
- ${TRAVEL_PERCENT}% { cx: ${endX}px; cy: ${msg.y}px; opacity: 1; }
- ${FADE_OUT_PERCENT}% { cx: ${endX}px; cy: ${msg.y}px; opacity: 0; }
- ${SLOT_PERCENT}% { cx: ${startX}px; cy: ${msg.y}px; opacity: 0; }
- 100% { cx: ${startX}px; cy: ${msg.y}px; opacity: 0; }
-}`;
-}
diff --git a/docs/app/components/animated/entity-schema.tsx b/docs/app/components/animated/entity-schema.tsx
deleted file mode 100644
index e7d7d8e3..00000000
--- a/docs/app/components/animated/entity-schema.tsx
+++ /dev/null
@@ -1,246 +0,0 @@
-import { DiagramFrame, SKETCH_FILTER } from "./_primitives";
-
-const FONT_MONO =
- 'var(--font-mono), "IBM Plex Mono", ui-monospace, SFMono-Regular, monospace';
-
-type Field = {
- name: string;
- type: string;
- key?: "PK" | "FK";
-};
-
-type EntitySchemaProps = {
- name: string;
- fields: Field[];
-};
-
-const ROW_H = 22;
-const HEADER_H = 36;
-const PAD_X = 18;
-const SCHEMA_W = 360;
-
-export function EntitySchema({ name, fields }: EntitySchemaProps) {
- const h = HEADER_H + fields.length * ROW_H + 14;
- return (
-
-
- {name}
-
-
- table
-
-
- {fields.map((field, i) => (
-
- );
-}
-
-function FieldRow({ field, y }: { field: Field; y: number }) {
- const tagX = SCHEMA_W - PAD_X - 30;
- const tagColor =
- field.key === "PK"
- ? "var(--color-fd-primary)"
- : "var(--color-fd-muted-foreground)";
- return (
-
-
- {field.name}
-
-
- {field.type}
-
- {field.key ? (
-
-
- {field.key}
-
-
- ) : null}
-
- );
-}
-
-type EntityRelationsProps = {
- caption?: string;
- relations: Array<{
- from: string;
- to: string;
- cardinality: string;
- label?: string;
- }>;
-};
-
-export function EntityRelations({ caption, relations }: EntityRelationsProps) {
- const names = Array.from(new Set(relations.flatMap((r) => [r.from, r.to])));
- const w = 600;
- const slotW = w / Math.max(names.length, 1);
- const boxW = Math.min(slotW - 24, 160);
- const boxH = 56;
- const topY = 40;
- const linkBaseY = topY + boxH + 50;
- const linkSpacing = 60;
- const h = topY + boxH + 60 + linkSpacing * relations.length;
-
- const xFor = (entity: string) => {
- const i = names.indexOf(entity);
- return slotW * i + slotW / 2;
- };
-
- return (
-
-
- {names.map((name) => {
- const cx = xFor(name);
- return (
-
-
- {name}
-
-
- );
- })}
-
- {relations.map((rel, i) => {
- const x1 = xFor(rel.from);
- const x2 = xFor(rel.to);
- const y = linkBaseY + i * linkSpacing;
- const midX = (x1 + x2) / 2;
- return (
- // biome-ignore lint/suspicious/noArrayIndexKey: relations are statically authored; index disambiguates same-pair duplicates
-
-
- {rel.cardinality}
- {rel.label ? ` · ${rel.label}` : ""}
-
-
- );
- })}
-
- {caption ? (
-
- {caption}
-
- ) : null}
-
- );
-}
diff --git a/docs/app/components/animated/how-it-works.tsx b/docs/app/components/animated/how-it-works.tsx
deleted file mode 100644
index a5b7e47b..00000000
--- a/docs/app/components/animated/how-it-works.tsx
+++ /dev/null
@@ -1,317 +0,0 @@
-import type { ReactNode } from "react";
-
-type Station = {
- id: string;
- label: string;
- hint: string;
- cx: number;
- glyph: ReactNode;
-};
-
-const VIEW_W = 460;
-const VIEW_H = 130;
-const TRACK_Y = 50;
-const STATION_W = 56;
-const STATION_H = 44;
-
-const STATIONS: Station[] = [
- {
- id: "enqueue",
- label: "enqueue",
- hint: ".delay()",
- cx: 56,
- glyph:
-
-
- how it works
-
-
- Your code calls{" "}
- .delay() · the
- job durably queues · a Rust scheduler routes it · a worker returns the
- result.
-
-
-
-
-
-
- );
-}
-
-function StationNode({ station }: { station: Station }) {
- const isWorker = station.id === "worker";
- const x = station.cx - STATION_W / 2;
- const y = TRACK_Y - STATION_H / 2;
- return (
-
-
- {station.glyph}
-
- {isWorker ? (
-
- {station.label}
-
-
- {station.hint}
-
-
- );
-}
-
-function CodeGlyph() {
- return (
-
- );
-}
-
-function DatabaseGlyph() {
- return (
-
- );
-}
-
-function WorkerGlyph() {
- return (
-
- );
-}
-
-function CheckGlyph() {
- return (
-
- );
-}
-
-function FlowStyles() {
- return (
-
- );
-}
diff --git a/docs/app/components/animated/index.ts b/docs/app/components/animated/index.ts
deleted file mode 100644
index b369b7bc..00000000
--- a/docs/app/components/animated/index.ts
+++ /dev/null
@@ -1,10 +0,0 @@
-export { ArchitectureStack } from "./architecture-stack";
-export { CrashRecoveryTimeline } from "./crash-recovery-timeline";
-export { DispatchSequence } from "./dispatch-sequence";
-export { EntityRelations, EntitySchema } from "./entity-schema";
-export { HowItWorks } from "./how-it-works";
-export { JobStateMachine } from "./job-state-machine";
-export { ResourcePipeline } from "./resource-pipeline";
-export { SchedulerPollLoop } from "./scheduler-poll-loop";
-export { WorkerDispatch } from "./worker-dispatch";
-export { WorkerPool } from "./worker-pool";
diff --git a/docs/app/components/animated/job-state-machine.tsx b/docs/app/components/animated/job-state-machine.tsx
deleted file mode 100644
index a3cdfc7f..00000000
--- a/docs/app/components/animated/job-state-machine.tsx
+++ /dev/null
@@ -1,204 +0,0 @@
-import { Arrow, DiagramFrame, MotionStyles, NodeBox } from "./_primitives";
-
-const VIEW_W = 580;
-const VIEW_H = 280;
-const NODE_W = 116;
-const NODE_H = 46;
-const ROW_LIVE = 90;
-const ROW_FAULT = 200;
-
-type StateData = {
- id: string;
- label: string;
- cx: number;
- cy: number;
- variant?: "primary" | "terminal";
-};
-
-const STATES: StateData[] = [
- { id: "pending", label: "Pending", cx: 100, cy: ROW_LIVE },
- {
- id: "running",
- label: "Running",
- cx: 290,
- cy: ROW_LIVE,
- variant: "primary",
- },
- {
- id: "complete",
- label: "Complete",
- cx: 480,
- cy: ROW_LIVE,
- variant: "terminal",
- },
- {
- id: "cancelled",
- label: "Cancelled",
- cx: 100,
- cy: ROW_FAULT,
- variant: "terminal",
- },
- { id: "failed", label: "Failed", cx: 290, cy: ROW_FAULT },
- { id: "dead", label: "Dead", cx: 480, cy: ROW_FAULT, variant: "terminal" },
-];
-
-type EdgeData = {
- id: string;
- d: string;
- label?: string;
- labelX?: number;
- labelY?: number;
- anchor?: "start" | "middle" | "end";
- variant?: "muted";
-};
-
-const EDGES: EdgeData[] = [
- {
- id: "dequeue",
- d: `M 158 ${ROW_LIVE} L 232 ${ROW_LIVE}`,
- label: "dequeue",
- labelX: 195,
- labelY: ROW_LIVE - 10,
- },
- {
- id: "success",
- d: `M 348 ${ROW_LIVE} L 422 ${ROW_LIVE}`,
- label: "success",
- labelX: 385,
- labelY: ROW_LIVE - 10,
- },
- {
- id: "raise",
- d: `M 290 ${ROW_LIVE + NODE_H / 2} L 290 ${ROW_FAULT - NODE_H / 2}`,
- label: "raise",
- labelX: 302,
- labelY: 145,
- anchor: "start",
- },
- {
- id: "cancel",
- d: `M 100 ${ROW_LIVE + NODE_H / 2} L 100 ${ROW_FAULT - NODE_H / 2}`,
- label: "cancel",
- labelX: 92,
- labelY: 158,
- anchor: "end",
- variant: "muted",
- },
- {
- id: "exhausted",
- d: `M 348 ${ROW_FAULT} L 422 ${ROW_FAULT}`,
- label: "exhausted",
- labelX: 385,
- labelY: ROW_FAULT - 10,
- },
- {
- id: "retry",
- d: `M 232 ${ROW_FAULT - 6} Q 175 ${ROW_FAULT - 4} 158 ${ROW_LIVE + NODE_H / 2 - 2}`,
- label: "retry · backoff",
- labelX: 222,
- labelY: 142,
- anchor: "end",
- },
- {
- id: "retry-dead",
- d: `M 480 ${ROW_FAULT + NODE_H / 2} Q 290 ${VIEW_H - 10} 100 ${ROW_LIVE + NODE_H / 2 + 14}`,
- label: "retry_dead()",
- labelX: 290,
- labelY: VIEW_H - 14,
- variant: "muted",
- },
-];
-
-// Composite trajectories — each token traces a coherent story along the arrows.
-const PATH_HAPPY = "M 100 90 L 290 90 L 480 90";
-const PATH_RETRY =
- "M 100 90 L 290 90 L 290 200 Q 175 196 158 113 L 290 90 L 480 90";
-const PATH_DEATH = "M 100 90 L 290 90 L 290 200 L 480 200";
-
-export function JobStateMachine() {
- return (
-
- {EDGES.map((e) => (
-
- );
-}
diff --git a/docs/app/components/animated/resource-pipeline.tsx b/docs/app/components/animated/resource-pipeline.tsx
deleted file mode 100644
index a52fc371..00000000
--- a/docs/app/components/animated/resource-pipeline.tsx
+++ /dev/null
@@ -1,251 +0,0 @@
-import {
- Arrow,
- Caption,
- Cylinder,
- DiagramFrame,
- MotionStyles,
- NodeBox,
- Panel,
-} from "./_primitives";
-
-const VIEW_W = 820;
-const VIEW_H = 380;
-
-const ENQ_X = 20;
-const ENQ_Y = 24;
-const ENQ_W = 340;
-const ENQ_H = 332;
-const ENQ_CX = ENQ_X + ENQ_W / 2; // 190
-
-const WRK_X = 400;
-const WRK_Y = 24;
-const WRK_W = 400;
-const WRK_H = 332;
-const WRK_CX = WRK_X + WRK_W / 2; // 600
-
-const QUEUE_CX = 380;
-const QUEUE_CY = 196;
-const QUEUE_RX = 24;
-const QUEUE_RY = 16;
-
-const ROW_TOP = 78;
-const ROW_MID = 152;
-const ROW_PROXY = 232;
-const ROW_FN = 304;
-
-type NodeData = {
- id: string;
- label: string;
- hint?: string;
- cx: number;
- cy: number;
- w: number;
- h: number;
- variant?: "primary" | "muted";
-};
-
-const ENQ_NODES: NodeData[] = [
- {
- id: "args",
- label: "Task arguments",
- cx: ENQ_CX,
- cy: ROW_TOP,
- w: 200,
- h: 40,
- },
- {
- id: "ic",
- label: "ArgumentInterceptor",
- hint: "PASS · CONVERT · REDIRECT · PROXY",
- cx: ENQ_CX,
- cy: ROW_MID,
- w: 260,
- h: 50,
- variant: "primary",
- },
- {
- id: "px",
- label: "ProxyHandler",
- hint: ".deconstruct()",
- cx: ENQ_CX,
- cy: ROW_PROXY,
- w: 200,
- h: 42,
- },
- {
- id: "ser",
- label: "Serializer",
- hint: "bytes",
- cx: ENQ_CX,
- cy: ROW_FN,
- w: 170,
- h: 42,
- },
-];
-
-const WORKER_NODES: NodeData[] = [
- { id: "de", label: "Deserialize", cx: WRK_CX, cy: ROW_TOP, w: 170, h: 40 },
- {
- id: "rc",
- label: "reconstruct_args()",
- cx: WRK_CX,
- cy: ROW_MID,
- w: 220,
- h: 46,
- },
- {
- id: "pxr",
- label: "ProxyHandler",
- hint: ".reconstruct()",
- cx: 510,
- cy: ROW_PROXY,
- w: 140,
- h: 42,
- variant: "muted",
- },
- {
- id: "rr",
- label: "ResourceRuntime",
- hint: "inject()",
- cx: 690,
- cy: ROW_PROXY,
- w: 140,
- h: 42,
- variant: "muted",
- },
- {
- id: "fn",
- label: "Task function",
- hint: "f(**args)",
- cx: WRK_CX,
- cy: ROW_FN,
- w: 180,
- h: 50,
- variant: "primary",
- },
-];
-
-export function ResourcePipeline() {
- return (
-
-
- );
-}
diff --git a/docs/app/components/animated/scheduler-poll-loop.tsx b/docs/app/components/animated/scheduler-poll-loop.tsx
deleted file mode 100644
index 2cb477a6..00000000
--- a/docs/app/components/animated/scheduler-poll-loop.tsx
+++ /dev/null
@@ -1,291 +0,0 @@
-import {
- Arrow,
- Caption,
- DiagramFrame,
- MotionStyles,
- NodeBox,
- SKETCH_FILTER,
-} from "./_primitives";
-
-const VIEW_W = 760;
-const VIEW_H = 380;
-const CENTER_X = 510;
-const CENTER_Y = 200;
-const ORBIT_R = 120;
-
-type LoopNode = {
- id: string;
- label: string;
- hint?: string;
- cx: number;
- cy: number;
- shape: "rect" | "diamond" | "pill";
- variant?: "primary";
-};
-
-const LOOP_NODES: LoopNode[] = [
- {
- id: "tick",
- label: "loop tick",
- cx: CENTER_X,
- cy: CENTER_Y - ORBIT_R,
- shape: "pill",
- },
- {
- id: "sleep",
- label: "sleep",
- hint: "50ms",
- cx: CENTER_X + ORBIT_R,
- cy: CENTER_Y,
- shape: "rect",
- },
- {
- id: "dispatch",
- label: "try_dispatch()",
- cx: CENTER_X,
- cy: CENTER_Y + ORBIT_R,
- shape: "rect",
- variant: "primary",
- },
- {
- id: "periodic",
- label: "iteration % N",
- cx: CENTER_X - ORBIT_R,
- cy: CENTER_Y,
- shape: "diamond",
- },
-];
-
-type Branch = {
- id: string;
- label: string;
- every: string;
- cx: number;
- cy: number;
- /** Where the arrow exits the diamond. */
- startX: number;
- startY: number;
- pulseClass: string;
-};
-
-// Diamond geometry: center at (CENTER_X - ORBIT_R, CENTER_Y) = (390, 200).
-// halfX=64, halfY=40 → vertices: top (390,160), right (454,200), bottom
-// (390,240), left (326,200). Each branch arrow exits from a distinct point
-// on the diamond's left half so arrows are visibly anchored to the shape.
-const DIAMOND_CX = CENTER_X - ORBIT_R;
-const DIAMOND_TOP_LEFT = { x: DIAMOND_CX - 32, y: CENTER_Y - 20 };
-const DIAMOND_LEFT = { x: DIAMOND_CX - 64, y: CENTER_Y };
-const DIAMOND_BOTTOM_LEFT = { x: DIAMOND_CX - 32, y: CENTER_Y + 20 };
-
-const BRANCHES: Branch[] = [
- {
- id: "checkp",
- label: "check_periodic()",
- every: "every ~60",
- cx: 160,
- cy: 100,
- startX: DIAMOND_TOP_LEFT.x,
- startY: DIAMOND_TOP_LEFT.y,
- pulseClass: "pulse-fast",
- },
- {
- id: "reap",
- label: "reap_stale()",
- every: "every ~100",
- cx: 130,
- cy: 200,
- startX: DIAMOND_LEFT.x,
- startY: DIAMOND_LEFT.y,
- pulseClass: "pulse-mid",
- },
- {
- id: "cleanup",
- label: "auto_cleanup()",
- every: "every ~1200",
- cx: 160,
- cy: 300,
- startX: DIAMOND_BOTTOM_LEFT.x,
- startY: DIAMOND_BOTTOM_LEFT.y,
- pulseClass: "pulse-slow",
- },
-];
-
-export function SchedulerPollLoop() {
- return (
-
-
-
- );
- })}
-
-
- );
-}
-
-function LoopNodeShape({ node }: { node: LoopNode }) {
- if (node.shape === "diamond") {
- const halfX = 64;
- const halfY = 40;
- return (
-
-
- {node.label}
-
-
- );
- }
-
- if (node.shape === "pill") {
- return (
-
-
- );
-}
diff --git a/docs/app/components/animated/worker-dispatch.tsx b/docs/app/components/animated/worker-dispatch.tsx
deleted file mode 100644
index ad447ae0..00000000
--- a/docs/app/components/animated/worker-dispatch.tsx
+++ /dev/null
@@ -1,336 +0,0 @@
-import type { CSSProperties } from "react";
-import {
- Arrow,
- Caption,
- Cylinder,
- DiagramFrame,
- MotionStyles,
- NodeBox,
- SKETCH_FILTER,
-} from "./_primitives";
-
-const VIEW_W = 720;
-const VIEW_H = 320;
-
-const SCHED_CX = 80;
-const SCHED_CY = 160;
-const SCHED_W = 120;
-const SCHED_H = 60;
-
-const SYNC_LANE_Y = 110;
-const ASYNC_LANE_Y = 230;
-
-const WORKER_SIZE = 36;
-const WORKER_GAP = 10;
-const POOL_LEFT = 232;
-const POOL_TOP = SYNC_LANE_Y - WORKER_SIZE - WORKER_GAP / 2;
-const POOL_W = 3 * WORKER_SIZE + 2 * WORKER_GAP;
-const POOL_RIGHT = POOL_LEFT + POOL_W;
-
-const ASYNC_LEFT = 232;
-const ASYNC_W = POOL_W;
-const ASYNC_H = 44;
-const ASYNC_RIGHT = ASYNC_LEFT + ASYNC_W;
-
-const RESULT_CX = 460;
-const RESULT_CY = SCHED_CY;
-const RESULT_W = 116;
-const RESULT_H = 60;
-const RESULT_LEFT = RESULT_CX - RESULT_W / 2;
-const RESULT_RIGHT = RESULT_CX + RESULT_W / 2;
-
-const SQLITE_CX = 620;
-const SQLITE_CY = SCHED_CY;
-const SQLITE_RX = 50;
-const SQLITE_RY = 30;
-
-type Worker = {
- id: number;
- cx: number;
- cy: number;
- delay: string;
- duration: string;
-};
-
-const WORKERS: Worker[] = [
- {
- id: 0,
- cx: POOL_LEFT + WORKER_SIZE / 2,
- cy: POOL_TOP + WORKER_SIZE / 2,
- delay: "0s",
- duration: "2.4s",
- },
- {
- id: 1,
- cx: POOL_LEFT + WORKER_SIZE * 1.5 + WORKER_GAP,
- cy: POOL_TOP + WORKER_SIZE / 2,
- delay: "-0.4s",
- duration: "2.8s",
- },
- {
- id: 2,
- cx: POOL_LEFT + WORKER_SIZE * 2.5 + WORKER_GAP * 2,
- cy: POOL_TOP + WORKER_SIZE / 2,
- delay: "-1.1s",
- duration: "2.6s",
- },
- {
- id: 3,
- cx: POOL_LEFT + WORKER_SIZE / 2,
- cy: POOL_TOP + WORKER_SIZE * 1.5 + WORKER_GAP,
- delay: "-0.7s",
- duration: "3.1s",
- },
- {
- id: 4,
- cx: POOL_LEFT + WORKER_SIZE * 1.5 + WORKER_GAP,
- cy: POOL_TOP + WORKER_SIZE * 1.5 + WORKER_GAP,
- delay: "-1.6s",
- duration: "2.5s",
- },
- {
- id: 5,
- cx: POOL_LEFT + WORKER_SIZE * 2.5 + WORKER_GAP * 2,
- cy: POOL_TOP + WORKER_SIZE * 1.5 + WORKER_GAP,
- delay: "-0.2s",
- duration: "2.9s",
- },
-];
-
-const SYNC_DOTS = ["0s", "-0.6s", "-1.2s", "-1.8s"];
-const ASYNC_DOTS = ["-0.3s", "-1.5s"];
-const RESULT_DOTS = ["-0.2s", "-1.0s", "-1.7s"];
-
-export function WorkerDispatch() {
- return (
-
-
- );
-}
-
-function WorkerCell({ worker }: { worker: Worker }) {
- const half = WORKER_SIZE / 2;
- return (
-
-
- );
-}
diff --git a/docs/app/components/animated/worker-pool.tsx b/docs/app/components/animated/worker-pool.tsx
deleted file mode 100644
index ab3d7c62..00000000
--- a/docs/app/components/animated/worker-pool.tsx
+++ /dev/null
@@ -1,312 +0,0 @@
-const WORKERS = [
- { id: 0, x: 0, y: 0, delay: "0s", duration: "2.4s" },
- { id: 1, x: 1, y: 0, delay: "-0.4s", duration: "2.8s" },
- { id: 2, x: 2, y: 0, delay: "-1.1s", duration: "2.6s" },
- { id: 3, x: 0, y: 1, delay: "-0.7s", duration: "3.1s" },
- { id: 4, x: 1, y: 1, delay: "-1.6s", duration: "2.5s" },
- { id: 5, x: 2, y: 1, delay: "-0.2s", duration: "2.9s" },
-] as const;
-
-const INCOMING_JOBS = [
- { delay: "0s" },
- { delay: "-0.6s" },
- { delay: "-1.2s" },
- { delay: "-1.8s" },
-] as const;
-
-const RESULTS = [
- { delay: "-0.3s" },
- { delay: "-0.9s" },
- { delay: "-1.5s" },
-] as const;
-
-const VIEW_W = 580;
-const VIEW_H = 170;
-const POOL_LEFT = 210;
-const POOL_TOP = 50;
-const WORKER_SIZE = 38;
-const WORKER_GAP = 12;
-const POOL_WIDTH = 3 * WORKER_SIZE + 2 * WORKER_GAP;
-const POOL_HEIGHT = 2 * WORKER_SIZE + 1 * WORKER_GAP;
-const POOL_RIGHT = POOL_LEFT + POOL_WIDTH;
-const TRACK_Y = POOL_TOP + POOL_HEIGHT / 2;
-const INCOMING_LEFT = 30;
-const RESULT_LEFT = POOL_RIGHT + 30;
-const RESULT_END = VIEW_W - 30;
-
-export function WorkerPool() {
- return (
-
-
-
- six workers, constant flow
-
-
- Jobs stream in, workers pick them up, results stream out. No broker
- between them.
-
-
-
-
-
-
- );
-}
-
-function LaneLabels() {
- const labels = [
- { x: INCOMING_LEFT, text: "incoming" },
- { x: POOL_LEFT, text: "workers" },
- { x: RESULT_LEFT, text: "results" },
- ];
- return (
- <>
- {labels.map((label) => (
-
- {label.text}
-
- ))}
-
- );
-}
-
-function Lanes() {
- return (
- <>
-
-
- );
-}
-
-function PoolStyles() {
- return (
-
- );
-}
diff --git a/docs/app/components/diagram-carousel.tsx b/docs/app/components/diagram-carousel.tsx
deleted file mode 100644
index 97746311..00000000
--- a/docs/app/components/diagram-carousel.tsx
+++ /dev/null
@@ -1,147 +0,0 @@
-import { ChevronLeft, ChevronRight } from "lucide-react";
-import {
- Children,
- isValidElement,
- type ReactElement,
- type ReactNode,
- useCallback,
- useEffect,
- useRef,
- useState,
-} from "react";
-import { cn } from "@/lib/cn";
-
-type DiagramSlideProps = {
- title?: string;
- children: ReactNode;
-};
-
-export function DiagramSlide({ children }: DiagramSlideProps) {
- return <>{children};
-}
-
-type SlideElement = ReactElement;
-
-export function DiagramCarousel({
- children,
- title,
-}: {
- children: ReactNode;
- title?: string;
-}) {
- const slides = Children.toArray(children).filter(
- (child): child is SlideElement => isValidElement(child),
- );
- const total = slides.length;
- const containerRef = useRef(null);
- const [index, setIndex] = useState(0);
-
- const prev = useCallback(
- () => setIndex((i) => (i - 1 + total) % total),
- [total],
- );
- const next = useCallback(() => setIndex((i) => (i + 1) % total), [total]);
-
- useEffect(() => {
- const node = containerRef.current;
- if (!node) return;
- function onKey(e: KeyboardEvent) {
- if (e.key === "ArrowLeft") {
- e.preventDefault();
- prev();
- } else if (e.key === "ArrowRight") {
- e.preventDefault();
- next();
- }
- }
- node.addEventListener("keydown", onKey);
- return () => node.removeEventListener("keydown", onKey);
- }, [prev, next]);
-
- if (total === 0) return null;
-
- const activeTitle = slides[index]?.props.title;
-
- return (
- }
- className="taskito-carousel my-6 rounded-lg border border-fd-border bg-fd-card overflow-hidden focus:outline-none focus:ring-2 focus:ring-fd-primary/40"
- // biome-ignore lint/a11y/noNoninteractiveTabindex: container hosts arrow-key navigation per WAI-ARIA carousel pattern
- tabIndex={0}
- aria-roledescription="carousel"
- aria-label={title ?? "Diagram carousel"}
- >
-
-
- {title && (
-
- {title}
-
- )}
- {activeTitle && (
-
- {title ? "·" : ""} {activeTitle}
-
- )}
-
-
-
- {index + 1} / {total}
-
-
-
-
-
-
-
-
- {slides.map((slide, i) => (
-
- {slide}
-
- ))}
-
-
- {slides.map((slide, i) => {
- const slideTitle = slide.props.title;
- return (
-
-
- );
-}
diff --git a/docs/app/components/diagrams/arch-stack.tsx b/docs/app/components/diagrams/arch-stack.tsx
index bda65a60..8030b5f9 100644
--- a/docs/app/components/diagrams/arch-stack.tsx
+++ b/docs/app/components/diagrams/arch-stack.tsx
@@ -1,15 +1,21 @@
-import type { ReactNode } from "react";
+import { type CSSProperties, Fragment, type ReactNode } from "react";
-// Layered architecture stack — ports the prototype's `.archstack` HTML (clean
-// semantic layers + PyO3/store boundaries), replacing the old sketch SVG.
+// 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;
- tagKind?: "py" | "rust" | "store";
+ /** 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;
- accent?: boolean;
}
function ArchStack({
@@ -25,8 +31,11 @@ function ArchStack({
{legend ? {legend} : null}
{layers.map((l, i) => (
-
-
+
+
{l.tag}
{l.title}
@@ -35,7 +44,7 @@ function ArchStack({
{l.role ? {l.role} : null}
{i < bounds.length ? {bounds[i]} : null}
-
+
))}
);
@@ -133,17 +142,22 @@ export function ResourcePipeline() {
},
{
tag: "Layer 3",
- tagKind: "rust",
- title: "Transparent proxy",
+ tagKind: "py",
+ layerKind: "rust",
+ style: {
+ borderColor: "var(--indigo-line)",
+ background:
+ "linear-gradient(100deg,var(--indigo-soft),var(--panel))",
+ },
+ title: "Resource proxies",
body: (
<>
- Non-serializable handles (files, clients, sessions) are
- deconstructed on enqueue and reconstructed on the worker via
- registered ProxyHandlers — HMAC-signed,
- schema-validated, LIFO-cleaned.
+ ProxyHandlers 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.
),
- accent: true,
},
]}
bounds={["enqueue → worker", "before task()"]}
diff --git a/docs/app/components/diagrams/index.ts b/docs/app/components/diagrams/index.ts
index 33324ed0..fe3e30e9 100644
--- a/docs/app/components/diagrams/index.ts
+++ b/docs/app/components/diagrams/index.ts
@@ -1,18 +1,12 @@
-// Single barrel for every diagram component used in MDX. The architecture
-// diagrams below are prototype-faithful ports (arch.js + arch-*.html); the
-// remaining ones are re-exported from their existing homes so MDX imports one place.
+// Single barrel for every diagram component used in MDX. All architecture
+// diagrams below are prototype-faithful ports (arch.js + arch-*.html).
-// Still rendered by the existing implementations (no prototype counterpart).
-export {
- DispatchSequence,
- EntityRelations,
- EntitySchema,
-} from "@/components/animated";
-export { DiagramCarousel, DiagramSlide } from "@/components/diagram-carousel";
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";
diff --git a/docs/app/components/diagrams/schema-grid.tsx b/docs/app/components/diagrams/schema-grid.tsx
new file mode 100644
index 00000000..ba818d95
--- /dev/null
+++ b/docs/app/components/diagrams/schema-grid.tsx
@@ -0,0 +1,97 @@
+// Database schema — exact port of the prototype's `.schema-grid` (six SQLite
+// tables as `.entity` cards with PK/FK badges). `architecture/storage.mdx`.
+
+type Field = { name: string; key?: "PK" | "FK"; type: string };
+type Entity = { name: string; fields: Field[] };
+
+const ENTITIES: Entity[] = [
+ {
+ name: "jobs",
+ fields: [
+ { name: "id", key: "PK", type: "TEXT" },
+ { name: "queue", type: "TEXT" },
+ { name: "task_name", type: "TEXT" },
+ { name: "payload", type: "BLOB" },
+ { name: "status", type: "INTEGER" },
+ { name: "priority", type: "INTEGER" },
+ { name: "scheduled_at", type: "INTEGER" },
+ { name: "retry_count", type: "INTEGER" },
+ { name: "result", type: "BLOB" },
+ { name: "timeout_ms", type: "INTEGER" },
+ { name: "unique_key", type: "TEXT" },
+ ],
+ },
+ {
+ name: "dead_letter",
+ fields: [
+ { name: "id", key: "PK", type: "TEXT" },
+ { name: "original_job_id", type: "TEXT" },
+ { name: "task_name", type: "TEXT" },
+ { name: "payload", type: "BLOB" },
+ { name: "error", type: "TEXT" },
+ { name: "retry_count", type: "INTEGER" },
+ { name: "failed_at", type: "INTEGER" },
+ ],
+ },
+ {
+ name: "job_errors",
+ fields: [
+ { name: "id", key: "PK", type: "TEXT" },
+ { name: "job_id", key: "FK", type: "TEXT" },
+ { name: "attempt", type: "INTEGER" },
+ { name: "error", type: "TEXT" },
+ { name: "failed_at", type: "INTEGER" },
+ ],
+ },
+ {
+ name: "rate_limits",
+ fields: [
+ { name: "key", key: "PK", type: "TEXT" },
+ { name: "tokens", type: "REAL" },
+ { name: "max_tokens", type: "REAL" },
+ { name: "refill_rate", type: "REAL" },
+ { name: "last_refill", type: "INTEGER" },
+ ],
+ },
+ {
+ name: "periodic_tasks",
+ fields: [
+ { name: "name", key: "PK", type: "TEXT" },
+ { name: "task_name", type: "TEXT" },
+ { name: "cron_expr", type: "TEXT" },
+ { name: "args", type: "BLOB" },
+ { name: "queue", type: "TEXT" },
+ { name: "enabled", type: "BOOLEAN" },
+ { name: "next_run", type: "INTEGER" },
+ ],
+ },
+ {
+ name: "workers",
+ fields: [
+ { name: "worker_id", key: "PK", type: "TEXT" },
+ { name: "last_heartbeat", type: "INTEGER" },
+ { name: "queues", type: "TEXT" },
+ { name: "status", type: "TEXT" },
+ ],
+ },
+];
+
+export function SchemaGrid() {
+ return (
+
+ {ENTITIES.map((e) => (
+
+ {e.name}
+ {e.fields.map((f) => (
+
+ {f.name}
+ {f.key === "PK" ? PK : null}
+ {f.key === "FK" ? FK : null}
+ {f.type}
+
+ ))}
+
+ ))}
+
+ );
+}
diff --git a/docs/app/components/diagrams/seq.tsx b/docs/app/components/diagrams/seq.tsx
new file mode 100644
index 00000000..601c7b3e
--- /dev/null
+++ b/docs/app/components/diagrams/seq.tsx
@@ -0,0 +1,45 @@
+// Sequence strip — exact port of the prototype's `.seq` (paired actor heads +
+// directional message rows). Used on `architecture/mesh.mdx` for the local
+// deque and the work-stealing protocol.
+
+type SeqRow =
+ | { self: string }
+ | { left?: string; right?: string; rev?: boolean };
+
+export function Seq({ heads, rows }: { heads: string[]; rows: SeqRow[] }) {
+ return (
+
+
+ {heads.map((h) => (
+
+ {h}
+
+ ))}
+
+
+ {rows.map((row, i) =>
+ "self" in row ? (
+ // biome-ignore lint/suspicious/noArrayIndexKey: fixed sequence rows
+
+ {row.self}
+
+ ) : (
+
+ {row.left != null ? (
+ {row.left}
+ ) : null}
+
+ {row.right != null ? (
+ {row.right}
+ ) : null}
+
+ ),
+ )}
+
+
+ );
+}
diff --git a/docs/app/components/diagrams/worker-fork.tsx b/docs/app/components/diagrams/worker-fork.tsx
index 6b832af4..1820d8f0 100644
--- a/docs/app/components/diagrams/worker-fork.tsx
+++ b/docs/app/components/diagrams/worker-fork.tsx
@@ -1,26 +1,25 @@
-// Worker pool — ports the prototype's `.archstack` + `.archfork` (sync OS-thread
-// pool vs async pool, converging at the result channel). `architecture/worker-pool.mdx`.
+// Worker pool — exact port of the prototype's `.archstack` + `.fork-route` +
+// `.archfork` (scheduler routes by task type; sync OS-thread pool vs async pool).
+// `architecture/worker-pool.mdx`.
export function WorkerDispatch() {
return (
-
- Scheduler
+
+ Rust
- Dispatch
+ Scheduler
- The Rust scheduler claims a job and routes it by task kind — sync
- tasks to the thread pool, async def tasks to the native
- async pool.
+ Dequeues a job, applies rate limits, then routes it{" "}
+ by task type — sync functions to the thread pool,{" "}
+ async def functions to the async runtime.
+ routes by task type
-
- ↓route by task kind
- ↓
-
+ sync def · async def
- bounded mpsc · workers × N
+ bounded mpsc · workers × 2
Sync pool
@@ -40,29 +39,14 @@ export function WorkerDispatch() {
NativeAsyncPool
- async def tasks run on a dedicated event loop with
- bounded concurrency — no thread per task, no GIL contention for
- I/O-bound work.
+ async def tasks are dispatched to an{" "}
+ AsyncTaskExecutor on a Python daemon thread;{" "}
+ PyResultSender bridges results back.
-
- ↓result channel
- ↓
-
-
- Store
-
- Result handler → SQLite
-
- Both pools hand results to a single result channel; the handler
- commits them (and decides retry / dead-letter) before the outcome
- surfaces.
-
-
-
);
}
diff --git a/docs/content/docs/architecture/mesh.mdx b/docs/content/docs/architecture/mesh.mdx
index 542e06e8..9a131517 100644
--- a/docs/content/docs/architecture/mesh.mdx
+++ b/docs/content/docs/architecture/mesh.mdx
@@ -12,22 +12,25 @@ network that reduces DB contention and enables sub-millisecond load awareness.
For usage and configuration, see the
[Mesh Scheduling guide](/guides/operations/mesh).
- mesh --> durability
- `}
-/>
+
+ - Picks a random alive peer and sends a Ping (with sequence number).
+ - If no Ack within
protocol_period / 2 → sends PingReq to indirect_ping_count (3) random intermediaries to probe the target on its behalf.
+ - If still no response → marks the target as Suspect.
+ - After
suspicion_multiplier × ln(N+1) × protocol_period → declares Dead and removes from the hash ring.
+
### Message types
@@ -145,15 +147,12 @@ The ring recalculates on every membership change (join, leave, death). The
Each worker maintains a `Mutex>` as a local job buffer with
a configurable capacity (`local_buffer_capacity`, default 64):
- j1
- j5 -.-> pop["pop() LIFO"]
- `}
+>V: TCP connect (500ms timeout)
- T->>V: StealRequest{id, max_count}
- V->>V: rate-limit check
- V->>V: deque.steal(max)
- V->>T: StealResponse{jobs}
- T->>V: close
- `}
+|job_tx| MB[mesh_bridge]
- MB -->|dispatch_tx| D[Dispatcher]
- MB --- DQ[Local deque]
- MB --- SC[Steal client
TCP to peers]
- `}
-/>
-
The `run_mesh_bridge()` function:
-1. `recv` from `job_rx` (scheduler channel) — push into local deque
-2. `pop` from local deque — send to `dispatch_tx` (dispatcher channel)
-3. On idle (no jobs from scheduler, deque low) → `try_steal()` from
- busiest peer
-4. Loop until shutdown
+
+ recv from job_rx (scheduler channel) — push into the local deque.pop from the local deque — send to dispatch_tx (dispatcher channel).- On idle (no jobs from scheduler, deque low) →
try_steal() from the busiest peer.
+ - Loop until shutdown.
+
This keeps the scheduler and dispatcher completely unaware of mesh logic.
Without the `mesh` feature flag, the scheduler sends directly to the
diff --git a/docs/content/docs/architecture/scheduler.mdx b/docs/content/docs/architecture/scheduler.mdx
index 6cde5c85..19167906 100644
--- a/docs/content/docs/architecture/scheduler.mdx
+++ b/docs/content/docs/architecture/scheduler.mdx
@@ -32,17 +32,20 @@ loop {
## Polling cycle
+The loop wakes every 50 ms. `try_dispatch()` runs on every tick; the three
+maintenance tasks fire on coprime intervals so they rarely collide on the same wake.
+
+ dequeue_from() — atomically SELECT + UPDATE (pending → running) within a transaction.- Check rate limit — if over limit, reschedule 1s in the future.
+ - Send job to worker pool via
tokio::sync::mpsc channel.
+ - Worker executes task, sends result back.
+ handle_result() — mark complete, schedule retry, or move to DLQ.
With [mesh scheduling](/architecture/mesh) enabled, a mesh bridge sits
diff --git a/docs/content/docs/architecture/storage.mdx b/docs/content/docs/architecture/storage.mdx
index a577487a..e242c734 100644
--- a/docs/content/docs/architecture/storage.mdx
+++ b/docs/content/docs/architecture/storage.mdx
@@ -14,133 +14,15 @@ description: "SQLite pragmas, schema, indexes, connection pooling, and Postgres
## Database schema
-Six tables in the SQLite backend. Use the arrows or click a dot to flip between tables; the last slide shows their relationships.
+Six tables back the SQLite store — jobs and their error history, the dead letter
+queue, rate limits, periodic tasks, and worker heartbeats.
-
-
-
+
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+ **Relationships:** `jobs` → `job_errors` (1 ─ \*, error history) and `jobs` →
+ `dead_letter` (1 ─ 0..1, DLQ on retry exhaustion).
+
## Key indexes
From aee414cfd4b793fb92e2428ff46c2ad2ff9d1e60 Mon Sep 17 00:00:00 2001
From: Pratyush Sharma <56130065+pratyush618@users.noreply.github.com>
Date: Sun, 21 Jun 2026 11:19:16 +0530
Subject: [PATCH 21/48] fix(docs): rebuild on-this-page TOC when lazy content
mounts
---
docs/app/components/docs/toc.tsx | 90 ++++++++++++++++++--------------
1 file changed, 52 insertions(+), 38 deletions(-)
diff --git a/docs/app/components/docs/toc.tsx b/docs/app/components/docs/toc.tsx
index a6e91ffb..5c9f0f77 100644
--- a/docs/app/components/docs/toc.tsx
+++ b/docs/app/components/docs/toc.tsx
@@ -7,56 +7,70 @@ interface Heading {
level: number;
}
+function readHeadings(article: Element): Heading[] {
+ return [...article.querySelectorAll("h2[id], h3[id]")].map(
+ (el) => ({
+ id: el.id,
+ text: el.textContent ?? "",
+ level: el.tagName === "H3" ? 3 : 2,
+ }),
+ );
+}
+
/** On-this-page TOC, built from the rendered article headings with scroll-spy. */
export function Toc() {
const { pathname } = useLocation();
const [headings, setHeadings] = useState([]);
const [active, setActive] = useState("");
- // Rebuild from the DOM after each page renders (headings carry ids from rehype-slug).
- useEffect(() => {
- const nodes = document.querySelectorAll(
- ".article h2[id], .article h3[id]",
- );
- setHeadings(
- [...nodes].map((el) => ({
- id: el.id,
- text: el.textContent ?? "",
- level: el.tagName === "H3" ? 3 : 2,
- })),
- );
- }, []);
-
+ // The article is a lazily-loaded MDX chunk, so its headings are NOT in the DOM
+ // when this effect first runs after a client-side navigation. Re-scan on every
+ // article mutation (via MutationObserver) so the TOC fills in once the page
+ // content actually mounts, and re-arm scroll-spy whenever the heading set changes.
// biome-ignore lint/correctness/useExhaustiveDependencies: re-scan when the path changes
useEffect(() => {
- const nodes = document.querySelectorAll(
- ".article h2[id], .article h3[id]",
- );
- if (!nodes.length) {
+ const article = document.querySelector(".article");
+ if (!article) {
setHeadings([]);
return;
}
- setHeadings(
- [...nodes].map((el) => ({
- id: el.id,
- text: el.textContent ?? "",
- level: el.tagName === "H3" ? 3 : 2,
- })),
- );
- const observer = new IntersectionObserver(
- (entries) => {
- for (const entry of entries) {
- if (entry.isIntersecting) {
- setActive(entry.target.id);
+ let spy: IntersectionObserver | null = null;
+ let lastKey = "";
+
+ const scan = () => {
+ const next = readHeadings(article);
+ const key = next.map((h) => h.id).join("|");
+ if (key === lastKey) {
+ return;
+ }
+ lastKey = key;
+ setHeadings(next);
+ spy?.disconnect();
+ if (!next.length) {
+ return;
+ }
+ spy = new IntersectionObserver(
+ (entries) => {
+ for (const entry of entries) {
+ if (entry.isIntersecting) {
+ setActive(entry.target.id);
+ }
}
- }
- },
- { rootMargin: "-80px 0px -70% 0px" },
- );
- for (const node of nodes) {
- observer.observe(node);
- }
- return () => observer.disconnect();
+ },
+ { rootMargin: "-80px 0px -70% 0px" },
+ );
+ for (const el of article.querySelectorAll("h2[id], h3[id]")) {
+ spy.observe(el);
+ }
+ };
+
+ scan();
+ const content = new MutationObserver(scan);
+ content.observe(article, { childList: true, subtree: true });
+ return () => {
+ content.disconnect();
+ spy?.disconnect();
+ };
}, [pathname]);
if (headings.length === 0) {
From c16435f70fd0b1ca97bd8f7c029b09110c7707a9 Mon Sep 17 00:00:00 2001
From: Pratyush Sharma <56130065+pratyush618@users.noreply.github.com>
Date: Sun, 21 Jun 2026 11:19:16 +0530
Subject: [PATCH 22/48] feat(docs): grouped command palette with browse-on-open
---
docs/app/components/docs/search-modal.tsx | 177 ++++++++++++++++++----
docs/app/lib/search.ts | 42 ++++-
2 files changed, 185 insertions(+), 34 deletions(-)
diff --git a/docs/app/components/docs/search-modal.tsx b/docs/app/components/docs/search-modal.tsx
index 910cc594..54086b4a 100644
--- a/docs/app/components/docs/search-modal.tsx
+++ b/docs/app/components/docs/search-modal.tsx
@@ -1,8 +1,69 @@
-import { useEffect, useMemo, useState } from "react";
+import { Fragment, useEffect, useMemo, useRef, useState } from "react";
import { useNavigate } from "react-router";
-import { searchDocs } from "@/lib/search";
+import { type SearchHit, searchDocs } from "@/lib/search";
-/** ⌘K command palette: client-side search over the build-time MDX index. */
+// Section glyphs mirror the prototype's command-palette icons.
+const SECTION_ICON: { match: string; path: string }[] = [
+ { match: "getting", path: "M13 2L3 14h7l-1 8 10-12h-7l1-8z" },
+ {
+ match: "guide",
+ path: "M4 19.5A2.5 2.5 0 0 1 6.5 17H20M4 19.5A2.5 2.5 0 0 0 6.5 22H20V2H6.5A2.5 2.5 0 0 0 4 4.5v15z",
+ },
+ {
+ match: "architecture",
+ path: "M12 2L2 7l10 5 10-5-10-5zM2 17l10 5 10-5M2 12l10 5 10-5",
+ },
+ { match: "api", path: "M16 18l6-6-6-6M8 6l-6 6 6 6" },
+ { match: "node", path: "M12 2l8.5 5v10L12 22 3.5 17V7z" },
+ { match: "reference", path: "M16 18l6-6-6-6M8 6l-6 6 6 6" },
+];
+
+function sectionIconPath(section: string): string {
+ const key = section.toLowerCase();
+ return (
+ SECTION_ICON.find((s) => key.includes(s.match))?.path ??
+ "M12 2a10 10 0 1 0 0 20 10 10 0 0 0 0-20z"
+ );
+}
+
+function SectionIcon({ section }: { section: string }) {
+ return (
+
+ );
+}
+
+interface Group {
+ section: string;
+ items: SearchHit[];
+}
+
+/** Group ranked hits by section, preserving first-appearance order. */
+function groupBySection(hits: SearchHit[]): Group[] {
+ const groups: Group[] = [];
+ const byName = new Map();
+ for (const hit of hits) {
+ let group = byName.get(hit.section);
+ if (!group) {
+ group = { section: hit.section, items: [] };
+ byName.set(hit.section, group);
+ groups.push(group);
+ }
+ group.items.push(hit);
+ }
+ return groups;
+}
+
+/** ⌘K command palette: browse-by-section on open, ranked search as you type. */
export function SearchModal({
open,
onClose,
@@ -13,7 +74,10 @@ export function SearchModal({
const navigate = useNavigate();
const [query, setQuery] = useState("");
const [active, setActive] = useState(0);
- const results = useMemo(() => searchDocs(query), [query]);
+ const listRef = useRef(null);
+
+ const groups = useMemo(() => groupBySection(searchDocs(query)), [query]);
+ const flat = useMemo(() => groups.flatMap((g) => g.items), [groups]);
// biome-ignore lint/correctness/useExhaustiveDependencies: reset selection as results change
useEffect(() => {
@@ -26,6 +90,13 @@ export function SearchModal({
}
}, [open]);
+ // Keep the active row in view during keyboard navigation.
+ useEffect(() => {
+ listRef.current
+ ?.querySelector(`[data-idx="${active}"]`)
+ ?.scrollIntoView({ block: "nearest" });
+ }, [active]);
+
if (!open) {
return null;
}
@@ -40,15 +111,16 @@ export function SearchModal({
onClose();
} else if (e.key === "ArrowDown") {
e.preventDefault();
- setActive((i) => Math.min(i + 1, results.length - 1));
+ setActive((i) => Math.min(i + 1, flat.length - 1));
} else if (e.key === "ArrowUp") {
e.preventDefault();
setActive((i) => Math.max(i - 1, 0));
- } else if (e.key === "Enter" && results[active]) {
- go(results[active].id);
+ } else if (e.key === "Enter" && flat[active]) {
+ go(flat[active].id);
}
};
+ let idx = -1;
return (
{/* biome-ignore lint/a11y/noStaticElementInteractions: key handling for the palette */}
- setQuery(e.target.value)}
- />
-
- {results.length === 0 && query ? (
+
+
+ setQuery(e.target.value)}
+ />
+
+
+
+ {flat.length === 0 ? (
No results for “{query}”.
) : (
- results.map((hit, i) => (
-
+ groups.map((group) => (
+
+ {group.section}
+ {group.items.map((hit) => {
+ idx += 1;
+ const i = idx;
+ return (
+
+ );
+ })}
+
))
)}
- ↑↓ navigate ↵ open esc close
+
+ ↑
+ ↓ navigate
+
+
+ ↵ open
+
+
+ esc close
+
diff --git a/docs/app/lib/search.ts b/docs/app/lib/search.ts
index eea15f7c..80e205bc 100644
--- a/docs/app/lib/search.ts
+++ b/docs/app/lib/search.ts
@@ -5,6 +5,7 @@ export interface SearchDoc {
id: string; // slug
title: string;
section: string;
+ description: string;
text: string;
}
@@ -25,6 +26,7 @@ export const SEARCH_DOCS: SearchDoc[] = DOC_METAS.map((d) => ({
id: d.slug,
title: d.title,
section: sectionOf(d.slug),
+ description: d.description,
text: `${d.description} ${humanizeSlug(d.slug)}`.trim(),
}));
@@ -34,7 +36,7 @@ function getIndex(): MiniSearch {
if (!index) {
index = new MiniSearch({
fields: ["title", "text", "section"],
- storeFields: ["title", "section"],
+ storeFields: ["title", "section", "description"],
searchOptions: {
boost: { title: 3, section: 1.5 },
prefix: true,
@@ -50,15 +52,47 @@ export interface SearchHit {
id: string;
title: string;
section: string;
+ description: string;
}
+function toHit(d: SearchDoc): SearchHit {
+ return {
+ id: d.id,
+ title: d.title,
+ section: d.section,
+ description: d.description,
+ };
+}
+
+// Browse-mode section order (mirrors the sidebar); unknown sections sort last.
+const SECTION_ORDER = [
+ "Getting Started",
+ "Guides",
+ "Architecture",
+ "Api Reference",
+ "More",
+ "Node",
+];
+const sectionRank = (s: string) => {
+ const i = SECTION_ORDER.indexOf(s);
+ return i === -1 ? SECTION_ORDER.length : i;
+};
+
+/** Empty query → the full index (browse mode); otherwise ranked matches. */
export function searchDocs(query: string): SearchHit[] {
const q = query.trim();
if (!q) {
- return [];
+ return SEARCH_DOCS.map(toHit).sort(
+ (a, b) => sectionRank(a.section) - sectionRank(b.section),
+ );
}
return getIndex()
.search(q)
- .slice(0, 12)
- .map((r) => ({ id: r.id as string, title: r.title, section: r.section }));
+ .slice(0, 20)
+ .map((r) => ({
+ id: r.id as string,
+ title: r.title,
+ section: r.section,
+ description: r.description,
+ }));
}
From 9a124ba8c2e544357c4b4124f36e041e83b75e45 Mon Sep 17 00:00:00 2001
From: Pratyush Sharma <56130065+pratyush618@users.noreply.github.com>
Date: Sun, 21 Jun 2026 11:19:16 +0530
Subject: [PATCH 23/48] feat(docs): collapsible sidebar nav groups
---
docs/app/components/docs/sidebar.tsx | 118 +++++++++++++++++++++++----
docs/app/styles/docs.css | 40 +++++++++
2 files changed, 142 insertions(+), 16 deletions(-)
diff --git a/docs/app/components/docs/sidebar.tsx b/docs/app/components/docs/sidebar.tsx
index 186392c0..da6f8298 100644
--- a/docs/app/components/docs/sidebar.tsx
+++ b/docs/app/components/docs/sidebar.tsx
@@ -1,6 +1,14 @@
+import { useEffect, useState } from "react";
import { Link, useLocation } from "react-router";
import { type NavNode, navForSdk, type Sdk, sdkForPath } from "@/lib/nav";
+function containsHref(node: NavNode, current: string): boolean {
+ return (
+ node.href === current ||
+ (node.children?.some((c) => containsHref(c, current)) ?? false)
+ );
+}
+
function SdkSwitch({ sdk }: { sdk: Sdk }) {
return (
@@ -24,6 +32,39 @@ function SdkSwitch({ sdk }: { sdk: Sdk }) {
);
}
+function Caret({
+ open,
+ onToggle,
+ title,
+}: {
+ open: boolean;
+ onToggle: () => void;
+ title: string;
+}) {
+ return (
+
+ );
+}
+
function NavLink({ node, current }: { node: NavNode; current: string }) {
if (!node.href) {
return {node.title};
@@ -38,15 +79,36 @@ function NavLink({ node, current }: { node: NavNode; current: string }) {
);
}
+/** A subsection with children — collapsible, auto-opens around the active page. */
+function NavSection({ node, current }: { node: NavNode; current: string }) {
+ const active = node.children?.some((c) => containsHref(c, current)) ?? false;
+ const [open, setOpen] = useState(active);
+ useEffect(() => {
+ if (active) {
+ setOpen(true);
+ }
+ }, [active]);
+ return (
+
+
+ setOpen((o) => !o)}
+ title={node.title}
+ />
+
+ {open ? {
+ if (active) {
+ setOpen(true);
+ }
+ }, [active]);
+ const hasChildren = Boolean(group.children?.length);
+ return (
+
+
+ {group.href ? (
+
+ {group.title}
+
+ ) : (
+ {group.title}
+ )}
+ {hasChildren ? (
+ setOpen((o) => !o)}
+ title={group.title}
+ />
+ ) : null}
+
+ {hasChildren && open ? (
+ ` in the prototype's `.md-table` shell so
+ * tables across the docs get the rounded surface, header band, and row rules
+ * from `docs.css`. Mapped onto the `table` element in `mdxComponents`, so it
+ * applies everywhere without touching individual pages.
+ */
+export function MdxTable(props: ComponentProps<"table">) {
+ return (
+
+
+
+ );
+}
From 3aeed5d5014c4b41363fb1a5c4dcc5a48cb40281 Mon Sep 17 00:00:00 2001
From: Pratyush Sharma <56130065+pratyush618@users.noreply.github.com>
Date: Sun, 21 Jun 2026 11:19:16 +0530
Subject: [PATCH 25/48] feat(docs): make landing hero Python-focused
---
docs/app/components/landing/hero.tsx | 20 +++++++---------
docs/app/lib/landing-content.ts | 34 +---------------------------
2 files changed, 9 insertions(+), 45 deletions(-)
diff --git a/docs/app/components/landing/hero.tsx b/docs/app/components/landing/hero.tsx
index 687acdfc..043b6460 100644
--- a/docs/app/components/landing/hero.tsx
+++ b/docs/app/components/landing/hero.tsx
@@ -1,10 +1,10 @@
import { useState } from "react";
import { Link } from "react-router";
import { RawHtml } from "@/components/ui";
-import { highlightPython, highlightTs } from "@/lib/highlight-lite";
+import { highlightPython } from "@/lib/highlight-lite";
import { HERO_PANES, SOON_PANES, type SoonLang } from "@/lib/landing-content";
-type Lang = "py" | "ts" | "go" | "java";
+type Lang = "py" | "go" | "java";
function CopyButton({ text }: { text: string }) {
const [copied, setCopied] = useState(false);
@@ -37,23 +37,19 @@ function SoonBox({ pane }: { pane: SoonLang }) {
export function Hero() {
const [lang, setLang] = useState("py");
const pane = HERO_PANES.find((p) => p.id === lang);
- const codeHtml = pane
- ? lang === "py"
- ? highlightPython(pane.code)
- : highlightTs(pane.code)
- : "";
+ const codeHtml = pane ? highlightPython(pane.code) : "";
const active = pane ?? HERO_PANES[0];
return (
- One queue.Python and Node.
+ One queue.Built for Python.
- A Rust-powered task queue with first-class Python and{" "}
- Node.js SDKs over one core and one store — no broker. Start on{" "}
- SQLite, scale to Postgres.
+ A Rust-powered task queue with a first-class Python SDK over
+ one core and one store — no broker. Start on SQLite,
+ scale to Postgres.
@@ -69,7 +65,7 @@ export function Hero() {
Brokerless
Rust core
- Python & Node
+ Python SDK
DAG workflows
diff --git a/docs/app/lib/landing-content.ts b/docs/app/lib/landing-content.ts
index 3c693ed2..8ddfd96f 100644
--- a/docs/app/lib/landing-content.ts
+++ b/docs/app/lib/landing-content.ts
@@ -10,7 +10,7 @@ export interface OutLine {
}
export interface LangPane {
- id: "py" | "ts";
+ id: "py";
label: string;
filename: string;
install: string;
@@ -54,38 +54,6 @@ print(job.result()) # → 5`,
docHref: "/getting-started/quickstart",
docLabel: "Read the Python quickstart",
},
- {
- id: "ts",
- label: "Node.js",
- filename: "tasks.ts",
- install: "pnpm add taskito",
- code: `// pnpm add taskito
-import { Queue } from "taskito";
-
-const queue = new Queue({ dbPath: "taskito.db" });
-
-queue.task("add", (a: number, b: number) => a + b, {
- maxRetries: 3,
-});
-
-const id = queue.enqueue("add", [2, 3]);
-queue.runWorker();
-
-console.log(await queue.result(id)); // → 5`,
- output: [
- { glyph: "$", glyphKind: "p", text: "node tasks.js" },
- { glyph: "→", glyphKind: "p", text: "runWorker() · Rust core attached" },
- {
- glyph: "✓",
- glyphKind: "g",
- text: "add(2, 3) =",
- value: "5",
- timing: "9 ms",
- },
- ],
- docHref: "/node",
- docLabel: "Read the Node.js quickstart",
- },
];
/** Roadmap languages: disabled tab + "coming soon" panel (no fabricated SDK). */
From 7badd92d98c6e2782c2fa074ffad00e0432f9fbf Mon Sep 17 00:00:00 2001
From: Pratyush Sharma <56130065+pratyush618@users.noreply.github.com>
Date: Sun, 21 Jun 2026 11:19:16 +0530
Subject: [PATCH 26/48] fix(docs): drop Node from landing page title/meta
---
docs/app/routes/home.tsx | 5 ++---
1 file changed, 2 insertions(+), 3 deletions(-)
diff --git a/docs/app/routes/home.tsx b/docs/app/routes/home.tsx
index 356744e2..5adccc1c 100644
--- a/docs/app/routes/home.tsx
+++ b/docs/app/routes/home.tsx
@@ -14,11 +14,10 @@ import type { Route } from "./+types/home";
export function meta(_: Route.MetaArgs) {
return [
- { title: "Taskito — one queue, Python and Node" },
+ { title: "Taskito — one queue, built for Python" },
{
name: "description",
- content:
- "Rust-powered task queue for Python and Node.js. No broker required.",
+ content: "Rust-powered task queue for Python. No broker required.",
},
];
}
From dce649c1faf63cca83db3fa6502c8e37a8144752 Mon Sep 17 00:00:00 2001
From: Pratyush Sharma <56130065+pratyush618@users.noreply.github.com>
Date: Sun, 21 Jun 2026 11:19:16 +0530
Subject: [PATCH 27/48] refactor(docs): restructure Node SDK nav to mirror
Python
---
docs/content/docs/node/contrib/index.mdx | 42 -----
docs/content/docs/node/contrib/meta.json | 4 -
.../docs/node/contrib/observability.mdx | 170 -----------------
.../docs/node/contrib/web-frameworks.mdx | 173 ------------------
.../{ => guides}/workflows/conditions.mdx | 0
.../node/{ => guides}/workflows/fan-out.mdx | 0
.../node/{ => guides}/workflows/gates.mdx | 0
.../node/{ => guides}/workflows/index.mdx | 0
.../node/{ => guides}/workflows/meta.json | 0
.../docs/node/{ => guides}/workflows/saga.mdx | 0
.../{ => guides}/workflows/sub-workflows.mdx | 0
docs/content/docs/node/index.mdx | 78 --------
docs/content/docs/node/meta.json | 5 -
13 files changed, 472 deletions(-)
delete mode 100644 docs/content/docs/node/contrib/index.mdx
delete mode 100644 docs/content/docs/node/contrib/meta.json
delete mode 100644 docs/content/docs/node/contrib/observability.mdx
delete mode 100644 docs/content/docs/node/contrib/web-frameworks.mdx
rename docs/content/docs/node/{ => guides}/workflows/conditions.mdx (100%)
rename docs/content/docs/node/{ => guides}/workflows/fan-out.mdx (100%)
rename docs/content/docs/node/{ => guides}/workflows/gates.mdx (100%)
rename docs/content/docs/node/{ => guides}/workflows/index.mdx (100%)
rename docs/content/docs/node/{ => guides}/workflows/meta.json (100%)
rename docs/content/docs/node/{ => guides}/workflows/saga.mdx (100%)
rename docs/content/docs/node/{ => guides}/workflows/sub-workflows.mdx (100%)
delete mode 100644 docs/content/docs/node/index.mdx
delete mode 100644 docs/content/docs/node/meta.json
diff --git a/docs/content/docs/node/contrib/index.mdx b/docs/content/docs/node/contrib/index.mdx
deleted file mode 100644
index e9924a2f..00000000
--- a/docs/content/docs/node/contrib/index.mdx
+++ /dev/null
@@ -1,42 +0,0 @@
----
-title: Contrib Integrations
-description: "Optional helpers for OpenTelemetry, Prometheus, Express, Fastify, and NestJS."
----
-
-import { Cards, Card } from "fumadocs-ui/components/card";
-import { Callout } from "fumadocs-ui/components/callout";
-
-Contrib modules are optional integrations that ship alongside the core SDK but
-are **not exported from the main `taskito` barrel**. Each lives behind its own
-subpath import and requires you to install its peer dependency separately.
-
-```bash
-# Only install what you use.
-pnpm add @opentelemetry/api # for taskito/contrib/otel
-pnpm add prom-client # for taskito/contrib/prometheus
-pnpm add @sentry/node # for taskito/contrib/sentry
-pnpm add express # for taskito/contrib/express
-pnpm add fastify # for taskito/contrib/fastify
-pnpm add @nestjs/common reflect-metadata # for taskito/contrib/nest
-```
-
-
- Contrib modules never auto-initialize. Nothing runs until you call the export
- and register it with your framework or queue. If a peer dependency is missing,
- importing its subpath fails with a standard module-not-found error.
-
-
-## What's in contrib
-
-
-
diff --git a/docs/content/docs/node/contrib/meta.json b/docs/content/docs/node/contrib/meta.json
deleted file mode 100644
index 0547d2e9..00000000
--- a/docs/content/docs/node/contrib/meta.json
+++ /dev/null
@@ -1,4 +0,0 @@
-{
- "title": "Contrib",
- "pages": ["index", "observability", "web-frameworks"]
-}
diff --git a/docs/content/docs/node/contrib/observability.mdx b/docs/content/docs/node/contrib/observability.mdx
deleted file mode 100644
index 90fc9bf4..00000000
--- a/docs/content/docs/node/contrib/observability.mdx
+++ /dev/null
@@ -1,170 +0,0 @@
----
-title: Observability
-description: "OpenTelemetry tracing, Prometheus metrics, and Sentry error reporting for the Node.js SDK."
----
-
-import { Callout } from "fumadocs-ui/components/callout";
-
-## OpenTelemetry
-
-Peer dependency: `@opentelemetry/api`.
-
-```ts
-import { otelMiddleware } from "taskito/contrib/otel";
-
-queue.use(otelMiddleware());
-```
-
-One span is created per execution attempt, named
-`taskito.execute.`. The span ends with status `OK` on success and
-`ERROR` (with the exception recorded) on throw. A retry is a new attempt, so
-it produces a new span.
-
-### Span attributes
-
-| Attribute | Value |
-|---|---|
-| `taskito.job_id` | The job's UUID |
-| `taskito.task_name` | Registered task name |
-
-### Options
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `tracerName` | `string` | `"taskito"` | Name passed to `trace.getTracer()` |
-| `attributePrefix` | `string` | `"taskito"` | Prefix applied to span attribute keys |
-| `spanName` | `(ctx) => string` | — | Override the span name per execution |
-| `extraAttributes` | `(ctx) => Attributes` | — | Attach additional attributes to every span |
-| `taskFilter` | `(taskName) => boolean` | — | Return `false` to skip tracing for a task |
-
-```ts
-queue.use(
- otelMiddleware({
- tracerName: "my-service",
- attributePrefix: "app",
- spanName: (ctx) => `job.${ctx.taskName}`,
- extraAttributes: (ctx) => ({ "app.env": process.env.NODE_ENV ?? "dev" }),
- taskFilter: (name) => !name.startsWith("internal."),
- }),
-);
-```
-
-
- `otelMiddleware` does not configure an exporter or a tracer provider. Set
- those up with the OpenTelemetry SDK before calling `queue.runWorker()`.
-
-
----
-
-## Prometheus
-
-Peer dependency: `prom-client`.
-
-```ts
-import {
- prometheusMiddleware,
- PrometheusStatsCollector,
-} from "taskito/contrib/prometheus";
-import { register } from "prom-client";
-import express from "express";
-
-// 1. Instrument job executions.
-queue.use(prometheusMiddleware());
-
-// 2. Poll queue/DLQ depth gauges every 10 s.
-const collector = new PrometheusStatsCollector(queue);
-collector.start();
-
-// 3. Expose metrics.
-const app = express();
-app.get("/metrics", async (_req, res) => {
- res.set("Content-Type", register.contentType);
- res.end(await register.metrics());
-});
-```
-
-### Metrics
-
-| Metric | Type | Labels | Description |
-|---|---|---|---|
-| `taskito_jobs_total` | Counter | `task`, `status` | Finished executions by outcome (`status` = `completed` or `failed`) |
-| `taskito_job_duration_seconds` | Histogram | `task` | Execution duration |
-| `taskito_active_workers` | Gauge | — | Workers currently running |
-| `taskito_retries_total` | Counter | `task` | Retry attempts |
-| `taskito_queue_depth` | Gauge | `queue` | Pending jobs per queue (polled by `PrometheusStatsCollector`) |
-| `taskito_dlq_size` | Gauge | — | Dead-letter queue size (polled) |
-
-### `prometheusMiddleware` options
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `namespace` | `string` | `"taskito"` | Metric name prefix |
-| `register` | `Registry` | global `register` | prom-client registry to register metrics into |
-| `taskFilter` | `(taskName) => boolean` | — | Return `false` to skip a task |
-| `buckets` | `number[]` | prom-client defaults | Histogram bucket boundaries (seconds) |
-
-### `PrometheusStatsCollector` options
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `namespace` | `string` | `"taskito"` | Metric name prefix |
-| `register` | `Registry` | global `register` | Registry to write gauges into |
-| `intervalMs` | `number` | `10000` | Poll interval in milliseconds |
-
-The internal timer is unref'd so it does not prevent Node from exiting.
-Call `.stop()` on graceful shutdown.
-
-```ts
-process.on("SIGTERM", () => {
- collector.stop();
- worker.stop();
-});
-```
-
-
- Each `prometheusMiddleware()` and `PrometheusStatsCollector` instance
- registers its metrics into the supplied registry — pass the same `register`
- instance to both if you want all metrics in one registry.
-
-
----
-
-## Sentry
-
-Peer dependency: `@sentry/node`. Call `Sentry.init(...)` in your app before
-registering the middleware.
-
-```ts
-import * as Sentry from "@sentry/node";
-import { sentryMiddleware } from "taskito/contrib/sentry";
-
-Sentry.init({ dsn: process.env.SENTRY_DSN });
-
-queue.use(sentryMiddleware());
-```
-
-The real exception (with its stack trace) is captured in `onError` and held
-per job, then reported to Sentry when the job **dead-letters** — so each dead
-job produces a single event carrying the original stack plus task/job/queue
-tags. Successful jobs and jobs that recover on retry are never reported.
-
-### Options
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `tagPrefix` | `string` | `"taskito"` | Prefix for Sentry tag keys |
-| `captureRetries` | `boolean` | `false` | Also report each retried failure as a `"warning"` event |
-| `level` | `SeverityLevel` | `"error"` | Severity for the terminal dead-letter event |
-| `extraTags` | `(event) => Record` | — | Extra tags merged onto the event |
-| `taskFilter` | `(taskName) => boolean` | — | Return `false` to skip a task |
-
-Tags set on every event: `taskito.task_name`, `taskito.job_id`,
-`taskito.queue`, `taskito.retry_count`, and `taskito.timed_out` (when the job
-timed out).
-
-
- `sentryMiddleware` never calls `Sentry.init` — configure the DSN, environment,
- and sampling with the Sentry SDK yourself. If a task dead-letters from a
- timeout without throwing, a synthetic error is captured so the failure is
- still recorded.
-
diff --git a/docs/content/docs/node/contrib/web-frameworks.mdx b/docs/content/docs/node/contrib/web-frameworks.mdx
deleted file mode 100644
index 2669b101..00000000
--- a/docs/content/docs/node/contrib/web-frameworks.mdx
+++ /dev/null
@@ -1,173 +0,0 @@
----
-title: Web Frameworks
-description: "REST routers and dashboard mounts for Express, Fastify, and NestJS."
----
-
-import { Callout } from "fumadocs-ui/components/callout";
-
-## Express
-
-Peer dependency: `express`.
-
-```ts
-import express from "express";
-import { taskitoRouter, taskitoDashboard } from "taskito/contrib/express";
-
-const app = express();
-
-// REST API — mounted at /tasks
-app.use("/tasks", taskitoRouter(queue));
-
-// Dashboard SPA — mounted at /admin
-app.use("/admin", taskitoDashboard(queue));
-
-app.listen(3000);
-```
-
-### REST routes
-
-JSON body parsing is mounted internally on the router.
-
-| Method | Path | Description |
-|---|---|---|
-| `POST` | `/enqueue` | Enqueue a job. Body: `{ task, args?, options? }`. Returns `{ jobId }` with status 201. |
-| `GET` | `/stats` | Overall queue statistics. |
-| `GET` | `/stats/queues?queue=` | Per-queue statistics. |
-| `GET` | `/jobs/:id` | Fetch a job by ID. |
-| `GET` | `/jobs/:id/errors` | Error history for a job. |
-| `GET` | `/jobs/:id/result?timeoutMs=` | Wait for a result (long-poll). |
-| `POST` | `/jobs/:id/cancel` | Request cancellation. |
-| `GET` | `/dead-letters?limit=&offset=` | List dead-lettered jobs. |
-| `POST` | `/dead-letters/:id/retry` | Retry a dead-lettered job. |
-
-### `taskitoRouter` options
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `includeRoutes` | `string[]` | all | Route names to expose (see below). |
-| `excludeRoutes` | `string[]` | none | Route names to suppress. |
-| `resultTimeoutMs` | `number` | `5000` | Max wait for `/jobs/:id/result`. |
-
-Route names: `enqueue`, `stats`, `queue-stats`, `job`, `job-errors`,
-`job-result`, `cancel`, `dead-letters`, `retry-dead`.
-
-### Dashboard
-
-`taskitoDashboard(queue, { staticDir? })` returns a request handler that serves
-the built dashboard SPA and proxies `/api/*` to the queue. Mount it under a
-path prefix:
-
-```ts
-app.use("/admin", taskitoDashboard(queue));
-```
-
-
- The SPA assets must be built first: `pnpm build:dashboard`. The built files
- land in `node_modules/taskito/static/dashboard` by default; pass `staticDir`
- to point elsewhere.
-
-
----
-
-## Fastify
-
-Peer dependency: `fastify`.
-
-```ts
-import Fastify from "fastify";
-import {
- taskitoFastify,
- taskitoDashboardPlugin,
-} from "taskito/contrib/fastify";
-
-const app = Fastify();
-
-// REST API
-await app.register(taskitoFastify, { queue, prefix: "/tasks" });
-
-// Dashboard SPA
-await app.register(taskitoDashboardPlugin, { queue, prefix: "/admin" });
-
-await app.listen({ port: 3000 });
-```
-
-`taskitoFastify` is a `FastifyPluginAsync`. It exposes the same nine routes as
-the Express router (see the table above), mounted under `prefix`.
-
-The same `includeRoutes`, `excludeRoutes`, and `resultTimeoutMs` options are
-accepted and passed in the register options object alongside `queue`:
-
-```ts
-await app.register(taskitoFastify, {
- queue,
- prefix: "/tasks",
- excludeRoutes: ["enqueue"], // read-only API
- resultTimeoutMs: 10_000,
-});
-```
-
-`taskitoDashboardPlugin` accepts `queue`, `prefix`, and an optional
-`staticDir`:
-
-```ts
-await app.register(taskitoDashboardPlugin, {
- queue,
- prefix: "/admin",
- staticDir: "/app/dashboard-assets",
-});
-```
-
----
-
-## NestJS
-
-Peer dependencies: `@nestjs/common` + `reflect-metadata`.
-
-```ts
-import { Module } from "@nestjs/common";
-import { TaskitoModule } from "taskito/contrib/nest";
-
-@Module({
- imports: [TaskitoModule.forRoot(queue)],
-})
-export class AppModule {}
-```
-
-`TaskitoModule.forRoot(queue)` returns a `DynamicModule` that exports
-`TaskitoService` to any module that imports it.
-
-### Injecting `TaskitoService`
-
-```ts
-import { Injectable } from "@nestjs/common";
-import { TaskitoService } from "taskito/contrib/nest";
-
-@Injectable()
-export class ReportService {
- constructor(private readonly tasks: TaskitoService) {}
-
- scheduleReport(reportId: string): string {
- return this.tasks.enqueue("generateReport", [reportId], {
- maxRetries: 2,
- timeoutMs: 60_000,
- });
- }
-}
-```
-
-### `TaskitoService` methods
-
-| Method | Description |
-|---|---|
-| `enqueue(task, args?, options?)` | Enqueue a job, returns the job ID. |
-| `result(id, options?)` | Wait for a result. |
-| `getJob(id)` | Fetch job details by ID. |
-| `stats()` | Overall queue statistics. |
-| `requestCancel(id)` | Request cancellation of a running job. |
-| `deadLetters(limit?, offset?)` | List dead-lettered jobs. |
-| `tasks.queue` | The raw `Queue` instance for the full API surface. |
-
-
- `TaskitoService` wraps the most common operations. For anything not listed —
- workflows, distributed locks, metrics, etc. — access `tasks.queue` directly.
-
diff --git a/docs/content/docs/node/workflows/conditions.mdx b/docs/content/docs/node/guides/workflows/conditions.mdx
similarity index 100%
rename from docs/content/docs/node/workflows/conditions.mdx
rename to docs/content/docs/node/guides/workflows/conditions.mdx
diff --git a/docs/content/docs/node/workflows/fan-out.mdx b/docs/content/docs/node/guides/workflows/fan-out.mdx
similarity index 100%
rename from docs/content/docs/node/workflows/fan-out.mdx
rename to docs/content/docs/node/guides/workflows/fan-out.mdx
diff --git a/docs/content/docs/node/workflows/gates.mdx b/docs/content/docs/node/guides/workflows/gates.mdx
similarity index 100%
rename from docs/content/docs/node/workflows/gates.mdx
rename to docs/content/docs/node/guides/workflows/gates.mdx
diff --git a/docs/content/docs/node/workflows/index.mdx b/docs/content/docs/node/guides/workflows/index.mdx
similarity index 100%
rename from docs/content/docs/node/workflows/index.mdx
rename to docs/content/docs/node/guides/workflows/index.mdx
diff --git a/docs/content/docs/node/workflows/meta.json b/docs/content/docs/node/guides/workflows/meta.json
similarity index 100%
rename from docs/content/docs/node/workflows/meta.json
rename to docs/content/docs/node/guides/workflows/meta.json
diff --git a/docs/content/docs/node/workflows/saga.mdx b/docs/content/docs/node/guides/workflows/saga.mdx
similarity index 100%
rename from docs/content/docs/node/workflows/saga.mdx
rename to docs/content/docs/node/guides/workflows/saga.mdx
diff --git a/docs/content/docs/node/workflows/sub-workflows.mdx b/docs/content/docs/node/guides/workflows/sub-workflows.mdx
similarity index 100%
rename from docs/content/docs/node/workflows/sub-workflows.mdx
rename to docs/content/docs/node/guides/workflows/sub-workflows.mdx
diff --git a/docs/content/docs/node/index.mdx b/docs/content/docs/node/index.mdx
deleted file mode 100644
index 5254ad7d..00000000
--- a/docs/content/docs/node/index.mdx
+++ /dev/null
@@ -1,78 +0,0 @@
----
-title: Node.js SDK
-description: "Rust-powered task queue for Node.js — no broker, no Python."
----
-
-import { Cards, Card } from "fumadocs-ui/components/card";
-import { Callout } from "fumadocs-ui/components/callout";
-
-A thin [napi-rs](https://napi.rs) shell over the Taskito Rust core, peer to
-the Python SDK. Enqueue work and run workers in the same process or across
-processes that share storage. Zero Python dependency.
-
-## Install
-
-```bash
-pnpm add taskito
-```
-
-Requires Node.js >= 18. Ships as dual ESM + CommonJS. A prebuilt native binary is
-installed automatically for your platform via an optional per-platform package
-(`taskito--`): linux x64/arm64 (gnu + musl), macOS x64/arm64, and
-Windows x64. On any other platform, build from source (requires Rust + the
-napi-rs CLI):
-
-```bash
-pnpm build:native
-```
-
-## Quickstart
-
-```ts
-import { Queue } from "taskito";
-
-const queue = new Queue({ dbPath: "taskito.db" });
-
-// 1. Register a task.
-queue.task("add", (a: number, b: number) => a + b, {
- maxRetries: 3,
- timeoutMs: 30_000,
-});
-
-// 2. Enqueue a job.
-const id = queue.enqueue("add", [2, 3]);
-
-// 3. Start a worker (same process or a separate one).
-const worker = queue.runWorker();
-
-// 4. Await the result.
-const result = await queue.result(id); // 5
-worker.stop();
-```
-
-## Backends
-
-```ts
-new Queue({ dbPath: "taskito.db" }); // SQLite (default)
-new Queue({ backend: "postgres", dsn: process.env.PG_URL }); // PostgreSQL
-new Queue({ backend: "redis", dsn: "redis://localhost" }); // Redis
-```
-
-## What's available
-
-
-
-
-For the full API surface — serializers, cancellation, events, middleware,
-webhooks, distributed locks, periodic tasks, the CLI, and the dashboard — see
-the [Node SDK README](https://github.com/pratyushsharma/taskito/blob/master/sdks/node/README.md).
diff --git a/docs/content/docs/node/meta.json b/docs/content/docs/node/meta.json
deleted file mode 100644
index c503e54c..00000000
--- a/docs/content/docs/node/meta.json
+++ /dev/null
@@ -1,5 +0,0 @@
-{
- "title": "Node SDK",
- "root": true,
- "pages": ["index", "workflows", "contrib"]
-}
From dee6b353123e85e3235088c8ea15f499ca62875d Mon Sep 17 00:00:00 2001
From: Pratyush Sharma <56130065+pratyush618@users.noreply.github.com>
Date: Sun, 21 Jun 2026 11:19:16 +0530
Subject: [PATCH 28/48] feat(docs): wire Node nav + split contrib into
integrations
---
docs/app/components/docs/sidebar.tsx | 2 +-
docs/app/lib/nav.ts | 6 +-
.../docs/node/guides/integrations/express.mdx | 64 ++++++++++++++++
.../docs/node/guides/integrations/fastify.mdx | 52 +++++++++++++
.../docs/node/guides/integrations/index.mdx | 36 +++++++++
.../docs/node/guides/integrations/meta.json | 4 +
.../docs/node/guides/integrations/nest.mdx | 56 ++++++++++++++
.../docs/node/guides/integrations/otel.mdx | 51 +++++++++++++
.../node/guides/integrations/prometheus.mdx | 74 +++++++++++++++++++
.../docs/node/guides/integrations/sentry.mdx | 42 +++++++++++
docs/content/docs/node/guides/meta.json | 1 +
.../docs/node/guides/workflows/conditions.mdx | 2 +-
.../docs/node/guides/workflows/gates.mdx | 2 +-
.../docs/node/guides/workflows/index.mdx | 10 +--
.../node/guides/workflows/sub-workflows.mdx | 2 +-
15 files changed, 394 insertions(+), 10 deletions(-)
create mode 100644 docs/content/docs/node/guides/integrations/express.mdx
create mode 100644 docs/content/docs/node/guides/integrations/fastify.mdx
create mode 100644 docs/content/docs/node/guides/integrations/index.mdx
create mode 100644 docs/content/docs/node/guides/integrations/meta.json
create mode 100644 docs/content/docs/node/guides/integrations/nest.mdx
create mode 100644 docs/content/docs/node/guides/integrations/otel.mdx
create mode 100644 docs/content/docs/node/guides/integrations/prometheus.mdx
create mode 100644 docs/content/docs/node/guides/integrations/sentry.mdx
create mode 100644 docs/content/docs/node/guides/meta.json
diff --git a/docs/app/components/docs/sidebar.tsx b/docs/app/components/docs/sidebar.tsx
index da6f8298..d5a0a6c8 100644
--- a/docs/app/components/docs/sidebar.tsx
+++ b/docs/app/components/docs/sidebar.tsx
@@ -21,7 +21,7 @@ function SdkSwitch({ sdk }: { sdk: Sdk }) {
Python
+ The SPA assets must be built first: `pnpm build:dashboard`. The built files
+ land in `node_modules/taskito/static/dashboard` by default; pass `staticDir`
+ to point elsewhere.
+
diff --git a/docs/content/docs/node/guides/integrations/fastify.mdx b/docs/content/docs/node/guides/integrations/fastify.mdx
new file mode 100644
index 00000000..4df61a92
--- /dev/null
+++ b/docs/content/docs/node/guides/integrations/fastify.mdx
@@ -0,0 +1,52 @@
+---
+title: Fastify
+description: "Register the REST API and dashboard as Fastify plugins."
+---
+
+Peer dependency: `fastify`. Import from the `taskito/contrib/fastify` subpath.
+
+```ts
+import Fastify from "fastify";
+import {
+ taskitoFastify,
+ taskitoDashboardPlugin,
+} from "taskito/contrib/fastify";
+
+const app = Fastify();
+
+// REST API
+await app.register(taskitoFastify, { queue, prefix: "/tasks" });
+
+// Dashboard SPA
+await app.register(taskitoDashboardPlugin, { queue, prefix: "/admin" });
+
+await app.listen({ port: 3000 });
+```
+
+`taskitoFastify` is a `FastifyPluginAsync`. It exposes the same nine routes as
+the [Express router](/node/guides/integrations/express#rest-routes), mounted
+under `prefix`.
+
+## Options
+
+The same `includeRoutes`, `excludeRoutes`, and `resultTimeoutMs` options are
+accepted, passed in the register options object alongside `queue`:
+
+```ts
+await app.register(taskitoFastify, {
+ queue,
+ prefix: "/tasks",
+ excludeRoutes: ["enqueue"], // read-only API
+ resultTimeoutMs: 10_000,
+});
+```
+
+`taskitoDashboardPlugin` accepts `queue`, `prefix`, and an optional `staticDir`:
+
+```ts
+await app.register(taskitoDashboardPlugin, {
+ queue,
+ prefix: "/admin",
+ staticDir: "/app/dashboard-assets",
+});
+```
diff --git a/docs/content/docs/node/guides/integrations/index.mdx b/docs/content/docs/node/guides/integrations/index.mdx
new file mode 100644
index 00000000..b6c598fc
--- /dev/null
+++ b/docs/content/docs/node/guides/integrations/index.mdx
@@ -0,0 +1,36 @@
+---
+title: Integrations
+description: "Optional observability and web-framework helpers for the Node.js SDK."
+---
+
+Integrations are optional helpers that ship alongside the core SDK but are **not
+exported from the main `taskito` barrel**. Each lives behind its own
+`taskito/contrib/*` subpath and requires you to install its peer dependency.
+
+```bash
+# Only install what you use.
+pnpm add @opentelemetry/api # taskito/contrib/otel
+pnpm add prom-client # taskito/contrib/prometheus
+pnpm add @sentry/node # taskito/contrib/sentry
+pnpm add express # taskito/contrib/express
+pnpm add fastify # taskito/contrib/fastify
+pnpm add @nestjs/common reflect-metadata # taskito/contrib/nest
+```
+
+
+ Integrations never auto-initialize. Nothing runs until you call the export and
+ register it with your queue or framework. If a peer dependency is missing,
+ importing its subpath fails with a standard module-not-found error.
+
+
+## Observability
+
+- [OpenTelemetry](/node/guides/integrations/otel) — one span per execution attempt.
+- [Prometheus](/node/guides/integrations/prometheus) — execution metrics + polled depth gauges.
+- [Sentry](/node/guides/integrations/sentry) — capture the original exception on dead-letter.
+
+## Web frameworks
+
+- [Express](/node/guides/integrations/express) — REST router + dashboard mount.
+- [Fastify](/node/guides/integrations/fastify) — REST + dashboard plugins.
+- [NestJS](/node/guides/integrations/nest) — injectable `TaskitoService`.
diff --git a/docs/content/docs/node/guides/integrations/meta.json b/docs/content/docs/node/guides/integrations/meta.json
new file mode 100644
index 00000000..a85835c6
--- /dev/null
+++ b/docs/content/docs/node/guides/integrations/meta.json
@@ -0,0 +1,4 @@
+{
+ "title": "Integrations",
+ "pages": ["index", "otel", "prometheus", "sentry", "express", "fastify", "nest"]
+}
diff --git a/docs/content/docs/node/guides/integrations/nest.mdx b/docs/content/docs/node/guides/integrations/nest.mdx
new file mode 100644
index 00000000..ef59c125
--- /dev/null
+++ b/docs/content/docs/node/guides/integrations/nest.mdx
@@ -0,0 +1,56 @@
+---
+title: NestJS
+description: "Inject a TaskitoService into your Nest providers."
+---
+
+Peer dependencies: `@nestjs/common` + `reflect-metadata`. Import from the
+`taskito/contrib/nest` subpath.
+
+```ts
+import { Module } from "@nestjs/common";
+import { TaskitoModule } from "taskito/contrib/nest";
+
+@Module({
+ imports: [TaskitoModule.forRoot(queue)],
+})
+export class AppModule {}
+```
+
+`TaskitoModule.forRoot(queue)` returns a `DynamicModule` that exports
+`TaskitoService` to any module that imports it.
+
+## Injecting `TaskitoService`
+
+```ts
+import { Injectable } from "@nestjs/common";
+import { TaskitoService } from "taskito/contrib/nest";
+
+@Injectable()
+export class ReportService {
+ constructor(private readonly tasks: TaskitoService) {}
+
+ scheduleReport(reportId: string): string {
+ return this.tasks.enqueue("generateReport", [reportId], {
+ maxRetries: 2,
+ timeoutMs: 60_000,
+ });
+ }
+}
+```
+
+## `TaskitoService` methods
+
+| Method | Description |
+|---|---|
+| `enqueue(task, args?, options?)` | Enqueue a job, returns the job ID. |
+| `result(id, options?)` | Wait for a result. |
+| `getJob(id)` | Fetch job details by ID. |
+| `stats()` | Overall queue statistics. |
+| `requestCancel(id)` | Request cancellation of a running job. |
+| `deadLetters(limit?, offset?)` | List dead-lettered jobs. |
+| `queue` | The raw `Queue` instance for the full API surface. |
+
+
+ `TaskitoService` wraps the most common operations. For anything not listed —
+ workflows, distributed locks, metrics — access `tasks.queue` directly.
+
diff --git a/docs/content/docs/node/guides/integrations/otel.mdx b/docs/content/docs/node/guides/integrations/otel.mdx
new file mode 100644
index 00000000..81d97c97
--- /dev/null
+++ b/docs/content/docs/node/guides/integrations/otel.mdx
@@ -0,0 +1,51 @@
+---
+title: OpenTelemetry
+description: "Distributed tracing for Node.js task execution — one span per attempt."
+---
+
+Peer dependency: `@opentelemetry/api`. Import from the `taskito/contrib/otel`
+subpath — it is not exported from the main barrel.
+
+```ts
+import { otelMiddleware } from "taskito/contrib/otel";
+
+queue.use(otelMiddleware());
+```
+
+One span is created per execution attempt, named `taskito.execute.`.
+The span ends with status `OK` on success and `ERROR` (with the exception
+recorded) on throw. A retry is a new attempt, so it produces a new span.
+
+## Span attributes
+
+| Attribute | Value |
+|---|---|
+| `taskito.job_id` | The job's UUID |
+| `taskito.task_name` | Registered task name |
+
+## Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `tracerName` | `string` | `"taskito"` | Name passed to `trace.getTracer()` |
+| `attributePrefix` | `string` | `"taskito"` | Prefix applied to span attribute keys |
+| `spanName` | `(ctx) => string` | — | Override the span name per execution |
+| `extraAttributes` | `(ctx) => Attributes` | — | Attach additional attributes to every span |
+| `taskFilter` | `(taskName) => boolean` | — | Return `false` to skip tracing for a task |
+
+```ts
+queue.use(
+ otelMiddleware({
+ tracerName: "my-service",
+ attributePrefix: "app",
+ spanName: (ctx) => `job.${ctx.taskName}`,
+ extraAttributes: (ctx) => ({ "app.env": process.env.NODE_ENV ?? "dev" }),
+ taskFilter: (name) => !name.startsWith("internal."),
+ }),
+);
+```
+
+
+ `otelMiddleware` does not configure an exporter or a tracer provider. Set
+ those up with the OpenTelemetry SDK before calling `queue.runWorker()`.
+
diff --git a/docs/content/docs/node/guides/integrations/prometheus.mdx b/docs/content/docs/node/guides/integrations/prometheus.mdx
new file mode 100644
index 00000000..cc8f01f5
--- /dev/null
+++ b/docs/content/docs/node/guides/integrations/prometheus.mdx
@@ -0,0 +1,74 @@
+---
+title: Prometheus
+description: "Execution metrics and polled queue/DLQ depth gauges for Node.js workers."
+---
+
+Peer dependency: `prom-client`. Import from the `taskito/contrib/prometheus`
+subpath.
+
+```ts
+import {
+ prometheusMiddleware,
+ PrometheusStatsCollector,
+} from "taskito/contrib/prometheus";
+import { register } from "prom-client";
+import express from "express";
+
+// 1. Instrument job executions.
+queue.use(prometheusMiddleware());
+
+// 2. Poll queue/DLQ depth gauges every 10 s.
+const collector = new PrometheusStatsCollector(queue);
+collector.start();
+
+// 3. Expose metrics.
+const app = express();
+app.get("/metrics", async (_req, res) => {
+ res.set("Content-Type", register.contentType);
+ res.end(await register.metrics());
+});
+```
+
+## Metrics
+
+| Metric | Type | Labels | Description |
+|---|---|---|---|
+| `taskito_jobs_total` | Counter | `task`, `status` | Finished executions by outcome (`status` = `completed` or `failed`) |
+| `taskito_job_duration_seconds` | Histogram | `task` | Execution duration |
+| `taskito_active_workers` | Gauge | — | Workers currently running |
+| `taskito_retries_total` | Counter | `task` | Retry attempts |
+| `taskito_queue_depth` | Gauge | `queue` | Pending jobs per queue (polled by `PrometheusStatsCollector`) |
+| `taskito_dlq_size` | Gauge | — | Dead-letter queue size (polled) |
+
+## `prometheusMiddleware` options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `namespace` | `string` | `"taskito"` | Metric name prefix |
+| `register` | `Registry` | global `register` | prom-client registry to register metrics into |
+| `taskFilter` | `(taskName) => boolean` | — | Return `false` to skip a task |
+| `buckets` | `number[]` | prom-client defaults | Histogram bucket boundaries (seconds) |
+
+## `PrometheusStatsCollector` options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `namespace` | `string` | `"taskito"` | Metric name prefix |
+| `register` | `Registry` | global `register` | Registry to write gauges into |
+| `intervalMs` | `number` | `10000` | Poll interval in milliseconds |
+
+The internal timer is unref'd so it does not prevent Node from exiting. Call
+`.stop()` on graceful shutdown.
+
+```ts
+process.on("SIGTERM", () => {
+ collector.stop();
+ worker.stop();
+});
+```
+
+
+ Metrics for one namespace are built once per registry, so registering
+ multiple middlewares is safe. Pass the same `register` to the middleware and
+ the collector to keep everything in one registry.
+
diff --git a/docs/content/docs/node/guides/integrations/sentry.mdx b/docs/content/docs/node/guides/integrations/sentry.mdx
new file mode 100644
index 00000000..8c68c9d9
--- /dev/null
+++ b/docs/content/docs/node/guides/integrations/sentry.mdx
@@ -0,0 +1,42 @@
+---
+title: Sentry
+description: "Capture the original exception when a Node.js job dead-letters."
+---
+
+Peer dependency: `@sentry/node`. Call `Sentry.init(...)` in your app before
+registering the middleware. Import from the `taskito/contrib/sentry` subpath.
+
+```ts
+import * as Sentry from "@sentry/node";
+import { sentryMiddleware } from "taskito/contrib/sentry";
+
+Sentry.init({ dsn: process.env.SENTRY_DSN });
+
+queue.use(sentryMiddleware());
+```
+
+The real exception (with its stack trace) is captured in `onError` and held per
+job, then reported to Sentry when the job **dead-letters** — so each dead job
+produces a single event carrying the original stack plus task/job/queue tags.
+Successful jobs and jobs that recover on retry are never reported.
+
+## Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `tagPrefix` | `string` | `"taskito"` | Prefix for Sentry tag keys |
+| `captureRetries` | `boolean` | `false` | Also report each retried failure as a `"warning"` event |
+| `level` | `SeverityLevel` | `"error"` | Severity for the terminal dead-letter event |
+| `extraTags` | `(event) => Record` | — | Extra tags merged onto the event |
+| `taskFilter` | `(taskName) => boolean` | — | Return `false` to skip a task |
+
+Tags set on every event: `taskito.task_name`, `taskito.job_id`,
+`taskito.queue`, `taskito.retry_count`, and `taskito.timed_out` (when the job
+timed out).
+
+
+ `sentryMiddleware` never calls `Sentry.init` — configure the DSN, environment,
+ and sampling with the Sentry SDK yourself. If a task dead-letters from a
+ timeout without throwing, a synthetic error is captured so the failure is
+ still recorded.
+
diff --git a/docs/content/docs/node/guides/meta.json b/docs/content/docs/node/guides/meta.json
new file mode 100644
index 00000000..84548fd0
--- /dev/null
+++ b/docs/content/docs/node/guides/meta.json
@@ -0,0 +1 @@
+{ "title": "Guides", "root": true, "pages": ["core", "reliability", "workflows", "extensibility", "integrations", "operations"] }
diff --git a/docs/content/docs/node/guides/workflows/conditions.mdx b/docs/content/docs/node/guides/workflows/conditions.mdx
index ccb698d2..9357b547 100644
--- a/docs/content/docs/node/guides/workflows/conditions.mdx
+++ b/docs/content/docs/node/guides/workflows/conditions.mdx
@@ -82,7 +82,7 @@ in a task that catches internally and returns a status sentinel).
To roll back already-completed steps when a run fails, use
- [Saga compensation](/node/workflows/saga) instead of `on_failure` conditions.
+ [Saga compensation](/node/guides/workflows/saga) instead of `on_failure` conditions.
## `always` steps
diff --git a/docs/content/docs/node/guides/workflows/gates.mdx b/docs/content/docs/node/guides/workflows/gates.mdx
index e3375418..6307304e 100644
--- a/docs/content/docs/node/guides/workflows/gates.mdx
+++ b/docs/content/docs/node/guides/workflows/gates.mdx
@@ -96,7 +96,7 @@ Setting `timeoutMs` without `onTimeout` defaults to `"reject"`.
Rejecting a gate marks the gate node `failed` and skips its default
(`on_success`) successors; the workflow run ends in state `"failed"`. Any
`on_failure` / `always` successors still run — use those (see
-[conditions](/node/workflows/conditions)) if you need a rejection branch.
+[conditions](/node/guides/workflows/conditions)) if you need a rejection branch.
Calling `approveGate` or `rejectGate` on a gate that has already been
diff --git a/docs/content/docs/node/guides/workflows/index.mdx b/docs/content/docs/node/guides/workflows/index.mdx
index 21b8d1f3..0cd8b7bb 100644
--- a/docs/content/docs/node/guides/workflows/index.mdx
+++ b/docs/content/docs/node/guides/workflows/index.mdx
@@ -31,27 +31,27 @@ Requires the addon built with the `workflows` cargo feature (enabled by
diff --git a/docs/content/docs/node/guides/workflows/sub-workflows.mdx b/docs/content/docs/node/guides/workflows/sub-workflows.mdx
index d9d20766..76953cc8 100644
--- a/docs/content/docs/node/guides/workflows/sub-workflows.mdx
+++ b/docs/content/docs/node/guides/workflows/sub-workflows.mdx
@@ -128,4 +128,4 @@ the DAG — downstream steps are skipped.
To handle child failures without failing the parent, wrap the sub-workflow node
in a conditional branch: place an `on_failure` step after it and an `on_success`
-step for the happy path. See [Conditions](/node/workflows/conditions).
+step for the happy path. See [Conditions](/node/guides/workflows/conditions).
From 13af1b1178ffc922a61b52d83cdb60a4326ba2b2 Mon Sep 17 00:00:00 2001
From: Pratyush Sharma <56130065+pratyush618@users.noreply.github.com>
Date: Sun, 21 Jun 2026 11:19:17 +0530
Subject: [PATCH 29/48] =?UTF-8?q?docs(node):=20getting=20started=20?=
=?UTF-8?q?=E2=80=94=20install,=20quickstart,=20concepts?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
.../docs/node/getting-started/concepts.mdx | 54 +++++++++++++++++++
.../node/getting-started/installation.mdx | 47 ++++++++++++++++
.../docs/node/getting-started/meta.json | 1 +
.../docs/node/getting-started/quickstart.mdx | 46 ++++++++++++++++
4 files changed, 148 insertions(+)
create mode 100644 docs/content/docs/node/getting-started/concepts.mdx
create mode 100644 docs/content/docs/node/getting-started/installation.mdx
create mode 100644 docs/content/docs/node/getting-started/meta.json
create mode 100644 docs/content/docs/node/getting-started/quickstart.mdx
diff --git a/docs/content/docs/node/getting-started/concepts.mdx b/docs/content/docs/node/getting-started/concepts.mdx
new file mode 100644
index 00000000..f108f285
--- /dev/null
+++ b/docs/content/docs/node/getting-started/concepts.mdx
@@ -0,0 +1,54 @@
+---
+title: Concepts
+description: "Queue, task, worker, result — the Node.js mental model over the Rust core."
+---
+
+The Node SDK is a typed shell; the scheduler, dispatcher, worker pool, and
+storage are all the same Rust engine the Python SDK uses. Four concepts cover
+the surface.
+
+## Queue
+
+A `Queue` is the handle to one store (SQLite file, Postgres schema, or Redis
+prefix). You register tasks on it, enqueue jobs, run workers, and inspect state
+through it. Multiple processes pointed at the same storage share one logical
+queue.
+
+```ts
+const queue = new Queue({ dbPath: "taskito.db" });
+```
+
+## Task
+
+A **task** is a named function registered with `queue.task(name, fn, config?)`.
+Enqueuing references the task by name, so the producer never needs the function
+body — only the worker does. Per-task config (retries, timeout, concurrency,
+rate limit, circuit breaker) is attached at registration.
+
+## Job
+
+Enqueuing a task creates a **job** — a row in storage with arguments, priority,
+status, and result. Jobs move through a state machine: `pending → running →
+completed`, or `failed → retrying`, or `dead` (retries exhausted), or
+`cancelled`. The engine claims jobs atomically, so the same job never runs
+twice concurrently.
+
+## Worker
+
+`queue.runWorker()` starts a worker that polls storage, claims due jobs,
+dispatches them to the registered task function, and writes results back. Sync
+tasks run on an OS-thread pool; `async` tasks run on a native async pool. Call
+`worker.stop()` to drain and shut down.
+
+## Result
+
+`await queue.result(id)` resolves with the task's return value once the job
+finishes (or rejects if it dead-letters). Results are serialized with the
+queue's [serializer](/node/guides/extensibility/serializers) and stored, so any
+process sharing the storage can await them.
+
+
+ The architecture is engine-level and shared across SDKs — see
+ [Architecture](/architecture/overview) for the job lifecycle, scheduler,
+ storage schema, and mesh internals.
+
diff --git a/docs/content/docs/node/getting-started/installation.mdx b/docs/content/docs/node/getting-started/installation.mdx
new file mode 100644
index 00000000..8c304f08
--- /dev/null
+++ b/docs/content/docs/node/getting-started/installation.mdx
@@ -0,0 +1,47 @@
+---
+title: Installation
+description: "Install the Node.js SDK — prebuilt native binaries, dual ESM/CJS, three backends."
+---
+
+The Node.js SDK is a thin [napi-rs](https://napi.rs) shell over the Taskito Rust
+core — peer to the Python SDK, with **no Python dependency**.
+
+```bash
+pnpm add taskito
+```
+
+Requires Node.js >= 18. Ships as dual **ESM + CommonJS** with bundled type
+definitions.
+
+## Prebuilt native binaries
+
+A prebuilt native addon is installed automatically for your platform via an
+optional per-platform package (`taskito--`):
+
+- linux x64 / arm64 (gnu + musl)
+- macOS x64 / arm64
+- Windows x64
+
+On a platform without a prebuilt, build from source with the Rust toolchain +
+the napi-rs CLI:
+
+```bash
+pnpm build:native
+```
+
+The native crate lives at `crates/taskito-node`; `build:native` compiles it with
+the `postgres,redis,workflows,mesh` cargo features enabled.
+
+## Pick a backend
+
+```ts
+import { Queue } from "taskito";
+
+new Queue({ dbPath: "taskito.db" }); // SQLite (default)
+new Queue({ backend: "postgres", dsn: process.env.PG_URL, schema: "taskito" });
+new Queue({ backend: "redis", dsn: "redis://localhost", prefix: "taskito" });
+```
+
+SQLite needs nothing else — the whole queue lives in one file. See
+[Backends](/node/guides/operations/backends) for when to reach for Postgres or
+Redis. Next: the [quickstart](/node/getting-started/quickstart).
diff --git a/docs/content/docs/node/getting-started/meta.json b/docs/content/docs/node/getting-started/meta.json
new file mode 100644
index 00000000..35f890a4
--- /dev/null
+++ b/docs/content/docs/node/getting-started/meta.json
@@ -0,0 +1 @@
+{ "title": "Getting Started", "root": true, "pages": ["installation", "quickstart", "concepts"] }
diff --git a/docs/content/docs/node/getting-started/quickstart.mdx b/docs/content/docs/node/getting-started/quickstart.mdx
new file mode 100644
index 00000000..39c6d0b2
--- /dev/null
+++ b/docs/content/docs/node/getting-started/quickstart.mdx
@@ -0,0 +1,46 @@
+---
+title: Quickstart
+description: "Define a task, enqueue a job, run a worker, await the result — in TypeScript."
+---
+
+Four steps: construct a queue, register a task, enqueue a job, run a worker.
+
+```ts
+import { Queue } from "taskito";
+
+const queue = new Queue({ dbPath: "taskito.db" });
+
+// 1. Register a task with optional per-task config.
+queue.task("add", (a: number, b: number) => a + b, {
+ maxRetries: 3,
+ retryBackoff: { baseMs: 1000, maxMs: 60_000 },
+ timeoutMs: 30_000,
+ maxConcurrent: 4,
+});
+
+// 2. Enqueue a job (producer).
+const id = queue.enqueue("add", [2, 3], { priority: 5 });
+
+// 3. Start a worker — same process or a separate one that shares the DB.
+const worker = queue.runWorker({ queues: ["default"] });
+
+// 4. Await the result.
+const result = await queue.result(id); // 5
+worker.stop();
+```
+
+The producer and the worker only need to share storage — `enqueue` from your web
+app, `runWorker` from a separate process pointed at the same `dbPath` / DSN.
+
+
+ Tasks can be `async`. The dispatcher awaits the returned promise; an
+ `async def`-style task that does I/O runs on the native async pool without a
+ thread per job.
+
+
+## Where to next
+
+- [Concepts](/node/getting-started/concepts) — the mental model.
+- [Tasks](/node/guides/core/tasks) — registration and per-task config.
+- [Workers](/node/guides/core/workers) — running and stopping workers.
+- [Workflows](/node/guides/workflows) — multi-step DAGs.
From e5a47929e7a5ccba382c387babf0449eab051bb1 Mon Sep 17 00:00:00 2001
From: Pratyush Sharma <56130065+pratyush618@users.noreply.github.com>
Date: Sun, 21 Jun 2026 11:19:17 +0530
Subject: [PATCH 30/48] =?UTF-8?q?docs(node):=20core=20guides=20=E2=80=94?=
=?UTF-8?q?=20tasks,=20queues,=20workers,=20scheduling?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
.../docs/node/guides/core/cancellation.mdx | 51 +++++++++++++++++++
.../docs/node/guides/core/enqueue-options.mdx | 45 ++++++++++++++++
docs/content/docs/node/guides/core/meta.json | 1 +
docs/content/docs/node/guides/core/queues.mdx | 43 ++++++++++++++++
.../docs/node/guides/core/scheduling.mdx | 35 +++++++++++++
docs/content/docs/node/guides/core/tasks.mdx | 51 +++++++++++++++++++
.../content/docs/node/guides/core/workers.mdx | 41 +++++++++++++++
7 files changed, 267 insertions(+)
create mode 100644 docs/content/docs/node/guides/core/cancellation.mdx
create mode 100644 docs/content/docs/node/guides/core/enqueue-options.mdx
create mode 100644 docs/content/docs/node/guides/core/meta.json
create mode 100644 docs/content/docs/node/guides/core/queues.mdx
create mode 100644 docs/content/docs/node/guides/core/scheduling.mdx
create mode 100644 docs/content/docs/node/guides/core/tasks.mdx
create mode 100644 docs/content/docs/node/guides/core/workers.mdx
diff --git a/docs/content/docs/node/guides/core/cancellation.mdx b/docs/content/docs/node/guides/core/cancellation.mdx
new file mode 100644
index 00000000..cc7f586a
--- /dev/null
+++ b/docs/content/docs/node/guides/core/cancellation.mdx
@@ -0,0 +1,51 @@
+---
+title: Cancellation
+description: "Cooperative cancellation via AbortSignal, plus progress reporting."
+---
+
+Cancellation is **cooperative**. A running task reads its context via
+`currentJob()` and watches the `AbortSignal`:
+
+```ts
+import { currentJob } from "taskito";
+
+queue.task("download", async (url: string) => {
+ const { signal } = currentJob() ?? {};
+ const res = await fetch(url, { signal });
+ return res.text();
+});
+
+queue.requestCancel(jobId); // aborts the running task's signal
+```
+
+`requestCancel(id)` flips the cancel flag for a **running** job; the worker
+aborts the signal so signal-aware work (fetch, streams) unwinds. A task that
+ignores the signal runs to completion.
+
+## Cancel a pending job
+
+```ts
+queue.cancelJob(id); // cancels a still-pending job before it starts
+```
+
+## Progress
+
+A task can report progress 0–100 through its context:
+
+```ts
+queue.task("export", async () => {
+ const job = currentJob();
+ for (let i = 0; i < 100; i++) {
+ await step(i);
+ job?.setProgress(i + 1);
+ }
+});
+```
+
+Progress surfaces on the [dashboard](/node/guides/operations/dashboard) and via
+inspection.
+
+
+ `currentJob()` is backed by `AsyncLocalStorage`, so it works across `await`
+ boundaries inside the task. It returns `undefined` outside a running task.
+
diff --git a/docs/content/docs/node/guides/core/enqueue-options.mdx b/docs/content/docs/node/guides/core/enqueue-options.mdx
new file mode 100644
index 00000000..16e811e2
--- /dev/null
+++ b/docs/content/docs/node/guides/core/enqueue-options.mdx
@@ -0,0 +1,45 @@
+---
+title: Enqueue options
+description: "Priority, delay, idempotency, metadata, and namespace at enqueue time."
+---
+
+The third argument to `enqueue` sets per-job options:
+
+```ts
+queue.enqueue("send_email", [user], {
+ priority: 5,
+ delayMs: 30_000,
+ uniqueKey: `welcome:${user.id}`,
+ metadata: { source: "signup" },
+ namespace: "emails",
+});
+```
+
+| Option | Description |
+|---|---|
+| `priority` | Higher dequeues first within a queue. |
+| `maxRetries` | Override the task's retry budget for this job. |
+| `timeoutMs` | Override the per-attempt timeout for this job. |
+| `delayMs` | Delay first execution by this many ms (scheduled run). |
+| `uniqueKey` | Idempotency key — a duplicate enqueue is a no-op while the first job is pending/running. |
+| `metadata` | Arbitrary JSON attached to the job (surfaces on the dashboard / inspection). |
+| `namespace` | The queue name to route to. |
+
+## Idempotency
+
+`uniqueKey` dedupes concurrent producers — only one job runs for a given key
+while an earlier one is still pending or running. See
+[idempotency](/node/guides/reliability/idempotency).
+
+## Delayed jobs
+
+`delayMs` schedules the first attempt in the future; the scheduler picks it up
+when due. For recurring schedules use [periodic tasks](/node/guides/core/scheduling).
+
+## Batch enqueue
+
+`enqueueMany` enqueues an array in one call:
+
+```ts
+queue.enqueueMany("resize", urls.map((url) => ({ args: [url] })));
+```
diff --git a/docs/content/docs/node/guides/core/meta.json b/docs/content/docs/node/guides/core/meta.json
new file mode 100644
index 00000000..d2af37ad
--- /dev/null
+++ b/docs/content/docs/node/guides/core/meta.json
@@ -0,0 +1 @@
+{ "title": "Core", "pages": ["tasks", "queues", "workers", "enqueue-options", "scheduling", "cancellation"] }
diff --git a/docs/content/docs/node/guides/core/queues.mdx b/docs/content/docs/node/guides/core/queues.mdx
new file mode 100644
index 00000000..f177026f
--- /dev/null
+++ b/docs/content/docs/node/guides/core/queues.mdx
@@ -0,0 +1,43 @@
+---
+title: Queues
+description: "Route jobs to named queues, set priority, and pause/resume."
+---
+
+Every job belongs to a queue (default `"default"`). Queues are just routing
+labels in shared storage — a worker chooses which queues it serves.
+
+```ts
+const id = queue.enqueue("send_email", [user], { namespace: "emails" });
+
+queue.runWorker({ queues: ["emails", "default"] }); // serve two queues
+```
+
+## Priority
+
+Higher `priority` dequeues first within a queue:
+
+```ts
+queue.enqueue("report", [id], { priority: 10 }); // ahead of priority 0 jobs
+```
+
+## Pause and resume
+
+Pausing stops dispatch for a queue without stopping the worker — in-flight jobs
+finish, new ones wait.
+
+```ts
+queue.pauseQueue("emails");
+queue.listPausedQueues(); // ["emails"]
+queue.resumeQueue("emails");
+```
+
+## Per-queue limits
+
+```ts
+queue.configureQueue("emails", {
+ rateLimit: { limit: 50, windowMs: 1000 },
+ maxConcurrent: 10,
+});
+```
+
+Queue-level limits are checked before per-task limits in the scheduler.
diff --git a/docs/content/docs/node/guides/core/scheduling.mdx b/docs/content/docs/node/guides/core/scheduling.mdx
new file mode 100644
index 00000000..15ec121c
--- /dev/null
+++ b/docs/content/docs/node/guides/core/scheduling.mdx
@@ -0,0 +1,35 @@
+---
+title: Scheduling (cron)
+description: "Register periodic tasks on a cron expression; a worker fires them when due."
+---
+
+Schedule a registered task on a cron expression. A running worker enqueues it
+when due — the scheduler's maintenance loop drives this, so no extra process is
+needed.
+
+```ts
+queue.task("digest", (date: string) => sendDigest(date));
+
+// cron is 6/7-field, seconds first: sec min hour day-of-month month day-of-week
+queue.registerPeriodic("daily-digest", "digest", "0 0 9 * * *", {
+ args: ["2026-06-16"],
+ timezone: "America/New_York",
+});
+```
+
+`registerPeriodic(name, taskName, cron, options?)` returns the next fire time
+(Unix ms). Re-registering the same `name` replaces the schedule.
+
+| Option | Description |
+|---|---|
+| `args` | Arguments passed to the task on each fire. |
+| `timezone` | IANA timezone for the cron expression (default UTC). |
+| `queue` | Queue to enqueue into. |
+
+
+ The cron field order is **seconds first** (`sec min hour dom mon dow`).
+ `"0 0 9 * * *"` is 09:00:00 daily, not every minute.
+
+
+For a one-off future run, use [`delayMs`](/node/guides/core/enqueue-options#delayed-jobs)
+instead of a periodic schedule.
diff --git a/docs/content/docs/node/guides/core/tasks.mdx b/docs/content/docs/node/guides/core/tasks.mdx
new file mode 100644
index 00000000..bc921cf0
--- /dev/null
+++ b/docs/content/docs/node/guides/core/tasks.mdx
@@ -0,0 +1,51 @@
+---
+title: Tasks
+description: "Register task functions and attach per-task execution config."
+---
+
+A task is a named function registered on the queue. The name is the contract:
+producers enqueue by name, workers execute the registered function.
+
+```ts
+queue.task("add", (a: number, b: number) => a + b);
+```
+
+Tasks may be sync or `async`. The return value is serialized and stored as the
+job result.
+
+## Per-task config
+
+The optional third argument configures execution for every job of that task:
+
+```ts
+queue.task("add", (a: number, b: number) => a + b, {
+ maxRetries: 3,
+ retryBackoff: { baseMs: 1000, maxMs: 60_000 },
+ timeoutMs: 30_000,
+ maxConcurrent: 4,
+ rateLimit: { limit: 100, windowMs: 60_000 },
+ circuitBreaker: { threshold: 5, windowMs: 60_000, cooldownMs: 30_000 },
+});
+```
+
+| Option | Description |
+|---|---|
+| `maxRetries` | Attempts before dead-lettering. See [retries](/node/guides/reliability/retries). |
+| `retryBackoff` | Exponential backoff bounds (`baseMs`, `maxMs`). |
+| `timeoutMs` | Per-attempt [timeout](/node/guides/reliability/timeouts). |
+| `maxConcurrent` | Max simultaneously-running jobs of this task ([concurrency](/node/guides/reliability/concurrency)). |
+| `rateLimit` | Token-bucket [rate limit](/node/guides/reliability/rate-limiting). |
+| `circuitBreaker` | Trip after repeated failures ([circuit breakers](/node/guides/reliability/circuit-breakers)). |
+
+
+ Register a task before enqueuing or running a worker for it. Per-task config
+ is applied to the scheduler at registration time — re-registering replaces it.
+
+
+## Configure the queue or a queue name
+
+Beyond per-task config, you can set defaults for an entire named queue:
+
+```ts
+queue.configureQueue("emails", { rateLimit: { limit: 50, windowMs: 1000 } });
+```
diff --git a/docs/content/docs/node/guides/core/workers.mdx b/docs/content/docs/node/guides/core/workers.mdx
new file mode 100644
index 00000000..d33fabf0
--- /dev/null
+++ b/docs/content/docs/node/guides/core/workers.mdx
@@ -0,0 +1,41 @@
+---
+title: Workers
+description: "Run, scope, and stop workers; sync vs async dispatch."
+---
+
+A worker polls storage, claims due jobs, dispatches them to registered task
+functions, and writes results back.
+
+```ts
+const worker = queue.runWorker({ queues: ["default"] });
+// ... later
+worker.stop(); // drains and shuts down the scheduler + heartbeat
+```
+
+`runWorker` returns immediately; the worker runs in the background on the Rust
+core. A worker registers itself and heartbeats every 5 s, so it appears on the
+[dashboard](/node/guides/operations/dashboard) Workers panel; `stop()`
+unregisters it.
+
+## Sync vs async tasks
+
+- **Sync** task functions run on an OS-thread pool.
+- **`async`** task functions run on a native async pool — no thread per job, no
+ blocking for I/O-bound work. The dispatcher awaits the returned promise.
+
+```ts
+queue.task("fetch", async (url: string) => (await fetch(url)).text());
+```
+
+## Options
+
+| Option | Description |
+|---|---|
+| `queues` | Queue names to serve (default `["default"]`). |
+| `advanceWorkflows` | Drive [workflow](/node/guides/workflows) bookkeeping (default `true`; set `false` on workers that never process steps). |
+| `mesh` | Join a work-stealing [mesh](/node/guides/operations/mesh). |
+
+
+ Producers and workers only share storage. Enqueue from a web process and run
+ workers from a separate process pointed at the same `dbPath` / DSN.
+
From 0397da224b6a237a5809b776b4665e93bd267543 Mon Sep 17 00:00:00 2001
From: Pratyush Sharma <56130065+pratyush618@users.noreply.github.com>
Date: Sun, 21 Jun 2026 11:19:17 +0530
Subject: [PATCH 31/48] =?UTF-8?q?docs(node):=20reliability=20guides=20?=
=?UTF-8?q?=E2=80=94=20retries,=20locks,=20DLQ,=20breakers?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
.../guides/reliability/circuit-breakers.mdx | 29 ++++++++++++++
.../node/guides/reliability/concurrency.mdx | 27 +++++++++++++
.../node/guides/reliability/dead-letter.mdx | 34 ++++++++++++++++
.../node/guides/reliability/idempotency.mdx | 40 +++++++++++++++++++
.../docs/node/guides/reliability/locks.mdx | 38 ++++++++++++++++++
.../docs/node/guides/reliability/meta.json | 1 +
.../node/guides/reliability/rate-limiting.mdx | 33 +++++++++++++++
.../docs/node/guides/reliability/retries.mdx | 36 +++++++++++++++++
.../docs/node/guides/reliability/timeouts.mdx | 28 +++++++++++++
9 files changed, 266 insertions(+)
create mode 100644 docs/content/docs/node/guides/reliability/circuit-breakers.mdx
create mode 100644 docs/content/docs/node/guides/reliability/concurrency.mdx
create mode 100644 docs/content/docs/node/guides/reliability/dead-letter.mdx
create mode 100644 docs/content/docs/node/guides/reliability/idempotency.mdx
create mode 100644 docs/content/docs/node/guides/reliability/locks.mdx
create mode 100644 docs/content/docs/node/guides/reliability/meta.json
create mode 100644 docs/content/docs/node/guides/reliability/rate-limiting.mdx
create mode 100644 docs/content/docs/node/guides/reliability/retries.mdx
create mode 100644 docs/content/docs/node/guides/reliability/timeouts.mdx
diff --git a/docs/content/docs/node/guides/reliability/circuit-breakers.mdx b/docs/content/docs/node/guides/reliability/circuit-breakers.mdx
new file mode 100644
index 00000000..84ab45a9
--- /dev/null
+++ b/docs/content/docs/node/guides/reliability/circuit-breakers.mdx
@@ -0,0 +1,29 @@
+---
+title: Circuit breakers
+description: "Trip a task after repeated failures to shed load on a failing dependency."
+---
+
+A circuit breaker stops dispatching a task after it fails too often in a window,
+giving a failing downstream dependency time to recover instead of hammering it.
+
+```ts
+queue.task("call_flaky_api", callApi, {
+ circuitBreaker: { threshold: 5, windowMs: 60_000, cooldownMs: 30_000 },
+});
+```
+
+| Field | Description |
+|---|---|
+| `threshold` | Failures within `windowMs` that trip the breaker. |
+| `windowMs` | Rolling window for counting failures. |
+| `cooldownMs` | How long the breaker stays open before a trial dispatch. |
+
+While **open**, jobs of that task are held rather than dispatched. After
+`cooldownMs` the breaker half-opens and lets a job through; success closes it,
+failure re-opens it.
+
+
+ Pair with [retries](/node/guides/reliability/retries): retries handle
+ transient blips on a healthy dependency; the breaker handles a dependency
+ that is down, so you stop spending the retry budget on it.
+
diff --git a/docs/content/docs/node/guides/reliability/concurrency.mdx b/docs/content/docs/node/guides/reliability/concurrency.mdx
new file mode 100644
index 00000000..89d6da7a
--- /dev/null
+++ b/docs/content/docs/node/guides/reliability/concurrency.mdx
@@ -0,0 +1,27 @@
+---
+title: Concurrency
+description: "Cap simultaneously-running jobs per task or per queue."
+---
+
+`maxConcurrent` limits how many jobs of a task run at once across all workers —
+enforced by the scheduler against the live running count, so it holds even with
+many workers on shared storage.
+
+```ts
+queue.task("transcode", transcode, { maxConcurrent: 2 }); // never more than 2 at once
+```
+
+Over the limit, additional jobs stay `pending` and dispatch as running ones
+finish.
+
+Apply it to a whole queue:
+
+```ts
+queue.configureQueue("video", { maxConcurrent: 4 });
+```
+
+
+ Concurrency bounds *simultaneous* executions; [rate
+ limiting](/node/guides/reliability/rate-limiting) bounds *throughput over
+ time*. They compose — a task can be both `maxConcurrent: 2` and `100/min`.
+
diff --git a/docs/content/docs/node/guides/reliability/dead-letter.mdx b/docs/content/docs/node/guides/reliability/dead-letter.mdx
new file mode 100644
index 00000000..c502003f
--- /dev/null
+++ b/docs/content/docs/node/guides/reliability/dead-letter.mdx
@@ -0,0 +1,34 @@
+---
+title: Dead-letter queue
+description: "Inspect, retry, and purge jobs that exhausted their retries."
+---
+
+When a job exhausts its retries it moves to the **dead-letter queue** (DLQ) and
+the `job.dead` [event](/node/guides/extensibility/events) fires. The DLQ keeps
+the payload and error history so you can investigate and replay.
+
+```ts
+const dead = queue.deadLetters(); // dead-letter entries
+queue.retryDead(deadId); // re-enqueue (preserves notes/metadata)
+queue.deleteDead(deadId); // drop one entry
+queue.purgeDead(olderThanMs); // bulk-drop entries older than a cutoff
+```
+
+Inspect why a job failed:
+
+```ts
+queue.getJobErrors(jobId); // per-attempt error history
+```
+
+From the CLI:
+
+```bash
+taskito --db taskito.db dlq list
+taskito --db taskito.db dlq retry
+```
+
+
+ A retried dead job re-enters as `pending` with a fresh retry budget. Notes and
+ metadata survive the DLQ round-trip, so context attached at enqueue is
+ preserved through replay.
+
diff --git a/docs/content/docs/node/guides/reliability/idempotency.mdx b/docs/content/docs/node/guides/reliability/idempotency.mdx
new file mode 100644
index 00000000..ffd7d74a
--- /dev/null
+++ b/docs/content/docs/node/guides/reliability/idempotency.mdx
@@ -0,0 +1,40 @@
+---
+title: Idempotency
+description: "Dedupe concurrent enqueues with a uniqueKey; design tasks to re-run safely."
+---
+
+## Deduping enqueues
+
+A `uniqueKey` makes a duplicate enqueue a **no-op** while the first job for that
+key is still pending or running:
+
+```ts
+queue.enqueue("welcome", [user.id], { uniqueKey: `welcome:${user.id}` });
+queue.enqueue("welcome", [user.id], { uniqueKey: `welcome:${user.id}` }); // ignored
+```
+
+Backed by a partial unique index in the store, so the dedup is atomic across
+producers and processes. Once the first job finishes, the key frees up.
+
+## Idempotent tasks
+
+Separately from enqueue dedup, **task functions should be safe to run more than
+once**. At-least-once delivery means a crash after a side effect but before the
+result write will re-execute the task on recovery (the stale reaper re-enqueues
+it).
+
+```ts
+queue.task("charge", async (order: Order) => {
+ // key the external effect on a stable id so a re-run is a no-op
+ await stripe.charges.create(
+ { amount: order.total, customer: order.customer },
+ { idempotencyKey: order.id },
+ );
+});
+```
+
+
+ Use the provider's idempotency key (Stripe, etc.), an upsert, or a "already
+ done?" check at the top of the task. See the
+ [failure model](/architecture/failure-model) for the exact re-run windows.
+
diff --git a/docs/content/docs/node/guides/reliability/locks.mdx b/docs/content/docs/node/guides/reliability/locks.mdx
new file mode 100644
index 00000000..35b33252
--- /dev/null
+++ b/docs/content/docs/node/guides/reliability/locks.mdx
@@ -0,0 +1,38 @@
+---
+title: Distributed locks
+description: "TTL-bounded, owner-scoped locks backed by the queue's storage."
+---
+
+Coordinate across processes without a separate lock server. Locks are
+TTL-bounded and owner-scoped, backed by the queue's storage. A held lock
+auto-extends at `ttlMs / 3`, so a slow critical section never loses it.
+
+## Scoped helper
+
+`withLock` acquires, runs, and releases — throwing if the lock is held
+elsewhere:
+
+```ts
+await queue.withLock("report:2026-06", async () => {
+ await rebuildReport();
+});
+```
+
+## Manual handle
+
+```ts
+using lock = queue.lock("resource", { ttlMs: 30_000 });
+if (lock.acquire()) {
+ // ... critical section
+} // released at block exit (via `using`)
+```
+
+`lock.extend(ms)`, `lock.info()`, and `lock.ownerId` round out the API. With
+`using`, the lock releases automatically when the block exits; otherwise call
+`lock.release()`.
+
+
+ Expired locks are reaped by the worker's maintenance loop, so a crashed owner
+ never holds a lock past its TTL. Choose a `ttlMs` comfortably longer than the
+ protected work's worst case.
+
diff --git a/docs/content/docs/node/guides/reliability/meta.json b/docs/content/docs/node/guides/reliability/meta.json
new file mode 100644
index 00000000..f49fcbcc
--- /dev/null
+++ b/docs/content/docs/node/guides/reliability/meta.json
@@ -0,0 +1 @@
+{ "title": "Reliability", "pages": ["retries", "timeouts", "idempotency", "rate-limiting", "concurrency", "circuit-breakers", "dead-letter", "locks"] }
diff --git a/docs/content/docs/node/guides/reliability/rate-limiting.mdx b/docs/content/docs/node/guides/reliability/rate-limiting.mdx
new file mode 100644
index 00000000..8f9b3511
--- /dev/null
+++ b/docs/content/docs/node/guides/reliability/rate-limiting.mdx
@@ -0,0 +1,33 @@
+---
+title: Rate limiting
+description: "Token-bucket limits per task or per queue."
+---
+
+Cap how often a task runs with a token-bucket rate limit. When the bucket is
+empty, the scheduler reschedules the job slightly into the future rather than
+failing it.
+
+```ts
+queue.task("call_api", callApi, {
+ rateLimit: { limit: 100, windowMs: 60_000 }, // 100 / minute
+});
+```
+
+Apply a limit to a whole queue instead:
+
+```ts
+queue.configureQueue("emails", { rateLimit: { limit: 50, windowMs: 1000 } });
+```
+
+| Field | Description |
+|---|---|
+| `limit` | Tokens (executions) per window. |
+| `windowMs` | Window length in milliseconds. |
+
+Queue-level limits are evaluated before per-task limits. Rate-limited jobs stay
+`pending` and retry on the next tick — they do not consume the retry budget.
+
+
+ Rate limiting throttles *throughput*; to bound *simultaneous* executions use
+ [concurrency](/node/guides/reliability/concurrency).
+
diff --git a/docs/content/docs/node/guides/reliability/retries.mdx b/docs/content/docs/node/guides/reliability/retries.mdx
new file mode 100644
index 00000000..a6dab9d3
--- /dev/null
+++ b/docs/content/docs/node/guides/reliability/retries.mdx
@@ -0,0 +1,36 @@
+---
+title: Retries
+description: "Automatic retries with exponential backoff before dead-lettering."
+---
+
+A task that throws is retried up to `maxRetries` times before it dead-letters.
+Retries are scheduled with exponential backoff.
+
+```ts
+queue.task("charge", chargeCard, {
+ maxRetries: 5,
+ retryBackoff: { baseMs: 1000, maxMs: 60_000 },
+});
+```
+
+| Option | Description |
+|---|---|
+| `maxRetries` | Attempts after the first before dead-lettering. `0` = never retry. |
+| `retryBackoff.baseMs` | First backoff; doubles each attempt. |
+| `retryBackoff.maxMs` | Cap on the backoff delay. |
+
+Override per job at enqueue time:
+
+```ts
+queue.enqueue("charge", [order], { maxRetries: 1 });
+```
+
+The `job.retrying` [event](/node/guides/extensibility/events) fires on each
+retry; once exhausted, the job moves to the
+[dead-letter queue](/node/guides/reliability/dead-letter) and `job.dead` fires.
+
+
+ Retries re-run the whole task, so design tasks to be
+ [idempotent](/node/guides/reliability/idempotency) — a crash after a side
+ effect but before the result write will re-execute.
+
diff --git a/docs/content/docs/node/guides/reliability/timeouts.mdx b/docs/content/docs/node/guides/reliability/timeouts.mdx
new file mode 100644
index 00000000..a3b19baa
--- /dev/null
+++ b/docs/content/docs/node/guides/reliability/timeouts.mdx
@@ -0,0 +1,28 @@
+---
+title: Timeouts
+description: "Bound each execution attempt; timed-out jobs fail and may retry."
+---
+
+`timeoutMs` bounds a single execution attempt. The dispatcher races the task
+against the timeout (`tokio::time::timeout`); if it elapses, the attempt is
+marked failed and timed-out.
+
+```ts
+queue.task("scrape", scrape, { timeoutMs: 30_000 });
+
+queue.enqueue("scrape", [url], { timeoutMs: 10_000 }); // per-job override
+```
+
+A timeout counts as a failure: it consumes a retry and, if retries remain, the
+job is re-enqueued. When the budget is exhausted the job dead-letters with its
+`timedOut` flag set — surfaced to [middleware](/node/guides/extensibility/middleware)
+`onTimeout` and the Sentry/observability integrations.
+
+
+ For `async` tasks, the timeout aborts the task's
+ [`AbortSignal`](/node/guides/core/cancellation); honor it (e.g. pass `signal`
+ to `fetch`) so the underlying work actually stops, not just the bookkeeping.
+
+
+Always set a timeout on production tasks — without one, a wedged task can hold a
+worker slot indefinitely.
From 51abd0b85fb3f554333bb1bda70fe8a263618de5 Mon Sep 17 00:00:00 2001
From: Pratyush Sharma <56130065+pratyush618@users.noreply.github.com>
Date: Sun, 21 Jun 2026 11:19:17 +0530
Subject: [PATCH 32/48] =?UTF-8?q?docs(node):=20extensibility=20=E2=80=94?=
=?UTF-8?q?=20events,=20middleware,=20webhooks,=20serializers?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
.../docs/node/guides/extensibility/events.mdx | 31 +++++++++++++++
.../docs/node/guides/extensibility/meta.json | 1 +
.../node/guides/extensibility/middleware.mdx | 39 +++++++++++++++++++
.../node/guides/extensibility/serializers.mdx | 38 ++++++++++++++++++
.../node/guides/extensibility/webhooks.mdx | 35 +++++++++++++++++
5 files changed, 144 insertions(+)
create mode 100644 docs/content/docs/node/guides/extensibility/events.mdx
create mode 100644 docs/content/docs/node/guides/extensibility/meta.json
create mode 100644 docs/content/docs/node/guides/extensibility/middleware.mdx
create mode 100644 docs/content/docs/node/guides/extensibility/serializers.mdx
create mode 100644 docs/content/docs/node/guides/extensibility/webhooks.mdx
diff --git a/docs/content/docs/node/guides/extensibility/events.mdx b/docs/content/docs/node/guides/extensibility/events.mdx
new file mode 100644
index 00000000..8c8b7386
--- /dev/null
+++ b/docs/content/docs/node/guides/extensibility/events.mdx
@@ -0,0 +1,31 @@
+---
+title: Events
+description: "Subscribe to job lifecycle events emitted from the worker."
+---
+
+Subscribe to job lifecycle events with `queue.on`. Events fire from the worker
+process after the core decides a job's outcome.
+
+```ts
+queue.on("job.completed", (e) => console.log("done", e.jobId));
+queue.on("job.dead", (e) => alertOps(e));
+```
+
+## Events
+
+| Event | When |
+|---|---|
+| `job.completed` | A job finished successfully. |
+| `job.retrying` | A failed job is being retried. |
+| `job.dead` | A job exhausted its retries and dead-lettered. |
+| `job.cancelled` | A job was cancelled. |
+
+Each event payload carries the `jobId`, `taskName`, `queue`, and outcome
+details (error, retry count, `timedOut`).
+
+
+ Events are fire-and-forget notifications. To *wrap* execution (timing,
+ context, error transformation) use [middleware](/node/guides/extensibility/middleware);
+ to deliver events to external HTTP endpoints use
+ [webhooks](/node/guides/extensibility/webhooks).
+
diff --git a/docs/content/docs/node/guides/extensibility/meta.json b/docs/content/docs/node/guides/extensibility/meta.json
new file mode 100644
index 00000000..0cdf2157
--- /dev/null
+++ b/docs/content/docs/node/guides/extensibility/meta.json
@@ -0,0 +1 @@
+{ "title": "Extensibility", "pages": ["events", "middleware", "webhooks", "serializers"] }
diff --git a/docs/content/docs/node/guides/extensibility/middleware.mdx b/docs/content/docs/node/guides/extensibility/middleware.mdx
new file mode 100644
index 00000000..87020f14
--- /dev/null
+++ b/docs/content/docs/node/guides/extensibility/middleware.mdx
@@ -0,0 +1,39 @@
+---
+title: Middleware
+description: "Wrap task execution with before/after/error and outcome hooks."
+---
+
+Register middleware to wrap execution and react to outcomes. The
+`before`/`after`/`onError` hooks wrap each attempt and are awaited; the outcome
+hooks fire after the core decides the result.
+
+```ts
+queue.use({
+ before: (ctx) => log.info("start", ctx.taskName),
+ after: (ctx, result) => log.info("ok", ctx.taskName),
+ onError: (ctx, err) => log.error("threw", ctx.taskName, err),
+ onRetry: (e) => metrics.inc("retry", e.taskName),
+ onDeadLetter: (e) => alertOps(e),
+});
+```
+
+## Hooks
+
+| Hook | When | Awaited |
+|---|---|---|
+| `before(ctx)` | Before each execution attempt. | yes |
+| `after(ctx, result)` | After a successful attempt. | yes |
+| `onError(ctx, err)` | When an attempt throws (before retry/dead decision). | yes |
+| `onRetry(e)` | After the core schedules a retry. | no |
+| `onDeadLetter(e)` | After a job dead-letters. | no |
+| `onTimeout(e)` | After an attempt times out. | no |
+
+`ctx` carries `taskName`, `jobId`, `queue`, and `retryCount`. Multiple
+middlewares run in registration order; `before` outermost-first, `after`
+in reverse.
+
+
+ Middleware wraps execution and can do async work in the hot path — keep it
+ light. The contrib [observability](/node/guides/integrations) integrations are
+ built as middleware.
+
diff --git a/docs/content/docs/node/guides/extensibility/serializers.mdx b/docs/content/docs/node/guides/extensibility/serializers.mdx
new file mode 100644
index 00000000..f69600d8
--- /dev/null
+++ b/docs/content/docs/node/guides/extensibility/serializers.mdx
@@ -0,0 +1,38 @@
+---
+title: Serializers
+description: "Pluggable arg/result serialization — JSON or msgpack."
+---
+
+Arguments and results are serialized with a pluggable `Serializer`. The Rust
+core treats payloads as opaque bytes, so the serializer is purely a Node
+concern.
+
+- `JsonSerializer` — default; human-readable, debuggable.
+- `MsgpackSerializer` — compact binary, smaller payloads.
+
+```ts
+import { Queue, MsgpackSerializer } from "taskito";
+
+new Queue({ dbPath: "taskito.db", serializer: new MsgpackSerializer() });
+```
+
+## Custom serializer
+
+Implement the `Serializer` interface — `dumps` to bytes, `loads` back:
+
+```ts
+import type { Serializer } from "taskito";
+
+const mySerializer: Serializer = {
+ dumps: (value) => Buffer.from(JSON.stringify(value)),
+ loads: (bytes) => JSON.parse(Buffer.from(bytes).toString()),
+};
+
+new Queue({ dbPath: "taskito.db", serializer: mySerializer });
+```
+
+
+ Producers and workers must agree on the serializer — they exchange bytes
+ through storage. A job enqueued with msgpack can only be decoded by a worker
+ using a compatible serializer.
+
diff --git a/docs/content/docs/node/guides/extensibility/webhooks.mdx b/docs/content/docs/node/guides/extensibility/webhooks.mdx
new file mode 100644
index 00000000..74babad8
--- /dev/null
+++ b/docs/content/docs/node/guides/extensibility/webhooks.mdx
@@ -0,0 +1,35 @@
+---
+title: Webhooks
+description: "Deliver job events to HTTP endpoints — signed, retried, persisted."
+---
+
+Deliver job events to HTTP endpoints. Deliveries are HMAC-SHA256 signed, retried
+with backoff, and persisted across restarts.
+
+```ts
+const hook = queue.webhooks.create({
+ url: "https://hooks.example.com/jobs",
+ events: ["job.dead", "job.completed"], // omit for all
+ secret: process.env.WEBHOOK_SECRET, // signs X-Taskito-Signature: sha256=...
+ taskFilter: ["send_email"], // optional
+});
+
+queue.webhooks.list();
+queue.webhooks.delete(hook.id);
+```
+
+| Field | Description |
+|---|---|
+| `url` | Endpoint to POST events to. |
+| `events` | Event names to deliver (omit for all). |
+| `secret` | Signs each delivery as `X-Taskito-Signature: sha256=...`. |
+| `taskFilter` | Only deliver for these task names. |
+
+Deliveries fire from the **worker process** (where events originate). Verify the
+signature on your endpoint by HMAC-ing the raw body with the shared secret.
+
+
+ The [dashboard](/node/guides/operations/dashboard) exposes `/api/webhooks` for
+ managing hooks. Failed deliveries retry with backoff and survive restarts
+ since they are persisted in storage.
+
From 6f698a976c2af878d5dcf2f8735ea8f2ee2ba64c Mon Sep 17 00:00:00 2001
From: Pratyush Sharma <56130065+pratyush618@users.noreply.github.com>
Date: Sun, 21 Jun 2026 11:19:17 +0530
Subject: [PATCH 33/48] =?UTF-8?q?docs(node):=20operations=20=E2=80=94=20ba?=
=?UTF-8?q?ckends,=20dashboard,=20mesh,=20cli,=20deploy?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
.../docs/node/guides/operations/backends.mdx | 30 ++++++++++++
.../docs/node/guides/operations/cli.mdx | 43 +++++++++++++++++
.../docs/node/guides/operations/dashboard.mdx | 38 +++++++++++++++
.../node/guides/operations/deployment.mdx | 40 ++++++++++++++++
.../node/guides/operations/inspection.mdx | 48 +++++++++++++++++++
.../docs/node/guides/operations/mesh.mdx | 34 +++++++++++++
.../docs/node/guides/operations/meta.json | 1 +
7 files changed, 234 insertions(+)
create mode 100644 docs/content/docs/node/guides/operations/backends.mdx
create mode 100644 docs/content/docs/node/guides/operations/cli.mdx
create mode 100644 docs/content/docs/node/guides/operations/dashboard.mdx
create mode 100644 docs/content/docs/node/guides/operations/deployment.mdx
create mode 100644 docs/content/docs/node/guides/operations/inspection.mdx
create mode 100644 docs/content/docs/node/guides/operations/mesh.mdx
create mode 100644 docs/content/docs/node/guides/operations/meta.json
diff --git a/docs/content/docs/node/guides/operations/backends.mdx b/docs/content/docs/node/guides/operations/backends.mdx
new file mode 100644
index 00000000..fed98238
--- /dev/null
+++ b/docs/content/docs/node/guides/operations/backends.mdx
@@ -0,0 +1,30 @@
+---
+title: Backends
+description: "SQLite, PostgreSQL, or Redis — same API, different storage."
+---
+
+The queue stores everything — jobs, results, schedules, locks, rate-limit state
+— in one backend. The API is identical across all three; only the constructor
+differs.
+
+```ts
+new Queue({ dbPath: "taskito.db" }); // SQLite (default)
+new Queue({ backend: "postgres", dsn: process.env.PG_URL, schema: "taskito" });
+new Queue({ backend: "redis", dsn: "redis://localhost", prefix: "taskito" });
+```
+
+| Backend | Use when | Notes |
+|---|---|---|
+| **SQLite** | Single host, simplest deploy | One file, WAL mode, no server. Bundled. |
+| **PostgreSQL** | Multiple hosts, durability | `SELECT ... FOR UPDATE SKIP LOCKED` dispatch; isolated `schema`. |
+| **Redis** | High throughput, ephemeral OK | JSON values + sorted sets; atomic Lua claims. |
+
+Postgres and Redis require the addon built with their cargo features —
+`build:native` enables `--features postgres,redis`, and the published prebuilt
+binaries include them.
+
+
+ Producers and workers must point at the same backend. SQLite is per-host
+ (shared file); Postgres/Redis let producers and workers run on different
+ machines against one shared store.
+
diff --git a/docs/content/docs/node/guides/operations/cli.mdx b/docs/content/docs/node/guides/operations/cli.mdx
new file mode 100644
index 00000000..29faa37f
--- /dev/null
+++ b/docs/content/docs/node/guides/operations/cli.mdx
@@ -0,0 +1,43 @@
+---
+title: CLI
+description: "Operate the queue from the terminal with the standalone taskito command."
+---
+
+A standalone `taskito` command (no Python) operates the queue from the terminal.
+Connect with `--db `, or `--backend`/`--dsn` for Postgres/Redis.
+
+```bash
+taskito --db taskito.db enqueue add '[2,3]'
+taskito --db taskito.db stats
+taskito --db taskito.db jobs --status failed
+taskito --db taskito.db dlq list
+taskito --db taskito.db dlq retry
+taskito --db taskito.db queues
+taskito --db taskito.db pause default
+taskito --db taskito.db cancel
+```
+
+Add `--json` to any read command for machine-readable output.
+
+## Running a worker
+
+`run` loads a module that exports a configured `Queue` and runs its worker:
+
+```bash
+taskito run ./app.js --queues default,emails
+```
+
+The module registers its tasks on the exported queue; `run` starts a worker
+over them. Use it as your container entrypoint for worker processes.
+
+## Serving the dashboard
+
+```bash
+taskito --db taskito.db dashboard --port 8787
+```
+
+
+ The CLI ships in the package `bin`. Commands operate over `--db`/`--backend`/
+ `--dsn`, except `run` and `dashboard`, which load your app module and serve
+ the [dashboard](/node/guides/operations/dashboard) respectively.
+
diff --git a/docs/content/docs/node/guides/operations/dashboard.mdx b/docs/content/docs/node/guides/operations/dashboard.mdx
new file mode 100644
index 00000000..93409abb
--- /dev/null
+++ b/docs/content/docs/node/guides/operations/dashboard.mdx
@@ -0,0 +1,38 @@
+---
+title: Dashboard
+description: "Serve the React dashboard over a Node queue — no Python."
+---
+
+The Node SDK serves the **same React dashboard** the Python SDK serves, over the
+queue — no Python required. Build the SPA assets once, then serve.
+
+```bash
+pnpm build:dashboard # builds the SPA into static/dashboard (one-time)
+taskito --db taskito.db dashboard --port 8787
+```
+
+Or programmatically:
+
+```ts
+import { Queue, serveDashboard } from "taskito";
+
+const queue = new Queue({ dbPath: "taskito.db" });
+const server = serveDashboard(queue, { port: 8787 });
+// ... server.close() to stop
+```
+
+It serves the SPA plus the `/api/*` REST contract over the queue:
+
+- stats, per-queue stats, paused queues
+- jobs + job detail, dead-letters (retry / delete)
+- metrics and time-series, workers
+- webhooks, workflow runs
+
+Auth runs **open** (localhost). To mount the dashboard inside an existing app
+instead, use the [Express](/node/guides/integrations/express#dashboard) or
+[Fastify](/node/guides/integrations/fastify) helpers.
+
+
+ `serveDashboard` needs the built SPA in `static/dashboard`
+ (`pnpm build:dashboard`). Pass `staticDir` to point at assets elsewhere.
+
diff --git a/docs/content/docs/node/guides/operations/deployment.mdx b/docs/content/docs/node/guides/operations/deployment.mdx
new file mode 100644
index 00000000..26d920f4
--- /dev/null
+++ b/docs/content/docs/node/guides/operations/deployment.mdx
@@ -0,0 +1,40 @@
+---
+title: Deployment
+description: "Process model, shared storage, and graceful shutdown in production."
+---
+
+## Process model
+
+Producers and workers are separate processes that share storage. A typical
+deploy:
+
+- **Web / API process** — constructs a `Queue` and calls `enqueue`.
+- **Worker process(es)** — `taskito run ./app.js` (or `queue.runWorker()`),
+ pointed at the same backend.
+
+With SQLite, processes must share the file (same host / volume). With
+[Postgres or Redis](/node/guides/operations/backends), producers and workers
+can run on different machines.
+
+## Scaling
+
+Run more worker processes (or hosts) against one store to scale throughput —
+atomic claims keep jobs from double-running. Bound per-task load with
+[concurrency](/node/guides/reliability/concurrency) and
+[rate limits](/node/guides/reliability/rate-limiting). For locality across many
+workers, enable the [mesh](/node/guides/operations/mesh).
+
+## Graceful shutdown
+
+Stop the worker on a signal so in-flight jobs drain:
+
+```ts
+const worker = queue.runWorker();
+process.on("SIGTERM", () => worker.stop());
+```
+
+
+ Always set a [timeout](/node/guides/reliability/timeouts) on production tasks —
+ a crashed worker's `running` jobs are reaped and retried once their timeout
+ elapses. See the [failure model](/architecture/failure-model).
+
diff --git a/docs/content/docs/node/guides/operations/inspection.mdx b/docs/content/docs/node/guides/operations/inspection.mdx
new file mode 100644
index 00000000..c03c1c06
--- /dev/null
+++ b/docs/content/docs/node/guides/operations/inspection.mdx
@@ -0,0 +1,48 @@
+---
+title: Inspection & management
+description: "Stats, job listing, metrics, and queue pause/resume."
+---
+
+Read and manage queue state directly from the `Queue` handle.
+
+## Stats
+
+```ts
+queue.stats(); // { pending, running, completed, failed, dead, cancelled }
+queue.statsByQueue("default");
+queue.statsAllQueues();
+```
+
+## Jobs & metrics
+
+```ts
+queue.listJobs({ status: "failed", limit: 50 });
+queue.getJobErrors(id); // per-attempt error history
+queue.getMetrics(3600_000, "add"); // window (ms), optional task filter
+```
+
+`getMetrics(windowMs, task?)` returns per-task counts, success/failure split,
+and latency percentiles (p50/p95/p99) over the window.
+
+## Dead letters
+
+```ts
+queue.deadLetters();
+queue.retryDead(deadId);
+queue.deleteDead(deadId);
+queue.purgeDead(olderThanMs);
+queue.purgeCompleted(olderThanMs);
+```
+
+## Pause / resume
+
+```ts
+queue.pauseQueue("default");
+queue.resumeQueue("default");
+queue.listPausedQueues();
+```
+
+
+ The same data drives the [dashboard](/node/guides/operations/dashboard) and the
+ [CLI](/node/guides/operations/cli) read commands.
+
diff --git a/docs/content/docs/node/guides/operations/mesh.mdx b/docs/content/docs/node/guides/operations/mesh.mdx
new file mode 100644
index 00000000..857d6db8
--- /dev/null
+++ b/docs/content/docs/node/guides/operations/mesh.mdx
@@ -0,0 +1,34 @@
+---
+title: Mesh
+description: "Form a work-stealing overlay so idle workers pull from busy peers."
+---
+
+Workers can form a decentralized **mesh** — SWIM gossip for peer discovery,
+consistent-hash placement, and TCP work-stealing — so idle nodes pull work from
+busy ones. The database stays the source of truth; the mesh only optimizes
+dispatch locality.
+
+```ts
+queue.runWorker({
+ queues: ["default"],
+ mesh: {
+ port: 7946, // UDP gossip; TCP steal binds port + 1
+ seeds: ["10.0.0.2:7946"], // peers to join (empty = standalone)
+ steal: true,
+ encryptionKey: process.env.MESH_KEY, // optional XOR-encrypt gossip
+ },
+});
+```
+
+Other tunables: `bindAddr`, `advertiseAddr` (NAT), `affinityWeight`,
+`localBuffer`, `stealBatch`, `stealThreshold`, `virtualNodes`, `stealRateLimit`.
+
+Requires the addon built with the `mesh` cargo feature (`build:native` enables
+it; published prebuilts include it).
+
+
+ Mesh is an optimization, never a correctness dependency — atomic claims in
+ storage still guarantee exactly-once dispatch. See
+ [Mesh Scheduling](/architecture/mesh) for the SWIM/ring/work-stealing
+ internals (shared engine).
+
diff --git a/docs/content/docs/node/guides/operations/meta.json b/docs/content/docs/node/guides/operations/meta.json
new file mode 100644
index 00000000..59420dbe
--- /dev/null
+++ b/docs/content/docs/node/guides/operations/meta.json
@@ -0,0 +1 @@
+{ "title": "Operations", "pages": ["backends", "inspection", "dashboard", "mesh", "cli", "deployment"] }
From 75e57172005a2655b81930b38787f8d1db232004 Mon Sep 17 00:00:00 2001
From: Pratyush Sharma <56130065+pratyush618@users.noreply.github.com>
Date: Sun, 21 Jun 2026 11:19:17 +0530
Subject: [PATCH 34/48] docs(node): API reference
---
docs/content/docs/node/api-reference/cli.mdx | 34 ++++++++++
.../docs/node/api-reference/context.mdx | 33 ++++++++++
.../content/docs/node/api-reference/index.mdx | 18 ++++++
.../content/docs/node/api-reference/meta.json | 1 +
.../content/docs/node/api-reference/queue.mdx | 63 +++++++++++++++++++
.../docs/node/api-reference/result.mdx | 26 ++++++++
.../docs/node/api-reference/serializers.mdx | 35 +++++++++++
docs/content/docs/node/api-reference/task.mdx | 34 ++++++++++
.../docs/node/api-reference/worker.mdx | 38 +++++++++++
.../docs/node/api-reference/workflows.mdx | 46 ++++++++++++++
10 files changed, 328 insertions(+)
create mode 100644 docs/content/docs/node/api-reference/cli.mdx
create mode 100644 docs/content/docs/node/api-reference/context.mdx
create mode 100644 docs/content/docs/node/api-reference/index.mdx
create mode 100644 docs/content/docs/node/api-reference/meta.json
create mode 100644 docs/content/docs/node/api-reference/queue.mdx
create mode 100644 docs/content/docs/node/api-reference/result.mdx
create mode 100644 docs/content/docs/node/api-reference/serializers.mdx
create mode 100644 docs/content/docs/node/api-reference/task.mdx
create mode 100644 docs/content/docs/node/api-reference/worker.mdx
create mode 100644 docs/content/docs/node/api-reference/workflows.mdx
diff --git a/docs/content/docs/node/api-reference/cli.mdx b/docs/content/docs/node/api-reference/cli.mdx
new file mode 100644
index 00000000..d14ae9f0
--- /dev/null
+++ b/docs/content/docs/node/api-reference/cli.mdx
@@ -0,0 +1,34 @@
+---
+title: CLI
+description: "The standalone taskito command."
+---
+
+```bash
+taskito [--db | --backend --dsn ] [args] [--json]
+```
+
+Connect with `--db` (SQLite) or `--backend`/`--dsn` (Postgres/Redis). `--json`
+on read commands prints machine-readable output.
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `enqueue ''` | Enqueue a job. |
+| `stats` | Overall queue stats. |
+| `jobs [--status ] [--limit ]` | List jobs. |
+| `queues` | Per-queue stats. |
+| `cancel ` | Request cancellation. |
+| `pause ` / `resume ` | Queue control. |
+| `dlq list` / `dlq retry ` / `dlq delete ` | Dead-letter ops. |
+| `run [--queues a,b]` | Load a module exporting a `Queue` and run its worker. |
+| `dashboard [--port ]` | Serve the [dashboard](/node/guides/operations/dashboard). |
+
+```bash
+taskito --db taskito.db enqueue add '[2,3]'
+taskito --db taskito.db jobs --status failed --json
+taskito run ./app.js --queues default,emails
+```
+
+The CLI ships in the package `bin`; see the [CLI guide](/node/guides/operations/cli)
+for the worker and dashboard entrypoints.
diff --git a/docs/content/docs/node/api-reference/context.mdx b/docs/content/docs/node/api-reference/context.mdx
new file mode 100644
index 00000000..10c8adce
--- /dev/null
+++ b/docs/content/docs/node/api-reference/context.mdx
@@ -0,0 +1,33 @@
+---
+title: Context
+description: "currentJob() — the running task's job context."
+---
+
+```ts
+import { currentJob } from "taskito";
+
+const job = currentJob(); // JobContext | undefined
+```
+
+Returns the running task's context, or `undefined` outside a task. Backed by
+`AsyncLocalStorage`, so it survives `await` boundaries within the task.
+
+## `JobContext`
+
+| Member | Type | Description |
+|---|---|---|
+| `jobId` | `string` | The running job's id. |
+| `signal` | `AbortSignal` | Aborted on cancel or timeout — pass to `fetch`/streams. |
+| `setProgress(n)` | `(0–100) => void` | Report progress for inspection / dashboard. |
+
+```ts
+queue.task("download", async (url: string) => {
+ const job = currentJob();
+ const res = await fetch(url, { signal: job?.signal });
+ job?.setProgress(100);
+ return res.text();
+});
+```
+
+See [Cancellation](/node/guides/core/cancellation) for the cooperative
+cancellation flow.
diff --git a/docs/content/docs/node/api-reference/index.mdx b/docs/content/docs/node/api-reference/index.mdx
new file mode 100644
index 00000000..4c07a1e0
--- /dev/null
+++ b/docs/content/docs/node/api-reference/index.mdx
@@ -0,0 +1,18 @@
+---
+title: API Reference
+description: "The Node.js SDK public surface — classes, methods, and the CLI."
+---
+
+The public API exported from the `taskito` barrel. Contrib helpers live under
+`taskito/contrib/*` (see [Integrations](/node/guides/integrations)).
+
+| Page | Covers |
+|---|---|
+| [Queue](/node/api-reference/queue) | Construct, enqueue, inspect, manage, locks, periodic, webhooks. |
+| [Task](/node/api-reference/task) | `queue.task` registration and per-task config. |
+| [Worker](/node/api-reference/worker) | `runWorker` options and the worker handle. |
+| [Result](/node/api-reference/result) | Awaiting results and the result waiter. |
+| [Context](/node/api-reference/context) | `currentJob()` — signal, progress, ids. |
+| [Serializers](/node/api-reference/serializers) | `JsonSerializer`, `MsgpackSerializer`, the `Serializer` interface. |
+| [Workflows](/node/api-reference/workflows) | The workflow builder + run handle. |
+| [CLI](/node/api-reference/cli) | The `taskito` command. |
diff --git a/docs/content/docs/node/api-reference/meta.json b/docs/content/docs/node/api-reference/meta.json
new file mode 100644
index 00000000..04724d64
--- /dev/null
+++ b/docs/content/docs/node/api-reference/meta.json
@@ -0,0 +1 @@
+{ "title": "API Reference", "root": true, "pages": ["index", "queue", "task", "worker", "result", "context", "serializers", "workflows", "cli"] }
diff --git a/docs/content/docs/node/api-reference/queue.mdx b/docs/content/docs/node/api-reference/queue.mdx
new file mode 100644
index 00000000..dc950ffe
--- /dev/null
+++ b/docs/content/docs/node/api-reference/queue.mdx
@@ -0,0 +1,63 @@
+---
+title: Queue
+description: "Construct a queue and the full producer/admin API."
+---
+
+```ts
+import { Queue } from "taskito";
+
+const queue = new Queue(options);
+```
+
+## Constructor options
+
+| Option | Type | Description |
+|---|---|---|
+| `dbPath` | `string` | SQLite file path (default backend). |
+| `backend` | `"sqlite" \| "postgres" \| "redis"` | Storage backend. |
+| `dsn` | `string` | Connection string for postgres/redis. |
+| `schema` | `string` | Postgres schema (default `taskito`). |
+| `prefix` | `string` | Redis key prefix. |
+| `serializer` | `Serializer` | Arg/result serializer (default `JsonSerializer`). |
+
+## Tasks & enqueue
+
+| Method | Description |
+|---|---|
+| `task(name, fn, config?)` | Register a task. See [Task](/node/api-reference/task). |
+| `configureQueue(name, config)` | Set per-queue rate limit / concurrency. |
+| `enqueue(task, args?, options?)` | Enqueue a job → job id. |
+| `enqueueMany(task, jobs[])` | Enqueue a batch. |
+
+## Results & cancellation
+
+| Method | Description |
+|---|---|
+| `result(id, { timeoutMs? })` | Await a job's result. |
+| `requestCancel(id)` | Abort a running job's signal. |
+| `cancelJob(id)` | Cancel a pending job. |
+
+## Inspection & management
+
+| Method | Description |
+|---|---|
+| `stats()` / `statsByQueue(q)` / `statsAllQueues()` | Counts by status. |
+| `listJobs(filter)` | List jobs. |
+| `getJobErrors(id)` | Per-attempt error history. |
+| `getMetrics(windowMs, task?)` | Aggregated metrics. |
+| `deadLetters()` / `retryDead(id)` / `deleteDead(id)` / `purgeDead(ms)` | DLQ ops. |
+| `purgeCompleted(ms)` | Drop old completed jobs. |
+| `pauseQueue(q)` / `resumeQueue(q)` / `listPausedQueues()` | Queue control. |
+| `listWorkers()` | Registered workers. |
+
+## Subsystems
+
+| Member | Description |
+|---|---|
+| `runWorker(options?)` | Start a [worker](/node/api-reference/worker). |
+| `on(event, handler)` | [Events](/node/guides/extensibility/events). |
+| `use(middleware)` | [Middleware](/node/guides/extensibility/middleware). |
+| `webhooks` | [Webhooks](/node/guides/extensibility/webhooks) manager. |
+| `workflows` | [Workflow](/node/api-reference/workflows) builder + queries. |
+| `lock(name, opts)` / `withLock(name, fn)` | [Distributed locks](/node/guides/reliability/locks). |
+| `registerPeriodic(name, task, cron, opts?)` | [Periodic tasks](/node/guides/core/scheduling). |
diff --git a/docs/content/docs/node/api-reference/result.mdx b/docs/content/docs/node/api-reference/result.mdx
new file mode 100644
index 00000000..fa42fa9a
--- /dev/null
+++ b/docs/content/docs/node/api-reference/result.mdx
@@ -0,0 +1,26 @@
+---
+title: Result
+description: "Awaiting job results."
+---
+
+```ts
+const value = await queue.result(id: string, options?: { timeoutMs?: number }): Promise;
+```
+
+Resolves with the task's return value once the job finishes. Rejects if the job
+dead-letters or the optional `timeoutMs` elapses before completion.
+
+```ts
+const id = queue.enqueue("add", [2, 3]);
+const sum = await queue.result(id); // 5
+const sum2 = await queue.result(id, { timeoutMs: 5000 }); // throws on timeout
+```
+
+The result is deserialized with the queue's
+[serializer](/node/api-reference/serializers). Any process sharing the storage
+can await a result by id — the waiter polls the store.
+
+
+ `result` is for awaiting one job. To scan many jobs or read outcomes in bulk,
+ use [`listJobs` / `getMetrics`](/node/guides/operations/inspection).
+
diff --git a/docs/content/docs/node/api-reference/serializers.mdx b/docs/content/docs/node/api-reference/serializers.mdx
new file mode 100644
index 00000000..f9eec93e
--- /dev/null
+++ b/docs/content/docs/node/api-reference/serializers.mdx
@@ -0,0 +1,35 @@
+---
+title: Serializers
+description: "JsonSerializer, MsgpackSerializer, and the Serializer interface."
+---
+
+```ts
+import { Queue, JsonSerializer, MsgpackSerializer } from "taskito";
+import type { Serializer } from "taskito";
+```
+
+## Built-ins
+
+| Class | Description |
+|---|---|
+| `JsonSerializer` | Default. Human-readable JSON bytes. |
+| `MsgpackSerializer` | Compact binary (msgpack). |
+
+```ts
+new Queue({ dbPath: "taskito.db", serializer: new MsgpackSerializer() });
+```
+
+## `Serializer` interface
+
+```ts
+interface Serializer {
+ dumps(value: unknown): Uint8Array | Buffer;
+ loads(bytes: Uint8Array): unknown;
+}
+```
+
+The Rust core treats payloads as opaque bytes; serialization is entirely
+Node-side. Producers and workers must use a compatible serializer.
+
+See the [Serializers guide](/node/guides/extensibility/serializers) for a custom
+implementation.
diff --git a/docs/content/docs/node/api-reference/task.mdx b/docs/content/docs/node/api-reference/task.mdx
new file mode 100644
index 00000000..87971e99
--- /dev/null
+++ b/docs/content/docs/node/api-reference/task.mdx
@@ -0,0 +1,34 @@
+---
+title: Task
+description: "queue.task registration and per-task configuration."
+---
+
+```ts
+queue.task(name: string, fn: (...args) => R | Promise, config?: TaskConfig): void
+```
+
+Registers a task. `fn` may be sync or `async`; its return value becomes the job
+result. Re-registering a name replaces the function and config.
+
+## `TaskConfig`
+
+| Field | Type | Description |
+|---|---|---|
+| `maxRetries` | `number` | Attempts before dead-lettering. |
+| `retryBackoff` | `{ baseMs, maxMs }` | Exponential backoff bounds. |
+| `timeoutMs` | `number` | Per-attempt timeout. |
+| `maxConcurrent` | `number` | Max simultaneous running jobs of this task. |
+| `rateLimit` | `{ limit, windowMs }` | Token-bucket rate limit. |
+| `circuitBreaker` | `{ threshold, windowMs, cooldownMs }` | Trip after repeated failures. |
+
+```ts
+queue.task("add", (a: number, b: number) => a + b, {
+ maxRetries: 3,
+ retryBackoff: { baseMs: 1000, maxMs: 60_000 },
+ timeoutMs: 30_000,
+ maxConcurrent: 4,
+});
+```
+
+See the [Tasks guide](/node/guides/core/tasks) for usage, and
+[Reliability](/node/guides/reliability/retries) for the semantics of each field.
diff --git a/docs/content/docs/node/api-reference/worker.mdx b/docs/content/docs/node/api-reference/worker.mdx
new file mode 100644
index 00000000..ad5c5e00
--- /dev/null
+++ b/docs/content/docs/node/api-reference/worker.mdx
@@ -0,0 +1,38 @@
+---
+title: Worker
+description: "runWorker options and the worker handle."
+---
+
+```ts
+const worker = queue.runWorker(options?: WorkerOptions): Worker;
+```
+
+Starts a background worker over the Rust core and returns a handle.
+
+## `WorkerOptions`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `queues` | `string[]` | `["default"]` | Queue names to serve. |
+| `advanceWorkflows` | `boolean` | `true` | Drive workflow bookkeeping. |
+| `mesh` | `MeshOptions` | — | Join a [mesh](/node/guides/operations/mesh). |
+
+## `MeshOptions`
+
+`port`, `seeds`, `steal`, `encryptionKey`, `bindAddr`, `advertiseAddr`,
+`affinityWeight`, `localBuffer`, `stealBatch`, `stealThreshold`, `virtualNodes`,
+`stealRateLimit`.
+
+## `Worker`
+
+| Method | Description |
+|---|---|
+| `stop()` | Drain and shut down the scheduler + heartbeat. |
+
+```ts
+const worker = queue.runWorker({ queues: ["default", "emails"] });
+process.on("SIGTERM", () => worker.stop());
+```
+
+The worker registers + heartbeats (5 s) so it appears on the dashboard Workers
+panel; `stop()` unregisters it.
diff --git a/docs/content/docs/node/api-reference/workflows.mdx b/docs/content/docs/node/api-reference/workflows.mdx
new file mode 100644
index 00000000..c0758260
--- /dev/null
+++ b/docs/content/docs/node/api-reference/workflows.mdx
@@ -0,0 +1,46 @@
+---
+title: Workflows
+description: "The workflow builder, run handle, and queries."
+---
+
+```ts
+queue.workflows
+ .define(name: string)
+ // ... steps ...
+ .submit(): WorkflowHandle;
+```
+
+## Builder steps
+
+| Method | Description |
+|---|---|
+| `step(name, task, opts?)` | A task node. `opts`: `after`, `args`, `queue`, `maxRetries`, `timeoutMs`, `priority`, `condition`, `compensate`. |
+| `fanOut(name, { after, task, itemsFrom })` | Expand into one child per item. |
+| `fanIn(name, { after, task })` | Collect children's results into an array. |
+| `gate(name, { after, timeoutMs?, onTimeout? })` | Pause for [approval](/node/guides/workflows/gates). |
+| `subWorkflow(name, { after, workflow })` | Run a child workflow as a node. |
+| `submit()` | Pre-enqueue the DAG → `WorkflowHandle`. |
+| `build()` | Build (don't submit) — for use as a sub-workflow. |
+
+`condition`: `"on_success"` (default) · `"on_failure"` · `"always"`.
+
+## `WorkflowHandle`
+
+| Member | Description |
+|---|---|
+| `runId` | The run's id. |
+| `wait()` | Resolves with the `WorkflowRun` when terminal. |
+| `nodes()` | Per-step status (fan-out parents carry `fanOutCount`). |
+
+## Queries
+
+```ts
+queue.workflows.list({ state: "running" });
+queue.workflows.children(runId); // spawned sub-workflow runs
+queue.workflows.approveGate(runId, "review");
+queue.workflows.rejectGate(runId, "review", reason);
+```
+
+See the [Workflows guides](/node/guides/workflows) for fan-out, conditions,
+gates, sub-workflows, and saga compensation. Requires the addon built with the
+`workflows` cargo feature.
From 799688978488a1554a95d69838a2709211c42ac6 Mon Sep 17 00:00:00 2001
From: Pratyush Sharma <56130065+pratyush618@users.noreply.github.com>
Date: Sun, 21 Jun 2026 11:19:17 +0530
Subject: [PATCH 35/48] fix(docs): remove Node link from top nav
---
docs/app/components/ui/site-nav.tsx | 1 -
1 file changed, 1 deletion(-)
diff --git a/docs/app/components/ui/site-nav.tsx b/docs/app/components/ui/site-nav.tsx
index 1114d0d4..f66df0c2 100644
--- a/docs/app/components/ui/site-nav.tsx
+++ b/docs/app/components/ui/site-nav.tsx
@@ -19,7 +19,6 @@ function GithubMark() {
const LINKS = [
{ label: "Getting Started", href: "/getting-started/installation" },
- { label: "Node", href: "/node" },
{ label: "Guides", href: "/guides" },
{ label: "Architecture", href: "/architecture" },
{ label: "API", href: "/api-reference" },
From e03ac3e41633f7abff475a87e668e4ab91c4f3d6 Mon Sep 17 00:00:00 2001
From: Pratyush Sharma <56130065+pratyush618@users.noreply.github.com>
Date: Sun, 21 Jun 2026 11:19:17 +0530
Subject: [PATCH 36/48] feat(docs): show shared Architecture group in Node
sidebar
---
docs/app/lib/nav.ts | 1 +
1 file changed, 1 insertion(+)
diff --git a/docs/app/lib/nav.ts b/docs/app/lib/nav.ts
index 9b037530..bc2e9ad2 100644
--- a/docs/app/lib/nav.ts
+++ b/docs/app/lib/nav.ts
@@ -92,6 +92,7 @@ export const PYTHON_SECTIONS = [
export const NODE_SECTIONS = [
"node/getting-started",
"node/guides",
+ "architecture",
"node/api-reference",
];
From 83a007afa9bce64f8b899ea385262655d15e5e41 Mon Sep 17 00:00:00 2001
From: Pratyush Sharma <56130065+pratyush618@users.noreply.github.com>
Date: Sun, 21 Jun 2026 11:19:17 +0530
Subject: [PATCH 37/48] docs: add Seq flow diagrams to key lifecycle pages
---
.../docs/guides/extensibility/events-webhooks.mdx | 10 ++++++++++
docs/content/docs/guides/reliability/locking.mdx | 10 ++++++++++
docs/content/docs/node/getting-started/concepts.mdx | 10 ++++++++++
docs/content/docs/node/guides/core/cancellation.mdx | 10 ++++++++++
.../docs/node/guides/extensibility/webhooks.mdx | 10 ++++++++++
docs/content/docs/node/guides/reliability/locks.mdx | 10 ++++++++++
6 files changed, 60 insertions(+)
diff --git a/docs/content/docs/guides/extensibility/events-webhooks.mdx b/docs/content/docs/guides/extensibility/events-webhooks.mdx
index 3107f089..8922cadf 100644
--- a/docs/content/docs/guides/extensibility/events-webhooks.mdx
+++ b/docs/content/docs/guides/extensibility/events-webhooks.mdx
@@ -17,6 +17,16 @@ taskito has two complementary primitives for reacting to job lifecycle:
This guide covers both, starting with the events that drive them.
+
The architecture is engine-level and shared across SDKs — see
- [Architecture](/architecture/overview) for the job lifecycle, scheduler,
+ [Architecture](/python/architecture/overview) for the job lifecycle, scheduler,
storage schema, and mesh internals.
diff --git a/docs/content/docs/node/guides/operations/deployment.mdx b/docs/content/docs/node/guides/operations/deployment.mdx
index 26d920f4..9b92d950 100644
--- a/docs/content/docs/node/guides/operations/deployment.mdx
+++ b/docs/content/docs/node/guides/operations/deployment.mdx
@@ -36,5 +36,5 @@ process.on("SIGTERM", () => worker.stop());
Always set a [timeout](/node/guides/reliability/timeouts) on production tasks —
a crashed worker's `running` jobs are reaped and retried once their timeout
- elapses. See the [failure model](/architecture/failure-model).
+ elapses. See the [failure model](/python/architecture/failure-model).
diff --git a/docs/content/docs/node/guides/operations/mesh.mdx b/docs/content/docs/node/guides/operations/mesh.mdx
index 857d6db8..7320b3fb 100644
--- a/docs/content/docs/node/guides/operations/mesh.mdx
+++ b/docs/content/docs/node/guides/operations/mesh.mdx
@@ -29,6 +29,6 @@ it; published prebuilts include it).
Mesh is an optimization, never a correctness dependency — atomic claims in
storage still guarantee exactly-once dispatch. See
- [Mesh Scheduling](/architecture/mesh) for the SWIM/ring/work-stealing
+ [Mesh Scheduling](/python/architecture/mesh) for the SWIM/ring/work-stealing
internals (shared engine).
diff --git a/docs/content/docs/node/guides/reliability/idempotency.mdx b/docs/content/docs/node/guides/reliability/idempotency.mdx
index ffd7d74a..216eed4d 100644
--- a/docs/content/docs/node/guides/reliability/idempotency.mdx
+++ b/docs/content/docs/node/guides/reliability/idempotency.mdx
@@ -36,5 +36,5 @@ queue.task("charge", async (order: Order) => {
Use the provider's idempotency key (Stripe, etc.), an upsert, or a "already
done?" check at the top of the task. See the
- [failure model](/architecture/failure-model) for the exact re-run windows.
+ [failure model](/python/architecture/failure-model) for the exact re-run windows.
diff --git a/docs/content/docs/api-reference/batching.mdx b/docs/content/docs/python/api-reference/batching.mdx
similarity index 100%
rename from docs/content/docs/api-reference/batching.mdx
rename to docs/content/docs/python/api-reference/batching.mdx
diff --git a/docs/content/docs/api-reference/canvas.mdx b/docs/content/docs/python/api-reference/canvas.mdx
similarity index 97%
rename from docs/content/docs/api-reference/canvas.mdx
rename to docs/content/docs/python/api-reference/canvas.mdx
index b5e91f9e..1297d88c 100644
--- a/docs/content/docs/api-reference/canvas.mdx
+++ b/docs/content/docs/python/api-reference/canvas.mdx
@@ -94,7 +94,7 @@ chain.apply(queue: Queue | None = None) -> JobResult
```
Execute the chain by enqueuing and waiting for each step sequentially. Returns
-the [`JobResult`](/api-reference/result) of the **last** step.
+the [`JobResult`](/python/api-reference/result) of the **last** step.
Each step's return value is prepended to the next mutable signature's args.
Immutable signatures (`task.si()`) receive their args as-is.
@@ -154,7 +154,7 @@ group.apply(queue: Queue | None = None) -> list[JobResult]
```
Enqueue all signatures and return a list of
-[`JobResult`](/api-reference/result) handles. Jobs run concurrently
+[`JobResult`](/python/api-reference/result) handles. Jobs run concurrently
across available workers.
```python
@@ -209,7 +209,7 @@ chord.apply(queue: Queue | None = None) -> JobResult
Execute the group, wait for all results, then run the callback with the list
of results prepended to its args (unless immutable). Returns the
-[`JobResult`](/api-reference/result) of the callback.
+[`JobResult`](/python/api-reference/result) of the callback.
```python
@queue.task()
diff --git a/docs/content/docs/api-reference/cli.mdx b/docs/content/docs/python/api-reference/cli.mdx
similarity index 97%
rename from docs/content/docs/api-reference/cli.mdx
rename to docs/content/docs/python/api-reference/cli.mdx
index 03f7cb7a..9b146700 100644
--- a/docs/content/docs/api-reference/cli.mdx
+++ b/docs/content/docs/python/api-reference/cli.mdx
@@ -162,7 +162,7 @@ The server exposes three routes:
taskito scaler --app myapp:queue --port 9091 --target-queue-depth 5
```
-See the [KEDA Integration guide](/guides/operations) for Kubernetes deploy
+See the [KEDA Integration guide](/python/guides/operations) for Kubernetes deploy
templates.
### `taskito autoscale`
@@ -194,7 +194,7 @@ taskito autoscale --app [options]
taskito autoscale --app myapp.tasks:queue --min-workers 2 --max-workers 20
```
-See the [Autoscaler guide](/guides/operations/autoscaler) for deployment
+See the [Autoscaler guide](/python/guides/operations/autoscaler) for deployment
patterns and tuning advice.
## Error messages
diff --git a/docs/content/docs/api-reference/context.mdx b/docs/content/docs/python/api-reference/context.mdx
similarity index 94%
rename from docs/content/docs/api-reference/context.mdx
rename to docs/content/docs/python/api-reference/context.mdx
index 0a4487dd..541d2029 100644
--- a/docs/content/docs/api-reference/context.mdx
+++ b/docs/content/docs/python/api-reference/context.mdx
@@ -86,8 +86,8 @@ current_job.update_progress(progress: int) -> None
```
Update the job's progress percentage (0–100). The value is written directly to
-the database and can be read via [`job.progress`](/api-reference/result)
-or [`queue.get_job()`](/api-reference/queue/jobs).
+the database and can be read via [`job.progress`](/python/api-reference/result)
+or [`queue.get_job()`](/python/api-reference/queue/jobs).
```python
@queue.task()
@@ -116,7 +116,7 @@ current_job.publish(data: Any) -> None
```
Publish a partial result visible to
-[`job.stream()`](/api-reference/result) consumers. Use this to stream
+[`job.stream()`](/python/api-reference/result) consumers. Use this to stream
intermediate data from long-running tasks.
`data` must be JSON-serializable. It is stored as a task log entry with
diff --git a/docs/content/docs/api-reference/index.mdx b/docs/content/docs/python/api-reference/index.mdx
similarity index 82%
rename from docs/content/docs/api-reference/index.mdx
rename to docs/content/docs/python/api-reference/index.mdx
index 7ee5a0a7..db9be548 100644
--- a/docs/content/docs/api-reference/index.mdx
+++ b/docs/content/docs/python/api-reference/index.mdx
@@ -23,55 +23,55 @@ signature, parameters, return values, and a short example.
The Queue API is split across several pages for readability:
- - **[Job Management](/api-reference/queue/jobs)** — get, list, cancel, archive, replay jobs
- - **[Queue & Stats](/api-reference/queue/queues)** — rate limits, concurrency, pause/resume, statistics, dead letters
- - **[Workers & Hooks](/api-reference/queue/workers)** — run workers, lifecycle hooks, circuit breakers, async methods
- - **[Resources & Locking](/api-reference/queue/resources)** — resource system, distributed locks
- - **[Events & Logs](/api-reference/queue/events)** — event callbacks, webhooks, structured logs
+ - **[Job Management](/python/api-reference/queue/jobs)** — get, list, cancel, archive, replay jobs
+ - **[Queue & Stats](/python/api-reference/queue/queues)** — rate limits, concurrency, pause/resume, statistics, dead letters
+ - **[Workers & Hooks](/python/api-reference/queue/workers)** — run workers, lifecycle hooks, circuit breakers, async methods
+ - **[Resources & Locking](/python/api-reference/queue/resources)** — resource system, distributed locks
+ - **[Events & Logs](/python/api-reference/queue/events)** — event callbacks, webhooks, structured logs
## Constructor
@@ -54,7 +54,7 @@ Queue(
| `result_ttl` | `int \| None` | `None` | Auto-cleanup completed/dead jobs older than this many seconds. `None` disables. |
| `middleware` | `list[TaskMiddleware] \| None` | `None` | Queue-level middleware applied to all tasks. |
| `drain_timeout` | `int` | `30` | Seconds to wait for in-flight tasks during graceful shutdown. |
-| `interception` | `str` | `"off"` | Argument interception mode: `"strict"`, `"lenient"`, or `"off"`. See [Resource System](/guides/resources). |
+| `interception` | `str` | `"off"` | Argument interception mode: `"strict"`, `"lenient"`, or `"off"`. See [Resource System](/python/guides/resources). |
| `max_intercept_depth` | `int` | `10` | Max recursion depth for argument walking. |
| `recipe_signing_key` | `str \| None` | `None` | HMAC-SHA256 key for proxy recipe integrity. Falls back to `TASKITO_RECIPE_SECRET` env var. |
| `max_reconstruction_timeout` | `int` | `10` | Max seconds allowed for proxy reconstruction. |
@@ -92,7 +92,7 @@ Queue(
) -> TaskWrapper
```
-Register a function as a background task. Returns a [`TaskWrapper`](/api-reference/task).
+Register a function as a background task. Returns a [`TaskWrapper`](/python/api-reference/task).
| Parameter | Type | Default | Description |
|---|---|---|---|
@@ -109,7 +109,7 @@ Register a function as a background task. Returns a [`TaskWrapper`](/api-referen
| `circuit_breaker` | `dict \| None` | `None` | Circuit breaker config: `{"threshold": 5, "window": 60, "cooldown": 120}`. |
| `middleware` | `list[TaskMiddleware] \| None` | `None` | Per-task middleware, applied in addition to queue-level middleware. |
| `expires` | `float \| None` | `None` | Seconds until the job expires if not started. |
-| `inject` | `list[str] \| None` | `None` | Resource names to inject as keyword arguments. See [Resource System](/guides/resources). |
+| `inject` | `list[str] \| None` | `None` | Resource names to inject as keyword arguments. See [Resource System](/python/guides/resources). |
| `serializer` | `Serializer \| None` | `None` | Per-task serializer override. Falls back to queue-level serializer. |
| `max_concurrent` | `int \| None` | `None` | Max concurrent running instances. `None` = no limit. |
@@ -158,13 +158,13 @@ queue.enqueue(
) -> JobResult
```
-Enqueue a task for execution. Returns a [`JobResult`](/api-reference/result) handle.
+Enqueue a task for execution. Returns a [`JobResult`](/python/api-reference/result) handle.
| Parameter | Type | Default | Description |
|---|---|---|---|
| `metadata` | `str \| None` | `None` | Free-form JSON string blob. No size or shape constraint. |
-| `notes` | `dict \| None` | `None` | Structured annotations, max **15** top-level keys. See [Structured notes](/guides/observability/notes). |
-| `depends_on` | `str \| list[str] \| None` | `None` | Job ID(s) this job depends on. See [Dependencies](/guides/advanced-execution). |
+| `notes` | `dict \| None` | `None` | Structured annotations, max **15** top-level keys. See [Structured notes](/python/guides/observability/notes). |
+| `depends_on` | `str \| list[str] \| None` | `None` | Job ID(s) this job depends on. See [Dependencies](/python/guides/advanced-execution). |
### `queue.enqueue_many()`
@@ -201,7 +201,7 @@ uniform parameters (applied to all jobs) and per-job lists.
| `unique_keys` | `list[str \| None] \| None` | `None` | Per-job deduplication keys |
| `metadata` | `str \| None` | `None` | Uniform metadata JSON for all jobs |
| `metadata_list` | `list[str \| None] \| None` | `None` | Per-job metadata JSON |
-| `notes` | `dict \| None` | `None` | Uniform [structured notes](/guides/observability/notes) for all jobs (≤ 15 keys) |
+| `notes` | `dict \| None` | `None` | Uniform [structured notes](/python/guides/observability/notes) for all jobs (≤ 15 keys) |
| `notes_list` | `list[dict \| None] \| None` | `None` | Per-job structured notes (takes precedence over `notes`) |
| `expires` | `float \| None` | `None` | Uniform expiry in seconds for all jobs |
| `expires_list` | `list[float \| None] \| None` | `None` | Per-job expiry in seconds |
diff --git a/docs/content/docs/api-reference/queue/jobs.mdx b/docs/content/docs/python/api-reference/queue/jobs.mdx
similarity index 100%
rename from docs/content/docs/api-reference/queue/jobs.mdx
rename to docs/content/docs/python/api-reference/queue/jobs.mdx
diff --git a/docs/content/docs/api-reference/queue/meta.json b/docs/content/docs/python/api-reference/queue/meta.json
similarity index 100%
rename from docs/content/docs/api-reference/queue/meta.json
rename to docs/content/docs/python/api-reference/queue/meta.json
diff --git a/docs/content/docs/api-reference/queue/queues.mdx b/docs/content/docs/python/api-reference/queue/queues.mdx
similarity index 100%
rename from docs/content/docs/api-reference/queue/queues.mdx
rename to docs/content/docs/python/api-reference/queue/queues.mdx
diff --git a/docs/content/docs/api-reference/queue/resources.mdx b/docs/content/docs/python/api-reference/queue/resources.mdx
similarity index 99%
rename from docs/content/docs/api-reference/queue/resources.mdx
rename to docs/content/docs/python/api-reference/queue/resources.mdx
index fd183b8f..3e86104e 100644
--- a/docs/content/docs/api-reference/queue/resources.mdx
+++ b/docs/content/docs/python/api-reference/queue/resources.mdx
@@ -63,7 +63,7 @@ queue.load_resources(toml_path: str) -> None
```
Load resource definitions from a TOML file. Must be called before `run_worker()`.
-See [TOML configuration](/guides/resources).
+See [TOML configuration](/python/guides/resources).
### `queue.health_check()`
diff --git a/docs/content/docs/api-reference/queue/workers.mdx b/docs/content/docs/python/api-reference/queue/workers.mdx
similarity index 100%
rename from docs/content/docs/api-reference/queue/workers.mdx
rename to docs/content/docs/python/api-reference/queue/workers.mdx
diff --git a/docs/content/docs/api-reference/result.mdx b/docs/content/docs/python/api-reference/result.mdx
similarity index 90%
rename from docs/content/docs/api-reference/result.mdx
rename to docs/content/docs/python/api-reference/result.mdx
index d5de9a15..83611fa9 100644
--- a/docs/content/docs/api-reference/result.mdx
+++ b/docs/content/docs/python/api-reference/result.mdx
@@ -6,9 +6,9 @@ description: "Handle for an enqueued job — status polling, result retrieval, d
Handle to an enqueued job. Provides methods to check status and retrieve
results, both synchronously and asynchronously.
-Returned by [`task.delay()`](/api-reference/task),
-[`task.apply_async()`](/api-reference/task),
-[`queue.enqueue()`](/api-reference/queue), and canvas operations.
+Returned by [`task.delay()`](/python/api-reference/task),
+[`task.apply_async()`](/python/api-reference/task),
+[`queue.enqueue()`](/python/api-reference/queue), and canvas operations.
## Properties
@@ -45,7 +45,7 @@ job.progress -> int | None
```
Current progress (0–100) if reported by the task via
-[`current_job.update_progress()`](/api-reference/context). Returns `None`
+[`current_job.update_progress()`](/python/api-reference/context). Returns `None`
if no progress has been reported. Refreshes from the database.
### `job.error`
@@ -88,7 +88,7 @@ job.dependencies -> list[str]
```
List of job IDs this job depends on. Returns an empty list if the job has no
-dependencies. See [Dependencies](/guides/advanced-execution).
+dependencies. See [Dependencies](/python/guides/advanced-execution).
### `job.dependents`
@@ -108,8 +108,8 @@ job.to_dict() -> dict
```
Return all job fields as a plain dictionary. Useful for JSON serialization
-(e.g. in the [dashboard](/guides/observability) or
-[FastAPI integration](/guides/integrations)).
+(e.g. in the [dashboard](/python/guides/observability) or
+[FastAPI integration](/python/guides/integrations)).
### `job.result()`
@@ -192,7 +192,7 @@ job.stream(
```
Iterate over partial results published by the task via
-[`current_job.publish()`](/api-reference/context). Yields each result as
+[`current_job.publish()`](/python/api-reference/context). Yields each result as
it arrives, stops when the job reaches a terminal state.
| Parameter | Type | Default | Description |
diff --git a/docs/content/docs/api-reference/saga.mdx b/docs/content/docs/python/api-reference/saga.mdx
similarity index 100%
rename from docs/content/docs/api-reference/saga.mdx
rename to docs/content/docs/python/api-reference/saga.mdx
diff --git a/docs/content/docs/api-reference/task.mdx b/docs/content/docs/python/api-reference/task.mdx
similarity index 89%
rename from docs/content/docs/api-reference/task.mdx
rename to docs/content/docs/python/api-reference/task.mdx
index 271bee60..724226f9 100644
--- a/docs/content/docs/api-reference/task.mdx
+++ b/docs/content/docs/python/api-reference/task.mdx
@@ -26,7 +26,7 @@ task.delay(*args, **kwargs) -> JobResult
```
Enqueue the task for background execution using the decorator's default options.
-Returns a [`JobResult`](/api-reference/result) handle.
+Returns a [`JobResult`](/python/api-reference/result) handle.
```python
@queue.task(priority=5)
@@ -68,7 +68,7 @@ falls back to the decorator's default.
| `timeout` | `int \| None` | `None` | Override timeout in seconds |
| `unique_key` | `str \| None` | `None` | Deduplicate active jobs with same key |
| `metadata` | `str \| None` | `None` | Arbitrary JSON metadata to attach |
-| `depends_on` | `str \| list[str] \| None` | `None` | Job ID(s) this job depends on. See [Dependencies](/guides/advanced-execution). |
+| `depends_on` | `str \| list[str] \| None` | `None` | Job ID(s) this job depends on. See [Dependencies](/python/guides/advanced-execution). |
```python
job = send_email.apply_async(
@@ -102,8 +102,8 @@ print(results) # [3, 7, 11]
task.s(*args, **kwargs) -> Signature
```
-Create a **mutable** [`Signature`](/api-reference/canvas). In a
-[`chain`](/api-reference/canvas), the previous task's return value is
+Create a **mutable** [`Signature`](/python/api-reference/canvas). In a
+[`chain`](/python/api-reference/canvas), the previous task's return value is
prepended to `args`.
```python
@@ -118,7 +118,7 @@ sig = add.s(10)
task.si(*args, **kwargs) -> Signature
```
-Create an **immutable** [`Signature`](/api-reference/canvas). Ignores the
+Create an **immutable** [`Signature`](/python/api-reference/canvas). Ignores the
previous task's result — arguments are used as-is.
```python
diff --git a/docs/content/docs/api-reference/testing.mdx b/docs/content/docs/python/api-reference/testing.mdx
similarity index 100%
rename from docs/content/docs/api-reference/testing.mdx
rename to docs/content/docs/python/api-reference/testing.mdx
diff --git a/docs/content/docs/api-reference/workflows.mdx b/docs/content/docs/python/api-reference/workflows.mdx
similarity index 100%
rename from docs/content/docs/api-reference/workflows.mdx
rename to docs/content/docs/python/api-reference/workflows.mdx
diff --git a/docs/content/docs/architecture/failure-model.mdx b/docs/content/docs/python/architecture/failure-model.mdx
similarity index 94%
rename from docs/content/docs/architecture/failure-model.mdx
rename to docs/content/docs/python/architecture/failure-model.mdx
index a04f18fa..cfa6a2a9 100644
--- a/docs/content/docs/architecture/failure-model.mdx
+++ b/docs/content/docs/python/architecture/failure-model.mdx
@@ -35,7 +35,7 @@ Same behavior as database unavailable. The scheduler retries on the next poll cy
`claim_execution` prevents two workers from picking up the same job simultaneously.
But if a worker crashes *after* starting execution, the job will be retried —
potentially executing the same task twice. Design tasks to be
-[idempotent](/guides/reliability) to handle this safely.
+[idempotent](/python/guides/reliability) to handle this safely.
## Recovery timeline
@@ -46,7 +46,7 @@ potentially executing the same task twice. Design tasks to be
If a task completes successfully but the result write to the database fails (e.g.,
database full, connection lost), the job stays in `running` status. The stale reaper
eventually marks it failed and retries it. The task will execute again — make sure
-it's [idempotent](/guides/reliability).
+it's [idempotent](/python/guides/reliability).
## Jobs without timeouts
diff --git a/docs/content/docs/architecture/index.mdx b/docs/content/docs/python/architecture/index.mdx
similarity index 83%
rename from docs/content/docs/architecture/index.mdx
rename to docs/content/docs/python/architecture/index.mdx
index cf1b7869..3a93df9d 100644
--- a/docs/content/docs/architecture/index.mdx
+++ b/docs/content/docs/python/architecture/index.mdx
@@ -22,49 +22,49 @@ high-level model, then drill into the layer that interests you.
XOR encryption provides obfuscation, not cryptographic security. It
@@ -156,7 +156,7 @@ a configurable capacity (`local_buffer_capacity`, default 64):
/>
- **Prefetch**: the
- [scheduler](/architecture/scheduler) dequeues a batch from the DB and
+ [scheduler](/python/architecture/scheduler) dequeues a batch from the DB and
pushes into the deque via `push_sorted()`
- **Affinity sorting**: `push_sorted()` partitions the batch — non-owned
tasks go to the front (stealable), owned tasks to the back (hot)
@@ -247,8 +247,8 @@ after a period of queue emptiness.
## Integration with the scheduler
-The mesh does **not** modify the [`Scheduler`](/architecture/scheduler)
-struct or the [`WorkerDispatcher`](/architecture/worker-pool) trait.
+The mesh does **not** modify the [`Scheduler`](/python/architecture/scheduler)
+struct or the [`WorkerDispatcher`](/python/architecture/worker-pool) trait.
Instead, `run_worker` (in `crates/taskito-python/src/py_queue/worker.rs`)
spawns a **mesh bridge** — an intermediate `tokio::sync::mpsc` channel
between the scheduler and dispatcher:
@@ -288,7 +288,7 @@ values cloned atomically).
| Scenario | Behavior |
|---|---|
-| Gossip socket fails to bind | Warning logged, mesh disabled, [scheduler](/architecture/scheduler) runs normally |
+| Gossip socket fails to bind | Warning logged, mesh disabled, [scheduler](/python/architecture/scheduler) runs normally |
| Steal server fails to bind | Warning logged, stealing disabled, gossip + deque still work |
| All seeds unreachable | Worker operates standalone, retries on next protocol tick |
| Peer crashes | Detected in ~1.5s via SWIM, removed from ring |
@@ -299,12 +299,12 @@ values cloned atomically).
In every failure case, the database remains the source of truth. The worst
outcome is reduced performance (more DB polls), never data loss or
double-execution — those guarantees come from the
-[storage layer's](/architecture/storage) atomic claim mechanism.
+[storage layer's](/python/architecture/storage) atomic claim mechanism.
## See also
-- [Mesh Scheduling guide](/guides/operations/mesh) — configuration, cluster topology, Docker Compose example
-- [Scheduler](/architecture/scheduler) — the poll loop that feeds jobs into the mesh bridge
-- [Worker Pool](/architecture/worker-pool) — the dispatcher that receives jobs from the mesh bridge
-- [Storage](/architecture/storage) — atomic claim mechanism that guarantees exactly-once dispatch
-- [Failure Model](/architecture/failure-model) — how taskito handles crashes and timeouts
+- [Mesh Scheduling guide](/python/guides/operations/mesh) — configuration, cluster topology, Docker Compose example
+- [Scheduler](/python/architecture/scheduler) — the poll loop that feeds jobs into the mesh bridge
+- [Worker Pool](/python/architecture/worker-pool) — the dispatcher that receives jobs from the mesh bridge
+- [Storage](/python/architecture/storage) — atomic claim mechanism that guarantees exactly-once dispatch
+- [Failure Model](/python/architecture/failure-model) — how taskito handles crashes and timeouts
diff --git a/docs/content/docs/architecture/meta.json b/docs/content/docs/python/architecture/meta.json
similarity index 100%
rename from docs/content/docs/architecture/meta.json
rename to docs/content/docs/python/architecture/meta.json
diff --git a/docs/content/docs/python/architecture/overview.mdx b/docs/content/docs/python/architecture/overview.mdx
new file mode 100644
index 00000000..8f696711
--- /dev/null
+++ b/docs/content/docs/python/architecture/overview.mdx
@@ -0,0 +1,22 @@
+---
+title: Overview
+description: "Hybrid Python/Rust architecture: Python API on top, Rust engine underneath."
+---
+
+taskito is a hybrid Python/Rust system. Python provides the user-facing API. Rust
+handles all the heavy lifting: storage, scheduling, dispatch, rate limiting, and
+worker management.
+
+
- With [mesh scheduling](/architecture/mesh) enabled, a mesh bridge sits
+ With [mesh scheduling](/python/architecture/mesh) enabled, a mesh bridge sits
between the scheduler and the worker pool — buffering jobs in a local deque,
applying task affinity, and stealing from peers on idle ticks. The scheduler
itself is unchanged.
diff --git a/docs/content/docs/architecture/serialization.mdx b/docs/content/docs/python/architecture/serialization.mdx
similarity index 100%
rename from docs/content/docs/architecture/serialization.mdx
rename to docs/content/docs/python/architecture/serialization.mdx
diff --git a/docs/content/docs/architecture/storage.mdx b/docs/content/docs/python/architecture/storage.mdx
similarity index 96%
rename from docs/content/docs/architecture/storage.mdx
rename to docs/content/docs/python/architecture/storage.mdx
index e242c734..d585960c 100644
--- a/docs/content/docs/architecture/storage.mdx
+++ b/docs/content/docs/python/architecture/storage.mdx
@@ -40,7 +40,7 @@ per-connection).
## Postgres differences
taskito also supports PostgreSQL as an alternative storage backend. See the
-[Postgres backend guide](/guides/operations) for full details.
+[Postgres backend guide](/python/guides/operations) for full details.
- **Connection pooling**: `r2d2` pool with a default of 10 connections (vs. 8 for SQLite)
- **Schema isolation**: all tables are created inside a configurable PostgreSQL schema
diff --git a/docs/content/docs/architecture/worker-pool.mdx b/docs/content/docs/python/architecture/worker-pool.mdx
similarity index 100%
rename from docs/content/docs/architecture/worker-pool.mdx
rename to docs/content/docs/python/architecture/worker-pool.mdx
diff --git a/docs/content/docs/capabilities.mdx b/docs/content/docs/python/capabilities.mdx
similarity index 75%
rename from docs/content/docs/capabilities.mdx
rename to docs/content/docs/python/capabilities.mdx
index 4428da78..21ba0fd0 100644
--- a/docs/content/docs/capabilities.mdx
+++ b/docs/content/docs/python/capabilities.mdx
@@ -23,11 +23,11 @@ These are the capabilities most often assumed absent. They aren't.
| You might assume… | Reality |
| --- | --- |
-| No canvas / workflows — no chain, group, or chord | [`chain` / `group` / `chord`](/guides/workflows/canvas) are exported from the top-level package, backed by a full workflow DSL. |
-| No Flower-like dashboard | [`taskito dashboard --app myapp:queue`](/guides/dashboard) serves a built-in monitoring UI. |
-| No retry backoff or per-exception retries | [`max_retries`, `retry_backoff`, `retry_on`, `dont_retry_on`](/guides/reliability/retries) are arguments on every task. |
-| No soft timeouts | [`current_job.check_timeout()`](/guides/reliability/error-handling) gives cooperative soft timeouts. |
-| GIL bottleneck with no escape hatch | [`--pool prefork`](/guides/advanced-execution/prefork) runs child processes with independent GILs for true CPU parallelism. |
+| No canvas / workflows — no chain, group, or chord | [`chain` / `group` / `chord`](/python/guides/workflows/canvas) are exported from the top-level package, backed by a full workflow DSL. |
+| No Flower-like dashboard | [`taskito dashboard --app myapp:queue`](/python/guides/dashboard) serves a built-in monitoring UI. |
+| No retry backoff or per-exception retries | [`max_retries`, `retry_backoff`, `retry_on`, `dont_retry_on`](/python/guides/reliability/retries) are arguments on every task. |
+| No soft timeouts | [`current_job.check_timeout()`](/python/guides/reliability/error-handling) gives cooperative soft timeouts. |
+| GIL bottleneck with no escape hatch | [`--pool prefork`](/python/guides/advanced-execution/prefork) runs child processes with independent GILs for true CPU parallelism. |
## By capability
@@ -35,37 +35,37 @@ These are the capabilities most often assumed absent. They aren't.
diff --git a/docs/content/docs/getting-started/installation.mdx b/docs/content/docs/python/getting-started/installation.mdx
similarity index 89%
rename from docs/content/docs/getting-started/installation.mdx
rename to docs/content/docs/python/getting-started/installation.mdx
index fe3611b5..22fd0fb4 100644
--- a/docs/content/docs/getting-started/installation.mdx
+++ b/docs/content/docs/python/getting-started/installation.mdx
@@ -6,7 +6,7 @@ description: "Install taskito and prepare your environment."
import { Callout } from "fumadocs-ui/components/callout";
- See [**Capabilities at a glance**](/capabilities) for everything taskito does —
+ See [**Capabilities at a glance**](/python/capabilities) for everything taskito does —
workflows, retries, the dashboard, prefork pools — each with a link to its guide.
@@ -33,7 +33,7 @@ To use PostgreSQL as the storage backend instead of SQLite:
pip install taskito[postgres]
```
-See the [Postgres backend guide](/guides/operations) for configuration details.
+See the [Postgres backend guide](/python/guides/operations) for configuration details.
## From source
diff --git a/docs/content/docs/getting-started/meta.json b/docs/content/docs/python/getting-started/meta.json
similarity index 100%
rename from docs/content/docs/getting-started/meta.json
rename to docs/content/docs/python/getting-started/meta.json
diff --git a/docs/content/docs/getting-started/quickstart.mdx b/docs/content/docs/python/getting-started/quickstart.mdx
similarity index 83%
rename from docs/content/docs/getting-started/quickstart.mdx
rename to docs/content/docs/python/getting-started/quickstart.mdx
index 766ea480..31041fb1 100644
--- a/docs/content/docs/getting-started/quickstart.mdx
+++ b/docs/content/docs/python/getting-started/quickstart.mdx
@@ -122,12 +122,12 @@ taskito dashboard --app tasks:queue
Open `http://localhost:8080` in your browser. The dashboard includes pages
covering every aspect of your task queue — no extra dependencies needed.
-[Dashboard guide →](/guides/observability)
+[Dashboard guide →](/python/guides/observability)
## Next steps
-- [Tasks](/guides/core) — decorator options, `.delay()` vs `.apply_async()`
-- [Workers](/guides/core) — CLI flags, graceful shutdown, worker count
-- [Retries](/guides/reliability) — exponential backoff, dead letter queue
-- [Workflows](/guides/workflows) — chain, group, chord
-- [Testing](/guides/operations) — run tasks synchronously in tests with `queue.test_mode()`
+- [Tasks](/python/guides/core) — decorator options, `.delay()` vs `.apply_async()`
+- [Workers](/python/guides/core) — CLI flags, graceful shutdown, worker count
+- [Retries](/python/guides/reliability) — exponential backoff, dead letter queue
+- [Workflows](/python/guides/workflows) — chain, group, chord
+- [Testing](/python/guides/operations) — run tasks synchronously in tests with `queue.test_mode()`
diff --git a/docs/content/docs/guides/advanced-execution/async-tasks.mdx b/docs/content/docs/python/guides/advanced-execution/async-tasks.mdx
similarity index 100%
rename from docs/content/docs/guides/advanced-execution/async-tasks.mdx
rename to docs/content/docs/python/guides/advanced-execution/async-tasks.mdx
diff --git a/docs/content/docs/guides/advanced-execution/batch-enqueue.mdx b/docs/content/docs/python/guides/advanced-execution/batch-enqueue.mdx
similarity index 98%
rename from docs/content/docs/guides/advanced-execution/batch-enqueue.mdx
rename to docs/content/docs/python/guides/advanced-execution/batch-enqueue.mdx
index 392388ef..6fd84c48 100644
--- a/docs/content/docs/guides/advanced-execution/batch-enqueue.mdx
+++ b/docs/content/docs/python/guides/advanced-execution/batch-enqueue.mdx
@@ -43,7 +43,7 @@ jobs = queue.enqueue_many(
Per-job lists (`delay_list`, `metadata_list`, `expires_list`,
`result_ttl_list`) override uniform values when both are provided. See the
-[API reference](/api-reference/queue) for the full parameter list.
+[API reference](/python/api-reference/queue) for the full parameter list.
## Per-item results for batched tasks
diff --git a/docs/content/docs/guides/advanced-execution/dependencies.mdx b/docs/content/docs/python/guides/advanced-execution/dependencies.mdx
similarity index 100%
rename from docs/content/docs/guides/advanced-execution/dependencies.mdx
rename to docs/content/docs/python/guides/advanced-execution/dependencies.mdx
diff --git a/docs/content/docs/python/guides/advanced-execution/index.mdx b/docs/content/docs/python/guides/advanced-execution/index.mdx
new file mode 100644
index 00000000..addfcaba
--- /dev/null
+++ b/docs/content/docs/python/guides/advanced-execution/index.mdx
@@ -0,0 +1,15 @@
+---
+title: Advanced execution
+description: "Patterns for scaling and optimizing task execution."
+---
+
+Patterns for scaling and optimizing task execution.
+
+| Guide | Description |
+|---|---|
+| [Prefork Pool](/python/guides/advanced-execution/prefork) | Process-based isolation for CPU-bound or memory-leaking tasks |
+| [Native Async Tasks](/python/guides/advanced-execution/async-tasks) | `async def` tasks with native event loop integration |
+| [Result Streaming](/python/guides/advanced-execution/streaming) | Stream partial results and progress updates in real time |
+| [Dependencies](/python/guides/advanced-execution/dependencies) | DAG-based job dependencies — run tasks in order |
+| [Batch Enqueue](/python/guides/advanced-execution/batch-enqueue) | Enqueue many jobs efficiently with `task.map()` and `enqueue_many()` |
+| [Unique Tasks](/python/guides/advanced-execution/unique-tasks) | Deduplicate active jobs with unique keys |
diff --git a/docs/content/docs/guides/advanced-execution/meta.json b/docs/content/docs/python/guides/advanced-execution/meta.json
similarity index 100%
rename from docs/content/docs/guides/advanced-execution/meta.json
rename to docs/content/docs/python/guides/advanced-execution/meta.json
diff --git a/docs/content/docs/guides/advanced-execution/prefork.mdx b/docs/content/docs/python/guides/advanced-execution/prefork.mdx
similarity index 100%
rename from docs/content/docs/guides/advanced-execution/prefork.mdx
rename to docs/content/docs/python/guides/advanced-execution/prefork.mdx
diff --git a/docs/content/docs/guides/advanced-execution/streaming.mdx b/docs/content/docs/python/guides/advanced-execution/streaming.mdx
similarity index 100%
rename from docs/content/docs/guides/advanced-execution/streaming.mdx
rename to docs/content/docs/python/guides/advanced-execution/streaming.mdx
diff --git a/docs/content/docs/guides/advanced-execution/unique-tasks.mdx b/docs/content/docs/python/guides/advanced-execution/unique-tasks.mdx
similarity index 100%
rename from docs/content/docs/guides/advanced-execution/unique-tasks.mdx
rename to docs/content/docs/python/guides/advanced-execution/unique-tasks.mdx
diff --git a/docs/content/docs/guides/core/batching.mdx b/docs/content/docs/python/guides/core/batching.mdx
similarity index 95%
rename from docs/content/docs/guides/core/batching.mdx
rename to docs/content/docs/python/guides/core/batching.mdx
index ca8c1a50..94aae586 100644
--- a/docs/content/docs/guides/core/batching.mdx
+++ b/docs/content/docs/python/guides/core/batching.mdx
@@ -90,4 +90,4 @@ When not to use it:
- Tasks where per-item retry matters.
- Heterogeneous work that doesn't share the same downstream code path.
-See also the [`canvas.chunks()`](/guides/workflows/canvas) primitive — it's a producer-side equivalent that creates `N` separate jobs each holding a sub-list, with full per-chunk retry semantics.
+See also the [`canvas.chunks()`](/python/guides/workflows/canvas) primitive — it's a producer-side equivalent that creates `N` separate jobs each holding a sub-list, with full per-chunk retry semantics.
diff --git a/docs/content/docs/guides/core/execution-model.mdx b/docs/content/docs/python/guides/core/execution-model.mdx
similarity index 95%
rename from docs/content/docs/guides/core/execution-model.mdx
rename to docs/content/docs/python/guides/core/execution-model.mdx
index dd0cef9b..64040d3a 100644
--- a/docs/content/docs/guides/core/execution-model.mdx
+++ b/docs/content/docs/python/guides/core/execution-model.mdx
@@ -66,7 +66,7 @@ instance. It must be a module-level name (`"module:attribute"` format) —
tasks defined inside functions or closures cannot be imported by child
processes.
-For more details, see the [Prefork Pool guide](/guides/advanced-execution).
+For more details, see the [Prefork Pool guide](/python/guides/advanced-execution).
## Native async
@@ -90,7 +90,7 @@ queue = Queue(
)
```
-For more details, see the [Native Async Tasks guide](/guides/advanced-execution).
+For more details, see the [Native Async Tasks guide](/python/guides/advanced-execution).
## Mixing sync and async
diff --git a/docs/content/docs/python/guides/core/index.mdx b/docs/content/docs/python/guides/core/index.mdx
new file mode 100644
index 00000000..f3b4463d
--- /dev/null
+++ b/docs/content/docs/python/guides/core/index.mdx
@@ -0,0 +1,15 @@
+---
+title: Core
+description: "The building blocks of every taskito application."
+---
+
+The building blocks of every taskito application.
+
+| Guide | Description |
+|---|---|
+| [Tasks](/python/guides/core/tasks) | Define tasks with `@queue.task()`, configure retries, timeouts, and options |
+| [Workers](/python/guides/core/workers) | Start workers, control concurrency, graceful shutdown |
+| [Execution Models](/python/guides/core/execution-model) | How tasks move from enqueue to completion |
+| [Queues & Priority](/python/guides/core/queues) | Named queues, priority levels, and routing |
+| [Scheduling](/python/guides/core/scheduling) | Periodic tasks with cron expressions |
+| [Workflows](/python/guides/core/workflows) | Chains, groups, and chords for multi-step pipelines |
diff --git a/docs/content/docs/guides/core/meta.json b/docs/content/docs/python/guides/core/meta.json
similarity index 100%
rename from docs/content/docs/guides/core/meta.json
rename to docs/content/docs/python/guides/core/meta.json
diff --git a/docs/content/docs/guides/core/predicates.mdx b/docs/content/docs/python/guides/core/predicates.mdx
similarity index 100%
rename from docs/content/docs/guides/core/predicates.mdx
rename to docs/content/docs/python/guides/core/predicates.mdx
diff --git a/docs/content/docs/guides/core/queues.mdx b/docs/content/docs/python/guides/core/queues.mdx
similarity index 100%
rename from docs/content/docs/guides/core/queues.mdx
rename to docs/content/docs/python/guides/core/queues.mdx
diff --git a/docs/content/docs/guides/core/scheduling.mdx b/docs/content/docs/python/guides/core/scheduling.mdx
similarity index 100%
rename from docs/content/docs/guides/core/scheduling.mdx
rename to docs/content/docs/python/guides/core/scheduling.mdx
diff --git a/docs/content/docs/guides/core/tasks.mdx b/docs/content/docs/python/guides/core/tasks.mdx
similarity index 98%
rename from docs/content/docs/guides/core/tasks.mdx
rename to docs/content/docs/python/guides/core/tasks.mdx
index 31c311d1..534861c4 100644
--- a/docs/content/docs/guides/core/tasks.mdx
+++ b/docs/content/docs/python/guides/core/tasks.mdx
@@ -35,7 +35,7 @@ def process_data(data: dict) -> str:
| `circuit_breaker` | `dict \| None` | `None` | Circuit breaker config: `{"threshold": 5, "window": 60, "cooldown": 120}`. |
| `middleware` | `list[TaskMiddleware] \| None` | `None` | Per-task middleware, applied in addition to queue-level middleware. |
| `expires` | `float \| None` | `None` | Seconds until the job expires if not started. |
-| `inject` | `list[str] \| None` | `None` | Worker resource names to inject as keyword arguments. See [Resource System](/guides/resources). |
+| `inject` | `list[str] \| None` | `None` | Worker resource names to inject as keyword arguments. See [Resource System](/python/guides/resources). |
| `serializer` | `Serializer \| None` | `None` | Per-task serializer override. Falls back to the queue-level serializer. |
| `max_concurrent` | `int \| None` | `None` | Max concurrent running instances of this task. `None` means no limit. |
diff --git a/docs/content/docs/guides/core/workers.mdx b/docs/content/docs/python/guides/core/workers.mdx
similarity index 98%
rename from docs/content/docs/guides/core/workers.mdx
rename to docs/content/docs/python/guides/core/workers.mdx
index c6dcecc9..7d640980 100644
--- a/docs/content/docs/guides/core/workers.mdx
+++ b/docs/content/docs/python/guides/core/workers.mdx
@@ -274,7 +274,7 @@ queue = Queue(
)
```
-See [Native Async Tasks](/guides/advanced-execution) for the full guide.
+See [Native Async Tasks](/python/guides/advanced-execution) for the full guide.
## How workers work
@@ -304,6 +304,6 @@ See [Native Async Tasks](/guides/advanced-execution) for the full guide.
4. Results from both pools flow back through a **result channel** to the main loop
5. The main loop updates job status in SQLite (complete, retry, or DLQ)
-For multi-worker deployments, [mesh scheduling](/guides/operations/mesh)
+For multi-worker deployments, [mesh scheduling](/python/guides/operations/mesh)
adds gossip-based discovery, task affinity, and work-stealing between
workers.
diff --git a/docs/content/docs/guides/core/workflows.mdx b/docs/content/docs/python/guides/core/workflows.mdx
similarity index 60%
rename from docs/content/docs/guides/core/workflows.mdx
rename to docs/content/docs/python/guides/core/workflows.mdx
index 866dbec4..2b87f29e 100644
--- a/docs/content/docs/guides/core/workflows.mdx
+++ b/docs/content/docs/python/guides/core/workflows.mdx
@@ -4,10 +4,10 @@ description: "DAG workflows for multi-step pipelines and Canvas primitives for s
---
taskito provides two workflow models. See the dedicated
-[Workflows section](/guides/workflows) for full documentation.
+[Workflows section](/python/guides/workflows) for full documentation.
-- **[DAG Workflows](/guides/workflows)** — Multi-step pipelines as
+- **[DAG Workflows](/python/guides/workflows)** — Multi-step pipelines as
directed acyclic graphs with fan-out, conditions, gates, sub-workflows,
incremental caching, and visualization.
-- **[Canvas Primitives](/api-reference/canvas)** — Lightweight chain,
+- **[Canvas Primitives](/python/api-reference/canvas)** — Lightweight chain,
group, and chord composition for simple pipelines.
diff --git a/docs/content/docs/guides/dashboard/authentication.mdx b/docs/content/docs/python/guides/dashboard/authentication.mdx
similarity index 98%
rename from docs/content/docs/guides/dashboard/authentication.mdx
rename to docs/content/docs/python/guides/dashboard/authentication.mdx
index 6aa16fd7..1e333a26 100644
--- a/docs/content/docs/guides/dashboard/authentication.mdx
+++ b/docs/content/docs/python/guides/dashboard/authentication.mdx
@@ -155,7 +155,7 @@ guard on.
Native sign-in with Google, GitHub, and any OIDC-compliant provider
(Okta, Auth0, Keycloak, Microsoft Entra) is available alongside
-password auth — see [SSO (OAuth & OIDC)](/guides/dashboard/sso).
+password auth — see [SSO (OAuth & OIDC)](/python/guides/dashboard/sso).
Operators can mix-and-match providers or run an OAuth-only deployment
by setting `TASKITO_DASHBOARD_PASSWORD_AUTH_ENABLED=false`.
diff --git a/docs/content/docs/guides/dashboard/index.mdx b/docs/content/docs/python/guides/dashboard/index.mdx
similarity index 94%
rename from docs/content/docs/guides/dashboard/index.mdx
rename to docs/content/docs/python/guides/dashboard/index.mdx
index 4e5333c0..0bf4266f 100644
--- a/docs/content/docs/guides/dashboard/index.mdx
+++ b/docs/content/docs/python/guides/dashboard/index.mdx
@@ -69,7 +69,7 @@ taskito dashboard --app myapp:queue --host 0.0.0.0 --port 9000
On a fresh database the dashboard refuses every API request with
``503 setup_required`` until you create the first admin. See
- [Authentication](/guides/dashboard/authentication) for the full
+ [Authentication](/python/guides/dashboard/authentication) for the full
flow, including the env-var bootstrap path useful for managed
deployments.
@@ -93,12 +93,12 @@ Configuration (how to change it):
| Reliability | **Dead Letters** | Failed jobs that exhausted retries — retry or purge |
| Reliability | **Circuit Breakers** | Automatic failure protection state, thresholds, cooldowns |
| Reliability | **System** | Proxy reconstruction and interception strategy metrics |
-| Configuration | **Tasks** | Decorator defaults + runtime overrides per task ([guide](/guides/dashboard/task-overrides)) |
-| Configuration | **Webhooks** | HTTP event subscriptions with delivery history + replay ([guide](/guides/extensibility/events-webhooks)) |
+| Configuration | **Tasks** | Decorator defaults + runtime overrides per task ([guide](/python/guides/dashboard/task-overrides)) |
+| Configuration | **Webhooks** | HTTP event subscriptions with delivery history + replay ([guide](/python/guides/extensibility/events-webhooks)) |
| Configuration | **Settings** | Dashboard branding, external links, integrations |
The full REST API surface is documented at
-[Dashboard REST API](/guides/dashboard/rest-api).
+[Dashboard REST API](/python/guides/dashboard/rest-api).
## Design
@@ -138,7 +138,7 @@ first admin, every subsequent visit shows the sign-in form.
-See [Authentication](/guides/dashboard/authentication) for the env
+See [Authentication](/python/guides/dashboard/authentication) for the env
var-based bootstrap (`TASKITO_DASHBOARD_ADMIN_USER` /
`TASKITO_DASHBOARD_ADMIN_PASSWORD`) and the CSRF model.
@@ -158,7 +158,7 @@ The **Webhooks** page lists every HTTP endpoint subscribed to job
events. Add new endpoints with the **+ New webhook** button. Each row
has a dropdown menu — send a test event, enable/disable, rotate the
signing secret, or view the delivery history. Full guide:
-[Events & Webhooks](/guides/extensibility/events-webhooks).
+[Events & Webhooks](/python/guides/extensibility/events-webhooks).
@@ -169,7 +169,7 @@ defaults and any active runtime override. Click **Edit** to open a
side sheet with two tabs: **Overrides** (rate limit, concurrency,
retries, timeout, priority, paused) and **Middleware** (toggle each
middleware on or off for the task). Full guide:
-[Task & Queue Overrides](/guides/dashboard/task-overrides).
+[Task & Queue Overrides](/python/guides/dashboard/task-overrides).
diff --git a/docs/content/docs/guides/dashboard/meta.json b/docs/content/docs/python/guides/dashboard/meta.json
similarity index 100%
rename from docs/content/docs/guides/dashboard/meta.json
rename to docs/content/docs/python/guides/dashboard/meta.json
diff --git a/docs/content/docs/guides/dashboard/rest-api.mdx b/docs/content/docs/python/guides/dashboard/rest-api.mdx
similarity index 98%
rename from docs/content/docs/guides/dashboard/rest-api.mdx
rename to docs/content/docs/python/guides/dashboard/rest-api.mdx
index 77afabd4..7c4fc687 100644
--- a/docs/content/docs/guides/dashboard/rest-api.mdx
+++ b/docs/content/docs/python/guides/dashboard/rest-api.mdx
@@ -14,7 +14,7 @@ as the dashboard itself.
`/api/auth/login`, `/api/auth/setup`) requires a valid session cookie
obtained from `POST /api/auth/login`. State-changing requests
(POST/PUT/DELETE) additionally require a CSRF header. See
- [Dashboard Authentication](/guides/dashboard/authentication) for
+ [Dashboard Authentication](/python/guides/dashboard/authentication) for
the login flow and headless usage examples.
@@ -135,7 +135,7 @@ Purge all dead letters.
## Webhooks
-Full guide: [Events & Webhooks](/guides/extensibility/events-webhooks).
+Full guide: [Events & Webhooks](/python/guides/extensibility/events-webhooks).
### `GET /api/webhooks`
@@ -273,7 +273,7 @@ fresh delivery on top of the original (audit trail preserved).
## Tasks and overrides
-Full guide: [Task & Queue Overrides](/guides/dashboard/task-overrides).
+Full guide: [Task & Queue Overrides](/python/guides/dashboard/task-overrides).
### `GET /api/tasks`
diff --git a/docs/content/docs/guides/dashboard/sso.mdx b/docs/content/docs/python/guides/dashboard/sso.mdx
similarity index 100%
rename from docs/content/docs/guides/dashboard/sso.mdx
rename to docs/content/docs/python/guides/dashboard/sso.mdx
diff --git a/docs/content/docs/guides/dashboard/task-overrides.mdx b/docs/content/docs/python/guides/dashboard/task-overrides.mdx
similarity index 97%
rename from docs/content/docs/guides/dashboard/task-overrides.mdx
rename to docs/content/docs/python/guides/dashboard/task-overrides.mdx
index 4fe33da1..6fb7c0c3 100644
--- a/docs/content/docs/guides/dashboard/task-overrides.mdx
+++ b/docs/content/docs/python/guides/dashboard/task-overrides.mdx
@@ -217,6 +217,6 @@ queue.disable_middleware_for_task("myapp.tasks.process_image", "debug.payload")
## Reference
-- [Dashboard REST API: Tasks & overrides](/guides/dashboard/rest-api#tasks-and-overrides)
-- [Dashboard REST API: Middleware](/guides/dashboard/rest-api#middleware)
-- [Tasks decorator reference](/api-reference/task)
+- [Dashboard REST API: Tasks & overrides](/python/guides/dashboard/rest-api#tasks-and-overrides)
+- [Dashboard REST API: Middleware](/python/guides/dashboard/rest-api#middleware)
+- [Tasks decorator reference](/python/api-reference/task)
diff --git a/docs/content/docs/guides/extensibility/events-webhooks.mdx b/docs/content/docs/python/guides/extensibility/events-webhooks.mdx
similarity index 98%
rename from docs/content/docs/guides/extensibility/events-webhooks.mdx
rename to docs/content/docs/python/guides/extensibility/events-webhooks.mdx
index 8922cadf..73fec418 100644
--- a/docs/content/docs/guides/extensibility/events-webhooks.mdx
+++ b/docs/content/docs/python/guides/extensibility/events-webhooks.mdx
@@ -352,5 +352,5 @@ Within a single job's lifecycle, events always fire in this order:
## Reference
-- [Dashboard REST API for webhooks and deliveries](/guides/dashboard/rest-api#webhooks)
-- [Dashboard auth — how to call these endpoints from a script](/guides/dashboard/authentication)
+- [Dashboard REST API for webhooks and deliveries](/python/guides/dashboard/rest-api#webhooks)
+- [Dashboard auth — how to call these endpoints from a script](/python/guides/dashboard/authentication)
diff --git a/docs/content/docs/python/guides/extensibility/index.mdx b/docs/content/docs/python/guides/extensibility/index.mdx
new file mode 100644
index 00000000..cb317909
--- /dev/null
+++ b/docs/content/docs/python/guides/extensibility/index.mdx
@@ -0,0 +1,12 @@
+---
+title: Extensibility
+description: "Extend taskito at every stage of the task lifecycle."
+---
+
+Extend taskito with custom behavior at every stage of the task lifecycle.
+
+| Guide | Description |
+|---|---|
+| [Middleware](/python/guides/extensibility/middleware) | Hook into task execution with `before`, `after`, `on_retry`, and more |
+| [Serializers](/python/guides/extensibility/serializers) | Custom payload serialization — msgpack, orjson, encryption |
+| [Events & Webhooks](/python/guides/extensibility/events-webhooks) | React to queue events and push notifications to external services |
diff --git a/docs/content/docs/guides/extensibility/meta.json b/docs/content/docs/python/guides/extensibility/meta.json
similarity index 100%
rename from docs/content/docs/guides/extensibility/meta.json
rename to docs/content/docs/python/guides/extensibility/meta.json
diff --git a/docs/content/docs/guides/extensibility/middleware.mdx b/docs/content/docs/python/guides/extensibility/middleware.mdx
similarity index 98%
rename from docs/content/docs/guides/extensibility/middleware.mdx
rename to docs/content/docs/python/guides/extensibility/middleware.mdx
index b156fe8b..ada55f11 100644
--- a/docs/content/docs/guides/extensibility/middleware.mdx
+++ b/docs/content/docs/python/guides/extensibility/middleware.mdx
@@ -222,4 +222,4 @@ queue = Queue(middleware=[
])
```
-See the [OpenTelemetry guide](/guides/integrations) for setup details.
+See the [OpenTelemetry guide](/python/guides/integrations) for setup details.
diff --git a/docs/content/docs/guides/extensibility/serializers.mdx b/docs/content/docs/python/guides/extensibility/serializers.mdx
similarity index 100%
rename from docs/content/docs/guides/extensibility/serializers.mdx
rename to docs/content/docs/python/guides/extensibility/serializers.mdx
diff --git a/docs/content/docs/guides/index.mdx b/docs/content/docs/python/guides/index.mdx
similarity index 81%
rename from docs/content/docs/guides/index.mdx
rename to docs/content/docs/python/guides/index.mdx
index 8a2374ae..d8a8377e 100644
--- a/docs/content/docs/guides/index.mdx
+++ b/docs/content/docs/python/guides/index.mdx
@@ -19,61 +19,61 @@ import {
Pick the topic you're working through. Each guide is self-contained, with code
samples, gotchas, and links to the relevant API reference. For a one-page
overview of everything taskito does, see
-[**Capabilities at a glance**](/capabilities).
+[**Capabilities at a glance**](/python/capabilities).
diff --git a/docs/content/docs/guides/integrations/django.mdx b/docs/content/docs/python/guides/integrations/django.mdx
similarity index 100%
rename from docs/content/docs/guides/integrations/django.mdx
rename to docs/content/docs/python/guides/integrations/django.mdx
diff --git a/docs/content/docs/guides/integrations/fastapi.mdx b/docs/content/docs/python/guides/integrations/fastapi.mdx
similarity index 100%
rename from docs/content/docs/guides/integrations/fastapi.mdx
rename to docs/content/docs/python/guides/integrations/fastapi.mdx
diff --git a/docs/content/docs/guides/integrations/flask.mdx b/docs/content/docs/python/guides/integrations/flask.mdx
similarity index 100%
rename from docs/content/docs/guides/integrations/flask.mdx
rename to docs/content/docs/python/guides/integrations/flask.mdx
diff --git a/docs/content/docs/guides/integrations/index.mdx b/docs/content/docs/python/guides/integrations/index.mdx
similarity index 73%
rename from docs/content/docs/guides/integrations/index.mdx
rename to docs/content/docs/python/guides/integrations/index.mdx
index 9aa5be6d..f5d61d84 100644
--- a/docs/content/docs/guides/integrations/index.mdx
+++ b/docs/content/docs/python/guides/integrations/index.mdx
@@ -23,15 +23,15 @@ tools. Install only what you need.
## Framework integrations
-- **[Flask](/guides/integrations/flask)** — full Flask extension with app config, factory pattern, and CLI commands
-- **[FastAPI](/guides/integrations/fastapi)** — pre-built `APIRouter` with job status, SSE progress, and DLQ management
-- **[Django](/guides/integrations/django)** — admin views for browsing jobs, dead letters, and queue stats
+- **[Flask](/python/guides/integrations/flask)** — full Flask extension with app config, factory pattern, and CLI commands
+- **[FastAPI](/python/guides/integrations/fastapi)** — pre-built `APIRouter` with job status, SSE progress, and DLQ management
+- **[Django](/python/guides/integrations/django)** — admin views for browsing jobs, dead letters, and queue stats
## Observability integrations
-- **[OpenTelemetry](/guides/integrations/otel)** — distributed tracing with per-task spans
-- **[Prometheus](/guides/integrations/prometheus)** — counters, histograms, and gauges for task execution
-- **[Sentry](/guides/integrations/sentry)** — automatic error capture with task context
+- **[OpenTelemetry](/python/guides/integrations/otel)** — distributed tracing with per-task spans
+- **[Prometheus](/python/guides/integrations/prometheus)** — counters, histograms, and gauges for task execution
+- **[Sentry](/python/guides/integrations/sentry)** — automatic error capture with task context
## Combining integrations
diff --git a/docs/content/docs/guides/integrations/meta.json b/docs/content/docs/python/guides/integrations/meta.json
similarity index 100%
rename from docs/content/docs/guides/integrations/meta.json
rename to docs/content/docs/python/guides/integrations/meta.json
diff --git a/docs/content/docs/guides/integrations/otel.mdx b/docs/content/docs/python/guides/integrations/otel.mdx
similarity index 97%
rename from docs/content/docs/guides/integrations/otel.mdx
rename to docs/content/docs/python/guides/integrations/otel.mdx
index 9d5c1b00..e3c59509 100644
--- a/docs/content/docs/guides/integrations/otel.mdx
+++ b/docs/content/docs/python/guides/integrations/otel.mdx
@@ -106,5 +106,5 @@ queue = Queue(middleware=[
lock.
-See the [Middleware guide](/guides/extensibility/middleware) for more
+See the [Middleware guide](/python/guides/extensibility/middleware) for more
on combining middleware.
diff --git a/docs/content/docs/guides/integrations/prometheus.mdx b/docs/content/docs/python/guides/integrations/prometheus.mdx
similarity index 98%
rename from docs/content/docs/guides/integrations/prometheus.mdx
rename to docs/content/docs/python/guides/integrations/prometheus.mdx
index fac36c3e..f84dccc0 100644
--- a/docs/content/docs/guides/integrations/prometheus.mdx
+++ b/docs/content/docs/python/guides/integrations/prometheus.mdx
@@ -160,7 +160,7 @@ queue = Queue(
)
```
-See the [Middleware guide](/guides/extensibility/middleware) for more
+See the [Middleware guide](/python/guides/extensibility/middleware) for more
on combining middleware.
## Example: alert on high DLQ size
diff --git a/docs/content/docs/guides/integrations/sentry.mdx b/docs/content/docs/python/guides/integrations/sentry.mdx
similarity index 98%
rename from docs/content/docs/guides/integrations/sentry.mdx
rename to docs/content/docs/python/guides/integrations/sentry.mdx
index 211c03f6..0a01a86c 100644
--- a/docs/content/docs/guides/integrations/sentry.mdx
+++ b/docs/content/docs/python/guides/integrations/sentry.mdx
@@ -100,7 +100,7 @@ queue = Queue(
)
```
-See the [Middleware guide](/guides/extensibility/middleware) for more
+See the [Middleware guide](/python/guides/extensibility/middleware) for more
on combining middleware.
## Full example
diff --git a/docs/content/docs/guides/meta.json b/docs/content/docs/python/guides/meta.json
similarity index 100%
rename from docs/content/docs/guides/meta.json
rename to docs/content/docs/python/guides/meta.json
diff --git a/docs/content/docs/python/guides/observability/index.mdx b/docs/content/docs/python/guides/observability/index.mdx
new file mode 100644
index 00000000..5fb72fa6
--- /dev/null
+++ b/docs/content/docs/python/guides/observability/index.mdx
@@ -0,0 +1,16 @@
+---
+title: Observability
+description: "Monitor, log, and inspect your task queue in real time."
+---
+
+Monitor, log, and inspect your task queue in real time.
+
+| Guide | Description |
+|---|---|
+| [Monitoring & Hooks](/python/guides/observability/monitoring) | Queue stats, progress tracking, worker heartbeat, and alerting hooks |
+| [Structured Logging](/python/guides/observability/logging) | Per-task structured logs with automatic context |
+| [Structured Notes](/python/guides/observability/notes) | Operator-visible metadata attached to individual jobs |
+
+For the built-in web UI, see the [Dashboard](/python/guides/dashboard) section —
+it covers the browser app, password and SSO login, runtime task/queue
+overrides, and the underlying REST API.
diff --git a/docs/content/docs/guides/observability/logging.mdx b/docs/content/docs/python/guides/observability/logging.mdx
similarity index 100%
rename from docs/content/docs/guides/observability/logging.mdx
rename to docs/content/docs/python/guides/observability/logging.mdx
diff --git a/docs/content/docs/guides/observability/meta.json b/docs/content/docs/python/guides/observability/meta.json
similarity index 100%
rename from docs/content/docs/guides/observability/meta.json
rename to docs/content/docs/python/guides/observability/meta.json
diff --git a/docs/content/docs/guides/observability/monitoring.mdx b/docs/content/docs/python/guides/observability/monitoring.mdx
similarity index 96%
rename from docs/content/docs/guides/observability/monitoring.mdx
rename to docs/content/docs/python/guides/observability/monitoring.mdx
index c5e1d2ea..08b0d70c 100644
--- a/docs/content/docs/guides/observability/monitoring.mdx
+++ b/docs/content/docs/python/guides/observability/monitoring.mdx
@@ -120,7 +120,7 @@ workers = await queue.aworkers()
The worker heartbeat is also available via the dashboard REST API at
`GET /api/workers`. See the
-[Dashboard](/guides/dashboard) guide for details.
+[Dashboard](/python/guides/dashboard) guide for details.
## Events system
@@ -129,7 +129,7 @@ events (`JOB_ENQUEUED`, `JOB_COMPLETED`, `JOB_FAILED`, `JOB_RETRYING`,
`JOB_DEAD`, `JOB_CANCELLED`). Events can also be delivered as signed HTTP
webhooks to external systems.
-[Events & Webhooks guide →](/guides/extensibility)
+[Events & Webhooks guide →](/python/guides/extensibility)
## Prometheus metrics
@@ -140,7 +140,7 @@ counters, histograms, and gauges for task execution:
pip install taskito[prometheus]
```
-[Prometheus integration →](/guides/integrations)
+[Prometheus integration →](/python/guides/integrations)
## Hooks
diff --git a/docs/content/docs/guides/observability/notes.mdx b/docs/content/docs/python/guides/observability/notes.mdx
similarity index 100%
rename from docs/content/docs/guides/observability/notes.mdx
rename to docs/content/docs/python/guides/observability/notes.mdx
diff --git a/docs/content/docs/guides/operations/autoscaler.mdx b/docs/content/docs/python/guides/operations/autoscaler.mdx
similarity index 98%
rename from docs/content/docs/guides/operations/autoscaler.mdx
rename to docs/content/docs/python/guides/operations/autoscaler.mdx
index e8b17e28..ce3bc5bc 100644
--- a/docs/content/docs/guides/operations/autoscaler.mdx
+++ b/docs/content/docs/python/guides/operations/autoscaler.mdx
@@ -11,7 +11,7 @@ formula so the scaling behaviour is predictable if you're already familiar
with KEDA or the Horizontal Pod Autoscaler.
Use this when you're running on bare metal, Docker, or systemd and can't
-use [KEDA + Kubernetes](/guides/operations/keda).
+use [KEDA + Kubernetes](/python/guides/operations/keda).
## Quick start
@@ -286,4 +286,4 @@ volumes:
| Crash recovery | Auto-replaces crashed workers | Kubernetes restarts pods |
| Setup | Zero — no external components | KEDA operator + ScaledObject |
-For Kubernetes deployments, use [KEDA](/guides/operations/keda).
+For Kubernetes deployments, use [KEDA](/python/guides/operations/keda).
diff --git a/docs/content/docs/guides/operations/deployment.mdx b/docs/content/docs/python/guides/operations/deployment.mdx
similarity index 97%
rename from docs/content/docs/guides/operations/deployment.mdx
rename to docs/content/docs/python/guides/operations/deployment.mdx
index e74f887f..10e4e874 100644
--- a/docs/content/docs/guides/operations/deployment.mdx
+++ b/docs/content/docs/python/guides/operations/deployment.mdx
@@ -160,7 +160,7 @@ Both methods are safe while the worker is running.
## Postgres deployment
-If you're using the [Postgres backend](/guides/operations/postgres),
+If you're using the [Postgres backend](/python/guides/operations/postgres),
deployment is simpler in several ways:
- **No shared-file constraints** — workers connect over the network, no need for shared volumes or local storage
@@ -204,7 +204,7 @@ pg_dump -h localhost -U taskito -d myapp -n taskito > backup.sql
psql -h localhost -U taskito -d myapp < backup.sql
```
-See the [Postgres Backend guide](/guides/operations/postgres) for full
+See the [Postgres Backend guide](/python/guides/operations/postgres) for full
configuration details.
## Database maintenance
@@ -324,7 +324,7 @@ queue = Queue(
```
If you need distributed workers across multiple machines, use the
-[Postgres backend](/guides/operations/postgres) which removes the
+[Postgres backend](/python/guides/operations/postgres) which removes the
single-writer constraint and supports multi-machine deployments.
## SQLite scaling limits
@@ -349,7 +349,7 @@ are serialized. This is the primary throughput ceiling.
- Multiple processes contend heavily for writes (high lock wait times)
- You need sub-millisecond dequeue latency under high load
-taskito's [Postgres backend](/guides/operations/postgres) addresses all
+taskito's [Postgres backend](/python/guides/operations/postgres) addresses all
of these limitations while keeping the same API.
## Sizing your deployment
diff --git a/docs/content/docs/python/guides/operations/index.mdx b/docs/content/docs/python/guides/operations/index.mdx
new file mode 100644
index 00000000..0866b9e1
--- /dev/null
+++ b/docs/content/docs/python/guides/operations/index.mdx
@@ -0,0 +1,17 @@
+---
+title: Operations
+description: "Run taskito reliably in production — testing, deployment, scaling, migration."
+---
+
+Run taskito reliably in production.
+
+| Guide | Description |
+|---|---|
+| [Testing](/python/guides/operations/testing) | Test mode, fixtures, mocking resources, and workflow testing |
+| [Job Management](/python/guides/operations/job-management) | Cancel, pause, archive, revoke, replay, and clean up jobs |
+| [Troubleshooting](/python/guides/operations/troubleshooting) | Diagnose stuck jobs, lock contention, and worker issues |
+| [Deployment](/python/guides/operations/deployment) | systemd, Docker, WAL mode, Postgres, and production checklists |
+| [Bare-Metal Autoscaler](/python/guides/operations/autoscaler) | Automatically scale worker processes without Kubernetes |
+| [KEDA Autoscaling](/python/guides/operations/keda) | Kubernetes event-driven autoscaling for workers |
+| [Postgres Backend](/python/guides/operations/postgres) | Set up and run taskito with PostgreSQL |
+| [Migrating from Celery](/python/guides/operations/migration) | Side-by-side comparison and step-by-step migration guide |
diff --git a/docs/content/docs/guides/operations/job-management.mdx b/docs/content/docs/python/guides/operations/job-management.mdx
similarity index 100%
rename from docs/content/docs/guides/operations/job-management.mdx
rename to docs/content/docs/python/guides/operations/job-management.mdx
diff --git a/docs/content/docs/guides/operations/keda.mdx b/docs/content/docs/python/guides/operations/keda.mdx
similarity index 97%
rename from docs/content/docs/guides/operations/keda.mdx
rename to docs/content/docs/python/guides/operations/keda.mdx
index 34bee69c..e9702b83 100644
--- a/docs/content/docs/guides/operations/keda.mdx
+++ b/docs/content/docs/python/guides/operations/keda.mdx
@@ -193,7 +193,7 @@ spec:
threshold: "0.8"
```
-See the [Prometheus integration](/guides/integrations) for setting up
+See the [Prometheus integration](/python/guides/integrations) for setting up
the metrics collector.
## Deploy templates
@@ -210,6 +210,6 @@ Ready-to-use YAML templates are included in the repository under
When using SQLite, all worker replicas must share the same database
volume. For multi-replica Kubernetes deployments, use the
- [Postgres backend](/guides/operations/postgres) — workers connect
+ [Postgres backend](/python/guides/operations/postgres) — workers connect
over the network and there's no shared-file constraint.
diff --git a/docs/content/docs/guides/operations/mesh.mdx b/docs/content/docs/python/guides/operations/mesh.mdx
similarity index 91%
rename from docs/content/docs/guides/operations/mesh.mdx
rename to docs/content/docs/python/guides/operations/mesh.mdx
index 2f7af0e9..ba07004f 100644
--- a/docs/content/docs/guides/operations/mesh.mdx
+++ b/docs/content/docs/python/guides/operations/mesh.mdx
@@ -7,7 +7,7 @@ import { Callout } from "fumadocs-ui/components/callout";
import { Tab, Tabs } from "fumadocs-ui/components/tabs";
Mesh scheduling adds a decentralized overlay network on top of the
-[standard scheduler](/architecture/scheduler). Workers discover each other via
+[standard scheduler](/python/architecture/scheduler). Workers discover each other via
gossip, route tasks through a consistent-hashing ring, and steal work from
busy peers — all without a central coordinator.
@@ -56,18 +56,18 @@ Mesh scheduling composes five primitives that work together:
|---|---|
| **SWIM gossip** | UDP protocol for worker discovery and failure detection (~1.5s vs 30s DB heartbeat) |
| **Consistent hashing** | xxhash ring with virtual nodes maps tasks to preferred workers (soft affinity) |
-| **Local deque** | In-memory buffer between DB polls — workers drain the deque before hitting the [storage backend](/architecture/storage) |
+| **Local deque** | In-memory buffer between DB polls — workers drain the deque before hitting the [storage backend](/python/architecture/storage) |
| **Work-stealing** | TCP protocol lets idle workers steal jobs from busy peers |
| **Adaptive load balancing** | Prefetch size and poll timing auto-tune based on cluster state |
The database remains the source of truth. Gossip is an optimization layer —
if it fails, workers fall back to standard DB polling. See
-[Architecture: Mesh Scheduling](/architecture/mesh) for protocol-level details.
+[Architecture: Mesh Scheduling](/python/architecture/mesh) for protocol-level details.
## Configuration
All mesh settings live in `MeshWorker`, keeping the
-[`Queue`](/api-reference/queue) class clean:
+[`Queue`](/python/api-reference/queue) class clean:
```python
mesh = MeshWorker(
@@ -221,7 +221,7 @@ parameter controls how aggressively the ring biases dispatch. Set it to
This improves cache locality — if a task always runs on the same worker,
its imports, connections, and warm caches stay hot. Particularly useful with
-[worker resources](/guides/resources/overview) that have expensive
+[worker resources](/python/guides/resources/overview) that have expensive
initialization.
```python
@@ -325,15 +325,15 @@ queue.run_worker(mesh=mesh)
```
See also:
-- [Per-task concurrency](/guides/core/tasks#concurrency) for `max_concurrent`
-- [Rate limiting](/guides/core/tasks#rate-limiting) for `rate_limit`
-- [Worker resources](/guides/resources/overview) for DI into tasks
-- [Batch dequeue](/guides/core/scheduling#batch-dequeue) for `scheduler_batch_size`
+- [Per-task concurrency](/python/guides/core/tasks#concurrency) for `max_concurrent`
+- [Rate limiting](/python/guides/core/tasks#rate-limiting) for `rate_limit`
+- [Worker resources](/python/guides/resources/overview) for DI into tasks
+- [Batch dequeue](/python/guides/core/scheduling#batch-dequeue) for `scheduler_batch_size`
## Mixing mesh and non-mesh workers
-Mesh workers coexist safely with [standard workers](/guides/core/workers).
-Both use the same [storage backend](/architecture/storage) for atomic job
+Mesh workers coexist safely with [standard workers](/python/guides/core/workers).
+Both use the same [storage backend](/python/architecture/storage) for atomic job
claims — mesh just reduces how often workers hit the DB.
```python
@@ -372,13 +372,13 @@ Key log messages:
| `debug` | `giving N jobs to thief X` | Responded to steal request |
| `debug` | `ack from X resolved probe` | Healthy ping-ack cycle |
-If you use [Prometheus](/guides/integrations/prometheus), mesh metrics flow
+If you use [Prometheus](/python/guides/integrations/prometheus), mesh metrics flow
through the same worker observability pipeline.
## Graceful shutdown
When a mesh worker shuts down (via `SIGINT`, `SIGTERM`, or
-[`request_shutdown()`](/api-reference/queue#request_shutdown)), it broadcasts
+[`request_shutdown()`](/python/api-reference/queue#request_shutdown)), it broadcasts
a `Leave` message to all known peers. They remove it from the ring
immediately — no suspicion timeout needed.
@@ -402,6 +402,6 @@ With default settings (multiplier=4, period=500ms), a crashed worker in a
- Single worker setups
- Low throughput (< 100 jobs/second)
- Workers processing completely different queues (no overlap = no stealing)
-- Already using [bare-metal autoscaler](/guides/operations/autoscaler) or
- [KEDA](/guides/operations/keda) for process-level scaling (mesh is
+- Already using [bare-metal autoscaler](/python/guides/operations/autoscaler) or
+ [KEDA](/python/guides/operations/keda) for process-level scaling (mesh is
*within-process* optimization, not a replacement for autoscaling)
diff --git a/docs/content/docs/guides/operations/meta.json b/docs/content/docs/python/guides/operations/meta.json
similarity index 100%
rename from docs/content/docs/guides/operations/meta.json
rename to docs/content/docs/python/guides/operations/meta.json
diff --git a/docs/content/docs/guides/operations/migration.mdx b/docs/content/docs/python/guides/operations/migration.mdx
similarity index 100%
rename from docs/content/docs/guides/operations/migration.mdx
rename to docs/content/docs/python/guides/operations/migration.mdx
diff --git a/docs/content/docs/guides/operations/postgres.mdx b/docs/content/docs/python/guides/operations/postgres.mdx
similarity index 100%
rename from docs/content/docs/guides/operations/postgres.mdx
rename to docs/content/docs/python/guides/operations/postgres.mdx
diff --git a/docs/content/docs/guides/operations/security.mdx b/docs/content/docs/python/guides/operations/security.mdx
similarity index 100%
rename from docs/content/docs/guides/operations/security.mdx
rename to docs/content/docs/python/guides/operations/security.mdx
diff --git a/docs/content/docs/guides/operations/testing.mdx b/docs/content/docs/python/guides/operations/testing.mdx
similarity index 98%
rename from docs/content/docs/guides/operations/testing.mdx
rename to docs/content/docs/python/guides/operations/testing.mdx
index 4b696e98..7528e746 100644
--- a/docs/content/docs/guides/operations/testing.mdx
+++ b/docs/content/docs/python/guides/operations/testing.mdx
@@ -53,7 +53,7 @@ with queue.test_mode(propagate_errors=False, resources=None) as results:
| Parameter | Type | Default | Description |
|---|---|---|---|
| `propagate_errors` | `bool` | `False` | If `True`, task exceptions are re-raised immediately instead of being captured in `TestResult.error` |
-| `resources` | `dict[str, Any] \| None` | `None` | Map of resource name → mock instance or `MockResource` for injection. See [Resource System](/guides/resources). |
+| `resources` | `dict[str, Any] \| None` | `None` | Map of resource name → mock instance or `MockResource` for injection. See [Resource System](/python/guides/resources). |
The context manager yields a `TestResults` list that accumulates results as
tasks execute.
@@ -272,7 +272,7 @@ async def test_async_enqueue(task_results):
## Testing with worker resources
-If your tasks use [worker resources](/guides/resources) (injected via
+If your tasks use [worker resources](/python/guides/resources) (injected via
`inject=` or `Inject["name"]`), pass mock instances through `resources=`:
```python
diff --git a/docs/content/docs/guides/operations/troubleshooting.mdx b/docs/content/docs/python/guides/operations/troubleshooting.mdx
similarity index 100%
rename from docs/content/docs/guides/operations/troubleshooting.mdx
rename to docs/content/docs/python/guides/operations/troubleshooting.mdx
diff --git a/docs/content/docs/guides/operations/upgrading-0.15.mdx b/docs/content/docs/python/guides/operations/upgrading-0.15.mdx
similarity index 100%
rename from docs/content/docs/guides/operations/upgrading-0.15.mdx
rename to docs/content/docs/python/guides/operations/upgrading-0.15.mdx
diff --git a/docs/content/docs/guides/reliability/circuit-breakers.mdx b/docs/content/docs/python/guides/reliability/circuit-breakers.mdx
similarity index 100%
rename from docs/content/docs/guides/reliability/circuit-breakers.mdx
rename to docs/content/docs/python/guides/reliability/circuit-breakers.mdx
diff --git a/docs/content/docs/guides/reliability/error-handling.mdx b/docs/content/docs/python/guides/reliability/error-handling.mdx
similarity index 98%
rename from docs/content/docs/guides/reliability/error-handling.mdx
rename to docs/content/docs/python/guides/reliability/error-handling.mdx
index 82d5628f..2b48ae57 100644
--- a/docs/content/docs/guides/reliability/error-handling.mdx
+++ b/docs/content/docs/python/guides/reliability/error-handling.mdx
@@ -247,7 +247,7 @@ def on_task_failure(task_name, args, kwargs, error):
### Test mode for isolation
-Use [test mode](/guides/operations) to run tasks synchronously and inspect
+Use [test mode](/python/guides/operations) to run tasks synchronously and inspect
errors without a worker:
```python
@@ -287,7 +287,7 @@ def call_api(url):
return resp.json()
```
-See [Retries — Exception Filtering](/guides/reliability/retries) for details.
+See [Retries — Exception Filtering](/python/guides/reliability/retries) for details.
### Cancelling running tasks
diff --git a/docs/content/docs/guides/reliability/guarantees.mdx b/docs/content/docs/python/guides/reliability/guarantees.mdx
similarity index 98%
rename from docs/content/docs/guides/reliability/guarantees.mdx
rename to docs/content/docs/python/guides/reliability/guarantees.mdx
index 38040a75..f3523034 100644
--- a/docs/content/docs/guides/reliability/guarantees.mdx
+++ b/docs/content/docs/python/guides/reliability/guarantees.mdx
@@ -84,7 +84,7 @@ job = send_report.apply_async(
If a job with the same `unique_key` is already pending or running, the
duplicate is silently dropped. See
-[Unique Tasks](/guides/advanced-execution) for details.
+[Unique Tasks](/python/guides/advanced-execution) for details.
### Avoid side effects that can't be undone
diff --git a/docs/content/docs/guides/reliability/idempotency.mdx b/docs/content/docs/python/guides/reliability/idempotency.mdx
similarity index 100%
rename from docs/content/docs/guides/reliability/idempotency.mdx
rename to docs/content/docs/python/guides/reliability/idempotency.mdx
diff --git a/docs/content/docs/python/guides/reliability/index.mdx b/docs/content/docs/python/guides/reliability/index.mdx
new file mode 100644
index 00000000..70848e97
--- /dev/null
+++ b/docs/content/docs/python/guides/reliability/index.mdx
@@ -0,0 +1,15 @@
+---
+title: Reliability
+description: "Harden your task queue for production workloads."
+---
+
+Harden your task queue for production workloads.
+
+| Guide | Description |
+|---|---|
+| [Retries & Dead Letters](/python/guides/reliability/retries) | Automatic retries with exponential backoff, dead letter queue |
+| [Error Handling](/python/guides/reliability/error-handling) | Task failure lifecycle, error inspection, debugging patterns |
+| [Delivery Guarantees](/python/guides/reliability/guarantees) | At-least-once delivery, idempotency, and exactly-once patterns |
+| [Rate Limiting](/python/guides/reliability/rate-limiting) | Throttle task execution with token bucket rate limits |
+| [Circuit Breakers](/python/guides/reliability/circuit-breakers) | Protect downstream services from cascading failures |
+| [Distributed Locking](/python/guides/reliability/locking) | Mutual exclusion across workers with database-backed locks |
diff --git a/docs/content/docs/guides/reliability/locking.mdx b/docs/content/docs/python/guides/reliability/locking.mdx
similarity index 100%
rename from docs/content/docs/guides/reliability/locking.mdx
rename to docs/content/docs/python/guides/reliability/locking.mdx
diff --git a/docs/content/docs/guides/reliability/meta.json b/docs/content/docs/python/guides/reliability/meta.json
similarity index 100%
rename from docs/content/docs/guides/reliability/meta.json
rename to docs/content/docs/python/guides/reliability/meta.json
diff --git a/docs/content/docs/guides/reliability/rate-limiting.mdx b/docs/content/docs/python/guides/reliability/rate-limiting.mdx
similarity index 100%
rename from docs/content/docs/guides/reliability/rate-limiting.mdx
rename to docs/content/docs/python/guides/reliability/rate-limiting.mdx
diff --git a/docs/content/docs/guides/reliability/retries.mdx b/docs/content/docs/python/guides/reliability/retries.mdx
similarity index 100%
rename from docs/content/docs/guides/reliability/retries.mdx
rename to docs/content/docs/python/guides/reliability/retries.mdx
diff --git a/docs/content/docs/guides/resources/configuration.mdx b/docs/content/docs/python/guides/resources/configuration.mdx
similarity index 100%
rename from docs/content/docs/guides/resources/configuration.mdx
rename to docs/content/docs/python/guides/resources/configuration.mdx
diff --git a/docs/content/docs/guides/resources/dependency-injection.mdx b/docs/content/docs/python/guides/resources/dependency-injection.mdx
similarity index 98%
rename from docs/content/docs/guides/resources/dependency-injection.mdx
rename to docs/content/docs/python/guides/resources/dependency-injection.mdx
index 57304a70..c9f19003 100644
--- a/docs/content/docs/guides/resources/dependency-injection.mdx
+++ b/docs/content/docs/python/guides/resources/dependency-injection.mdx
@@ -115,7 +115,7 @@ def create_cache():
Pool configuration parameters (`pool_size`, `pool_min`, `acquire_timeout`,
`max_lifetime`, `idle_timeout`) only apply to task-scoped resources. See
-[Configuration](/guides/resources/configuration) for details.
+[Configuration](/python/guides/resources/configuration) for details.
## Dependencies
@@ -236,7 +236,7 @@ status = queue.resource_status()
```
Task-scoped resources include a `"pool"` key with pool statistics. See
-[Observability](/guides/resources/observability) for details.
+[Observability](/python/guides/resources/observability) for details.
## Full example
diff --git a/docs/content/docs/guides/resources/index.mdx b/docs/content/docs/python/guides/resources/index.mdx
similarity index 78%
rename from docs/content/docs/guides/resources/index.mdx
rename to docs/content/docs/python/guides/resources/index.mdx
index c3dc6a11..fc53e608 100644
--- a/docs/content/docs/guides/resources/index.mdx
+++ b/docs/content/docs/python/guides/resources/index.mdx
@@ -87,9 +87,9 @@ taskito worker --app myapp.tasks:queue
| Page | What it covers |
|---|---|
-| [Argument Interception](/guides/resources/interception) | Modes, strategies, custom types, `analyze()`, metrics |
-| [Dependency Injection](/guides/resources/dependency-injection) | `worker_resource()`, scopes, dependencies, teardown, health checks |
-| [Resource Proxies](/guides/resources/proxies) | Built-in handlers, HMAC signing, security, `NoProxy`, cloud handlers |
-| [Configuration](/guides/resources/configuration) | TOML config, pool tuning, frozen and reloadable resources, hot reload |
-| [Testing](/guides/resources/testing) | `test_mode(resources=)`, `MockResource`, pytest fixtures |
-| [Observability](/guides/resources/observability) | Prometheus metrics, dashboard endpoints, CLI commands |
+| [Argument Interception](/python/guides/resources/interception) | Modes, strategies, custom types, `analyze()`, metrics |
+| [Dependency Injection](/python/guides/resources/dependency-injection) | `worker_resource()`, scopes, dependencies, teardown, health checks |
+| [Resource Proxies](/python/guides/resources/proxies) | Built-in handlers, HMAC signing, security, `NoProxy`, cloud handlers |
+| [Configuration](/python/guides/resources/configuration) | TOML config, pool tuning, frozen and reloadable resources, hot reload |
+| [Testing](/python/guides/resources/testing) | `test_mode(resources=)`, `MockResource`, pytest fixtures |
+| [Observability](/python/guides/resources/observability) | Prometheus metrics, dashboard endpoints, CLI commands |
diff --git a/docs/content/docs/guides/resources/interception.mdx b/docs/content/docs/python/guides/resources/interception.mdx
similarity index 97%
rename from docs/content/docs/guides/resources/interception.mdx
rename to docs/content/docs/python/guides/resources/interception.mdx
index 05712dab..aa0b3a58 100644
--- a/docs/content/docs/guides/resources/interception.mdx
+++ b/docs/content/docs/python/guides/resources/interception.mdx
@@ -92,7 +92,7 @@ These objects are deconstructed to a recipe dict and rebuilt by the worker:
| boto3 clients (via `botocore.client.BaseClient`) | `"boto3_client"` |
| `google.cloud.storage.Client` / `Bucket` / `Blob` | `"gcs_client"` |
-See [Resource Proxies](/guides/resources/proxies) for security options
+See [Resource Proxies](/python/guides/resources/proxies) for security options
and handler details.
## Built-in REJECT types
@@ -192,5 +192,5 @@ stats = queue.interception_stats()
# }
```
-See [Observability](/guides/resources/observability) for Prometheus
+See [Observability](/python/guides/resources/observability) for Prometheus
metrics and dashboard endpoints.
diff --git a/docs/content/docs/guides/resources/meta.json b/docs/content/docs/python/guides/resources/meta.json
similarity index 100%
rename from docs/content/docs/guides/resources/meta.json
rename to docs/content/docs/python/guides/resources/meta.json
diff --git a/docs/content/docs/guides/resources/observability.mdx b/docs/content/docs/python/guides/resources/observability.mdx
similarity index 97%
rename from docs/content/docs/guides/resources/observability.mdx
rename to docs/content/docs/python/guides/resources/observability.mdx
index e9a25b76..d4a110b2 100644
--- a/docs/content/docs/guides/resources/observability.mdx
+++ b/docs/content/docs/python/guides/resources/observability.mdx
@@ -122,7 +122,7 @@ Start the dashboard:
taskito dashboard --app myapp.tasks:queue
```
-See the [Web Dashboard](/guides/dashboard) guide for
+See the [Web Dashboard](/python/guides/dashboard) guide for
full dashboard documentation.
## CLI commands
@@ -214,5 +214,5 @@ from taskito.contrib.prometheus import start_metrics_server
start_metrics_server(port=9090)
```
-See the [Prometheus integration](/guides/integrations) page for full
+See the [Prometheus integration](/python/guides/integrations) page for full
setup instructions.
diff --git a/docs/content/docs/guides/resources/proxies.mdx b/docs/content/docs/python/guides/resources/proxies.mdx
similarity index 98%
rename from docs/content/docs/guides/resources/proxies.mdx
rename to docs/content/docs/python/guides/resources/proxies.mdx
index 2863183c..15a04423 100644
--- a/docs/content/docs/guides/resources/proxies.mdx
+++ b/docs/content/docs/python/guides/resources/proxies.mdx
@@ -181,5 +181,5 @@ stats = queue.proxy_stats()
# ]
```
-See [Observability](/guides/resources/observability) for Prometheus
+See [Observability](/python/guides/resources/observability) for Prometheus
metrics and dashboard endpoints.
diff --git a/docs/content/docs/guides/resources/testing.mdx b/docs/content/docs/python/guides/resources/testing.mdx
similarity index 100%
rename from docs/content/docs/guides/resources/testing.mdx
rename to docs/content/docs/python/guides/resources/testing.mdx
diff --git a/docs/content/docs/guides/workflows/analysis.mdx b/docs/content/docs/python/guides/workflows/analysis.mdx
similarity index 100%
rename from docs/content/docs/guides/workflows/analysis.mdx
rename to docs/content/docs/python/guides/workflows/analysis.mdx
diff --git a/docs/content/docs/guides/workflows/building.mdx b/docs/content/docs/python/guides/workflows/building.mdx
similarity index 98%
rename from docs/content/docs/guides/workflows/building.mdx
rename to docs/content/docs/python/guides/workflows/building.mdx
index 3be147c1..7a54bf02 100644
--- a/docs/content/docs/guides/workflows/building.mdx
+++ b/docs/content/docs/python/guides/workflows/building.mdx
@@ -106,7 +106,7 @@ This creates a `WorkflowRun` handle. Under the hood:
| `name` | `str` | `"workflow"` | Workflow name |
| `version` | `int` | `1` | Version number |
| `on_failure` | `str` | `"fail_fast"` | Error strategy: `"fail_fast"` or `"continue"` |
-| `cache_ttl` | `float` | `None` | Cache TTL in seconds for [incremental runs](/guides/workflows/caching) |
+| `cache_ttl` | `float` | `None` | Cache TTL in seconds for [incremental runs](/python/guides/workflows/caching) |
## Node statuses
diff --git a/docs/content/docs/guides/workflows/caching.mdx b/docs/content/docs/python/guides/workflows/caching.mdx
similarity index 100%
rename from docs/content/docs/guides/workflows/caching.mdx
rename to docs/content/docs/python/guides/workflows/caching.mdx
diff --git a/docs/content/docs/guides/workflows/canvas.mdx b/docs/content/docs/python/guides/workflows/canvas.mdx
similarity index 99%
rename from docs/content/docs/guides/workflows/canvas.mdx
rename to docs/content/docs/python/guides/workflows/canvas.mdx
index 5f84b17a..05e45947 100644
--- a/docs/content/docs/guides/workflows/canvas.mdx
+++ b/docs/content/docs/python/guides/workflows/canvas.mdx
@@ -101,7 +101,7 @@ succeeded — no workflow engine required.
Canvas compensation is in-thread: compensators are enqueued synchronously
during the `apply()` call that raised. For DAG-level sagas with full
observability and sub-workflow propagation, see the
- [Sagas guide](/guides/workflows/sagas).
+ [Sagas guide](/python/guides/workflows/sagas).
### chain compensation
diff --git a/docs/content/docs/guides/workflows/composition.mdx b/docs/content/docs/python/guides/workflows/composition.mdx
similarity index 100%
rename from docs/content/docs/guides/workflows/composition.mdx
rename to docs/content/docs/python/guides/workflows/composition.mdx
diff --git a/docs/content/docs/guides/workflows/conditions.mdx b/docs/content/docs/python/guides/workflows/conditions.mdx
similarity index 100%
rename from docs/content/docs/guides/workflows/conditions.mdx
rename to docs/content/docs/python/guides/workflows/conditions.mdx
diff --git a/docs/content/docs/guides/workflows/fan-out.mdx b/docs/content/docs/python/guides/workflows/fan-out.mdx
similarity index 97%
rename from docs/content/docs/guides/workflows/fan-out.mdx
rename to docs/content/docs/python/guides/workflows/fan-out.mdx
index 85c35ed8..dbcd9007 100644
--- a/docs/content/docs/guides/workflows/fan-out.mdx
+++ b/docs/content/docs/python/guides/workflows/fan-out.mdx
@@ -109,7 +109,7 @@ By default (`on_failure="fail_fast"`), if any fan-out child fails:
- The fan-in and downstream steps are `SKIPPED`
- The workflow transitions to `FAILED`
-Combine with [conditions](/guides/workflows/conditions) for more
+Combine with [conditions](/python/guides/workflows/conditions) for more
control:
```python
diff --git a/docs/content/docs/guides/workflows/gates.mdx b/docs/content/docs/python/guides/workflows/gates.mdx
similarity index 100%
rename from docs/content/docs/guides/workflows/gates.mdx
rename to docs/content/docs/python/guides/workflows/gates.mdx
diff --git a/docs/content/docs/guides/workflows/index.mdx b/docs/content/docs/python/guides/workflows/index.mdx
similarity index 59%
rename from docs/content/docs/guides/workflows/index.mdx
rename to docs/content/docs/python/guides/workflows/index.mdx
index 661ec38b..9332cc90 100644
--- a/docs/content/docs/guides/workflows/index.mdx
+++ b/docs/content/docs/python/guides/workflows/index.mdx
@@ -50,11 +50,11 @@ print(result.state) # WorkflowState.COMPLETED
| Page | What it covers |
|---|---|
-| [Building Workflows](/guides/workflows/building) | `Workflow.step()`, decorator pattern, step configuration, DAG structure |
-| [Fan-Out & Fan-In](/guides/workflows/fan-out) | Splitting results into parallel jobs, collecting with aggregation |
-| [Conditions & Error Handling](/guides/workflows/conditions) | `on_success`, `on_failure`, `always`, callable conditions, `on_failure` modes |
-| [Approval Gates](/guides/workflows/gates) | Human-in-the-loop pause/resume, timeout, approve/reject API |
-| [Sub-Workflows & Scheduling](/guides/workflows/composition) | Nesting workflows, cron-scheduled runs |
-| [Incremental Runs](/guides/workflows/caching) | Result hashing, `CACHE_HIT`, dirty-set propagation, TTL |
-| [Analysis & Visualization](/guides/workflows/analysis) | Critical path, bottleneck analysis, Mermaid/DOT rendering |
-| [Canvas Primitives](/guides/workflows/canvas) | Chain, group, chord — simple composition without DAGs |
+| [Building Workflows](/python/guides/workflows/building) | `Workflow.step()`, decorator pattern, step configuration, DAG structure |
+| [Fan-Out & Fan-In](/python/guides/workflows/fan-out) | Splitting results into parallel jobs, collecting with aggregation |
+| [Conditions & Error Handling](/python/guides/workflows/conditions) | `on_success`, `on_failure`, `always`, callable conditions, `on_failure` modes |
+| [Approval Gates](/python/guides/workflows/gates) | Human-in-the-loop pause/resume, timeout, approve/reject API |
+| [Sub-Workflows & Scheduling](/python/guides/workflows/composition) | Nesting workflows, cron-scheduled runs |
+| [Incremental Runs](/python/guides/workflows/caching) | Result hashing, `CACHE_HIT`, dirty-set propagation, TTL |
+| [Analysis & Visualization](/python/guides/workflows/analysis) | Critical path, bottleneck analysis, Mermaid/DOT rendering |
+| [Canvas Primitives](/python/guides/workflows/canvas) | Chain, group, chord — simple composition without DAGs |
diff --git a/docs/content/docs/guides/workflows/meta.json b/docs/content/docs/python/guides/workflows/meta.json
similarity index 100%
rename from docs/content/docs/guides/workflows/meta.json
rename to docs/content/docs/python/guides/workflows/meta.json
diff --git a/docs/content/docs/guides/workflows/sagas.mdx b/docs/content/docs/python/guides/workflows/sagas.mdx
similarity index 100%
rename from docs/content/docs/guides/workflows/sagas.mdx
rename to docs/content/docs/python/guides/workflows/sagas.mdx
diff --git a/docs/content/docs/python/meta.json b/docs/content/docs/python/meta.json
new file mode 100644
index 00000000..937521e1
--- /dev/null
+++ b/docs/content/docs/python/meta.json
@@ -0,0 +1,5 @@
+{
+ "title": "Python",
+ "root": true,
+ "pages": ["capabilities", "getting-started", "guides", "architecture", "api-reference", "more"]
+}
diff --git a/docs/content/docs/more/changelog.mdx b/docs/content/docs/python/more/changelog.mdx
similarity index 99%
rename from docs/content/docs/more/changelog.mdx
rename to docs/content/docs/python/more/changelog.mdx
index 4b198d8b..7c41b4b6 100644
--- a/docs/content/docs/more/changelog.mdx
+++ b/docs/content/docs/python/more/changelog.mdx
@@ -183,7 +183,7 @@ Security-hardening release. No breaking changes.
## 0.15.0
-See the [Upgrading to 0.15](/guides/operations/upgrading-0.15) guide for
+See the [Upgrading to 0.15](/python/guides/operations/upgrading-0.15) guide for
migration steps, rolling-upgrade notes, and the downgrade floor.
### Breaking
@@ -245,7 +245,7 @@ migration steps, rolling-upgrade notes, and the downgrade floor.
### Added
-- **Bare-metal autoscaler.** `taskito.autoscale` provides an in-process HPA-style control loop that spawns and drains `taskito worker` subprocesses based on queue depth and utilisation. Mirrors the Kubernetes HPA dual-signal formula (`depth_desired` + `util_desired`). Configurable stabilisation windows (default: scale-up immediate, scale-down 5 minutes), tolerance band (10%), overload override, and crash recovery. Use `serve_autoscaler(queue, AutoscaleConfig(...))` as the entry point. See the [Bare-Metal Autoscaler guide](/guides/operations/autoscaler).
+- **Bare-metal autoscaler.** `taskito.autoscale` provides an in-process HPA-style control loop that spawns and drains `taskito worker` subprocesses based on queue depth and utilisation. Mirrors the Kubernetes HPA dual-signal formula (`depth_desired` + `util_desired`). Configurable stabilisation windows (default: scale-up immediate, scale-down 5 minutes), tolerance band (10%), overload override, and crash recovery. Use `serve_autoscaler(queue, AutoscaleConfig(...))` as the entry point. See the [Bare-Metal Autoscaler guide](/python/guides/operations/autoscaler).
- **Dashboard `/api/workflows` backend.** Four new REST endpoints expose workflow run data: `GET /api/workflows/runs` (paginated list, filterable by definition name and state), `GET /api/workflows/runs/{id}` (run header + per-node detail with compensation fields), `GET /api/workflows/runs/{id}/dag` (DAG JSON), and `GET /api/workflows/runs/{id}/children` (sub-workflow runs). All timestamps are Unix milliseconds.
- **Canvas saga compensation.** `chain`, `group`, and `chord` support `.with_compensation([...])`. On failure, compensators for completed steps are enqueued with a deterministic `canvas_compensation:{run_id}:{slot}` idempotency key. Dispatch order: chain → reverse-sequential, group → parallel, chord → callback compensator first then group members. `Signature.with_compensation(compensator)` lets individual signatures carry their own compensator.
- **Per-item batch results.** `@queue.task(batch={"per_item_results": True})` enables per-item tracking for batched tasks. The task returns `list[BatchItemResult]`; each caller's `BatchedJobResult.result()` returns **only that caller's value**. `BatchItemResult.success(item_index, result)` and `BatchItemResult.failure(item_index, error)` are the constructors. `partial_failures()` returns failed items after a successful batch. `BatchPartialFailureError` and `BatchResultTypeError` are the new exception types. Cannot be combined with `idempotent=True`.
diff --git a/docs/content/docs/more/comparison.mdx b/docs/content/docs/python/more/comparison.mdx
similarity index 98%
rename from docs/content/docs/more/comparison.mdx
rename to docs/content/docs/python/more/comparison.mdx
index d34610dc..b07dbcf9 100644
--- a/docs/content/docs/more/comparison.mdx
+++ b/docs/content/docs/python/more/comparison.mdx
@@ -77,7 +77,7 @@ widely adopted.
**Choose taskito** if you want zero-infrastructure simplicity on a single machine.
**Choose Celery** if you need distributed workers, complex routing, or enterprise features.
-Looking to switch? See the [Migrating from Celery](/guides/operations) guide for a
+Looking to switch? See the [Migrating from Celery](/python/guides/operations) guide for a
step-by-step walkthrough with side-by-side code examples.
### vs RQ (Redis Queue)
diff --git a/docs/content/docs/more/examples/batch-emails.mdx b/docs/content/docs/python/more/examples/batch-emails.mdx
similarity index 100%
rename from docs/content/docs/more/examples/batch-emails.mdx
rename to docs/content/docs/python/more/examples/batch-emails.mdx
diff --git a/docs/content/docs/more/examples/benchmark.mdx b/docs/content/docs/python/more/examples/benchmark.mdx
similarity index 100%
rename from docs/content/docs/more/examples/benchmark.mdx
rename to docs/content/docs/python/more/examples/benchmark.mdx
diff --git a/docs/content/docs/more/examples/data-pipeline.mdx b/docs/content/docs/python/more/examples/data-pipeline.mdx
similarity index 100%
rename from docs/content/docs/more/examples/data-pipeline.mdx
rename to docs/content/docs/python/more/examples/data-pipeline.mdx
diff --git a/docs/content/docs/more/examples/fastapi-service.mdx b/docs/content/docs/python/more/examples/fastapi-service.mdx
similarity index 100%
rename from docs/content/docs/more/examples/fastapi-service.mdx
rename to docs/content/docs/python/more/examples/fastapi-service.mdx
diff --git a/docs/content/docs/python/more/examples/index.mdx b/docs/content/docs/python/more/examples/index.mdx
new file mode 100644
index 00000000..6d1f43e6
--- /dev/null
+++ b/docs/content/docs/python/more/examples/index.mdx
@@ -0,0 +1,16 @@
+---
+title: Examples
+description: "End-to-end examples demonstrating common taskito patterns."
+---
+
+End-to-end examples demonstrating common taskito patterns.
+
+| Example | Description |
+|---------|-------------|
+| [FastAPI Service](/python/more/examples/fastapi-service) | REST API that enqueues tasks and streams progress via SSE |
+| [Notification Service](/python/more/examples/notifications) | Multi-channel notifications with retries and rate limiting |
+| [Web Scraper Pipeline](/python/more/examples/web-scraper) | Distributed scraping with chains and error handling |
+| [Data Pipeline](/python/more/examples/data-pipeline) | ETL pipeline with dependencies, groups, and chords |
+| [DAG Workflows](/python/more/examples/workflows) | Fan-out, conditions, gates, sub-workflows, incremental runs |
+| [Predicate-Gated Jobs](/python/more/examples/predicate-gated-jobs) | Business-hours windows, load-shedding, feature flags, per-tenant quotas |
+| [Benchmark](/python/more/examples/benchmark) | Performance benchmarks comparing taskito to alternatives |
diff --git a/docs/content/docs/more/examples/meta.json b/docs/content/docs/python/more/examples/meta.json
similarity index 100%
rename from docs/content/docs/more/examples/meta.json
rename to docs/content/docs/python/more/examples/meta.json
diff --git a/docs/content/docs/more/examples/notifications.mdx b/docs/content/docs/python/more/examples/notifications.mdx
similarity index 100%
rename from docs/content/docs/more/examples/notifications.mdx
rename to docs/content/docs/python/more/examples/notifications.mdx
diff --git a/docs/content/docs/more/examples/predicate-gated-jobs.mdx b/docs/content/docs/python/more/examples/predicate-gated-jobs.mdx
similarity index 100%
rename from docs/content/docs/more/examples/predicate-gated-jobs.mdx
rename to docs/content/docs/python/more/examples/predicate-gated-jobs.mdx
diff --git a/docs/content/docs/more/examples/saga-checkout.mdx b/docs/content/docs/python/more/examples/saga-checkout.mdx
similarity index 100%
rename from docs/content/docs/more/examples/saga-checkout.mdx
rename to docs/content/docs/python/more/examples/saga-checkout.mdx
diff --git a/docs/content/docs/more/examples/web-scraper.mdx b/docs/content/docs/python/more/examples/web-scraper.mdx
similarity index 100%
rename from docs/content/docs/more/examples/web-scraper.mdx
rename to docs/content/docs/python/more/examples/web-scraper.mdx
diff --git a/docs/content/docs/more/examples/workflows.mdx b/docs/content/docs/python/more/examples/workflows.mdx
similarity index 100%
rename from docs/content/docs/more/examples/workflows.mdx
rename to docs/content/docs/python/more/examples/workflows.mdx
diff --git a/docs/content/docs/more/faq.mdx b/docs/content/docs/python/more/faq.mdx
similarity index 90%
rename from docs/content/docs/more/faq.mdx
rename to docs/content/docs/python/more/faq.mdx
index 7a30b15f..7299d38b 100644
--- a/docs/content/docs/more/faq.mdx
+++ b/docs/content/docs/python/more/faq.mdx
@@ -96,7 +96,7 @@ Use the **Postgres backend** (`pip install taskito[postgres]`) when you need:
- **Existing Postgres infrastructure** — leverage your existing database and backups
For single-machine workloads, SQLite is simpler and requires zero setup. See
-the [Postgres backend guide](/guides/operations).
+the [Postgres backend guide](/python/guides/operations).
## Is taskito production-ready?
@@ -104,7 +104,7 @@ taskito is suitable for production workloads — background job processing,
periodic tasks, data pipelines, and similar use cases.
For single-machine deployments, use the default SQLite backend. For
-multi-server setups, use the [Postgres backend](/guides/operations).
+multi-server setups, use the [Postgres backend](/python/guides/operations).
## What observability options does taskito support?
@@ -112,9 +112,9 @@ taskito offers three observability integrations, each suited to different needs:
| Integration | Best for | Install |
|-------------|----------|---------|
-| **[OpenTelemetry](/guides/integrations)** | Distributed tracing, correlating tasks with HTTP requests | `pip install taskito[otel]` |
-| **[Prometheus](/guides/integrations)** | Metrics dashboards, alerting on queue depth/error rates | `pip install taskito[prometheus]` |
-| **[Sentry](/guides/integrations)** | Error tracking with rich context and breadcrumbs | `pip install taskito[sentry]` |
+| **[OpenTelemetry](/python/guides/integrations)** | Distributed tracing, correlating tasks with HTTP requests | `pip install taskito[otel]` |
+| **[Prometheus](/python/guides/integrations)** | Metrics dashboards, alerting on queue depth/error rates | `pip install taskito[prometheus]` |
+| **[Sentry](/python/guides/integrations)** | Error tracking with rich context and breadcrumbs | `pip install taskito[sentry]` |
All three are implemented as `TaskMiddleware` and can be combined together.
@@ -153,7 +153,7 @@ stats = await queue.astats()
Sync and async tasks can coexist in the same queue. The worker automatically
routes each job to the correct pool based on the task type. See the
-[Async Tasks guide](/guides/advanced-execution) for details including
+[Async Tasks guide](/python/guides/advanced-execution) for details including
`async_concurrency` tuning and `current_job` context in async tasks.
## What serialization format does taskito use?
diff --git a/docs/content/docs/more/meta.json b/docs/content/docs/python/more/meta.json
similarity index 100%
rename from docs/content/docs/more/meta.json
rename to docs/content/docs/python/more/meta.json
From 3bf7ea518efd496650c63a6b385b1347b19f6c9e Mon Sep 17 00:00:00 2001
From: Pratyush Sharma <56130065+pratyush618@users.noreply.github.com>
Date: Sun, 21 Jun 2026 11:19:17 +0530
Subject: [PATCH 39/48] feat(docs): add TypeScript snippet + quickstart link to
hero
---
docs/app/components/landing/hero.tsx | 10 ++++++---
docs/app/lib/landing-content.ts | 33 +++++++++++++++++++++++++++-
2 files changed, 39 insertions(+), 4 deletions(-)
diff --git a/docs/app/components/landing/hero.tsx b/docs/app/components/landing/hero.tsx
index 4791eb7a..f3d16244 100644
--- a/docs/app/components/landing/hero.tsx
+++ b/docs/app/components/landing/hero.tsx
@@ -1,10 +1,10 @@
import { useState } from "react";
import { Link } from "react-router";
import { RawHtml } from "@/components/ui";
-import { highlightPython } from "@/lib/highlight-lite";
+import { highlightPython, highlightTs } from "@/lib/highlight-lite";
import { HERO_PANES, SOON_PANES, type SoonLang } from "@/lib/landing-content";
-type Lang = "py" | "go" | "java";
+type Lang = "py" | "ts" | "go" | "java";
function CopyButton({ text }: { text: string }) {
const [copied, setCopied] = useState(false);
@@ -37,7 +37,11 @@ function SoonBox({ pane }: { pane: SoonLang }) {
export function Hero() {
const [lang, setLang] = useState("py");
const pane = HERO_PANES.find((p) => p.id === lang);
- const codeHtml = pane ? highlightPython(pane.code) : "";
+ const codeHtml = pane
+ ? lang === "ts"
+ ? highlightTs(pane.code)
+ : highlightPython(pane.code)
+ : "";
const active = pane ?? HERO_PANES[0];
return (
diff --git a/docs/app/lib/landing-content.ts b/docs/app/lib/landing-content.ts
index cde6b80d..d5a15e99 100644
--- a/docs/app/lib/landing-content.ts
+++ b/docs/app/lib/landing-content.ts
@@ -10,7 +10,7 @@ export interface OutLine {
}
export interface LangPane {
- id: "py";
+ id: "py" | "ts";
label: string;
filename: string;
install: string;
@@ -54,6 +54,37 @@ print(job.result()) # → 5`,
docHref: "/python/getting-started/quickstart",
docLabel: "Read the Python quickstart",
},
+ {
+ id: "ts",
+ label: "TypeScript",
+ filename: "tasks.ts",
+ install: "pnpm add taskito",
+ code: `import { Queue } from "taskito";
+
+const queue = new Queue({ dbPath: "taskito.db" });
+
+queue.task("add", (a: number, b: number) => a + b, {
+ maxRetries: 3,
+});
+
+const id = queue.enqueue("add", [2, 3]);
+queue.runWorker();
+
+console.log(await queue.result(id)); // → 5`,
+ output: [
+ { glyph: "$", glyphKind: "p", text: "taskito run ./tasks.js" },
+ { glyph: "→", glyphKind: "p", text: "runWorker() · Rust core attached" },
+ {
+ glyph: "✓",
+ glyphKind: "g",
+ text: "add(2, 3) =",
+ value: "5",
+ timing: "9 ms",
+ },
+ ],
+ docHref: "/node/getting-started/quickstart",
+ docLabel: "Read the TypeScript quickstart",
+ },
];
/** Roadmap languages: disabled tab + "coming soon" panel (no fabricated SDK). */
From 9dd6e2f191b84c15934b29b9a8649c50fe1d82d1 Mon Sep 17 00:00:00 2001
From: Pratyush Sharma <56130065+pratyush618@users.noreply.github.com>
Date: Sun, 21 Jun 2026 11:19:17 +0530
Subject: [PATCH 40/48] feat(docs): show Python + TypeScript quickstart links
in hero
---
docs/app/components/landing/hero.tsx | 14 +++++++++++---
docs/app/styles/landing.css | 8 +++++++-
2 files changed, 18 insertions(+), 4 deletions(-)
diff --git a/docs/app/components/landing/hero.tsx b/docs/app/components/landing/hero.tsx
index f3d16244..192c2602 100644
--- a/docs/app/components/landing/hero.tsx
+++ b/docs/app/components/landing/hero.tsx
@@ -141,9 +141,17 @@ export function Hero() {
) : null}
-
- {active.docLabel} →
-
+
+
+ Read the Python quickstart →
+
+
+ Read the TypeScript quickstart →
+
+
);
diff --git a/docs/app/styles/landing.css b/docs/app/styles/landing.css
index ad83bccb..b7e55e07 100644
--- a/docs/app/styles/landing.css
+++ b/docs/app/styles/landing.css
@@ -130,11 +130,17 @@ main {
background: var(--indigo);
opacity: 0.75;
}
+.hero-doclinks {
+ display: flex;
+ flex-wrap: wrap;
+ gap: 10px;
+ margin-top: 14px;
+ align-self: flex-start;
+}
.hero-doclink {
display: inline-flex;
align-items: center;
gap: 7px;
- margin-top: 14px;
align-self: flex-start;
font-family: var(--mono);
font-size: 13px;
From cae7d125a52b0cd68de356ecbc5648509198f365 Mon Sep 17 00:00:00 2001
From: Pratyush Sharma <56130065+pratyush618@users.noreply.github.com>
Date: Sun, 21 Jun 2026 11:19:17 +0530
Subject: [PATCH 41/48] feat(docs): global SDK store + useSdk hook with
no-flash boot
---
docs/app/app.css | 1 +
docs/app/hooks/index.ts | 1 +
docs/app/hooks/use-sdk.ts | 28 ++++++
docs/app/lib/index.ts | 2 +
docs/app/lib/sdk-store.ts | 85 +++++++++++++++++++
docs/app/root.tsx | 13 ++-
docs/app/styles/sdk.css | 21 +++++
.../architecture/failure-model.mdx | 0
.../docs/{python => }/architecture/index.mdx | 0
.../architecture/job-lifecycle.mdx | 0
.../docs/{python => }/architecture/mesh.mdx | 0
.../docs/{python => }/architecture/meta.json | 0
.../{python => }/architecture/overview.mdx | 0
.../{python => }/architecture/resources.mdx | 0
.../{python => }/architecture/scheduler.mdx | 0
.../architecture/serialization.mdx | 0
.../{python => }/architecture/storage.mdx | 0
.../{python => }/architecture/worker-pool.mdx | 0
.../{python/more => resources}/changelog.mdx | 0
.../{python/more => resources}/comparison.mdx | 0
.../docs/{python/more => resources}/faq.mdx | 0
21 files changed, 150 insertions(+), 1 deletion(-)
create mode 100644 docs/app/hooks/index.ts
create mode 100644 docs/app/hooks/use-sdk.ts
create mode 100644 docs/app/lib/index.ts
create mode 100644 docs/app/lib/sdk-store.ts
create mode 100644 docs/app/styles/sdk.css
rename docs/content/docs/{python => }/architecture/failure-model.mdx (100%)
rename docs/content/docs/{python => }/architecture/index.mdx (100%)
rename docs/content/docs/{python => }/architecture/job-lifecycle.mdx (100%)
rename docs/content/docs/{python => }/architecture/mesh.mdx (100%)
rename docs/content/docs/{python => }/architecture/meta.json (100%)
rename docs/content/docs/{python => }/architecture/overview.mdx (100%)
rename docs/content/docs/{python => }/architecture/resources.mdx (100%)
rename docs/content/docs/{python => }/architecture/scheduler.mdx (100%)
rename docs/content/docs/{python => }/architecture/serialization.mdx (100%)
rename docs/content/docs/{python => }/architecture/storage.mdx (100%)
rename docs/content/docs/{python => }/architecture/worker-pool.mdx (100%)
rename docs/content/docs/{python/more => resources}/changelog.mdx (100%)
rename docs/content/docs/{python/more => resources}/comparison.mdx (100%)
rename docs/content/docs/{python/more => resources}/faq.mdx (100%)
diff --git a/docs/app/app.css b/docs/app/app.css
index 766ccd5a..c066aaee 100644
--- a/docs/app/app.css
+++ b/docs/app/app.css
@@ -9,3 +9,4 @@
@import "./styles/diagrams.css";
@import "./styles/landing.css";
@import "./styles/shiki.css";
+@import "./styles/sdk.css";
diff --git a/docs/app/hooks/index.ts b/docs/app/hooks/index.ts
new file mode 100644
index 00000000..73471711
--- /dev/null
+++ b/docs/app/hooks/index.ts
@@ -0,0 +1 @@
+export { type Sdk, useActiveSdk, useSdk } from "./use-sdk";
diff --git a/docs/app/hooks/use-sdk.ts b/docs/app/hooks/use-sdk.ts
new file mode 100644
index 00000000..2b9b9315
--- /dev/null
+++ b/docs/app/hooks/use-sdk.ts
@@ -0,0 +1,28 @@
+import { useSyncExternalStore } from "react";
+import { useLocation } from "react-router";
+import { forcedSdkForPath, type Sdk, sdkStore } from "@/lib";
+
+export type { Sdk };
+
+/** Reactive active SDK + setter, backed by the SSG-safe external store. The
+ * server snapshot is the default SDK, so prerendered HTML and the first client
+ * render agree; the boot script has already applied the real value to
+ * `` before paint. */
+export function useSdk(): { sdk: Sdk; setSdk: (sdk: Sdk) => void } {
+ const sdk = useSyncExternalStore(
+ sdkStore.subscribe,
+ sdkStore.getSnapshot,
+ sdkStore.getServerSnapshot,
+ );
+ return { sdk, setSdk: sdkStore.set };
+}
+
+/** The SDK to render for the current page: forced by the URL prefix on
+ * SDK-specific pages, otherwise the global store value (shared pages). Avoids a
+ * first-paint nav flash when a `/node/*` URL loads while the store still holds
+ * the default. */
+export function useActiveSdk(): Sdk {
+ const { sdk } = useSdk();
+ const { pathname } = useLocation();
+ return forcedSdkForPath(pathname.replace(/\/$/, "") || "/") ?? sdk;
+}
diff --git a/docs/app/lib/index.ts b/docs/app/lib/index.ts
new file mode 100644
index 00000000..6f6530c7
--- /dev/null
+++ b/docs/app/lib/index.ts
@@ -0,0 +1,2 @@
+export * from "./nav";
+export * from "./sdk-store";
diff --git a/docs/app/lib/sdk-store.ts b/docs/app/lib/sdk-store.ts
new file mode 100644
index 00000000..54a4d7f7
--- /dev/null
+++ b/docs/app/lib/sdk-store.ts
@@ -0,0 +1,85 @@
+// Global active-SDK store. Single source of truth shared by the no-flash boot
+// script (root.tsx), the sidebar switcher, inline ``, and ``.
+// Kept as a tiny external store so `useSyncExternalStore` can hand React an
+// explicit server snapshot — the SSG-safe way to read a browser-only value
+// without a hydration mismatch. The live value lives on ``; CSS
+// shows/hides each SDK's variants off that attribute.
+
+export type Sdk = "python" | "node";
+
+const KEY = "taskito-sdk";
+const DEFAULT: Sdk = "python";
+
+const listeners = new Set<() => void>();
+
+function isSdk(value: string | null | undefined): value is Sdk {
+ return value === "python" || value === "node";
+}
+
+/** Resolve the active SDK: `?sdk=` query > localStorage > default. Used by the
+ * no-flash bootstrap in root.tsx and as the first client read. */
+export function readSdk(): Sdk {
+ if (typeof document === "undefined") {
+ return DEFAULT;
+ }
+ try {
+ const param = new URLSearchParams(window.location.search).get("sdk");
+ if (isSdk(param)) {
+ return param;
+ }
+ const stored = localStorage.getItem(KEY);
+ if (isSdk(stored)) {
+ return stored;
+ }
+ } catch {
+ // ignore storage/URL access failures (private mode etc.)
+ }
+ return DEFAULT;
+}
+
+function currentSdk(): Sdk {
+ const attr = document.documentElement.dataset.sdk;
+ return isSdk(attr) ? attr : DEFAULT;
+}
+
+function notify(): void {
+ for (const listener of listeners) {
+ listener();
+ }
+}
+
+// Another tab changed the choice — mirror it onto this document, then notify.
+function onStorage(event: StorageEvent): void {
+ if (event.key !== KEY || !isSdk(event.newValue)) {
+ return;
+ }
+ document.documentElement.dataset.sdk = event.newValue;
+ notify();
+}
+
+export const sdkStore = {
+ subscribe(callback: () => void): () => void {
+ if (listeners.size === 0) {
+ window.addEventListener("storage", onStorage);
+ }
+ listeners.add(callback);
+ return () => {
+ listeners.delete(callback);
+ if (listeners.size === 0) {
+ window.removeEventListener("storage", onStorage);
+ }
+ };
+ },
+ getSnapshot: currentSdk,
+ getServerSnapshot: (): Sdk => DEFAULT,
+ /** Set + persist the active SDK; drives the CSS show/hide via ``. */
+ set(sdk: Sdk): void {
+ document.documentElement.dataset.sdk = sdk;
+ try {
+ localStorage.setItem(KEY, sdk);
+ } catch {
+ // ignore storage failures (private mode etc.)
+ }
+ notify();
+ },
+};
diff --git a/docs/app/root.tsx b/docs/app/root.tsx
index c2b0ba90..eaa60842 100644
--- a/docs/app/root.tsx
+++ b/docs/app/root.tsx
@@ -25,14 +25,25 @@ export const links: Route.LinksFunction = () => [
// Apply the persisted theme before paint to avoid a light/dark flash.
const THEME_INIT = `(function(){try{var t=localStorage.getItem('taskito-theme')||'dark';document.documentElement.setAttribute('data-theme',t);}catch(e){}})();`;
+// Apply the active SDK before paint (query > localStorage > default) so the
+// CSS show/hide picks the right variant with no flash. Mirrors readSdk().
+const SDK_INIT = `(function(){try{var u=new URLSearchParams(location.search).get('sdk');var s=(u==='python'||u==='node')?u:(localStorage.getItem('taskito-sdk')||'python');if(s!=='python'&&s!=='node'){s='python';}document.documentElement.setAttribute('data-sdk',s);}catch(e){document.documentElement.setAttribute('data-sdk','python');}})();`;
+
export function Layout({ children }: { children: React.ReactNode }) {
return (
-
+
{/* biome-ignore lint/security/noDangerouslySetInnerHtml: tiny no-flash theme bootstrap */}
+ {/* biome-ignore lint/security/noDangerouslySetInnerHtml: tiny no-flash sdk bootstrap */}
+
= { python: "Python", node: "Node.js" };
+
+/** Show children only under one SDK. All variants ship in the HTML; the inactive
+ * one is hidden by CSS off `` — no flash, no hydration mismatch. */
+export function SdkOnly({ sdk, children }: { sdk: Sdk; children: ReactNode }) {
+ return {children};
+}
+
+/** Internal link from a shared page into an SDK-specific tree. `to="guides/x"`
+ * resolves to `/{activeSdk}/guides/x` and re-points when the SDK switches. */
+export function SdkLink({
+ to,
+ children,
+ ...rest
+}: { to: string; children: ReactNode } & Omit<
+ ComponentProps,
+ "to" | "children"
+>) {
+ const { sdk } = useSdk();
+ const path = to.startsWith("/") ? to : `/${to}`;
+ return (
+
+ {children}
+
+ );
+}
+
+type TabChild = ReactElement<{ sdk: Sdk; children: ReactNode }>;
+
+/** Synced code/prose tabs: one panel per ``. Selecting a tab sets
+ * the global SDK, so every CodeTabs on the page and the sidebar switch together.
+ * Visibility is CSS-driven (data-sdk-variant); the tablist is APG-compliant. */
+export function CodeTabs({ children }: { children: ReactNode }) {
+ const { sdk, setSdk } = useSdk();
+ const baseId = useId();
+ const panels = Children.toArray(children).filter(
+ isValidElement,
+ ) as TabChild[];
+ const order = panels.map((p) => p.props.sdk);
+ const tabs = useRef<(HTMLButtonElement | null)[]>([]);
+ const tabId = (variant: Sdk) => `${baseId}-tab-${variant}`;
+ const panelId = (variant: Sdk) => `${baseId}-panel-${variant}`;
+
+ function onKeyDown(event: React.KeyboardEvent, index: number) {
+ const delta =
+ event.key === "ArrowRight" ? 1 : event.key === "ArrowLeft" ? -1 : 0;
+ if (delta === 0) {
+ return;
+ }
+ event.preventDefault();
+ const next = (index + delta + order.length) % order.length;
+ setSdk(order[next]);
+ tabs.current[next]?.focus();
+ }
+
+ return (
+
+
+ {order.map((variant, index) => {
+ const selected = variant === sdk;
+ return (
+
+ );
+ })}
+
+ {panels.map((panel) => (
+
+ {panel.props.children}
+
+ ))}
+
+ );
+}
diff --git a/docs/app/components/mdx/tabs.tsx b/docs/app/components/mdx/tabs.tsx
index 896dda8b..c5e98ab0 100644
--- a/docs/app/components/mdx/tabs.tsx
+++ b/docs/app/components/mdx/tabs.tsx
@@ -6,8 +6,15 @@ import {
useState,
} from "react";
-/** Design-matched replacement for `fumadocs-ui/components/tabs` (aliased in vite). */
-export function Tab({ children }: { value: string; children?: ReactNode }) {
+/** Tab panel for both `` (keyed by `value`) and `` (keyed
+ * by `sdk`); a pass-through whose parent reads the relevant prop. */
+export function Tab({
+ children,
+}: {
+ value?: string;
+ sdk?: string;
+ children?: ReactNode;
+}) {
return <>{children};
}
From a23658f06d24d730a4e278d662b49e1a5ae07baf Mon Sep 17 00:00:00 2001
From: Pratyush Sharma <56130065+pratyush618@users.noreply.github.com>
Date: Sun, 21 Jun 2026 11:19:17 +0530
Subject: [PATCH 43/48] feat(docs): drive nav + sidebar from SDK store,
collapsible groups
---
docs/app/components/docs/prev-next.tsx | 5 +-
docs/app/components/docs/sidebar.tsx | 79 ++++++++++++++++++--------
docs/app/lib/nav.ts | 41 ++++++++++---
docs/app/routes/docs-layout.tsx | 15 ++++-
docs/app/styles/docs.css | 23 ++++++++
5 files changed, 130 insertions(+), 33 deletions(-)
diff --git a/docs/app/components/docs/prev-next.tsx b/docs/app/components/docs/prev-next.tsx
index 95e31204..f78fa6aa 100644
--- a/docs/app/components/docs/prev-next.tsx
+++ b/docs/app/components/docs/prev-next.tsx
@@ -1,11 +1,12 @@
import { Link, useLocation } from "react-router";
-import { flatNav, sdkForPath } from "@/lib/nav";
+import { useActiveSdk } from "@/hooks";
+import { flatNav } from "@/lib";
/** Previous/next page links derived from the flattened SDK nav order. */
export function PrevNext() {
const { pathname } = useLocation();
const current = pathname.replace(/\/$/, "") || "/";
- const pages = flatNav(sdkForPath(current));
+ const pages = flatNav(useActiveSdk());
const i = pages.findIndex((p) => p.href === current);
if (i === -1) {
return null;
diff --git a/docs/app/components/docs/sidebar.tsx b/docs/app/components/docs/sidebar.tsx
index c6ca7955..391a9cdb 100644
--- a/docs/app/components/docs/sidebar.tsx
+++ b/docs/app/components/docs/sidebar.tsx
@@ -1,6 +1,13 @@
import { useEffect, useState } from "react";
-import { Link, useLocation } from "react-router";
-import { type NavNode, navForSdk, type Sdk, sdkForPath } from "@/lib/nav";
+import { Link, useLocation, useNavigate } from "react-router";
+import { useActiveSdk, useSdk } from "@/hooks";
+import {
+ forcedSdkForPath,
+ type NavNode,
+ navForSdk,
+ type Sdk,
+ sdkSwitchTarget,
+} from "@/lib";
function containsHref(node: NavNode, current: string): boolean {
return (
@@ -9,25 +16,42 @@ function containsHref(node: NavNode, current: string): boolean {
);
}
-function SdkSwitch({ sdk }: { sdk: Sdk }) {
+const SDK_LABELS: { id: Sdk; label: string }[] = [
+ { id: "python", label: "Python" },
+ { id: "node", label: "Node.js" },
+];
+
+/** Global SDK toggle. Sets the shared store (flips inline variants + this nav);
+ * on an SDK-specific page it also navigates to the counterpart page, on a shared
+ * page it stays put. A labelled control — it switches the whole page, not a panel. */
+function SdkSwitch({ sdk, current }: { sdk: Sdk; current: string }) {
+ const { setSdk } = useSdk();
+ const navigate = useNavigate();
+
+ function select(target: Sdk) {
+ if (target === sdk) {
+ return;
+ }
+ setSdk(target);
+ if (forcedSdkForPath(current)) {
+ navigate(sdkSwitchTarget(current, target));
+ }
+ }
+
return (
-
-
- Python
-
-
- Node.js
-
+
+ {SDK_LABELS.map(({ id, label }) => (
+
+ ))}
);
}
@@ -134,7 +158,16 @@ function NavGroup({ group, current }: { group: NavNode; current: string }) {
return (
- {group.href ? (
+ {hasChildren ? (
+
+ ) : group.href ? (
{group.title}
@@ -159,7 +192,7 @@ function NavGroup({ group, current }: { group: NavNode; current: string }) {
export function Sidebar({ onSearch }: { onSearch?: () => void }) {
const { pathname } = useLocation();
const current = pathname.replace(/\/$/, "") || "/";
- const sdk = sdkForPath(current);
+ const sdk = useActiveSdk();
return (