From f2be4a87c1b8afa297b60a411b6725983dc004ad Mon Sep 17 00:00:00 2001 From: Pratyush Sharma <56130065+pratyush618@users.noreply.github.com> Date: Sun, 3 May 2026 11:00:38 +0530 Subject: [PATCH 01/14] feat(docs): add How It Works job-flow strip with reduced-motion fallback --- .../src/app/(home)/_sections/how-it-works.tsx | 117 ++++++++++++++++++ docs/src/app/(home)/_sections/index.ts | 1 + docs/src/app/(home)/page.tsx | 9 +- 3 files changed, 126 insertions(+), 1 deletion(-) create mode 100644 docs/src/app/(home)/_sections/how-it-works.tsx diff --git a/docs/src/app/(home)/_sections/how-it-works.tsx b/docs/src/app/(home)/_sections/how-it-works.tsx new file mode 100644 index 0000000..62c716b --- /dev/null +++ b/docs/src/app/(home)/_sections/how-it-works.tsx @@ -0,0 +1,117 @@ +const STATIONS = [ + { label: "enqueue", cx: 30 }, + { label: "queue", cx: 110 }, + { label: "worker", cx: 190 }, + { label: "result", cx: 270 }, +] as const; + +const VIEW_WIDTH = 300; +const TRACK_Y = 22; +const STATION_RADIUS = 6; + +export function HowItWorks() { + return ( +
+
+

+ How it works +

+
+
+ + + {STATIONS.map((station) => ( + + + + {station.label} + + + ))} + + + +
+ +
+ ); +} diff --git a/docs/src/app/(home)/_sections/index.ts b/docs/src/app/(home)/_sections/index.ts index 272f7e4..59c8562 100644 --- a/docs/src/app/(home)/_sections/index.ts +++ b/docs/src/app/(home)/_sections/index.ts @@ -2,3 +2,4 @@ export { ComparisonSection } from "./comparison-section"; export { CTA } from "./cta"; export { Features } from "./features"; export { Hero } from "./hero"; +export { HowItWorks } from "./how-it-works"; diff --git a/docs/src/app/(home)/page.tsx b/docs/src/app/(home)/page.tsx index 8ad91ad..c061c5e 100644 --- a/docs/src/app/(home)/page.tsx +++ b/docs/src/app/(home)/page.tsx @@ -1,9 +1,16 @@ -import { ComparisonSection, CTA, Features, Hero } from "./_sections"; +import { + ComparisonSection, + CTA, + Features, + Hero, + HowItWorks, +} from "./_sections"; export default function HomePage() { return (
+ From 85cdd21b5475fac38c2cd9f23d50a35e2615c424 Mon Sep 17 00:00:00 2001 From: Pratyush Sharma <56130065+pratyush618@users.noreply.github.com> Date: Sun, 3 May 2026 11:06:04 +0530 Subject: [PATCH 02/14] feat(docs): polish How It Works strip with multi-job flow and glyphs --- .../src/app/(home)/_sections/how-it-works.tsx | 426 ++++++++++++++---- 1 file changed, 340 insertions(+), 86 deletions(-) diff --git a/docs/src/app/(home)/_sections/how-it-works.tsx b/docs/src/app/(home)/_sections/how-it-works.tsx index 62c716b..62988e0 100644 --- a/docs/src/app/(home)/_sections/how-it-works.tsx +++ b/docs/src/app/(home)/_sections/how-it-works.tsx @@ -1,117 +1,371 @@ -const STATIONS = [ - { label: "enqueue", cx: 30 }, - { label: "queue", cx: 110 }, - { label: "worker", cx: 190 }, - { label: "result", cx: 270 }, -] as const; +import type { ReactNode } from "react"; -const VIEW_WIDTH = 300; -const TRACK_Y = 22; -const STATION_RADIUS = 6; +type Station = { + id: string; + label: string; + hint: string; + cx: number; + glyph: ReactNode; +}; + +const VIEW_WIDTH = 380; +const TRACK_Y = 36; +const STATION_RADIUS = 14; + +const STATIONS: Station[] = [ + { + id: "enqueue", + label: "enqueue", + hint: ".delay()", + cx: 40, + glyph: , + }, + { + id: "queue", + label: "queue", + hint: "SQLite · Postgres", + cx: 145, + glyph: , + }, + { + id: "worker", + label: "worker", + hint: "Rust pool", + cx: 250, + glyph: , + }, + { + id: "result", + label: "result", + hint: ".result()", + cx: 340, + glyph: , + }, +]; + +const JOB_DELAYS = ["0s", "-1.6s", "-3.2s"] as const; export function HowItWorks() { return ( -
-
-

+
+
+

How it works

+

+ Your code calls{" "} + .delay() · the + job durably queues · a Rust scheduler routes it · a worker returns the + result. +

+ + + + + + + + + + + + + + + {STATIONS.map((station) => ( - + + ))} + + {JOB_DELAYS.map((delay, index) => ( + + - - {station.label} - ))} - -
- -
+ .taskito-flow .taskito-result-pulse { + animation: taskito-result-pulse 4.8s ease-out infinite; + } + .taskito-flow .taskito-track { + animation: taskito-track-shimmer 1.6s linear infinite; + } + } + `} ); } From 9cc04c8697d05283c3fdde894fdb59e2d2d5f0ce Mon Sep 17 00:00:00 2001 From: Pratyush Sharma <56130065+pratyush618@users.noreply.github.com> Date: Sun, 3 May 2026 11:11:33 +0530 Subject: [PATCH 03/14] feat(docs): add WorkerPool, UseCases, and Integrations landing sections --- docs/src/app/(home)/_sections/index.ts | 3 + .../src/app/(home)/_sections/integrations.tsx | 39 +++ docs/src/app/(home)/_sections/use-cases.tsx | 52 ++++ docs/src/app/(home)/_sections/worker-pool.tsx | 269 ++++++++++++++++++ docs/src/app/(home)/page.tsx | 6 + docs/src/lib/landing-content.tsx | 69 +++++ 6 files changed, 438 insertions(+) create mode 100644 docs/src/app/(home)/_sections/integrations.tsx create mode 100644 docs/src/app/(home)/_sections/use-cases.tsx create mode 100644 docs/src/app/(home)/_sections/worker-pool.tsx diff --git a/docs/src/app/(home)/_sections/index.ts b/docs/src/app/(home)/_sections/index.ts index 59c8562..5a5c059 100644 --- a/docs/src/app/(home)/_sections/index.ts +++ b/docs/src/app/(home)/_sections/index.ts @@ -3,3 +3,6 @@ export { CTA } from "./cta"; export { Features } from "./features"; export { Hero } from "./hero"; export { HowItWorks } from "./how-it-works"; +export { Integrations } from "./integrations"; +export { UseCases } from "./use-cases"; +export { WorkerPool } from "./worker-pool"; diff --git a/docs/src/app/(home)/_sections/integrations.tsx b/docs/src/app/(home)/_sections/integrations.tsx new file mode 100644 index 0000000..ca0eb69 --- /dev/null +++ b/docs/src/app/(home)/_sections/integrations.tsx @@ -0,0 +1,39 @@ +import { SectionHeader } from "@/components/ui"; +import { + INTEGRATIONS, + INTEGRATIONS_DESCRIPTION, + INTEGRATIONS_TITLE, +} from "@/lib/landing-content"; + +export function Integrations() { + return ( +
+ +
+ {INTEGRATIONS.map((group) => ( +
+
+ {group.group} +
+
+ {group.items.map((item) => ( + + {item} + + ))} +
+
+ ))} +
+
+ ); +} diff --git a/docs/src/app/(home)/_sections/use-cases.tsx b/docs/src/app/(home)/_sections/use-cases.tsx new file mode 100644 index 0000000..3458d3d --- /dev/null +++ b/docs/src/app/(home)/_sections/use-cases.tsx @@ -0,0 +1,52 @@ +import { ArrowUpRight } from "lucide-react"; +import Link from "next/link"; +import { SectionHeader } from "@/components/ui"; +import { + USE_CASES, + USE_CASES_DESCRIPTION, + USE_CASES_TITLE, + type UseCase, +} from "@/lib/landing-content"; + +export function UseCases() { + return ( +
+ +
+ {USE_CASES.map((useCase) => ( + + ))} +
+
+ ); +} + +function UseCaseCard({ useCase }: { useCase: UseCase }) { + const { icon: Icon, title, body, href } = useCase; + return ( + +
+
+
+
+ +
+ +
+

{title}

+

+ {body} +

+
+ + ); +} diff --git a/docs/src/app/(home)/_sections/worker-pool.tsx b/docs/src/app/(home)/_sections/worker-pool.tsx new file mode 100644 index 0000000..e95df58 --- /dev/null +++ b/docs/src/app/(home)/_sections/worker-pool.tsx @@ -0,0 +1,269 @@ +import { SectionHeader } from "@/components/ui"; + +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 POOL_LEFT = 180; +const POOL_TOP = 30; +const WORKER_SIZE = 32; +const WORKER_GAP = 10; +const POOL_WIDTH = 3 * WORKER_SIZE + 2 * WORKER_GAP; +const POOL_HEIGHT = 2 * WORKER_SIZE + 1 * WORKER_GAP; +const VIEW_W = 560; +const VIEW_H = 130; +const POOL_RIGHT = POOL_LEFT + POOL_WIDTH; + +export function WorkerPool() { + return ( +
+ +
+ + + + + + + + + + + + + + INCOMING + + + WORKERS + + + RESULTS + + + {INCOMING_JOBS.map((job, i) => ( + + ))} + + {WORKERS.map((worker) => { + const x = POOL_LEFT + worker.x * (WORKER_SIZE + WORKER_GAP); + const y = POOL_TOP + worker.y * (WORKER_SIZE + WORKER_GAP); + return ( + + + + + ); + })} + + {RESULTS.map((result, i) => ( + + + + + ))} + + + 6 workers · 0 brokers + + +
+ +
+ ); +} + +function PoolStyles() { + return ( + + ); +} diff --git a/docs/src/app/(home)/page.tsx b/docs/src/app/(home)/page.tsx index c061c5e..dc0dc09 100644 --- a/docs/src/app/(home)/page.tsx +++ b/docs/src/app/(home)/page.tsx @@ -4,6 +4,9 @@ import { Features, Hero, HowItWorks, + Integrations, + UseCases, + WorkerPool, } from "./_sections"; export default function HomePage() { @@ -11,7 +14,10 @@ export default function HomePage() {
+ + +
diff --git a/docs/src/lib/landing-content.tsx b/docs/src/lib/landing-content.tsx index 295aeb6..ad092be 100644 --- a/docs/src/lib/landing-content.tsx +++ b/docs/src/lib/landing-content.tsx @@ -1,8 +1,11 @@ import { Activity, + Clock, Cpu, + Database, Layers, type LucideIcon, + Mail, Shield, Workflow, Zap, @@ -199,6 +202,72 @@ send_email.delay("alice@example.com", "Hi", "Body") ], }; +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: "/docs/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: "/docs/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: "/docs/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: "/docs/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: From 7c1fcf98d51072bba51262a13d80359a4c7749ef Mon Sep 17 00:00:00 2001 From: Pratyush Sharma <56130065+pratyush618@users.noreply.github.com> Date: Sun, 3 May 2026 11:24:59 +0530 Subject: [PATCH 04/14] fix(docs): repair WorkerPool result lane and active-worker visual --- docs/src/app/(home)/_sections/worker-pool.tsx | 340 +++++++++--------- 1 file changed, 180 insertions(+), 160 deletions(-) diff --git a/docs/src/app/(home)/_sections/worker-pool.tsx b/docs/src/app/(home)/_sections/worker-pool.tsx index e95df58..5a8627f 100644 --- a/docs/src/app/(home)/_sections/worker-pool.tsx +++ b/docs/src/app/(home)/_sections/worker-pool.tsx @@ -22,15 +22,19 @@ const RESULTS = [ { delay: "-1.5s" }, ] as const; -const POOL_LEFT = 180; -const POOL_TOP = 30; -const WORKER_SIZE = 32; +const VIEW_W = 560; +const VIEW_H = 150; +const POOL_LEFT = 200; +const POOL_TOP = 38; +const WORKER_SIZE = 34; const WORKER_GAP = 10; const POOL_WIDTH = 3 * WORKER_SIZE + 2 * WORKER_GAP; const POOL_HEIGHT = 2 * WORKER_SIZE + 1 * WORKER_GAP; -const VIEW_W = 560; -const VIEW_H = 130; 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 ( @@ -46,149 +50,47 @@ export function WorkerPool() { viewBox={`0 0 ${VIEW_W} ${VIEW_H}`} className="w-full max-w-2xl taskito-pool" > - - - - - - - - - - - - - INCOMING - - - WORKERS - - - RESULTS - + + {INCOMING_JOBS.map((job, i) => ( ))} - {WORKERS.map((worker) => { - const x = POOL_LEFT + worker.x * (WORKER_SIZE + WORKER_GAP); - const y = POOL_TOP + worker.y * (WORKER_SIZE + WORKER_GAP); - return ( - - - - - ); - })} + {WORKERS.map((worker) => ( + + ))} {RESULTS.map((result, i) => ( ))} @@ -211,58 +113,176 @@ export function WorkerPool() { ); } +function LaneLabels() { + return ( + <> + + INCOMING + + + WORKERS + + + RESULTS + + + ); +} + +function Lanes() { + return ( + <> + + + + ); +} + +function Worker({ worker }: { worker: (typeof WORKERS)[number] }) { + const x = POOL_LEFT + worker.x * (WORKER_SIZE + WORKER_GAP); + const y = POOL_TOP + worker.y * (WORKER_SIZE + WORKER_GAP); + const cx = x + WORKER_SIZE / 2; + const cy = y + WORKER_SIZE / 2; + return ( + + + + + + + ); +} + function PoolStyles() { return ( ); From 02d6dd117f7b77a225060bad2e8556e18fc588d4 Mon Sep 17 00:00:00 2001 From: Pratyush Sharma <56130065+pratyush618@users.noreply.github.com> Date: Sun, 3 May 2026 11:27:20 +0530 Subject: [PATCH 05/14] docs: enrich docs section-index pages with icon cards --- docs/content/docs/api-reference/index.mdx | 77 ++++++++++++++++++++++ docs/content/docs/architecture/index.mdx | 70 ++++++++++++++++++++ docs/content/docs/guides/index.mdx | 79 ++++++++++++++++++++--- docs/content/docs/index.mdx | 15 +++-- 4 files changed, 226 insertions(+), 15 deletions(-) create mode 100644 docs/content/docs/api-reference/index.mdx create mode 100644 docs/content/docs/architecture/index.mdx diff --git a/docs/content/docs/api-reference/index.mdx b/docs/content/docs/api-reference/index.mdx new file mode 100644 index 0000000..b778af5 --- /dev/null +++ b/docs/content/docs/api-reference/index.mdx @@ -0,0 +1,77 @@ +--- +title: API Reference +description: Every public class, method, and CLI command in taskito. +--- + +import { Cards, Card } from "fumadocs-ui/components/card"; +import { + Compass, + Inbox, + ListTodo, + CheckCircle2, + Variable, + GitFork, + Workflow, + TestTube, + Terminal, +} from "lucide-react"; + +Reference docs for everything taskito exposes. Each page lists the full +signature, parameters, return values, and a short example. + + + } + title="Overview" + href="/docs/api-reference/overview" + description="The shape of the public API — what's stable, what's experimental." + /> + } + title="Queue" + href="/docs/api-reference/queue" + description="Construct queues, enqueue jobs, manage workers, inspect state." + /> + } + title="Task" + href="/docs/api-reference/task" + description="The @queue.task decorator — options, methods, async variants." + /> + } + title="Result" + href="/docs/api-reference/result" + description="JobResult, polling, awaiting, timeouts, sync and async APIs." + /> + } + title="Context" + href="/docs/api-reference/context" + description="current_job — progress, logging, cancellation, timeouts inside a task." + /> + } + title="Canvas" + href="/docs/api-reference/canvas" + description="chain, group, chord — the Celery-compatible composition primitives." + /> + } + title="Workflows" + href="/docs/api-reference/workflows" + description="The DAG builder — fan-out, fan-in, gates, conditions, sub-workflows." + /> + } + title="Testing" + href="/docs/api-reference/testing" + description="test_mode, MockResource, fixtures for synchronous in-process verification." + /> + } + title="CLI" + href="/docs/api-reference/cli" + description="taskito worker, dashboard, info — every flag and subcommand." + /> + diff --git a/docs/content/docs/architecture/index.mdx b/docs/content/docs/architecture/index.mdx new file mode 100644 index 0000000..b3560bd --- /dev/null +++ b/docs/content/docs/architecture/index.mdx @@ -0,0 +1,70 @@ +--- +title: Architecture +description: How taskito works under the hood — Rust core, scheduler, storage, worker pool. +--- + +import { Cards, Card } from "fumadocs-ui/components/card"; +import { + Compass, + GitBranch, + Layers, + CalendarClock, + Database, + Boxes, + ShieldAlert, + FileCode2, +} from "lucide-react"; + +The internals, explained from the outside in. Start with **Overview** for the +high-level model, then drill into the layer that interests you. + + + } + title="Overview" + href="/docs/architecture/overview" + description="The big picture — Python ↔ PyO3 ↔ Rust core, end to end." + /> + } + title="Job lifecycle" + href="/docs/architecture/job-lifecycle" + description="Every state a job moves through, from enqueue to result or dead letter." + /> + } + title="Worker pool" + href="/docs/architecture/worker-pool" + description="OS-thread pool, prefork children, async executor — how each model dispatches work." + /> + } + title="Scheduler" + href="/docs/architecture/scheduler" + description="The Tokio polling loop — how jobs are picked, claimed, and routed to workers." + /> + } + title="Storage" + href="/docs/architecture/storage" + description="The Storage trait, Diesel for SQLite/Postgres, Redis backend, table schemas." + /> + } + title="Resources" + href="/docs/architecture/resources" + description="The 3-layer DI pipeline — argument interception, worker injection, proxy reconstruction." + /> + } + title="Failure model" + href="/docs/architecture/failure-model" + description="Retries, dead letters, circuit breakers, cancellation — what happens when things go wrong." + /> + } + title="Serialization" + href="/docs/architecture/serialization" + description="Cloudpickle, JSON, MsgPack — how arguments and results cross the worker boundary." + /> + diff --git a/docs/content/docs/guides/index.mdx b/docs/content/docs/guides/index.mdx index 9c0ba0b..262b94d 100644 --- a/docs/content/docs/guides/index.mdx +++ b/docs/content/docs/guides/index.mdx @@ -3,16 +3,75 @@ title: Guides description: Topical guides covering taskito's surface area. --- -import { Cards, Card } from 'fumadocs-ui/components/card'; +import { Cards, Card } from "fumadocs-ui/components/card"; +import { + Boxes, + ShieldCheck, + Cpu, + Wrench, + Activity, + Layers, + Workflow, + Plug, + Puzzle, +} from "lucide-react"; + +Pick the topic you're working through. Each guide is self-contained, with code +samples, gotchas, and links to the relevant API reference. - - - - - - - - - + } + title="Core" + href="/docs/guides/core" + description="Define tasks, route to queues, run workers, schedule periodics." + /> + } + title="Reliability" + href="/docs/guides/reliability" + description="Retries, dead letters, circuit breakers, idempotency, error handling." + /> + } + title="Advanced execution" + href="/docs/guides/advanced-execution" + description="Prefork pools, native async, streaming, cancellation, soft timeouts." + /> + } + title="Operations" + href="/docs/guides/operations" + description="Deployment, scaling, namespaces, migration from Celery." + /> + } + title="Observability" + href="/docs/guides/observability" + description="Metrics, logs, dashboard, OpenTelemetry, Sentry, Prometheus." + /> + } + title="Resources" + href="/docs/guides/resources" + description="Inject DB clients, HTTP sessions, and cloud SDKs by name with hot reload." + /> + } + title="Workflows" + href="/docs/guides/workflows" + description="DAGs, fan-out, fan-in, conditions, gates, sub-workflows, incremental re-runs." + /> + } + title="Integrations" + href="/docs/guides/integrations" + description="Django, FastAPI, Flask — admin views, REST routers, management commands." + /> + } + title="Extensibility" + href="/docs/guides/extensibility" + description="Custom serializers, middleware, events, webhooks, proxies." + /> diff --git a/docs/content/docs/index.mdx b/docs/content/docs/index.mdx index c73649e..7e42a9a 100644 --- a/docs/content/docs/index.mdx +++ b/docs/content/docs/index.mdx @@ -4,6 +4,7 @@ description: Rust-powered task queue for Python. No broker required. --- import { Cards, Card } from "fumadocs-ui/components/card"; +import { Rocket, BookOpen, Boxes, Code2 } from "lucide-react"; A brokerless, Rust-powered task queue for Python. Replace Celery without Redis. @@ -26,23 +27,27 @@ Python only runs during actual task execution. } title="Getting Started" href="/docs/getting-started/installation" description="Install and run your first task in 5 minutes." /> } title="Guides" href="/docs/guides" - description="Core, reliability, advanced execution, operations, observability." + description="Topical walkthroughs grouped by intent — core, reliability, advanced execution, operations, more." /> } title="Architecture" - href="/docs/architecture/overview" - description="How taskito is built — Rust core, PyO3 boundary, storage layer." + href="/docs/architecture" + description="How the Rust core, scheduler, storage, and worker pool fit together." /> } title="API Reference" - href="/docs/api-reference/overview" - description="Complete API surface for the Queue, tasks, results, locks, and workflows." + href="/docs/api-reference" + description="Every public class, method, and CLI command with signatures and examples." /> From 787851cab00f5aee0cb90c1a8c7cfa1a5d20234c Mon Sep 17 00:00:00 2001 From: Pratyush Sharma <56130065+pratyush618@users.noreply.github.com> Date: Sun, 3 May 2026 11:37:59 +0530 Subject: [PATCH 06/14] chore(docs): load IBM Plex Sans/Mono and Caveat handwritten font --- docs/biome.json | 10 +++++++++- docs/src/app/global.css | 13 +++++++++++++ docs/src/app/layout.tsx | 24 +++++++++++++++++++++--- 3 files changed, 43 insertions(+), 4 deletions(-) diff --git a/docs/biome.json b/docs/biome.json index dd49529..87cba3b 100644 --- a/docs/biome.json +++ b/docs/biome.json @@ -7,7 +7,15 @@ }, "files": { "ignoreUnknown": true, - "includes": ["**", "!node_modules", "!.next", "!dist", "!build", "!.source"] + "includes": [ + "**", + "!node_modules", + "!.next", + "!dist", + "!build", + "!.source", + "!src/app/global.css" + ] }, "formatter": { "enabled": true, diff --git a/docs/src/app/global.css b/docs/src/app/global.css index 488ce0e..be36e7f 100644 --- a/docs/src/app/global.css +++ b/docs/src/app/global.css @@ -2,6 +2,19 @@ @import "fumadocs-ui/css/neutral.css"; @import "fumadocs-ui/css/preset.css"; +@theme { + --font-sans: + var(--font-sans), "IBM Plex Sans", ui-sans-serif, system-ui, sans-serif; + --font-mono: + var(--font-mono), "IBM Plex Mono", ui-monospace, SFMono-Regular, + "Cascadia Mono", monospace; + --font-handwritten: var(--font-handwritten), "Caveat", cursive; + --color-fd-sketch: + color-mix(in oklch, var(--color-fd-foreground) 55%, transparent); + --color-fd-sketch-strong: + color-mix(in oklch, var(--color-fd-foreground) 75%, transparent); +} + html { scrollbar-gutter: stable; } diff --git a/docs/src/app/layout.tsx b/docs/src/app/layout.tsx index c77d7cc..a9b81f8 100644 --- a/docs/src/app/layout.tsx +++ b/docs/src/app/layout.tsx @@ -1,10 +1,24 @@ import type { Metadata } from "next"; -import { Inter } from "next/font/google"; +import { Caveat, IBM_Plex_Mono, IBM_Plex_Sans } from "next/font/google"; import { Provider } from "@/components/provider"; import "./global.css"; -const inter = Inter({ +const ibmPlexSans = IBM_Plex_Sans({ subsets: ["latin"], + weight: ["400", "500", "600", "700"], + variable: "--font-sans", +}); + +const ibmPlexMono = IBM_Plex_Mono({ + subsets: ["latin"], + weight: ["400", "500", "600"], + variable: "--font-mono", +}); + +const caveat = Caveat({ + subsets: ["latin"], + weight: ["500", "600", "700"], + variable: "--font-handwritten", }); export const metadata: Metadata = { @@ -18,7 +32,11 @@ export const metadata: Metadata = { export default function Layout({ children }: LayoutProps<"/">) { return ( - + {children} From 1db3ead11a3f45e34dda03087465bcd860c1c46e Mon Sep 17 00:00:00 2001 From: Pratyush Sharma <56130065+pratyush618@users.noreply.github.com> Date: Sun, 3 May 2026 11:37:59 +0530 Subject: [PATCH 07/14] feat(docs): handwritten + sketchy aesthetic for diagrams, dark-mode contrast --- .../src/app/(home)/_sections/how-it-works.tsx | 293 +++++++----------- docs/src/app/(home)/_sections/worker-pool.tsx | 191 +++++++----- 2 files changed, 228 insertions(+), 256 deletions(-) diff --git a/docs/src/app/(home)/_sections/how-it-works.tsx b/docs/src/app/(home)/_sections/how-it-works.tsx index 62988e0..8204b5f 100644 --- a/docs/src/app/(home)/_sections/how-it-works.tsx +++ b/docs/src/app/(home)/_sections/how-it-works.tsx @@ -8,53 +8,55 @@ type Station = { glyph: ReactNode; }; -const VIEW_WIDTH = 380; -const TRACK_Y = 36; -const STATION_RADIUS = 14; +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: 40, + cx: 56, glyph: , }, { id: "queue", label: "queue", hint: "SQLite · Postgres", - cx: 145, + cx: 184, glyph: , }, { id: "worker", label: "worker", hint: "Rust pool", - cx: 250, + cx: 304, glyph: , }, { id: "result", label: "result", hint: ".result()", - cx: 340, + cx: 412, glyph: , }, ]; -const JOB_DELAYS = ["0s", "-1.6s", "-3.2s"] as const; +const JOB_DELAYS = ["0s", "-1.7s", "-3.4s"] as const; export function HowItWorks() { return (
-
-

- How it works +
+

+ how it works

-

+

Your code calls{" "} - .delay() · the + .delay() · the job durably queues · a Rust scheduler routes it · a worker returns the result.

@@ -63,79 +65,73 @@ export function HowItWorks() { - - - - - - - + - + + + - + - - - + {STATIONS.slice(0, -1).map((station, i) => { + const next = STATIONS[i + 1]; + return ( + + ); + })} {STATIONS.map((station) => ( ))} {JOB_DELAYS.map((delay, index) => ( - - - - + /> ))}
@@ -146,66 +142,58 @@ export function HowItWorks() { function StationNode({ station }: { station: Station }) { const isWorker = station.id === "worker"; - const isResult = station.id === "result"; + const x = station.cx - STATION_W / 2; + const y = TRACK_Y - STATION_H / 2; return ( - - + + + {station.glyph} + {isWorker ? ( ) : null} - {isResult ? ( - - ) : null} - - {station.glyph} - {station.label} @@ -215,31 +203,11 @@ function StationNode({ station }: { station: Station }) { ); } -function BackgroundGrid() { - const dots = []; - const step = 14; - for (let x = 8; x < VIEW_WIDTH; x += step) { - for (let y = 4; y < 84; y += step) { - dots.push( - , - ); - } - } - return {dots}; -} - function CodeGlyph() { return ( {` - .taskito-flow .taskito-station { + .taskito-flow .taskito-flow-station { transition: transform 200ms ease; } - .taskito-flow .taskito-station:hover { - transform: translateY(-1px); + .taskito-flow .taskito-flow-station:hover { + transform: translateY(-1.5px); } - .taskito-flow .taskito-station:hover .taskito-station-label { - fill: var(--color-fd-primary); - } - @keyframes taskito-job-travel { - 0% { cx: 40px; opacity: 0; } + @keyframes taskito-flow-job-travel { + 0% { cx: 56px; opacity: 0; } 4% { opacity: 1; } - 25% { cx: 145px; opacity: 1; } - 33% { cx: 145px; opacity: 1; } - 50% { cx: 250px; opacity: 1; } - 58% { cx: 250px; opacity: 1; } - 80% { cx: 340px; opacity: 1; } + 24% { cx: 184px; opacity: 1; } + 32% { cx: 184px; opacity: 1; } + 50% { cx: 304px; opacity: 1; } + 58% { cx: 304px; opacity: 1; } + 80% { cx: 412px; opacity: 1; } 92% { opacity: 0; } - 100% { cx: 40px; opacity: 0; } + 100% { cx: 56px; opacity: 0; } } - @keyframes taskito-worker-spin { + @keyframes taskito-flow-worker-spin { from { transform: rotate(0deg); } to { transform: rotate(360deg); } } - @keyframes taskito-result-pulse { - 0%, 70% { r: 18px; opacity: 0; } - 80% { r: 18px; opacity: 0.6; } - 100% { r: 26px; opacity: 0; } - } - @keyframes taskito-track-shimmer { - 0% { stroke-dashoffset: 0; } - 100% { stroke-dashoffset: -16; } - } @media (prefers-reduced-motion: no-preference) { - .taskito-flow .taskito-job-dot { - animation: taskito-job-travel 4.8s cubic-bezier(0.45, 0.05, 0.55, 0.95) infinite; - filter: drop-shadow(0 0 3px var(--color-fd-primary)); - } - .taskito-flow .taskito-job-aura { - animation: taskito-job-travel 4.8s cubic-bezier(0.45, 0.05, 0.55, 0.95) infinite; - } - .taskito-flow .taskito-worker-spinner { - animation: taskito-worker-spin 6s linear infinite; - } - .taskito-flow .taskito-result-pulse { - animation: taskito-result-pulse 4.8s ease-out infinite; + .taskito-flow .taskito-flow-job { + animation: taskito-flow-job-travel 5.1s cubic-bezier(0.45, 0.05, 0.55, 0.95) infinite; + filter: drop-shadow(0 0 4px var(--color-fd-primary)); } - .taskito-flow .taskito-track { - animation: taskito-track-shimmer 1.6s linear infinite; + .taskito-flow .taskito-flow-worker-spinner { + animation: taskito-flow-worker-spin 7s linear infinite; } } `} diff --git a/docs/src/app/(home)/_sections/worker-pool.tsx b/docs/src/app/(home)/_sections/worker-pool.tsx index 5a8627f..548df5d 100644 --- a/docs/src/app/(home)/_sections/worker-pool.tsx +++ b/docs/src/app/(home)/_sections/worker-pool.tsx @@ -1,5 +1,3 @@ -import { SectionHeader } from "@/components/ui"; - 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" }, @@ -22,12 +20,12 @@ const RESULTS = [ { delay: "-1.5s" }, ] as const; -const VIEW_W = 560; -const VIEW_H = 150; -const POOL_LEFT = 200; -const POOL_TOP = 38; -const WORKER_SIZE = 34; -const WORKER_GAP = 10; +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; @@ -39,10 +37,15 @@ 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. +

+
+ + + + + + + + + + @@ -59,7 +92,7 @@ export function WorkerPool() { key={`incoming-${i}`} cx={INCOMING_LEFT} cy={TRACK_Y} - r="3.5" + r="4" fill="var(--color-fd-primary)" className="taskito-incoming-dot" style={{ animationDelay: job.delay }} @@ -79,15 +112,16 @@ export function WorkerPool() { style={{ animationDelay: result.delay }} > 6 workers · 0 brokers @@ -114,41 +148,26 @@ export function WorkerPool() { } function LaneLabels() { + const labels = [ + { x: INCOMING_LEFT, text: "incoming" }, + { x: POOL_LEFT, text: "workers" }, + { x: RESULT_LEFT, text: "results" }, + ]; return ( <> - - INCOMING - - - WORKERS - - - RESULTS - + {labels.map((label) => ( + + {label.text} + + ))} ); } @@ -159,20 +178,26 @@ function Lanes() { ); @@ -198,33 +223,33 @@ function Worker({ worker }: { worker: (typeof WORKERS)[number] }) { y={y} width={WORKER_SIZE} height={WORKER_SIZE} - rx="6" + rx="7" fill="var(--color-fd-card)" - stroke="var(--color-fd-border)" - strokeWidth="1.5" + stroke="var(--color-fd-sketch-strong)" + strokeWidth="1.75" + filter="url(#taskito-pool-sketch)" /> @@ -238,25 +263,25 @@ function PoolStyles() { @keyframes taskito-incoming-flow { 0% { cx: ${INCOMING_LEFT}px; opacity: 0; } 10% { opacity: 1; } - 88% { cx: ${POOL_LEFT - 6}px; opacity: 1; } - 100% { cx: ${POOL_LEFT - 6}px; opacity: 0; } + 88% { cx: ${POOL_LEFT - 8}px; opacity: 1; } + 100% { cx: ${POOL_LEFT - 8}px; opacity: 0; } } @keyframes taskito-result-flow { 0% { transform: translate(${RESULT_LEFT}px, ${TRACK_Y}px); opacity: 0; } 10% { opacity: 1; } - 90% { transform: translate(${RESULT_END}px, ${TRACK_Y}px); opacity: 1; } - 100% { transform: translate(${RESULT_END}px, ${TRACK_Y}px); opacity: 0; } + 90% { transform: translate(${RESULT_END - 4}px, ${TRACK_Y}px); opacity: 1; } + 100% { transform: translate(${RESULT_END - 4}px, ${TRACK_Y}px); opacity: 0; } } @keyframes taskito-worker-active-pulse { - 0%, 35% { opacity: 0; transform: scale(0.7); } + 0%, 35% { opacity: 0; transform: scale(0.6); } 50% { opacity: 1; transform: scale(1); } 85% { opacity: 1; transform: scale(1); } - 100% { opacity: 0; transform: scale(0.7); } + 100% { opacity: 0; transform: scale(0.6); } } @keyframes taskito-worker-ring-pulse { - 0%, 35% { opacity: 0; transform: scale(0.6); } - 55% { opacity: 0.5; transform: scale(1.4); } - 100% { opacity: 0; transform: scale(2); } + 0%, 35% { opacity: 0; transform: scale(0.55); } + 55% { opacity: 0.55; transform: scale(1.5); } + 100% { opacity: 0; transform: scale(2.1); } } .taskito-pool .taskito-worker-dot-active { opacity: 0; @@ -269,11 +294,11 @@ function PoolStyles() { } @media (prefers-reduced-motion: no-preference) { .taskito-pool .taskito-incoming-dot { - animation: taskito-incoming-flow 2.2s linear infinite; - filter: drop-shadow(0 0 2px var(--color-fd-primary)); + animation: taskito-incoming-flow 2.4s linear infinite; + filter: drop-shadow(0 0 3px var(--color-fd-primary)); } .taskito-pool .taskito-result { - animation: taskito-result-flow 2.2s linear infinite; + animation: taskito-result-flow 2.4s linear infinite; } .taskito-pool .taskito-worker-dot-active { animation: taskito-worker-active-pulse var(--worker-duration) ease-in-out infinite; From b18778e96e6c8a8a0ab90f9fa3bfed23479993ad Mon Sep 17 00:00:00 2001 From: Pratyush Sharma <56130065+pratyush618@users.noreply.github.com> Date: Sun, 3 May 2026 11:39:55 +0530 Subject: [PATCH 08/14] chore(docs): swap Caveat for Shantell Sans on diagram labels --- docs/src/app/(home)/_sections/how-it-works.tsx | 2 +- docs/src/app/(home)/_sections/worker-pool.tsx | 4 ++-- docs/src/app/global.css | 2 +- docs/src/app/layout.tsx | 7 +++---- 4 files changed, 7 insertions(+), 8 deletions(-) diff --git a/docs/src/app/(home)/_sections/how-it-works.tsx b/docs/src/app/(home)/_sections/how-it-works.tsx index 8204b5f..9b6e649 100644 --- a/docs/src/app/(home)/_sections/how-it-works.tsx +++ b/docs/src/app/(home)/_sections/how-it-works.tsx @@ -184,7 +184,7 @@ function StationNode({ station }: { station: Station }) { fill="var(--color-fd-foreground)" fontSize="16" fontWeight="600" - fontFamily="var(--font-handwritten), Caveat, cursive" + fontFamily="var(--font-handwritten), 'Shantell Sans', cursive" > {station.label} diff --git a/docs/src/app/(home)/_sections/worker-pool.tsx b/docs/src/app/(home)/_sections/worker-pool.tsx index 548df5d..8b838e1 100644 --- a/docs/src/app/(home)/_sections/worker-pool.tsx +++ b/docs/src/app/(home)/_sections/worker-pool.tsx @@ -135,7 +135,7 @@ export function WorkerPool() { textAnchor="middle" fill="var(--color-fd-muted-foreground)" fontSize="14" - fontFamily="var(--font-handwritten), Caveat, cursive" + fontFamily="var(--font-handwritten), 'Shantell Sans', cursive" fontWeight="500" > 6 workers · 0 brokers @@ -162,7 +162,7 @@ function LaneLabels() { y="28" fill="var(--color-fd-foreground)" fontSize="17" - fontFamily="var(--font-handwritten), Caveat, cursive" + fontFamily="var(--font-handwritten), 'Shantell Sans', cursive" fontWeight="600" > {label.text} diff --git a/docs/src/app/global.css b/docs/src/app/global.css index be36e7f..50f6bb7 100644 --- a/docs/src/app/global.css +++ b/docs/src/app/global.css @@ -8,7 +8,7 @@ --font-mono: var(--font-mono), "IBM Plex Mono", ui-monospace, SFMono-Regular, "Cascadia Mono", monospace; - --font-handwritten: var(--font-handwritten), "Caveat", cursive; + --font-handwritten: var(--font-handwritten), "Shantell Sans", "Caveat", cursive; --color-fd-sketch: color-mix(in oklch, var(--color-fd-foreground) 55%, transparent); --color-fd-sketch-strong: diff --git a/docs/src/app/layout.tsx b/docs/src/app/layout.tsx index a9b81f8..d42bee3 100644 --- a/docs/src/app/layout.tsx +++ b/docs/src/app/layout.tsx @@ -1,5 +1,5 @@ import type { Metadata } from "next"; -import { Caveat, IBM_Plex_Mono, IBM_Plex_Sans } from "next/font/google"; +import { IBM_Plex_Mono, IBM_Plex_Sans, Shantell_Sans } from "next/font/google"; import { Provider } from "@/components/provider"; import "./global.css"; @@ -15,9 +15,8 @@ const ibmPlexMono = IBM_Plex_Mono({ variable: "--font-mono", }); -const caveat = Caveat({ +const shantellSans = Shantell_Sans({ subsets: ["latin"], - weight: ["500", "600", "700"], variable: "--font-handwritten", }); @@ -34,7 +33,7 @@ export default function Layout({ children }: LayoutProps<"/">) { return ( From 5bbe9ae7a6e788bbe955c357f3d435f2fd3318a1 Mon Sep 17 00:00:00 2001 From: Pratyush Sharma <56130065+pratyush618@users.noreply.github.com> Date: Sun, 3 May 2026 11:43:16 +0530 Subject: [PATCH 09/14] fix(docs): boost diagram contrast and reduce sketch displacement for dark mode --- .../src/app/(home)/_sections/how-it-works.tsx | 14 ++++++------ docs/src/app/(home)/_sections/worker-pool.tsx | 22 +++++++++---------- docs/src/app/global.css | 6 +++-- 3 files changed, 22 insertions(+), 20 deletions(-) diff --git a/docs/src/app/(home)/_sections/how-it-works.tsx b/docs/src/app/(home)/_sections/how-it-works.tsx index 9b6e649..49a1f07 100644 --- a/docs/src/app/(home)/_sections/how-it-works.tsx +++ b/docs/src/app/(home)/_sections/how-it-works.tsx @@ -72,11 +72,11 @@ export function HowItWorks() { - + @@ -107,8 +107,8 @@ export function HowItWorks() { y1={TRACK_Y} x2={next.cx - STATION_W / 2 - 8} y2={TRACK_Y} - stroke="var(--color-fd-sketch)" - strokeWidth="1.5" + stroke="var(--color-fd-sketch-accent)" + strokeWidth="1.75" strokeLinecap="round" strokeDasharray="2 5" markerEnd="url(#taskito-flow-arrow)" @@ -154,7 +154,7 @@ function StationNode({ station }: { station: Station }) { rx="6" fill="var(--color-fd-card)" stroke="var(--color-fd-sketch-strong)" - strokeWidth="1.75" + strokeWidth="2.25" filter="url(#taskito-flow-sketch)" /> - + @@ -115,7 +115,7 @@ export function WorkerPool() { r="8" fill="var(--color-fd-card)" stroke="var(--color-fd-primary)" - strokeWidth="1.75" + strokeWidth="2" filter="url(#taskito-pool-sketch)" /> Date: Sun, 3 May 2026 15:21:34 +0530 Subject: [PATCH 10/14] feat(docs): inherit handwritten font on diagrams (incl. mermaid) --- docs/src/app/(home)/_sections/how-it-works.tsx | 3 +-- docs/src/app/(home)/_sections/worker-pool.tsx | 4 +--- docs/src/components/mermaid.tsx | 2 +- 3 files changed, 3 insertions(+), 6 deletions(-) diff --git a/docs/src/app/(home)/_sections/how-it-works.tsx b/docs/src/app/(home)/_sections/how-it-works.tsx index 49a1f07..b0672fc 100644 --- a/docs/src/app/(home)/_sections/how-it-works.tsx +++ b/docs/src/app/(home)/_sections/how-it-works.tsx @@ -66,7 +66,7 @@ export function HowItWorks() { role="img" aria-label="Job lifecycle: enqueue from your code, durable queue, Rust worker pool, result returned" viewBox={`0 0 ${VIEW_W} ${VIEW_H}`} - className="w-full max-w-2xl taskito-flow" + className="w-full max-w-2xl font-handwritten taskito-flow" > @@ -184,7 +184,6 @@ function StationNode({ station }: { station: Station }) { fill="var(--color-fd-foreground)" fontSize="16" fontWeight="600" - fontFamily="var(--font-handwritten), 'Shantell Sans', cursive" > {station.label} diff --git a/docs/src/app/(home)/_sections/worker-pool.tsx b/docs/src/app/(home)/_sections/worker-pool.tsx index 4f9c469..bb8a173 100644 --- a/docs/src/app/(home)/_sections/worker-pool.tsx +++ b/docs/src/app/(home)/_sections/worker-pool.tsx @@ -51,7 +51,7 @@ export function WorkerPool() { role="img" aria-label="Six-worker pool with jobs streaming in from the left and results streaming out to the right" viewBox={`0 0 ${VIEW_W} ${VIEW_H}`} - className="w-full max-w-2xl taskito-pool" + className="w-full max-w-2xl font-handwritten taskito-pool" > @@ -135,7 +135,6 @@ export function WorkerPool() { textAnchor="middle" fill="var(--color-fd-muted-foreground)" fontSize="14" - fontFamily="var(--font-handwritten), 'Shantell Sans', cursive" fontWeight="500" > 6 workers · 0 brokers @@ -162,7 +161,6 @@ function LaneLabels() { y="28" fill="var(--color-fd-foreground)" fontSize="17" - fontFamily="var(--font-handwritten), 'Shantell Sans', cursive" fontWeight="600" > {label.text} diff --git a/docs/src/components/mermaid.tsx b/docs/src/components/mermaid.tsx index ecbcfa2..575945e 100644 --- a/docs/src/components/mermaid.tsx +++ b/docs/src/components/mermaid.tsx @@ -39,7 +39,7 @@ export function Mermaid({ chart }: { chart: string }) { return (
From 6f7141ef17b2ced2de67a9e8bb133e34edab74af Mon Sep 17 00:00:00 2001 From: Pratyush Sharma <56130065+pratyush618@users.noreply.github.com> Date: Sun, 3 May 2026 15:28:49 +0530 Subject: [PATCH 11/14] fix(docs): use IBM Plex Sans + tuned theme variables for Mermaid --- docs/src/components/mermaid.tsx | 63 +++++++++++++++++++++++++++++++-- 1 file changed, 60 insertions(+), 3 deletions(-) diff --git a/docs/src/components/mermaid.tsx b/docs/src/components/mermaid.tsx index 575945e..7ad956e 100644 --- a/docs/src/components/mermaid.tsx +++ b/docs/src/components/mermaid.tsx @@ -3,6 +3,52 @@ import { useTheme } from "next-themes"; import { useEffect, useId, useRef, useState } from "react"; +const DARK_THEME_VARIABLES = { + background: "transparent", + primaryColor: "#1f2024", + primaryTextColor: "#f5f5f7", + primaryBorderColor: "#7a7d85", + lineColor: "#9b9ea6", + secondaryColor: "#2a2c31", + tertiaryColor: "#26282d", + mainBkg: "#1f2024", + nodeBkg: "#1f2024", + nodeBorder: "#7a7d85", + clusterBkg: "#1a1b1e", + clusterBorder: "#5a5d65", + edgeLabelBackground: "#2a2c31", + titleColor: "#f5f5f7", + labelTextColor: "#f5f5f7", + textColor: "#f5f5f7", + noteBkgColor: "#3a3c41", + noteTextColor: "#f5f5f7", + noteBorderColor: "#7a7d85", + errorBkgColor: "#4a1d1d", + errorTextColor: "#fca5a5", +} as const; + +const LIGHT_THEME_VARIABLES = { + background: "transparent", + primaryColor: "#ffffff", + primaryTextColor: "#1a1a1a", + primaryBorderColor: "#3a3a3a", + lineColor: "#4a4a4a", + secondaryColor: "#f4f4f5", + tertiaryColor: "#fafafa", + mainBkg: "#ffffff", + nodeBkg: "#ffffff", + nodeBorder: "#3a3a3a", + clusterBkg: "#f4f4f5", + clusterBorder: "#a1a1aa", + edgeLabelBackground: "#ffffff", + titleColor: "#1a1a1a", + labelTextColor: "#1a1a1a", + textColor: "#1a1a1a", + noteBkgColor: "#fef9c3", + noteTextColor: "#1a1a1a", + noteBorderColor: "#a1a1aa", +} as const; + export function Mermaid({ chart }: { chart: string }) { const id = useId(); const containerRef = useRef(null); @@ -13,11 +59,22 @@ export function Mermaid({ chart }: { chart: string }) { let cancelled = false; void (async () => { const mermaid = (await import("mermaid")).default; + if (typeof document !== "undefined" && document.fonts?.ready) { + await document.fonts.ready; + } + const isDark = resolvedTheme === "dark"; mermaid.initialize({ startOnLoad: false, - theme: resolvedTheme === "dark" ? "dark" : "default", + theme: "base", + themeVariables: isDark ? DARK_THEME_VARIABLES : LIGHT_THEME_VARIABLES, securityLevel: "loose", - fontFamily: "inherit", + fontFamily: '"IBM Plex Sans", "Inter", system-ui, sans-serif', + flowchart: { padding: 18, htmlLabels: true, useMaxWidth: true }, + sequence: { + actorFontFamily: '"IBM Plex Sans", sans-serif', + noteFontFamily: '"IBM Plex Sans", sans-serif', + messageFontFamily: '"IBM Plex Sans", sans-serif', + }, }); try { const renderId = `m${id.replace(/[^a-zA-Z0-9]/g, "")}`; @@ -39,7 +96,7 @@ export function Mermaid({ chart }: { chart: string }) { return (
From fd7cbd778ce5839df1bd71de30e598837e80c12e Mon Sep 17 00:00:00 2001 From: Pratyush Sharma <56130065+pratyush618@users.noreply.github.com> Date: Sun, 3 May 2026 15:37:31 +0530 Subject: [PATCH 12/14] feat(docs): add DiagramCarousel and split storage schema into per-table slides --- docs/content/docs/architecture/storage.mdx | 196 ++++++++++++--------- docs/src/components/diagram-carousel.tsx | 149 ++++++++++++++++ docs/src/components/mdx.tsx | 3 + 3 files changed, 268 insertions(+), 80 deletions(-) create mode 100644 docs/src/components/diagram-carousel.tsx diff --git a/docs/content/docs/architecture/storage.mdx b/docs/content/docs/architecture/storage.mdx index 5ecc571..9219eff 100644 --- a/docs/content/docs/architecture/storage.mdx +++ b/docs/content/docs/architecture/storage.mdx @@ -14,86 +14,122 @@ 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ## Key indexes diff --git a/docs/src/components/diagram-carousel.tsx b/docs/src/components/diagram-carousel.tsx new file mode 100644 index 0000000..dbe690f --- /dev/null +++ b/docs/src/components/diagram-carousel.tsx @@ -0,0 +1,149 @@ +"use client"; + +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/src/components/mdx.tsx b/docs/src/components/mdx.tsx index 1e29908..00c1d1d 100644 --- a/docs/src/components/mdx.tsx +++ b/docs/src/components/mdx.tsx @@ -1,11 +1,14 @@ import defaultMdxComponents from "fumadocs-ui/mdx"; import type { MDXComponents } from "mdx/types"; +import { DiagramCarousel, DiagramSlide } from "./diagram-carousel"; import { Mermaid } from "./mermaid"; export function getMDXComponents(components?: MDXComponents) { return { ...defaultMdxComponents, Mermaid, + DiagramCarousel, + DiagramSlide, ...components, } satisfies MDXComponents; } From f671a1bc67afdf0d1b8e28f41c0975eb90e23ffa Mon Sep 17 00:00:00 2001 From: Pratyush Sharma <56130065+pratyush618@users.noreply.github.com> Date: Sun, 3 May 2026 15:40:07 +0530 Subject: [PATCH 13/14] fix(docs): cover erDiagram, stateDiagram, sequenceDiagram theme vars --- docs/src/components/mermaid.tsx | 38 +++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/docs/src/components/mermaid.tsx b/docs/src/components/mermaid.tsx index 7ad956e..b4a78bd 100644 --- a/docs/src/components/mermaid.tsx +++ b/docs/src/components/mermaid.tsx @@ -25,6 +25,25 @@ const DARK_THEME_VARIABLES = { noteBorderColor: "#7a7d85", errorBkgColor: "#4a1d1d", errorTextColor: "#fca5a5", + // erDiagram-specific (entity attribute rows) + attributeBackgroundColorOdd: "#1f2024", + attributeBackgroundColorEven: "#272a30", + // stateDiagram-specific + altBackground: "#26282d", + // flowchart label colors + labelBackground: "#2a2c31", + // sequenceDiagram + actorBkg: "#1f2024", + actorBorder: "#7a7d85", + actorTextColor: "#f5f5f7", + actorLineColor: "#9b9ea6", + signalColor: "#f5f5f7", + signalTextColor: "#f5f5f7", + labelBoxBkgColor: "#2a2c31", + labelBoxBorderColor: "#7a7d85", + loopTextColor: "#f5f5f7", + activationBkgColor: "#3a3c41", + activationBorderColor: "#9b9ea6", } as const; const LIGHT_THEME_VARIABLES = { @@ -47,6 +66,25 @@ const LIGHT_THEME_VARIABLES = { noteBkgColor: "#fef9c3", noteTextColor: "#1a1a1a", noteBorderColor: "#a1a1aa", + // erDiagram-specific (entity attribute rows) + attributeBackgroundColorOdd: "#ffffff", + attributeBackgroundColorEven: "#f4f4f5", + // stateDiagram-specific + altBackground: "#f4f4f5", + // flowchart label colors + labelBackground: "#ffffff", + // sequenceDiagram + actorBkg: "#ffffff", + actorBorder: "#3a3a3a", + actorTextColor: "#1a1a1a", + actorLineColor: "#4a4a4a", + signalColor: "#1a1a1a", + signalTextColor: "#1a1a1a", + labelBoxBkgColor: "#ffffff", + labelBoxBorderColor: "#3a3a3a", + loopTextColor: "#1a1a1a", + activationBkgColor: "#f4f4f5", + activationBorderColor: "#4a4a4a", } as const; export function Mermaid({ chart }: { chart: string }) { From 6592b38e3b9f17e4d2f91e1039a175367c7875ed Mon Sep 17 00:00:00 2001 From: Pratyush Sharma <56130065+pratyush618@users.noreply.github.com> Date: Sun, 3 May 2026 15:46:38 +0530 Subject: [PATCH 14/14] docs: add polling-cycle and dispatch-flow diagrams to Scheduler page --- docs/content/docs/architecture/scheduler.mdx | 48 +++++++++++++++++++- 1 file changed, 47 insertions(+), 1 deletion(-) diff --git a/docs/content/docs/architecture/scheduler.mdx b/docs/content/docs/architecture/scheduler.mdx index 65ca5d9..4978a8d 100644 --- a/docs/content/docs/architecture/scheduler.mdx +++ b/docs/content/docs/architecture/scheduler.mdx @@ -5,7 +5,7 @@ description: "The Tokio-based poll loop that dequeues, dispatches, retries, and The scheduler runs in a dedicated Tokio single-threaded async runtime: -``` +```text loop { sleep(50ms) or shutdown signal @@ -23,6 +23,28 @@ loop { } ``` +> **Why those numbers?** 50 ms is fast enough that dequeue latency is imperceptible +> but slow enough to leave the CPU 99% idle when the queue is empty. The periodic +> intervals (~60, ~100, ~1200) are deliberately coprime so the four maintenance +> tasks rarely fire on the same tick — keeping each individual iteration cheap. + +## Polling cycle + + Sleep["sleep 50ms"] + Sleep --> Dispatch["try_dispatch()"] + Dispatch --> Periodic{"iteration
multiple?"} + Periodic -->|"every ~60"| CP["check_periodic()"] + Periodic -->|"every ~100"| RS["reap_stale()"] + Periodic -->|"every ~1200"| AC["auto_cleanup()"] + Periodic -->|"otherwise"| Next["next tick"] + CP --> Next + RS --> Next + AC --> Next + Next --> Tick`} +/> + ## Dispatch flow 1. `dequeue_from()` — atomically `SELECT` + `UPDATE` (pending → running) within a transaction. @@ -30,3 +52,27 @@ loop { 3. Send job to worker pool via `tokio::sync::mpsc` channel. 4. Worker executes task, sends result back. 5. `handle_result()` — mark complete, schedule retry, or move to DLQ. + +>DB: dequeue_from() + DB-->>S: pending job + S->>RL: check(task) + alt over limit + RL-->>S: limited + S->>DB: reschedule +1s + else under limit + RL-->>S: ok + S->>WP: mpsc.send(job) + WP->>W: execute() + W-->>S: result + S->>DB: handle_result() + end`} +/>