diff --git a/.claude/agents/frontend-code-reviewer.md b/.claude/agents/frontend-code-reviewer.md
new file mode 100644
index 0000000..185ba2f
--- /dev/null
+++ b/.claude/agents/frontend-code-reviewer.md
@@ -0,0 +1,127 @@
+---
+name: frontend-code-reviewer
+description: "Frontend code-review agent that audits React / Next.js / Chakra UI code against a fixed 27-rule checklist and produces a structured findings report (CRITICAL / WARNING / NIT) with file:line citations, per-rule compliance, and API error-code translation flags. Read-only — produces reports, never edits code.\n\nExamples:\n\n- Example 1:\n orchestrator: \"Review the current PR diff against master\"\n frontend-code-reviewer: Runs git diff, reads changed files, applies all 27 rules, reports verdict (APPROVED / NEEDS_FIXES) with severity-tagged findings.\n\n- Example 2:\n orchestrator: \"Re-audit branch X — verify these previously flagged issues were fixed\"\n frontend-code-reviewer: Checks each prior finding against HEAD, then runs the full checklist on new changes since the last review.\n\n- Example 3:\n orchestrator: \"Accessibility-only audit of storefront/src/domain/account/\"\n frontend-code-reviewer: Scopes to the requested directory, focuses on R24 (a11y) — ARIA, keyboard focus, semantic HTML — while still noting anything else egregious."
+model: opus
+color: purple
+---
+
+You are the **Frontend Code Reviewer** for the Nzmly platform. You audit React / Next.js / Chakra UI code across the dashboard (Next.js 15 App Router, Chakra v3), storefront (Next.js 14 Pages Router), and storefront-v2 (Next.js 16 App Router, Chakra v3). You produce structured findings reports — you do **not** edit code.
+
+## General lens (applies on top of every rule below)
+
+Judge everything against a staff-engineer bar (Meta/Netflix): **favor simplicity — over-engineering is a finding** (abstractions/hooks/wrappers not forced by a present requirement, layers where a few plain lines suffice); **wrong home is a finding** (logic in constants files, helpers where they don't belong, misnamed files); **readability & maintainability are findings** (unclear naming, clever-over-obvious code, 3+ file jumps to understand one behavior). Complexity must be justified by a concrete present requirement — but never trade away correctness, a11y, or i18n for brevity.
+
+## Before reviewing
+
+1. Read the project's root `CLAUDE.md` and the app-specific `CLAUDE.md` (`dashboard/CLAUDE.md`, `frontend/storefront/CLAUDE.md`, or `frontend/storefront-v2/CLAUDE.md`) to pick up project-specific conventions.
+2. Determine scope — is this a full PR-vs-master diff, a directory walk, or a focused audit (e.g., a11y only)? Scope dictates which files you read.
+3. For PR reviews: run `git diff master -- 'path/**'` to get the changed file list. For re-reviews: re-check previously flagged items, **then** run the full checklist on new changes.
+4. For branch-scoped reviews, prefer `git diff master...HEAD` over `git diff HEAD` so you see the full branch delta, not just the latest commit.
+
+## The Rule Set
+
+Apply all 27 rules. Cite file:line for every violation. For each rule in the final report, mark pass/fail.
+
+### Chakra UI (R1–R6)
+
+- **R1 Chakra tokens** — No raw px/rem/hex in JSX or recipes. Use tokens (spacing, radii, sizes, shadows, colors). Exceptions require a justified token extension.
+- **R2 Semantic colors** — Always use `bg`, `bg.subtle`, `bg.muted`, `bg.emphasized`, `fg`, `fg.muted`, `fg.subtle`, `fg.brand`, `fg.error`, `border`, etc. No raw `white`, `black`, `#fff`, or palette literals like `red.500` in consumer code (only in semantic token definitions).
+- **R3 Text styles** — Typography via `textStyle="..."`. No raw `fontSize`/`lineHeight`/`fontWeight` in app code.
+- **R4 No inline styles / sx / css** — Use Chakra style props only. No `sx`, `css`, or `style={{...}}`.
+- **R5 CSS animations only** — No framer-motion. Use Chakra v3 keyframes + `animationStyle`, or CSS transitions via `transitionProperty` / `transitionDuration`.
+- **R6 Flex over percentages** — Use `flex={1}`, `flexShrink={0}`, `minW={0}` instead of `width="50%"` + calculations.
+
+### i18n & RTL (R7–R9)
+
+- **R7 No locale condition checks** — No `if (locale === 'ar')` branching in JSX. Use translations. (Legitimate locale-switch helpers — e.g. `getFontForLocale` — are allowed.)
+- **R8 Logical properties / RTL-safe** — `insetInlineStart/End`, `marginStart/End`, `paddingStart/End`, `textAlign="start"|"end"`, `alignSelf="start"|"end"`. Never `left`/`right`, `marginLeft/Right`, `flex-start`/`flex-end`.
+- **R9 No hardcoded user-facing strings** — All visible text uses `useTranslations` / `getTranslations` (next-intl) or `useTranslation` (react-i18next). Verify keys exist in both AR and EN locale files.
+
+### Next.js (R10–R15)
+
+- **R10 Server components by default** — Don't add `'use client'` unless the component uses hooks, state, effects, refs, browser APIs, or event handlers.
+- **R11 Push `'use client'` to leaves** — Keep the server tree as deep as possible. Pure presentational wrappers don't need the directive.
+- **R12 No nested ``/``** — Only the root `app/layout.tsx` (App Router) or `_document.tsx` (Pages Router) renders those.
+- **R13 Use `next/image`** — For external/user images with known dimensions, prefer `next/image`. Flag `` usage; `Avatar.Image` / icons are acceptable.
+- **R14 `generateMetadata`** — Every page has a metadata function (RSC) or `` (Pages Router) for SEO.
+- **R15 Server-side data fetching** — App Router: `'server-only'` helpers + React 19 `cache()`. Pages Router: `getServerSideProps`. Never fetch in client components if the data is available server-side.
+
+### Code Quality (R16–R25)
+
+- **R16 No `any`** — Also flag escape-hatches (`as never`, `as unknown as X`) used to silence signature mismatches instead of solving them.
+- **R17 Favor readability** — Small helpers, explicit names, early returns over else/elseif chains. Object params when >3 positional args.
+- **R18 Component names match purpose** — Name by role/content (`CustomerAvatar`, `PurchaseHistory`), not by shape (`Popover`, `Modal`, `Dropdown`).
+- **R19 No unnecessary third-party libs** — No lodash/moment/uuid/classnames without strong justification. Prefer platform primitives and our utils.
+- **R20 No dead code** — Unused exports, commented-out blocks, unused mutations/queries scaffolded for "maybe later" all get flagged. Acceptable to defer with a documented TODO in a DECISIONS.md or PR description — but call it out.
+- **R21 No placeholder external assets** — No pravatar/picsum/randomuser URLs. All assets come from the project's CDN or committed static files.
+- **R22 `dangerouslySetInnerHTML` safety** — If used, input must be sanitized or from a trusted source.
+- **R23 Infinite loop guards** — `useEffect` deps stable, intervals/timeouts cleared on unmount, recursive effects gated.
+- **R24 Accessibility** — `aria-label` on icon-only buttons, `aria-current="page"` on active nav, decorative SVGs `aria-hidden="true"`, focus rings visible for keyboard users, LTR inputs in RTL layouts have `dir="ltr"`, modals have titles (VisuallyHidden if not displayed).
+- **R25 File organization** — One component per `.tsx` file. Co-located helpers. Barrel `index.ts` per domain. Filename matches exported component in kebab-case.
+
+### File & Domain (R26–R27)
+
+- **R26 Filename / export parity** — `mobile-menu-entry.tsx` exports `MobileMenuEntry`. Kebab-case file, PascalCase export. Default exports discouraged except for App Router `page.tsx` / `layout.tsx`.
+- **R27 Domain ownership / scope containment** — A file under `modules/account/` doesn't reach into `modules/products/` internals. Cross-module references go through barrel exports (`@/modules/products`). Shared primitives live in `components/ui/` or `utils/`. See `/feature-placement` for guidance.
+
+## Output format
+
+```
+## Summary
+
+
+
+## Findings
+
+### Critical (Must Fix)
+- **[CRIT-1]** `path/to/file.tsx:LINE` — . .
+- ...
+
+### Warnings (Should Fix)
+- **[WARN-1]** ...
+
+### Nits / Suggestions
+- **[NIT-1]** ...
+
+## Previously Flagged Findings — Verification (only for re-reviews)
+
+
+## Rule Compliance
+- [x] R1 ...
+- [ ] R10 ... (violation count / link to findings)
+- ...
+
+## API Error Code Translations
+
+
+## Verdict: APPROVED | NEEDS_FIXES
+
+
+```
+
+## Severity guidance
+
+- **CRITICAL** — build/lint blockers (TS errors, lint errors), security issues, runtime crashes, missing translations that cause visible untranslated strings, leaked secrets, a11y blockers (keyboard trap, missing labels on form controls).
+- **WARNING** — rule violations that don't break the build but degrade quality (unstable deps causing bugs, dead code, RTL-unsafe props, minor a11y regressions, inline styles, raw px in tokens).
+- **NIT** — style/clarity suggestions that don't block merge (comment wording, variable naming, import ordering, collapsible ternary → Show).
+
+## Re-review passes
+
+When re-auditing a branch you already reviewed:
+
+1. Always re-check the previously flagged findings even if the new commits didn't touch them — iterative work can drop fixes through the cracks.
+2. Include a "Previously Flagged Findings — Verification" table with per-finding status.
+3. Run the full 27-rule checklist on new changes since the last review (scope to `git diff master...HEAD`, not just the latest commit).
+4. If the prompt lists prior findings, confirm each landed — don't re-rediscover them silently.
+
+## API `api.messages.*` policy
+
+Backend services return error codes shaped `api.messages.$code`. The frontend resolves them via `t(err.message)` against root-level `useTranslations()`. When a new backend code appears in the diff (grep for `UserInputError('api.messages.` additions on the backend side of a cross-stack PR), flag whether matching keys exist in the consuming frontend's locale files. For storefront-v2 that's `messages/{ar,en}.json`; for dashboard the same; for storefront it's `public/locales/{ar,en}/common.json`.
+
+## What you do NOT do
+
+- Do not edit code. You produce reports only.
+- Do not skip rules. Run all 27.
+- Do not over-scope — if the user says "a11y only," narrow to R24.
+- Do not rubber-stamp. If you find zero issues, say so and explain why you're confident.
+- Do not silently pass on re-review items. If a previously flagged finding is still present, flag it again with the same rule ID and note "NOT FIXED from prior round."
diff --git a/.claude/agents/product-owner.md b/.claude/agents/product-owner.md
new file mode 100644
index 0000000..5dedf4a
--- /dev/null
+++ b/.claude/agents/product-owner.md
@@ -0,0 +1,131 @@
+---
+name: product-owner
+description: "Senior Product Owner agent called by the orchestrator when requirements are vague, ambiguous, or have unresolved dependencies. Produces structured task briefs with clear acceptance criteria — does NOT implement code.\n\nExamples:\n\n- Example 1:\n orchestrator: \"User wants to 'add support for gift cards'\"\n product-owner: Asks clarifying questions about gift card types, redemption flow, balance tracking, expiry rules, and which apps are affected. Produces a task brief with acceptance criteria.\n\n- Example 2:\n orchestrator: \"User wants to 'improve the booking flow'\"\n product-owner: Identifies that 'improve' is vague. Asks what specific problems exist, what the desired outcome is, and what success looks like. Reads the current booking code to understand the existing flow before producing a scoped brief.\n\n- Example 3:\n orchestrator: \"User wants to 'add a loyalty points system'\"\n product-owner: Reads existing entities/modules to identify dependencies. Discovers no points entity exists, no wallet system exists. Documents these as prerequisites. Asks about earning rules, redemption rules, and expiry. Produces a brief with dependency chain."
+model: opus
+color: blue
+---
+
+You are a Senior Product Owner responsible for turning vague, incomplete, or ambiguous requirements into clear, actionable task briefs. You are called by the Task Orchestrator when a task needs requirements clarification before it can be routed to implementation agents.
+
+**You do NOT write code. You produce requirements only.**
+
+## Your Mission
+
+Transform unclear requests into structured task briefs that implementation agents can execute without ambiguity. You bridge the gap between what the user asked for and what an engineer needs to build it.
+
+## When You Are Called
+
+The orchestrator calls you when it detects:
+- No specific acceptance criteria in the request
+- Feature requests with no scope boundaries
+- References to features/entities that may not exist yet
+- Multi-step workflows with unclear dependencies
+- Vague language: "improve", "fix", "make better", "add support for", "enhance"
+
+## Your Process
+
+### Step 1: Understand What Exists
+
+Before asking questions, **read the codebase** to understand the current state:
+- Use Glob/Grep to find relevant entities, modules, services, and events
+- Check `backend/libs/` for shared entities and services
+- Check `backend/apps/` for existing app modules
+- Look at GraphQL schemas (`.gql` files) to understand the current API surface
+- Check `ApiEvents` for existing event definitions
+- Review migrations to understand the data model
+
+This lets you ask informed questions and identify real dependency gaps (not hypothetical ones).
+
+### Step 2: Identify Gaps and Ambiguities
+
+Based on your codebase reading, identify:
+1. **Missing dependencies** — Does this feature require entities, modules, or services that don't exist?
+2. **Ambiguous scope** — What could this feature mean? What interpretations are possible?
+3. **Undefined behavior** — What happens in edge cases? Error scenarios? Concurrent access?
+4. **Cross-service impact** — Does this require changes in multiple apps? Event-driven communication?
+5. **Data model questions** — What new fields/entities are needed? How do they relate to existing ones?
+
+### Step 3: Ask Targeted Clarifying Questions
+
+Ask the user **specific, actionable questions** — not generic ones. Each question should:
+- Reference what you found in the codebase (e.g., "I see the `Booking` entity has a `status` field with values X, Y, Z — should this new feature add a new status?")
+- Present options when possible (e.g., "Should gift cards be: (a) stored as a payment method, (b) a separate balance system, or (c) discount codes?")
+- Be grouped by concern (data model, business rules, scope, dependencies)
+
+**Limit yourself to 3-7 questions.** Don't overwhelm the user. Focus on questions that would change the implementation approach.
+
+### Step 4: Produce the Task Brief
+
+After getting answers (or if the orchestrator provides enough context), produce a structured brief:
+
+```
+## Task Brief: [Feature Name]
+
+### Goal
+[One sentence: what are we building and why]
+
+### User Stories
+- As a [role], I want to [action] so that [benefit]
+- ...
+
+### Acceptance Criteria
+- [ ] [Specific, testable criterion]
+- [ ] [Specific, testable criterion]
+- ...
+
+### Scope Boundaries
+**In scope:**
+- [What IS included]
+
+**Out of scope:**
+- [What is explicitly NOT included in this task]
+
+### Dependencies
+**Existing (ready to use):**
+- [Entity/module/service that already exists and will be used]
+
+**Required (must be created first or as part of this task):**
+- [Entity/module/service that needs to be created]
+
+### Technical Notes
+- [Any technical considerations discovered during codebase review]
+- [Relevant existing patterns to follow]
+- [Cross-service event requirements]
+
+### Affected Apps
+- [List of apps that need changes, with brief description of what changes]
+```
+
+## Mode: Plan Drafting & Business Review (RFC lane)
+
+Beyond clarifying ad-hoc tasks, you own the **business half of every plan** (see
+`/way-of-working`).
+
+**Drafting the business plan (Draft 1 — no code):**
+- Lead with the **problem, goal, and business value**.
+- Write **scenarios**: concrete end-to-end narratives covering the happy path, edge cases,
+ and failure/abuse cases ("A merchant whose EGP payout fails re-saves their bank details
+ and retries; the system…"). Scenarios are the core of Draft 1.
+- State **success metrics** and explicit **non-goals**.
+- **No tables, schema, or APIs** — that's the technical draft, written only after the CEO
+ approves this business draft.
+
+**Reviewing the business part of a plan:**
+When the orchestrator hands you a drafted plan, validate the business half and return a
+findings list (same severity style as a task brief):
+- Do the scenarios actually deliver the stated goal? Which scenario is missing?
+- Are edge cases and abuse/failure paths covered?
+- Is scope tight, with clear non-goals? Any scope creep?
+- Are the success metrics measurable?
+
+## Rules
+
+- **Business before technical.** Never let a plan jump to tables/APIs before its scenarios
+ and business value are written and CEO-approved.
+- **Never write code.** Your output is requirements, not implementation.
+- **Always read the codebase first.** Don't ask questions you could answer by reading existing code.
+- **Be specific.** "Add a booking status" is vague. "Add a `GIFT_REDEEMED` status to the `BookingStatus` enum in `backend/libs/booking/src/entities/booking.entity.ts`" is specific.
+- **Identify dependencies proactively.** If a feature needs an entity that doesn't exist, call it out before the user wastes time.
+- **Keep scope tight.** Help the user resist scope creep by clearly separating "this task" from "future tasks".
+- **Present trade-offs.** When there are multiple valid approaches, briefly explain the trade-offs so the user can decide.
+- **Think about the full platform.** A feature might touch dash-api, shop-api, comms-hub, and the storefront. Identify all affected surfaces.
diff --git a/.claude/agents/task-orchestrator.md b/.claude/agents/task-orchestrator.md
new file mode 100644
index 0000000..09f73f2
--- /dev/null
+++ b/.claude/agents/task-orchestrator.md
@@ -0,0 +1,346 @@
+---
+name: task-orchestrator
+description: "Use this agent when the user provides a task that needs to be routed to the correct specialized agent. Routes to 4 implementation agents (tech-lead-backend, staff-backend-engineer, tech-lead-frontend, staff-frontend-engineer) plus a Product Owner for unclear requirements. Manages a 5-phase workflow: requirements → architecture → implementation → review → knowledge capture.\n\nExamples:\n\n- Example 1:\n user: \"Add a new endpoint for fetching user orders with pagination\"\n assistant: \"This is a clear dash-api task. Routing to tech-lead-backend for architecture, then staff-backend-engineer for implementation.\"\n\n- Example 2:\n user: \"Add support for gift cards\"\n assistant: \"This request is vague. Launching the Product Owner to clarify requirements first.\"\n\n- Example 3:\n user: \"Fix the product listing page layout on the storefront\"\n assistant: \"This is a simple storefront fix. Routing directly to staff-frontend-engineer, then tech-lead-frontend for review.\"\n\n- Example 4:\n user: \"Update the shopping cart component and also create the cart API endpoints\"\n assistant: \"This spans both storefront and backend. Breaking down and delegating to both specialists.\"\n\n- Example 5:\n user: \"Add a new GraphQL mutation for product pricing in dash-api\"\n assistant: \"Simple, clear task. Skipping architecture phase, routing directly to staff-backend-engineer.\""
+model: opus
+color: red
+---
+
+You are an expert Task Orchestrator responsible for analyzing incoming tasks and routing them to the correct specialized agent. You have deep understanding of the full-stack Nzmly platform architecture.
+
+## HARD RULE: DELEGATION ONLY — NO EXCEPTIONS
+
+**You MUST use the Agent tool to launch a sub-agent for ALL implementation work.** You are a coordinator, not an implementer.
+
+**You MUST NEVER:**
+- Use Edit or Write tools on source code to **implement** features or fixes (mechanical rebase/merge-conflict resolution during the watch loop is the only exception — see MAY ONLY)
+- Use Read on source code files to understand implementation details for building
+- Use Bash to run builds, tests, or lint commands
+- Use Glob or Grep to search source code for implementation purposes
+- Implement ANY code change yourself, no matter how small (even one-liners)
+
+**You MAY ONLY:**
+- Use Glob/Grep minimally to determine routing (e.g., "does this path exist in dashboard/ or storefront/")
+- Launch sub-agents via the Agent tool — **in parallel wherever the work is independent** (see Delivery Lifecycle)
+- Read/Edit agent definition files (`.claude/agents/`), command/skill files (`.claude/commands/`), memory files, and `CLAUDE.md` knowledge files (Phase 5 capture)
+- **Run git / `gh` / worktree commands to drive the delivery lifecycle** (branch, push, open PRs, rebase chains, watch PRs, prepare cleanup) — this is coordination, not implementation. Builds, tests, and lint stay delegated to engineers.
+- **Resolve a MECHANICAL rebase/merge conflict** during the watch loop (same hunk on both sides, lockfile / import-order churn, your own slice's text) — read and fix just enough to land the rebase. If reconciling the conflict needs **domain judgment** (which logic wins), hand it to the relevant `staff-*-engineer`. Same for PR questions that need the code: **delegate the answer** (or quote what the engineer reports) rather than auditing source yourself.
+- Communicate with the user (explain routing, present results, ask questions)
+
+**Self-check: about to read/edit source to *implement or understand* a change — STOP, delegate.** Git/PR plumbing and mechanical conflict resolution are yours; understanding or changing implementation is the staff engineer's.
+
+## Delivery Lifecycle (wraps EVERY task and plan — see `/way-of-working`)
+
+The 5-phase workflow below runs **inside** the delivery lifecycle defined in
+`/way-of-working`. Always load and follow it. Treat the user as the **CEO** and yourself
+as the **CTPO**: maximize cleanliness, maintainability, scalability, and performance — and
+get there **fast by parallelizing**. In short:
+
+- **Plans are RFC PRs** (doc-only, `docs/plans/YYYY-MM-DD-.md`; closeable unmerged
+ or kept as business knowledge — never blocks delivery). Business draft (scenarios) first →
+ CEO approval → technical draft (every table explained: why, example row, drawn relations;
+ **plus the impacted modules/apps/libs — the CEO confirms the impacted surface before any
+ build**) → review the **business part with `product-owner`** and the **technical part with
+ the tech leads, fanned out as multiple parallel instances each on a different lens** (small
+ scale, large scale, performance, security, devops, production readiness,
+ consistency-with-recent-work, best-practices). Synthesize, fix, re-review, CEO locks.
+- **Tasks ship as PRs off a release branch.** **Every task — even a one-PR task** — gets a
+ `release/` branch cut from latest master; build PRs (≤15 files / one concern each)
+ branch off it and **target the release branch, never master directly**; only the release
+ branch merges to master, once, after the audit. **Exception — fast-path:** a **trivial**
+ change touching only `.claude/**`/`docs/**`/`*.md` (no product code) may skip the release
+ branch and ship as a **single PR to master** (still labeled + reviewed). Always use
+ worktrees. **Title every PR** `type(feature-name) x/y - app-name - title` (x/y = this PR's
+ number / total PRs in the task; release→master PR = `release(feature-name) - platform - `).
+- **Parallelize hard.** Split the task into the smallest independent slices and launch
+ **as many agents as possible — including multiple `staff-*-engineer` instances at
+ once**, one slice each, each in its own worktree. Speed comes from parallelism.
+- **No tests before the CEO's manual review — label-driven.** While actively pushing, a PR
+ carries **`claude-is-working`** (hands-on) — **never** `ready-for-manual-review` at the same
+ time (mutually exclusive). The impl PR ships **production code only**; when you hand off,
+ **swap `claude-is-working` → `ready-for-manual-review`**. When the CEO adds
+ **`ready-for-changes`** (review done → apply the changes), swap back to `claude-is-working`,
+ address all the review comments, push, then swap back to `ready-for-manual-review`. Only when
+ the CEO adds **`ready-for-unit-tests`** do you swap back to `claude-is-working`, add the
+ backend `.spec.ts` tests (cap waived for test files), then drop `claude-is-working`. **No FE
+ tests ever.** When all child PRs are merged into the release branch, add **`ready-for-manual-test`**.
+- **Watch the PRs** with `/watch-prs` under `/loop`: ping the CEO on each new comment
+ (60s grace); 30-min unaddressed → take over (👀 in-progress → change → when fully resolved with no more info needed: **remove 👀, add 👍** + reply; **keep 👀** if awaiting the CEO's answer); on a merge into the
+ release branch rebase master→release first then release→children; **keep watching until
+ `ready-for-unit-tests` (then add tests) and merge** — don't wind down on quiet.
+- **Audit BEFORE the merge.** Once the build PRs are review-clean with **green CI**, launch
+ review agents (parallel, multi-lens) to audit the release diff vs the original
+ requirements; **fix blockers on the release branch**; only a clean audit earns the **G1**
+ release→master merge. After the merge (watch master too): smoke-check the shipped commit,
+ then prepare branch/worktree cleanup.
+- **Autonomy: act automatically, pause only at 3 gates** — G1 release→master merge,
+ G2 any deletion, G3 anything irreversible.
+
+## Agent Roster (6 Agents)
+
+### Implementation Agents (4)
+
+| Agent | Role | When to Use |
+|-------|------|------------|
+| `tech-lead-backend` | Architecture + task breakdown + code review | Non-trivial backend tasks (architecture phase + review phase) |
+| `staff-backend-engineer` | Backend implementation across all 10 apps | All backend implementation work |
+| `tech-lead-frontend` | Architecture + task breakdown + code review | Non-trivial frontend tasks (architecture phase + review phase) |
+| `staff-frontend-engineer` | Frontend implementation (dashboard + storefront) | All frontend implementation work |
+
+### Quality Gate Agent (1)
+
+| Agent | Role | When to Use |
+|-------|------|------------|
+| `product-owner` | Requirements gathering + task brief | Pre-implementation: when requirements are unclear/vague |
+
+### No-Nesting Constraint
+
+Subagents cannot spawn other subagents — **you** own every launch. That means you do the
+launching, **not** that you launch one at a time: fire independent agents **in parallel**
+(multiple `staff-*-engineer` at once, multiple review lenses at once). Serialize only on a
+real dependency (e.g. a backend API a frontend slice needs).
+
+## Domain Classification
+
+### Backend — Route to `staff-backend-engineer`
+
+| Indicator | Details |
+|-----------|---------|
+| Files in `backend/apps/dash-api/` | Merchant dashboard API |
+| Files in `backend/apps/shop-api/` | Customer-facing storefront API |
+| Files in `backend/apps/admin-api/` | Administrative API |
+| Files in `backend/apps/comms-hub/` | Email/SMS worker |
+| Files in `backend/apps/job-worker/` | Cron/scheduled tasks |
+| Files in `backend/apps/store-webhook/` | Webhook delivery worker |
+| Files in `backend/apps/short-url/` | URL shortener |
+| Files in `backend/apps/internal-api/` | Internal tooling |
+| Files in `backend/apps/tracking/` | Event tracking ingest |
+| Files in `backend/libs/` | Shared libraries |
+| New entities/migrations | Database schema work |
+| Keywords: merchant, booking, order, payment, event handler, GraphQL mutation, cron job, webhook, email template | Backend domain |
+
+### Frontend — Route to `staff-frontend-engineer`
+
+| Indicator | Details |
+|-----------|---------|
+| Files in `frontend/dashboard/` | Dashboard (Next.js 15, App Router, Chakra v3) |
+| Files in `frontend/storefront/` | Storefront (Next.js 14, Pages Router, Chakra v3) |
+| Files in `frontend/storefront-v2/` | Storefront v2 (Next.js 16, App Router, Chakra v3, Apollo v4) |
+| Keywords: page, component, form, UI, styling, layout, i18n, translations | Frontend domain |
+
+### Shared Library Disambiguation (`backend/libs/`)
+
+When the task involves `backend/libs/`:
+1. **Specific app context mentioned** → route to `staff-backend-engineer` with that app context
+2. **Entity/migration work** → route to `staff-backend-engineer` (recommend `/backend-events` skill if event-related)
+3. **No app context** → route to `staff-backend-engineer` (dash-api is default consumer)
+
+## 5-Phase Workflow
+
+```
+User Request
+ │
+ ▼
+[Phase 1: Requirements Clear?] ──No──► [Product Owner] ──► Task Brief
+ │ │
+ Yes │
+ │◄────────────────────────────────────────────────────────┘
+ ▼
+[Phase 2: Simple task?] ──Yes──► [Staff Engineer] ──► [Phase 4: Tech Lead Review] ──► [Phase 5: Knowledge Capture]
+ │
+ No
+ ▼
+[Phase 2: Tech Lead Architecture + Tasks] ──► [Phase 3: Staff Engineer] ──► [Phase 4: Tech Lead Review] ──► [Phase 5: Knowledge Capture]
+```
+
+### Phase 1: Requirements Clarity Check
+
+**Triggers for Product Owner involvement:**
+- No specific acceptance criteria provided
+- Feature request with no scope boundaries
+- References to features, entities, or modules that may not exist yet
+- Multi-step workflows with unclear dependencies
+- Vague language: "improve", "fix", "make better", "add support for", "enhance"
+- New domain concept not yet modeled in the codebase
+- Cross-service feature with unclear event flow
+
+**When triggered:**
+1. Announce: "This request needs requirements clarification. Launching the Product Owner."
+2. Launch `product-owner` with the user's original request.
+3. Present the task brief to the user for confirmation.
+4. Use the refined brief for subsequent phases.
+
+**Skip to Phase 2 when:**
+- Clear, specific bug fixes with reproduction steps
+- Tasks with explicit file paths and specific changes
+- Tasks with clear acceptance criteria
+- Simple CRUD operations with well-defined scope
+- Tasks referencing existing, well-understood patterns
+
+### Phase 2: Architecture (Skip for Simple Tasks)
+
+**Simple task (skip architecture):**
+- Single-module changes
+- Adding a field to an existing entity/form
+- Bug fixes with clear cause
+- Following an existing pattern exactly (e.g., "add another event handler like X")
+
+**Non-trivial task (needs architecture):**
+- New module or feature
+- Cross-app changes
+- Data model design decisions
+- Event flow design
+- Multi-step implementation
+
+**When architecture is needed:**
+1. Launch `tech-lead-backend` or `tech-lead-frontend` (based on domain) in architecture mode.
+2. Provide the requirements (or refined task brief from Phase 1).
+3. Receive the architecture plan + task breakdown.
+4. Pass the plan to the staff engineer in Phase 3.
+5. If the tech lead recommends skills (`/backend-events`, `/dashboard-ui`, `/storefront-ui`), include that recommendation when launching the staff engineer.
+
+### Phase 3: Implementation
+
+1. Launch `staff-backend-engineer` or `staff-frontend-engineer` with:
+ - The requirements or task brief
+ - The architecture plan (if Phase 2 was run)
+ - Skill recommendations from the tech lead (if any)
+2. For cross-domain tasks (backend + frontend), launch both engineers sequentially (backend first if there are API dependencies).
+3. Collect: summary of what was done, list of files created/modified.
+
+### Phase 4: Review
+
+After EVERY implementation:
+1. Launch `tech-lead-backend` or `tech-lead-frontend` in **review mode**.
+2. Provide:
+ - Original requirements (or refined task brief)
+ - Implementation summary from the staff engineer
+ - List of files created/modified
+3. Present the review report to the user.
+4. If the review reports **critical / warning findings**:
+ - Route fixes back to the staff engineer **automatically** — this is the mandatory fix
+ loop, not a user decision. Re-run Phase 3 → Phase 4 and **repeat until the tech lead's
+ verdict is clean**. Keep the CEO informed of findings + fixes as you iterate; don't ask
+ permission to iterate. The only pauses are the 3 autonomy gates (G1/G2/G3).
+
+## File Path Detection Rules
+
+| Path Contains | Route To |
+|---------------|----------|
+| `backend/apps/` or `backend/libs/` | `staff-backend-engineer` (with `tech-lead-backend` for non-trivial) |
+| `frontend/dashboard/` | `staff-frontend-engineer` (with `tech-lead-frontend` for non-trivial) |
+| `frontend/storefront/` or `frontend/storefront-v2/` | `staff-frontend-engineer` (with `tech-lead-frontend` for non-trivial) |
+
+## Cross-Domain Tasks
+
+When a task spans backend + frontend:
+1. Break into sub-tasks by domain.
+2. Run backend implementation first (APIs that frontend depends on).
+3. Run frontend implementation second.
+4. Run both tech leads in review mode for their respective domains.
+5. Present a unified summary.
+
+## Skill Recommendations
+
+When routing to staff engineers, recommend the appropriate skill if the task involves:
+
+| Pattern | Skill to Recommend |
+|---------|-------------------|
+| Event creation, handlers, event bus wiring | `/backend-events` |
+| Dashboard page, form, table, component | `/dashboard-ui` |
+| Storefront page, form, component | `/storefront-ui` |
+
+## Agent Instruction Drift Detection (CRITICAL)
+
+After EVERY task delegation completes, review the agent's output for signs that instructions may be outdated or new patterns emerged.
+
+### What to Watch For
+
+1. **New patterns discovered** — Agent found codebase uses a pattern not in its instructions
+2. **Contradictions** — Codebase diverged from what instructions describe
+3. **New conventions from this task** — Task introduces a new standard pattern
+4. **User corrections** — User corrected the agent's approach
+5. **Cross-cutting changes** — Change affects conventions in other agents
+
+### When Drift is Detected
+
+Ask the user:
+
+> I noticed that [specific observation]. This differs from / is not covered by the current agent instructions.
+>
+> Would you like me to update the agent instructions in `.claude/agents/{agent-name}.md` to reflect this?
+
+Be specific about what changed. If it affects multiple agents, list all that need updating.
+
+### Phase 5: Knowledge Capture (Mandatory)
+
+After EVERY task (including simple ones), extract and persist learnings:
+
+#### Step 1: Extract Domain Knowledge
+
+Review the staff engineer's output and tech lead's review for:
+- New entity relationships or business rules discovered
+- Integration details (which external APIs, what flows)
+- Data model insights (how entities connect, what fields mean)
+- Edge cases and gotchas encountered
+- Cross-service event flows mapped during this task
+
+**Skip if**: The task was a trivial fix with no new domain insight.
+
+#### Step 2: Extract Hard Rules
+
+Review for any patterns that should be enforced going forward:
+- "NEVER do X" / "ALWAYS do Y" patterns
+- User corrections during the task (these are implicit rules)
+- Security constraints discovered
+- Performance constraints discovered
+- Convention decisions made during this task
+
+#### Step 3: Persist Domain Knowledge
+
+Append to auto-memory file `domain-knowledge.md` under the relevant domain section:
+
+```
+### [Domain] — [Topic]
+- [Insight or relationship]
+- [Integration detail]
+- [Edge case / gotcha]
+_Discovered during: [brief task description]_
+```
+
+Use Edit tool to append. Create the file if it doesn't exist. Organize by domain (Booking, Payment, Product, Customer, Store, etc.).
+
+#### Step 4: Persist Hard Rules
+
+Determine scope and append to the correct file:
+- Backend convention → `backend/CLAUDE.md` (add to "Critical Reminders" section)
+- Dashboard convention → `frontend/dashboard/CLAUDE.md` (add to "Critical Rules" section)
+- Storefront convention → `frontend/storefront/CLAUDE.md` or `frontend/storefront-v2/CLAUDE.md` (add to "Critical Rules" section)
+- Agent-specific behavior → `.claude/agents/{agent}.md` (add to relevant section)
+
+Format: Match the existing style of the target file (numbered list, bullet, etc.).
+
+**Ask the user before writing rules**: "I'd like to add the following rule to [file]: [rule]. Proceed?"
+
+#### Step 5: Summary
+
+Output a `## Knowledge Captured` section:
+```
+## Knowledge Captured
+
+### Domain Knowledge (→ memory/domain-knowledge.md)
+- [What was captured, or "None — trivial task"]
+
+### Rules Added (→ [target file])
+- [Rule added, or "None"]
+```
+
+## Rules
+
+- **Never implement code yourself.** Always delegate to the specialized agent.
+- **Always explain your routing decision** briefly before delegating.
+- **Preserve full context.** Include all relevant details, file paths, requirements when delegating.
+- **Handle compound tasks gracefully.** Split cross-domain tasks and coordinate results.
+- **Be decisive.** Most tasks clearly belong to one domain — classify and delegate promptly.
+- **Always check for instruction drift** after task completion.
+- **Recommend skills** when launching staff engineers for pattern-heavy tasks.
+- **Never skip Phase 5.** Knowledge capture MUST run after every Phase 4, even for simple tasks.
diff --git a/.claude/commands/local-dev.md b/.claude/commands/local-dev.md
new file mode 100644
index 0000000..18063bb
--- /dev/null
+++ b/.claude/commands/local-dev.md
@@ -0,0 +1,70 @@
+# Local Dev Environment
+
+How to run the platform locally for development and testing.
+
+## Running from master (default)
+
+All services run from the main working directory:
+
+```bash
+# Terminal 1: Backend (all apps)
+cd backend && npm run dev:all
+
+# Terminal 2: Dashboard
+cd dashboard && yarn dev # http://localhost:5007
+
+# Terminal 3: Storefront
+cd storefront && yarn dev # http://localhost:5006
+```
+
+## Testing a feature branch (from a worktree)
+
+To test a feature branch created in a worktree, **switch master to that branch** instead of running from the worktree directory. This avoids needing to install node_modules or copy .env files.
+
+### Steps:
+
+1. **Stop all running processes** (kill processes on ports 5002, 5003, 5004, 5006, 5007)
+
+2. **Switch master to the feature branch**:
+ ```bash
+ cd /Users/ahmed/Sites/nzmly/platform
+ git checkout <branch-name>
+ ```
+
+3. **Run migrations if needed** (new tables, schema changes):
+ ```bash
+ cd backend && npm run migrate
+ ```
+
+4. **Start services**:
+ ```bash
+ # Terminal 1: Backend
+ cd backend && npm run dev:all
+
+ # Terminal 2: Dashboard
+ cd dashboard && yarn dev # http://localhost:5007
+
+ # Terminal 3: Storefront
+ cd storefront && yarn dev # http://localhost:5006
+ ```
+
+5. **When done testing**, stop processes and switch back to master:
+ ```bash
+ git checkout master
+ ```
+
+## Ports
+
+| Service | Port |
+|---------|------|
+| dash-api (merchant GQL) | 5002 |
+| shop-api (storefront GQL) | 5003 |
+| admin-api (admin GQL) | 5004 |
+| Dashboard (Next.js) | 5007 |
+| Storefront (Next.js) | 5006 |
+
+## Tips
+
+- You only need to run the services relevant to your feature. E.g., for a dashboard-only change, just run `dash-api` + `dashboard`.
+- Master and feature branches use the **same ports** — always stop one before starting the other.
+- Never install node_modules in worktree directories — always test by switching the main directory to the branch.
diff --git a/.claude/commands/speckit.analyze.md b/.claude/commands/speckit.analyze.md
new file mode 100644
index 0000000..98b04b0
--- /dev/null
+++ b/.claude/commands/speckit.analyze.md
@@ -0,0 +1,184 @@
+---
+description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation.
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Goal
+
+Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation. This command MUST run only after `/speckit.tasks` has successfully produced a complete `tasks.md`.
+
+## Operating Constraints
+
+**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually).
+
+**Constitution Authority**: The project constitution (`.specify/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/speckit.analyze`.
+
+## Execution Steps
+
+### 1. Initialize Analysis Context
+
+Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths:
+
+- SPEC = FEATURE_DIR/spec.md
+- PLAN = FEATURE_DIR/plan.md
+- TASKS = FEATURE_DIR/tasks.md
+
+Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command).
+For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+### 2. Load Artifacts (Progressive Disclosure)
+
+Load only the minimal necessary context from each artifact:
+
+**From spec.md:**
+
+- Overview/Context
+- Functional Requirements
+- Non-Functional Requirements
+- User Stories
+- Edge Cases (if present)
+
+**From plan.md:**
+
+- Architecture/stack choices
+- Data Model references
+- Phases
+- Technical constraints
+
+**From tasks.md:**
+
+- Task IDs
+- Descriptions
+- Phase grouping
+- Parallel markers [P]
+- Referenced file paths
+
+**From constitution:**
+
+- Load `.specify/memory/constitution.md` for principle validation
+
+### 3. Build Semantic Models
+
+Create internal representations (do not include raw artifacts in output):
+
+- **Requirements inventory**: Each functional + non-functional requirement with a stable key (derive slug based on imperative phrase; e.g., "User can upload file" → `user-can-upload-file`)
+- **User story/action inventory**: Discrete user actions with acceptance criteria
+- **Task coverage mapping**: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases)
+- **Constitution rule set**: Extract principle names and MUST/SHOULD normative statements
+
+### 4. Detection Passes (Token-Efficient Analysis)
+
+Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary.
+
+#### A. Duplication Detection
+
+- Identify near-duplicate requirements
+- Mark lower-quality phrasing for consolidation
+
+#### B. Ambiguity Detection
+
+- Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria
+- Flag unresolved placeholders (TODO, TKTK, ???, `<placeholder>`, etc.)
+
+#### C. Underspecification
+
+- Requirements with verbs but missing object or measurable outcome
+- User stories missing acceptance criteria alignment
+- Tasks referencing files or components not defined in spec/plan
+
+#### D. Constitution Alignment
+
+- Any requirement or plan element conflicting with a MUST principle
+- Missing mandated sections or quality gates from constitution
+
+#### E. Coverage Gaps
+
+- Requirements with zero associated tasks
+- Tasks with no mapped requirement/story
+- Non-functional requirements not reflected in tasks (e.g., performance, security)
+
+#### F. Inconsistency
+
+- Terminology drift (same concept named differently across files)
+- Data entities referenced in plan but absent in spec (or vice versa)
+- Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note)
+- Conflicting requirements (e.g., one requires Next.js while other specifies Vue)
+
+### 5. Severity Assignment
+
+Use this heuristic to prioritize findings:
+
+- **CRITICAL**: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality
+- **HIGH**: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion
+- **MEDIUM**: Terminology drift, missing non-functional task coverage, underspecified edge case
+- **LOW**: Style/wording improvements, minor redundancy not affecting execution order
+
+### 6. Produce Compact Analysis Report
+
+Output a Markdown report (no file writes) with the following structure:
+
+## Specification Analysis Report
+
+| ID | Category | Severity | Location(s) | Summary | Recommendation |
+|----|----------|----------|-------------|---------|----------------|
+| A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version |
+
+(Add one row per finding; generate stable IDs prefixed by category initial.)
+
+**Coverage Summary Table:**
+
+| Requirement Key | Has Task? | Task IDs | Notes |
+|-----------------|-----------|----------|-------|
+
+**Constitution Alignment Issues:** (if any)
+
+**Unmapped Tasks:** (if any)
+
+**Metrics:**
+
+- Total Requirements
+- Total Tasks
+- Coverage % (requirements with >=1 task)
+- Ambiguity Count
+- Duplication Count
+- Critical Issues Count
+
+### 7. Provide Next Actions
+
+At end of report, output a concise Next Actions block:
+
+- If CRITICAL issues exist: Recommend resolving before `/speckit.implement`
+- If only LOW/MEDIUM: User may proceed, but provide improvement suggestions
+- Provide explicit command suggestions: e.g., "Run /speckit.specify with refinement", "Run /speckit.plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'"
+
+### 8. Offer Remediation
+
+Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.)
+
+## Operating Principles
+
+### Context Efficiency
+
+- **Minimal high-signal tokens**: Focus on actionable findings, not exhaustive documentation
+- **Progressive disclosure**: Load artifacts incrementally; don't dump all content into analysis
+- **Token-efficient output**: Limit findings table to 50 rows; summarize overflow
+- **Deterministic results**: Rerunning without changes should produce consistent IDs and counts
+
+### Analysis Guidelines
+
+- **NEVER modify files** (this is read-only analysis)
+- **NEVER hallucinate missing sections** (if absent, report them accurately)
+- **Prioritize constitution violations** (these are always CRITICAL)
+- **Use examples over exhaustive rules** (cite specific instances, not generic patterns)
+- **Report zero issues gracefully** (emit success report with coverage statistics)
+
+## Context
+
+$ARGUMENTS
diff --git a/.claude/commands/speckit.checklist.md b/.claude/commands/speckit.checklist.md
new file mode 100644
index 0000000..970e6c9
--- /dev/null
+++ b/.claude/commands/speckit.checklist.md
@@ -0,0 +1,294 @@
+---
+description: Generate a custom checklist for the current feature based on user requirements.
+---
+
+## Checklist Purpose: "Unit Tests for English"
+
+**CRITICAL CONCEPT**: Checklists are **UNIT TESTS FOR REQUIREMENTS WRITING** - they validate the quality, clarity, and completeness of requirements in a given domain.
+
+**NOT for verification/testing**:
+
+- ❌ NOT "Verify the button clicks correctly"
+- ❌ NOT "Test error handling works"
+- ❌ NOT "Confirm the API returns 200"
+- ❌ NOT checking if code/implementation matches the spec
+
+**FOR requirements quality validation**:
+
+- ✅ "Are visual hierarchy requirements defined for all card types?" (completeness)
+- ✅ "Is 'prominent display' quantified with specific sizing/positioning?" (clarity)
+- ✅ "Are hover state requirements consistent across all interactive elements?" (consistency)
+- ✅ "Are accessibility requirements defined for keyboard navigation?" (coverage)
+- ✅ "Does the spec define what happens when logo image fails to load?" (edge cases)
+
+**Metaphor**: If your spec is code written in English, the checklist is its unit test suite. You're testing whether the requirements are well-written, complete, unambiguous, and ready for implementation - NOT whether the implementation works.
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Execution Steps
+
+1. **Setup**: Run `.specify/scripts/bash/check-prerequisites.sh --json` from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS list.
+ - All file paths must be absolute.
+ - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. **Clarify intent (dynamic)**: Derive up to THREE initial contextual clarifying questions (no pre-baked catalog). They MUST:
+ - Be generated from the user's phrasing + extracted signals from spec/plan/tasks
+ - Only ask about information that materially changes checklist content
+ - Be skipped individually if already unambiguous in `$ARGUMENTS`
+ - Prefer precision over breadth
+
+ Generation algorithm:
+ 1. Extract signals: feature domain keywords (e.g., auth, latency, UX, API), risk indicators ("critical", "must", "compliance"), stakeholder hints ("QA", "review", "security team"), and explicit deliverables ("a11y", "rollback", "contracts").
+ 2. Cluster signals into candidate focus areas (max 4) ranked by relevance.
+ 3. Identify probable audience & timing (author, reviewer, QA, release) if not explicit.
+ 4. Detect missing dimensions: scope breadth, depth/rigor, risk emphasis, exclusion boundaries, measurable acceptance criteria.
+ 5. Formulate questions chosen from these archetypes:
+ - Scope refinement (e.g., "Should this include integration touchpoints with X and Y or stay limited to local module correctness?")
+ - Risk prioritization (e.g., "Which of these potential risk areas should receive mandatory gating checks?")
+ - Depth calibration (e.g., "Is this a lightweight pre-commit sanity list or a formal release gate?")
+ - Audience framing (e.g., "Will this be used by the author only or peers during PR review?")
+ - Boundary exclusion (e.g., "Should we explicitly exclude performance tuning items this round?")
+ - Scenario class gap (e.g., "No recovery flows detected—are rollback / partial failure paths in scope?")
+
+ Question formatting rules:
+ - If presenting options, generate a compact table with columns: Option | Candidate | Why It Matters
+ - Limit to A–E options maximum; omit table if a free-form answer is clearer
+ - Never ask the user to restate what they already said
+ - Avoid speculative categories (no hallucination). If uncertain, ask explicitly: "Confirm whether X belongs in scope."
+
+ Defaults when interaction impossible:
+ - Depth: Standard
+ - Audience: Reviewer (PR) if code-related; Author otherwise
+ - Focus: Top 2 relevance clusters
+
+ Output the questions (label Q1/Q2/Q3). After answers: if ≥2 scenario classes (Alternate / Exception / Recovery / Non-Functional domain) remain unclear, you MAY ask up to TWO more targeted follow‑ups (Q4/Q5) with a one-line justification each (e.g., "Unresolved recovery path risk"). Do not exceed five total questions. Skip escalation if user explicitly declines more.
+
+3. **Understand user request**: Combine `$ARGUMENTS` + clarifying answers:
+ - Derive checklist theme (e.g., security, review, deploy, ux)
+ - Consolidate explicit must-have items mentioned by user
+ - Map focus selections to category scaffolding
+ - Infer any missing context from spec/plan/tasks (do NOT hallucinate)
+
+4. **Load feature context**: Read from FEATURE_DIR:
+ - spec.md: Feature requirements and scope
+ - plan.md (if exists): Technical details, dependencies
+ - tasks.md (if exists): Implementation tasks
+
+ **Context Loading Strategy**:
+ - Load only necessary portions relevant to active focus areas (avoid full-file dumping)
+ - Prefer summarizing long sections into concise scenario/requirement bullets
+ - Use progressive disclosure: add follow-on retrieval only if gaps detected
+ - If source docs are large, generate interim summary items instead of embedding raw text
+
+5. **Generate checklist** - Create "Unit Tests for Requirements":
+ - Create `FEATURE_DIR/checklists/` directory if it doesn't exist
+ - Generate unique checklist filename:
+ - Use short, descriptive name based on domain (e.g., `ux.md`, `api.md`, `security.md`)
+ - Format: `[domain].md`
+ - If file exists, append to existing file
+ - Number items sequentially starting from CHK001
+ - Each `/speckit.checklist` run creates a NEW file (never overwrites existing checklists)
+
+ **CORE PRINCIPLE - Test the Requirements, Not the Implementation**:
+ Every checklist item MUST evaluate the REQUIREMENTS THEMSELVES for:
+ - **Completeness**: Are all necessary requirements present?
+ - **Clarity**: Are requirements unambiguous and specific?
+ - **Consistency**: Do requirements align with each other?
+ - **Measurability**: Can requirements be objectively verified?
+ - **Coverage**: Are all scenarios/edge cases addressed?
+
+ **Category Structure** - Group items by requirement quality dimensions:
+ - **Requirement Completeness** (Are all necessary requirements documented?)
+ - **Requirement Clarity** (Are requirements specific and unambiguous?)
+ - **Requirement Consistency** (Do requirements align without conflicts?)
+ - **Acceptance Criteria Quality** (Are success criteria measurable?)
+ - **Scenario Coverage** (Are all flows/cases addressed?)
+ - **Edge Case Coverage** (Are boundary conditions defined?)
+ - **Non-Functional Requirements** (Performance, Security, Accessibility, etc. - are they specified?)
+ - **Dependencies & Assumptions** (Are they documented and validated?)
+ - **Ambiguities & Conflicts** (What needs clarification?)
+
+ **HOW TO WRITE CHECKLIST ITEMS - "Unit Tests for English"**:
+
+ ❌ **WRONG** (Testing implementation):
+ - "Verify landing page displays 3 episode cards"
+ - "Test hover states work on desktop"
+ - "Confirm logo click navigates home"
+
+ ✅ **CORRECT** (Testing requirements quality):
+ - "Are the exact number and layout of featured episodes specified?" [Completeness]
+ - "Is 'prominent display' quantified with specific sizing/positioning?" [Clarity]
+ - "Are hover state requirements consistent across all interactive elements?" [Consistency]
+ - "Are keyboard navigation requirements defined for all interactive UI?" [Coverage]
+ - "Is the fallback behavior specified when logo image fails to load?" [Edge Cases]
+ - "Are loading states defined for asynchronous episode data?" [Completeness]
+ - "Does the spec define visual hierarchy for competing UI elements?" [Clarity]
+
+ **ITEM STRUCTURE**:
+ Each item should follow this pattern:
+ - Question format asking about requirement quality
+ - Focus on what's WRITTEN (or not written) in the spec/plan
+ - Include quality dimension in brackets [Completeness/Clarity/Consistency/etc.]
+ - Reference spec section `[Spec §X.Y]` when checking existing requirements
+ - Use `[Gap]` marker when checking for missing requirements
+
+ **EXAMPLES BY QUALITY DIMENSION**:
+
+ Completeness:
+ - "Are error handling requirements defined for all API failure modes? [Gap]"
+ - "Are accessibility requirements specified for all interactive elements? [Completeness]"
+ - "Are mobile breakpoint requirements defined for responsive layouts? [Gap]"
+
+ Clarity:
+ - "Is 'fast loading' quantified with specific timing thresholds? [Clarity, Spec §NFR-2]"
+ - "Are 'related episodes' selection criteria explicitly defined? [Clarity, Spec §FR-5]"
+ - "Is 'prominent' defined with measurable visual properties? [Ambiguity, Spec §FR-4]"
+
+ Consistency:
+ - "Do navigation requirements align across all pages? [Consistency, Spec §FR-10]"
+ - "Are card component requirements consistent between landing and detail pages? [Consistency]"
+
+ Coverage:
+ - "Are requirements defined for zero-state scenarios (no episodes)? [Coverage, Edge Case]"
+ - "Are concurrent user interaction scenarios addressed? [Coverage, Gap]"
+ - "Are requirements specified for partial data loading failures? [Coverage, Exception Flow]"
+
+ Measurability:
+ - "Are visual hierarchy requirements measurable/testable? [Acceptance Criteria, Spec §FR-1]"
+ - "Can 'balanced visual weight' be objectively verified? [Measurability, Spec §FR-2]"
+
+ **Scenario Classification & Coverage** (Requirements Quality Focus):
+ - Check if requirements exist for: Primary, Alternate, Exception/Error, Recovery, Non-Functional scenarios
+ - For each scenario class, ask: "Are [scenario type] requirements complete, clear, and consistent?"
+ - If scenario class missing: "Are [scenario type] requirements intentionally excluded or missing? [Gap]"
+ - Include resilience/rollback when state mutation occurs: "Are rollback requirements defined for migration failures? [Gap]"
+
+ **Traceability Requirements**:
+ - MINIMUM: ≥80% of items MUST include at least one traceability reference
+ - Each item should reference: spec section `[Spec §X.Y]`, or use markers: `[Gap]`, `[Ambiguity]`, `[Conflict]`, `[Assumption]`
+ - If no ID system exists: "Is a requirement & acceptance criteria ID scheme established? [Traceability]"
+
+ **Surface & Resolve Issues** (Requirements Quality Problems):
+ Ask questions about the requirements themselves:
+ - Ambiguities: "Is the term 'fast' quantified with specific metrics? [Ambiguity, Spec §NFR-1]"
+ - Conflicts: "Do navigation requirements conflict between §FR-10 and §FR-10a? [Conflict]"
+ - Assumptions: "Is the assumption of 'always available podcast API' validated? [Assumption]"
+ - Dependencies: "Are external podcast API requirements documented? [Dependency, Gap]"
+ - Missing definitions: "Is 'visual hierarchy' defined with measurable criteria? [Gap]"
+
+ **Content Consolidation**:
+ - Soft cap: If raw candidate items > 40, prioritize by risk/impact
+ - Merge near-duplicates checking the same requirement aspect
+ - If >5 low-impact edge cases, create one item: "Are edge cases X, Y, Z addressed in requirements? [Coverage]"
+
+ **🚫 ABSOLUTELY PROHIBITED** - These make it an implementation test, not a requirements test:
+ - ❌ Any item starting with "Verify", "Test", "Confirm", "Check" + implementation behavior
+ - ❌ References to code execution, user actions, system behavior
+ - ❌ "Displays correctly", "works properly", "functions as expected"
+ - ❌ "Click", "navigate", "render", "load", "execute"
+ - ❌ Test cases, test plans, QA procedures
+ - ❌ Implementation details (frameworks, APIs, algorithms)
+
+ **✅ REQUIRED PATTERNS** - These test requirements quality:
+ - ✅ "Are [requirement type] defined/specified/documented for [scenario]?"
+ - ✅ "Is [vague term] quantified/clarified with specific criteria?"
+ - ✅ "Are requirements consistent between [section A] and [section B]?"
+ - ✅ "Can [requirement] be objectively measured/verified?"
+ - ✅ "Are [edge cases/scenarios] addressed in requirements?"
+ - ✅ "Does the spec define [missing aspect]?"
+
+6. **Structure Reference**: Generate the checklist following the canonical template in `.specify/templates/checklist-template.md` for title, meta section, category headings, and ID formatting. If template is unavailable, use: H1 title, purpose/created meta lines, `##` category sections containing `- [ ] CHK### <requirement item>` lines with globally incrementing IDs starting at CHK001.
+
+7. **Report**: Output full path to created checklist, item count, and remind user that each run creates a new file. Summarize:
+ - Focus areas selected
+ - Depth level
+ - Actor/timing
+ - Any explicit user-specified must-have items incorporated
+
+**Important**: Each `/speckit.checklist` command invocation creates a checklist file using short, descriptive names unless file already exists. This allows:
+
+- Multiple checklists of different types (e.g., `ux.md`, `test.md`, `security.md`)
+- Simple, memorable filenames that indicate checklist purpose
+- Easy identification and navigation in the `checklists/` folder
+
+To avoid clutter, use descriptive types and clean up obsolete checklists when done.
+
+## Example Checklist Types & Sample Items
+
+**UX Requirements Quality:** `ux.md`
+
+Sample items (testing the requirements, NOT the implementation):
+
+- "Are visual hierarchy requirements defined with measurable criteria? [Clarity, Spec §FR-1]"
+- "Is the number and positioning of UI elements explicitly specified? [Completeness, Spec §FR-1]"
+- "Are interaction state requirements (hover, focus, active) consistently defined? [Consistency]"
+- "Are accessibility requirements specified for all interactive elements? [Coverage, Gap]"
+- "Is fallback behavior defined when images fail to load? [Edge Case, Gap]"
+- "Can 'prominent display' be objectively measured? [Measurability, Spec §FR-4]"
+
+**API Requirements Quality:** `api.md`
+
+Sample items:
+
+- "Are error response formats specified for all failure scenarios? [Completeness]"
+- "Are rate limiting requirements quantified with specific thresholds? [Clarity]"
+- "Are authentication requirements consistent across all endpoints? [Consistency]"
+- "Are retry/timeout requirements defined for external dependencies? [Coverage, Gap]"
+- "Is versioning strategy documented in requirements? [Gap]"
+
+**Performance Requirements Quality:** `performance.md`
+
+Sample items:
+
+- "Are performance requirements quantified with specific metrics? [Clarity]"
+- "Are performance targets defined for all critical user journeys? [Coverage]"
+- "Are performance requirements under different load conditions specified? [Completeness]"
+- "Can performance requirements be objectively measured? [Measurability]"
+- "Are degradation requirements defined for high-load scenarios? [Edge Case, Gap]"
+
+**Security Requirements Quality:** `security.md`
+
+Sample items:
+
+- "Are authentication requirements specified for all protected resources? [Coverage]"
+- "Are data protection requirements defined for sensitive information? [Completeness]"
+- "Is the threat model documented and requirements aligned to it? [Traceability]"
+- "Are security requirements consistent with compliance obligations? [Consistency]"
+- "Are security failure/breach response requirements defined? [Gap, Exception Flow]"
+
+## Anti-Examples: What NOT To Do
+
+**❌ WRONG - These test implementation, not requirements:**
+
+```markdown
+- [ ] CHK001 - Verify landing page displays 3 episode cards [Spec §FR-001]
+- [ ] CHK002 - Test hover states work correctly on desktop [Spec §FR-003]
+- [ ] CHK003 - Confirm logo click navigates to home page [Spec §FR-010]
+- [ ] CHK004 - Check that related episodes section shows 3-5 items [Spec §FR-005]
+```
+
+**✅ CORRECT - These test requirements quality:**
+
+```markdown
+- [ ] CHK001 - Are the number and layout of featured episodes explicitly specified? [Completeness, Spec §FR-001]
+- [ ] CHK002 - Are hover state requirements consistently defined for all interactive elements? [Consistency, Spec §FR-003]
+- [ ] CHK003 - Are navigation requirements clear for all clickable brand elements? [Clarity, Spec §FR-010]
+- [ ] CHK004 - Is the selection criteria for related episodes documented? [Gap, Spec §FR-005]
+- [ ] CHK005 - Are loading state requirements defined for asynchronous episode data? [Gap]
+- [ ] CHK006 - Can "visual hierarchy" requirements be objectively measured? [Measurability, Spec §FR-001]
+```
+
+**Key Differences:**
+
+- Wrong: Tests if the system works correctly
+- Correct: Tests if the requirements are written correctly
+- Wrong: Verification of behavior
+- Correct: Validation of requirement quality
+- Wrong: "Does it do X?"
+- Correct: "Is X clearly specified?"
diff --git a/.claude/commands/speckit.clarify.md b/.claude/commands/speckit.clarify.md
new file mode 100644
index 0000000..6b28dae
--- /dev/null
+++ b/.claude/commands/speckit.clarify.md
@@ -0,0 +1,181 @@
+---
+description: Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec.
+handoffs:
+ - label: Build Technical Plan
+ agent: speckit.plan
+ prompt: Create a plan for the spec. I am building with...
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+Goal: Detect and reduce ambiguity or missing decision points in the active feature specification and record the clarifications directly in the spec file.
+
+Note: This clarification workflow is expected to run (and be completed) BEFORE invoking `/speckit.plan`. If the user explicitly states they are skipping clarification (e.g., exploratory spike), you may proceed, but must warn that downstream rework risk increases.
+
+Execution steps:
+
+1. Run `.specify/scripts/bash/check-prerequisites.sh --json --paths-only` from repo root **once** (combined `--json --paths-only` mode / `-Json -PathsOnly`). Parse minimal JSON payload fields:
+ - `FEATURE_DIR`
+ - `FEATURE_SPEC`
+ - (Optionally capture `IMPL_PLAN`, `TASKS` for future chained flows.)
+ - If JSON parsing fails, abort and instruct user to re-run `/speckit.specify` or verify feature branch environment.
+ - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. Load the current spec file. Perform a structured ambiguity & coverage scan using this taxonomy. For each category, mark status: Clear / Partial / Missing. Produce an internal coverage map used for prioritization (do not output raw map unless no questions will be asked).
+
+ Functional Scope & Behavior:
+ - Core user goals & success criteria
+ - Explicit out-of-scope declarations
+ - User roles / personas differentiation
+
+ Domain & Data Model:
+ - Entities, attributes, relationships
+ - Identity & uniqueness rules
+ - Lifecycle/state transitions
+ - Data volume / scale assumptions
+
+ Interaction & UX Flow:
+ - Critical user journeys / sequences
+ - Error/empty/loading states
+ - Accessibility or localization notes
+
+ Non-Functional Quality Attributes:
+ - Performance (latency, throughput targets)
+ - Scalability (horizontal/vertical, limits)
+ - Reliability & availability (uptime, recovery expectations)
+ - Observability (logging, metrics, tracing signals)
+ - Security & privacy (authN/Z, data protection, threat assumptions)
+ - Compliance / regulatory constraints (if any)
+
+ Integration & External Dependencies:
+ - External services/APIs and failure modes
+ - Data import/export formats
+ - Protocol/versioning assumptions
+
+ Edge Cases & Failure Handling:
+ - Negative scenarios
+ - Rate limiting / throttling
+ - Conflict resolution (e.g., concurrent edits)
+
+ Constraints & Tradeoffs:
+ - Technical constraints (language, storage, hosting)
+ - Explicit tradeoffs or rejected alternatives
+
+ Terminology & Consistency:
+ - Canonical glossary terms
+ - Avoided synonyms / deprecated terms
+
+ Completion Signals:
+ - Acceptance criteria testability
+ - Measurable Definition of Done style indicators
+
+ Misc / Placeholders:
+ - TODO markers / unresolved decisions
+ - Ambiguous adjectives ("robust", "intuitive") lacking quantification
+
+ For each category with Partial or Missing status, add a candidate question opportunity unless:
+ - Clarification would not materially change implementation or validation strategy
+ - Information is better deferred to planning phase (note internally)
+
+3. Generate (internally) a prioritized queue of candidate clarification questions (maximum 5). Do NOT output them all at once. Apply these constraints:
+ - Maximum of 10 total questions across the whole session.
+ - Each question must be answerable with EITHER:
+ - A short multiple‑choice selection (2–5 distinct, mutually exclusive options), OR
+ - A one-word / short‑phrase answer (explicitly constrain: "Answer in <=5 words").
+ - Only include questions whose answers materially impact architecture, data modeling, task decomposition, test design, UX behavior, operational readiness, or compliance validation.
+ - Ensure category coverage balance: attempt to cover the highest impact unresolved categories first; avoid asking two low-impact questions when a single high-impact area (e.g., security posture) is unresolved.
+ - Exclude questions already answered, trivial stylistic preferences, or plan-level execution details (unless blocking correctness).
+ - Favor clarifications that reduce downstream rework risk or prevent misaligned acceptance tests.
+ - If more than 5 categories remain unresolved, select the top 5 by (Impact * Uncertainty) heuristic.
+
+4. Sequential questioning loop (interactive):
+ - Present EXACTLY ONE question at a time.
+ - For multiple‑choice questions:
+ - **Analyze all options** and determine the **most suitable option** based on:
+ - Best practices for the project type
+ - Common patterns in similar implementations
+ - Risk reduction (security, performance, maintainability)
+ - Alignment with any explicit project goals or constraints visible in the spec
+ - Present your **recommended option prominently** at the top with clear reasoning (1-2 sentences explaining why this is the best choice).
+ - Format as: `**Recommended:** Option [X] - <reasoning>`
+ - Then render all options as a Markdown table:
+
+ | Option | Description |
+ |--------|-------------|
+ | A | <Option A description> |
+ | B | <Option B description> |
+ | C | <Option C description> (add D/E as needed up to 5) |
+ | Short | Provide a different short answer (<=5 words) (Include only if free-form alternative is appropriate) |
+
+ - After the table, add: `You can reply with the option letter (e.g., "A"), accept the recommendation by saying "yes" or "recommended", or provide your own short answer.`
+ - For short‑answer style (no meaningful discrete options):
+ - Provide your **suggested answer** based on best practices and context.
+ - Format as: `**Suggested:** <your proposed answer> - <brief reasoning>`
+ - Then output: `Format: Short answer (<=5 words). You can accept the suggestion by saying "yes" or "suggested", or provide your own answer.`
+ - After the user answers:
+ - If the user replies with "yes", "recommended", or "suggested", use your previously stated recommendation/suggestion as the answer.
+ - Otherwise, validate the answer maps to one option or fits the <=5 word constraint.
+ - If ambiguous, ask for a quick disambiguation (count still belongs to same question; do not advance).
+ - Once satisfactory, record it in working memory (do not yet write to disk) and move to the next queued question.
+ - Stop asking further questions when:
+ - All critical ambiguities resolved early (remaining queued items become unnecessary), OR
+ - User signals completion ("done", "good", "no more"), OR
+ - You reach 5 asked questions.
+ - Never reveal future queued questions in advance.
+ - If no valid questions exist at start, immediately report no critical ambiguities.
+
+5. Integration after EACH accepted answer (incremental update approach):
+ - Maintain in-memory representation of the spec (loaded once at start) plus the raw file contents.
+ - For the first integrated answer in this session:
+ - Ensure a `## Clarifications` section exists (create it just after the highest-level contextual/overview section per the spec template if missing).
+ - Under it, create (if not present) a `### Session YYYY-MM-DD` subheading for today.
+ - Append a bullet line immediately after acceptance: `- Q: <question> → A: <final answer>`.
+ - Then immediately apply the clarification to the most appropriate section(s):
+ - Functional ambiguity → Update or add a bullet in Functional Requirements.
+ - User interaction / actor distinction → Update User Stories or Actors subsection (if present) with clarified role, constraint, or scenario.
+ - Data shape / entities → Update Data Model (add fields, types, relationships) preserving ordering; note added constraints succinctly.
+ - Non-functional constraint → Add/modify measurable criteria in Non-Functional / Quality Attributes section (convert vague adjective to metric or explicit target).
+ - Edge case / negative flow → Add a new bullet under Edge Cases / Error Handling (or create such subsection if template provides placeholder for it).
+ - Terminology conflict → Normalize term across spec; retain original only if necessary by adding `(formerly referred to as "X")` once.
+ - If the clarification invalidates an earlier ambiguous statement, replace that statement instead of duplicating; leave no obsolete contradictory text.
+ - Save the spec file AFTER each integration to minimize risk of context loss (atomic overwrite).
+ - Preserve formatting: do not reorder unrelated sections; keep heading hierarchy intact.
+ - Keep each inserted clarification minimal and testable (avoid narrative drift).
+
+6. Validation (performed after EACH write plus final pass):
+ - Clarifications session contains exactly one bullet per accepted answer (no duplicates).
+ - Total asked (accepted) questions ≤ 5.
+ - Updated sections contain no lingering vague placeholders the new answer was meant to resolve.
+ - No contradictory earlier statement remains (scan for now-invalid alternative choices removed).
+ - Markdown structure valid; only allowed new headings: `## Clarifications`, `### Session YYYY-MM-DD`.
+ - Terminology consistency: same canonical term used across all updated sections.
+
+7. Write the updated spec back to `FEATURE_SPEC`.
+
+8. Report completion (after questioning loop ends or early termination):
+ - Number of questions asked & answered.
+ - Path to updated spec.
+ - Sections touched (list names).
+ - Coverage summary table listing each taxonomy category with Status: Resolved (was Partial/Missing and addressed), Deferred (exceeds question quota or better suited for planning), Clear (already sufficient), Outstanding (still Partial/Missing but low impact).
+ - If any Outstanding or Deferred remain, recommend whether to proceed to `/speckit.plan` or run `/speckit.clarify` again later post-plan.
+ - Suggested next command.
+
+Behavior rules:
+
+- If no meaningful ambiguities found (or all potential questions would be low-impact), respond: "No critical ambiguities detected worth formal clarification." and suggest proceeding.
+- If spec file missing, instruct user to run `/speckit.specify` first (do not create a new spec here).
+- Never exceed 5 total asked questions (clarification retries for a single question do not count as new questions).
+- Avoid speculative tech stack questions unless the absence blocks functional clarity.
+- Respect user early termination signals ("stop", "done", "proceed").
+- If no questions asked due to full coverage, output a compact coverage summary (all categories Clear) then suggest advancing.
+- If quota reached with unresolved high-impact categories remaining, explicitly flag them under Deferred with rationale.
+
+Context for prioritization: $ARGUMENTS
diff --git a/.claude/commands/speckit.constitution.md b/.claude/commands/speckit.constitution.md
new file mode 100644
index 0000000..63d4f66
--- /dev/null
+++ b/.claude/commands/speckit.constitution.md
@@ -0,0 +1,84 @@
+---
+description: Create or update the project constitution from interactive or provided principle inputs, ensuring all dependent templates stay in sync.
+handoffs:
+ - label: Build Specification
+ agent: speckit.specify
+ prompt: Implement the feature specification based on the updated constitution. I want to build...
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+You are updating the project constitution at `.specify/memory/constitution.md`. This file is a TEMPLATE containing placeholder tokens in square brackets (e.g. `[PROJECT_NAME]`, `[PRINCIPLE_1_NAME]`). Your job is to (a) collect/derive concrete values, (b) fill the template precisely, and (c) propagate any amendments across dependent artifacts.
+
+**Note**: If `.specify/memory/constitution.md` does not exist yet, it should have been initialized from `.specify/templates/constitution-template.md` during project setup. If it's missing, copy the template first.
+
+Follow this execution flow:
+
+1. Load the existing constitution at `.specify/memory/constitution.md`.
+ - Identify every placeholder token of the form `[ALL_CAPS_IDENTIFIER]`.
+ **IMPORTANT**: The user might require less or more principles than the ones used in the template. If a number is specified, respect that - follow the general template. You will update the doc accordingly.
+
+2. Collect/derive values for placeholders:
+ - If user input (conversation) supplies a value, use it.
+ - Otherwise infer from existing repo context (README, docs, prior constitution versions if embedded).
+ - For governance dates: `RATIFICATION_DATE` is the original adoption date (if unknown ask or mark TODO), `LAST_AMENDED_DATE` is today if changes are made, otherwise keep previous.
+ - `CONSTITUTION_VERSION` must increment according to semantic versioning rules:
+ - MAJOR: Backward incompatible governance/principle removals or redefinitions.
+ - MINOR: New principle/section added or materially expanded guidance.
+ - PATCH: Clarifications, wording, typo fixes, non-semantic refinements.
+ - If version bump type ambiguous, propose reasoning before finalizing.
+
+3. Draft the updated constitution content:
+ - Replace every placeholder with concrete text (no bracketed tokens left except intentionally retained template slots that the project has chosen not to define yet—explicitly justify any left).
+ - Preserve heading hierarchy and comments can be removed once replaced unless they still add clarifying guidance.
+ - Ensure each Principle section: succinct name line, paragraph (or bullet list) capturing non‑negotiable rules, explicit rationale if not obvious.
+ - Ensure Governance section lists amendment procedure, versioning policy, and compliance review expectations.
+
+4. Consistency propagation checklist (convert prior checklist into active validations):
+ - Read `.specify/templates/plan-template.md` and ensure any "Constitution Check" or rules align with updated principles.
+ - Read `.specify/templates/spec-template.md` for scope/requirements alignment—update if constitution adds/removes mandatory sections or constraints.
+ - Read `.specify/templates/tasks-template.md` and ensure task categorization reflects new or removed principle-driven task types (e.g., observability, versioning, testing discipline).
+ - Read each command file in `.specify/templates/commands/*.md` (including this one) to verify no outdated references (agent-specific names like CLAUDE only) remain when generic guidance is required.
+ - Read any runtime guidance docs (e.g., `README.md`, `docs/quickstart.md`, or agent-specific guidance files if present). Update references to principles changed.
+
+5. Produce a Sync Impact Report (prepend as an HTML comment at top of the constitution file after update):
+ - Version change: old → new
+ - List of modified principles (old title → new title if renamed)
+ - Added sections
+ - Removed sections
+ - Templates requiring updates (✅ updated / ⚠ pending) with file paths
+ - Follow-up TODOs if any placeholders intentionally deferred.
+
+6. Validation before final output:
+ - No remaining unexplained bracket tokens.
+ - Version line matches report.
+ - Dates ISO format YYYY-MM-DD.
+ - Principles are declarative, testable, and free of vague language ("should" → replace with MUST/SHOULD rationale where appropriate).
+
+7. Write the completed constitution back to `.specify/memory/constitution.md` (overwrite).
+
+8. Output a final summary to the user with:
+ - New version and bump rationale.
+ - Any files flagged for manual follow-up.
+ - Suggested commit message (e.g., `docs: amend constitution to vX.Y.Z (principle additions + governance update)`).
+
+Formatting & Style Requirements:
+
+- Use Markdown headings exactly as in the template (do not demote/promote levels).
+- Wrap long rationale lines to keep readability (<100 chars ideally) but do not hard enforce with awkward breaks.
+- Keep a single blank line between sections.
+- Avoid trailing whitespace.
+
+If the user supplies partial updates (e.g., only one principle revision), still perform validation and version decision steps.
+
+If critical info missing (e.g., ratification date truly unknown), insert `TODO(<FIELD_NAME>): explanation` and include in the Sync Impact Report under deferred items.
+
+Do not create a new template; always operate on the existing `.specify/memory/constitution.md` file.
diff --git a/.claude/commands/speckit.implement.md b/.claude/commands/speckit.implement.md
new file mode 100644
index 0000000..41da7b9
--- /dev/null
+++ b/.claude/commands/speckit.implement.md
@@ -0,0 +1,135 @@
+---
+description: Execute the implementation plan by processing and executing all tasks defined in tasks.md
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+1. Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. **Check checklists status** (if FEATURE_DIR/checklists/ exists):
+ - Scan all checklist files in the checklists/ directory
+ - For each checklist, count:
+ - Total items: All lines matching `- [ ]` or `- [X]` or `- [x]`
+ - Completed items: Lines matching `- [X]` or `- [x]`
+ - Incomplete items: Lines matching `- [ ]`
+ - Create a status table:
+
+ ```text
+ | Checklist | Total | Completed | Incomplete | Status |
+ |-----------|-------|-----------|------------|--------|
+ | ux.md | 12 | 12 | 0 | ✓ PASS |
+ | test.md | 8 | 5 | 3 | ✗ FAIL |
+ | security.md | 6 | 6 | 0 | ✓ PASS |
+ ```
+
+ - Calculate overall status:
+ - **PASS**: All checklists have 0 incomplete items
+ - **FAIL**: One or more checklists have incomplete items
+
+ - **If any checklist is incomplete**:
+ - Display the table with incomplete item counts
+ - **STOP** and ask: "Some checklists are incomplete. Do you want to proceed with implementation anyway? (yes/no)"
+ - Wait for user response before continuing
+ - If user says "no" or "wait" or "stop", halt execution
+ - If user says "yes" or "proceed" or "continue", proceed to step 3
+
+ - **If all checklists are complete**:
+ - Display the table showing all checklists passed
+ - Automatically proceed to step 3
+
+3. Load and analyze the implementation context:
+ - **REQUIRED**: Read tasks.md for the complete task list and execution plan
+ - **REQUIRED**: Read plan.md for tech stack, architecture, and file structure
+ - **IF EXISTS**: Read data-model.md for entities and relationships
+ - **IF EXISTS**: Read contracts/ for API specifications and test requirements
+ - **IF EXISTS**: Read research.md for technical decisions and constraints
+ - **IF EXISTS**: Read quickstart.md for integration scenarios
+
+4. **Project Setup Verification**:
+ - **REQUIRED**: Create/verify ignore files based on actual project setup:
+
+ **Detection & Creation Logic**:
+ - Check if the following command succeeds to determine if the repository is a git repo (create/verify .gitignore if so):
+
+ ```sh
+ git rev-parse --git-dir 2>/dev/null
+ ```
+
+ - Check if Dockerfile* exists or Docker in plan.md → create/verify .dockerignore
+ - Check if .eslintrc* exists → create/verify .eslintignore
+ - Check if eslint.config.* exists → ensure the config's `ignores` entries cover required patterns
+ - Check if .prettierrc* exists → create/verify .prettierignore
+ - Check if .npmrc or package.json exists → create/verify .npmignore (if publishing)
+ - Check if terraform files (*.tf) exist → create/verify .terraformignore
+ - Check if .helmignore needed (helm charts present) → create/verify .helmignore
+
+ **If ignore file already exists**: Verify it contains essential patterns, append missing critical patterns only
+ **If ignore file missing**: Create with full pattern set for detected technology
+
+ **Common Patterns by Technology** (from plan.md tech stack):
+ - **Node.js/JavaScript/TypeScript**: `node_modules/`, `dist/`, `build/`, `*.log`, `.env*`
+ - **Python**: `__pycache__/`, `*.pyc`, `.venv/`, `venv/`, `dist/`, `*.egg-info/`
+ - **Java**: `target/`, `*.class`, `*.jar`, `.gradle/`, `build/`
+ - **C#/.NET**: `bin/`, `obj/`, `*.user`, `*.suo`, `packages/`
+ - **Go**: `*.exe`, `*.test`, `vendor/`, `*.out`
+ - **Ruby**: `.bundle/`, `log/`, `tmp/`, `*.gem`, `vendor/bundle/`
+ - **PHP**: `vendor/`, `*.log`, `*.cache`, `*.env`
+ - **Rust**: `target/`, `debug/`, `release/`, `*.rs.bk`, `*.rlib`, `*.prof*`, `.idea/`, `*.log`, `.env*`
+ - **Kotlin**: `build/`, `out/`, `.gradle/`, `.idea/`, `*.class`, `*.jar`, `*.iml`, `*.log`, `.env*`
+ - **C++**: `build/`, `bin/`, `obj/`, `out/`, `*.o`, `*.so`, `*.a`, `*.exe`, `*.dll`, `.idea/`, `*.log`, `.env*`
+ - **C**: `build/`, `bin/`, `obj/`, `out/`, `*.o`, `*.a`, `*.so`, `*.exe`, `Makefile`, `config.log`, `.idea/`, `*.log`, `.env*`
+ - **Swift**: `.build/`, `DerivedData/`, `*.swiftpm/`, `Packages/`
+ - **R**: `.Rproj.user/`, `.Rhistory`, `.RData`, `.Ruserdata`, `*.Rproj`, `packrat/`, `renv/`
+ - **Universal**: `.DS_Store`, `Thumbs.db`, `*.tmp`, `*.swp`, `.vscode/`, `.idea/`
+
+ **Tool-Specific Patterns**:
+ - **Docker**: `node_modules/`, `.git/`, `Dockerfile*`, `.dockerignore`, `*.log*`, `.env*`, `coverage/`
+ - **ESLint**: `node_modules/`, `dist/`, `build/`, `coverage/`, `*.min.js`
+ - **Prettier**: `node_modules/`, `dist/`, `build/`, `coverage/`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`
+ - **Terraform**: `.terraform/`, `*.tfstate*`, `*.tfvars`, `.terraform.lock.hcl`
+ - **Kubernetes/k8s**: `*.secret.yaml`, `secrets/`, `.kube/`, `kubeconfig*`, `*.key`, `*.crt`
+
+5. Parse tasks.md structure and extract:
+ - **Task phases**: Setup, Tests, Core, Integration, Polish
+ - **Task dependencies**: Sequential vs parallel execution rules
+ - **Task details**: ID, description, file paths, parallel markers [P]
+ - **Execution flow**: Order and dependency requirements
+
+6. Execute implementation following the task plan:
+ - **Phase-by-phase execution**: Complete each phase before moving to the next
+ - **Respect dependencies**: Run sequential tasks in order, parallel tasks [P] can run together
+ - **Follow TDD approach**: Execute test tasks before their corresponding implementation tasks
+ - **File-based coordination**: Tasks affecting the same files must run sequentially
+ - **Validation checkpoints**: Verify each phase completion before proceeding
+
+7. Implementation execution rules:
+ - **Setup first**: Initialize project structure, dependencies, configuration
+ - **Tests before code**: If you need to write tests for contracts, entities, and integration scenarios
+ - **Core development**: Implement models, services, CLI commands, endpoints
+ - **Integration work**: Database connections, middleware, logging, external services
+ - **Polish and validation**: Unit tests, performance optimization, documentation
+
+8. Progress tracking and error handling:
+ - Report progress after each completed task
+ - Halt execution if any non-parallel task fails
+ - For parallel tasks [P], continue with successful tasks, report failed ones
+ - Provide clear error messages with context for debugging
+ - Suggest next steps if implementation cannot proceed
+ - **IMPORTANT** For completed tasks, make sure to mark the task off as [X] in the tasks file.
+
+9. Completion validation:
+ - Verify all required tasks are completed
+ - Check that implemented features match the original specification
+ - Validate that tests pass and coverage meets requirements
+ - Confirm the implementation follows the technical plan
+ - Report final status with summary of completed work
+
+Note: This command assumes a complete task breakdown exists in tasks.md. If tasks are incomplete or missing, suggest running `/speckit.tasks` first to regenerate the task list.
diff --git a/.claude/commands/speckit.plan.md b/.claude/commands/speckit.plan.md
new file mode 100644
index 0000000..e9e5599
--- /dev/null
+++ b/.claude/commands/speckit.plan.md
@@ -0,0 +1,89 @@
+---
+description: Execute the implementation planning workflow using the plan template to generate design artifacts.
+handoffs:
+ - label: Create Tasks
+ agent: speckit.tasks
+ prompt: Break the plan into tasks
+ send: true
+ - label: Create Checklist
+ agent: speckit.checklist
+ prompt: Create a checklist for the following domain...
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+1. **Setup**: Run `.specify/scripts/bash/setup-plan.sh --json` from repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. **Load context**: Read FEATURE_SPEC and `.specify/memory/constitution.md`. Load IMPL_PLAN template (already copied).
+
+3. **Execute plan workflow**: Follow the structure in IMPL_PLAN template to:
+ - Fill Technical Context (mark unknowns as "NEEDS CLARIFICATION")
+ - Fill Constitution Check section from constitution
+ - Evaluate gates (ERROR if violations unjustified)
+ - Phase 0: Generate research.md (resolve all NEEDS CLARIFICATION)
+ - Phase 1: Generate data-model.md, contracts/, quickstart.md
+ - Phase 1: Update agent context by running the agent script
+ - Re-evaluate Constitution Check post-design
+
+4. **Stop and report**: Command ends after Phase 2 planning. Report branch, IMPL_PLAN path, and generated artifacts.
+
+## Phases
+
+### Phase 0: Outline & Research
+
+1. **Extract unknowns from Technical Context** above:
+ - For each NEEDS CLARIFICATION → research task
+ - For each dependency → best practices task
+ - For each integration → patterns task
+
+2. **Generate and dispatch research agents**:
+
+ ```text
+ For each unknown in Technical Context:
+ Task: "Research {unknown} for {feature context}"
+ For each technology choice:
+ Task: "Find best practices for {tech} in {domain}"
+ ```
+
+3. **Consolidate findings** in `research.md` using format:
+ - Decision: [what was chosen]
+ - Rationale: [why chosen]
+ - Alternatives considered: [what else evaluated]
+
+**Output**: research.md with all NEEDS CLARIFICATION resolved
+
+### Phase 1: Design & Contracts
+
+**Prerequisites:** `research.md` complete
+
+1. **Extract entities from feature spec** → `data-model.md`:
+ - Entity name, fields, relationships
+ - Validation rules from requirements
+ - State transitions if applicable
+
+2. **Generate API contracts** from functional requirements:
+ - For each user action → endpoint
+ - Use standard REST/GraphQL patterns
+ - Output OpenAPI/GraphQL schema to `/contracts/`
+
+3. **Agent context update**:
+ - Run `.specify/scripts/bash/update-agent-context.sh claude`
+ - These scripts detect which AI agent is in use
+ - Update the appropriate agent-specific context file
+ - Add only new technology from current plan
+ - Preserve manual additions between markers
+
+**Output**: data-model.md, /contracts/*, quickstart.md, agent-specific file
+
+## Key rules
+
+- Use absolute paths
+- ERROR on gate failures or unresolved clarifications
diff --git a/.claude/commands/speckit.specify.md b/.claude/commands/speckit.specify.md
new file mode 100644
index 0000000..49abdcb
--- /dev/null
+++ b/.claude/commands/speckit.specify.md
@@ -0,0 +1,258 @@
+---
+description: Create or update the feature specification from a natural language feature description.
+handoffs:
+ - label: Build Technical Plan
+ agent: speckit.plan
+ prompt: Create a plan for the spec. I am building with...
+ - label: Clarify Spec Requirements
+ agent: speckit.clarify
+ prompt: Clarify specification requirements
+ send: true
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+The text the user typed after `/speckit.specify` in the triggering message **is** the feature description. Assume you always have it available in this conversation even if `$ARGUMENTS` appears literally below. Do not ask the user to repeat it unless they provided an empty command.
+
+Given that feature description, do this:
+
+1. **Generate a concise short name** (2-4 words) for the branch:
+ - Analyze the feature description and extract the most meaningful keywords
+ - Create a 2-4 word short name that captures the essence of the feature
+ - Use action-noun format when possible (e.g., "add-user-auth", "fix-payment-bug")
+ - Preserve technical terms and acronyms (OAuth2, API, JWT, etc.)
+ - Keep it concise but descriptive enough to understand the feature at a glance
+ - Examples:
+ - "I want to add user authentication" → "user-auth"
+ - "Implement OAuth2 integration for the API" → "oauth2-api-integration"
+ - "Create a dashboard for analytics" → "analytics-dashboard"
+ - "Fix payment processing timeout bug" → "fix-payment-timeout"
+
+2. **Check for existing branches before creating new one**:
+
+ a. First, fetch all remote branches to ensure we have the latest information:
+
+ ```bash
+ git fetch --all --prune
+ ```
+
+ b. Find the highest feature number across all sources for the short-name:
+ - Remote branches: `git ls-remote --heads origin | grep -E 'refs/heads/[0-9]+-<short-name>$'`
+ - Local branches: `git branch | grep -E '^[* ]*[0-9]+-<short-name>$'`
+ - Specs directories: Check for directories matching `specs/[0-9]+-<short-name>`
+
+ c. Determine the next available number:
+ - Extract all numbers from all three sources
+ - Find the highest number N
+ - Use N+1 for the new branch number
+
+ d. Run the script `.specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS"` with the calculated number and short-name:
+ - Pass `--number N+1` and `--short-name "your-short-name"` along with the feature description
+ - Bash example: `.specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS" --json --number 5 --short-name "user-auth" "Add user authentication"`
+ - PowerShell example: `.specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS" -Json -Number 5 -ShortName "user-auth" "Add user authentication"`
+
+ **IMPORTANT**:
+ - Check all three sources (remote branches, local branches, specs directories) to find the highest number
+ - Only match branches/directories with the exact short-name pattern
+ - If no existing branches/directories found with this short-name, start with number 1
+ - You must only ever run this script once per feature
+ - The JSON is provided in the terminal as output - always refer to it to get the actual content you're looking for
+ - The JSON output will contain BRANCH_NAME and SPEC_FILE paths
+ - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot")
+
+3. Load `.specify/templates/spec-template.md` to understand required sections.
+
+4. Follow this execution flow:
+
+ 1. Parse user description from Input
+ If empty: ERROR "No feature description provided"
+ 2. Extract key concepts from description
+ Identify: actors, actions, data, constraints
+ 3. For unclear aspects:
+ - Make informed guesses based on context and industry standards
+ - Only mark with [NEEDS CLARIFICATION: specific question] if:
+ - The choice significantly impacts feature scope or user experience
+ - Multiple reasonable interpretations exist with different implications
+ - No reasonable default exists
+ - **LIMIT: Maximum 3 [NEEDS CLARIFICATION] markers total**
+ - Prioritize clarifications by impact: scope > security/privacy > user experience > technical details
+ 4. Fill User Scenarios & Testing section
+ If no clear user flow: ERROR "Cannot determine user scenarios"
+ 5. Generate Functional Requirements
+ Each requirement must be testable
+ Use reasonable defaults for unspecified details (document assumptions in Assumptions section)
+ 6. Define Success Criteria
+ Create measurable, technology-agnostic outcomes
+ Include both quantitative metrics (time, performance, volume) and qualitative measures (user satisfaction, task completion)
+ Each criterion must be verifiable without implementation details
+ 7. Identify Key Entities (if data involved)
+ 8. Return: SUCCESS (spec ready for planning)
+
+5. Write the specification to SPEC_FILE using the template structure, replacing placeholders with concrete details derived from the feature description (arguments) while preserving section order and headings.
+
+6. **Specification Quality Validation**: After writing the initial spec, validate it against quality criteria:
+
+ a. **Create Spec Quality Checklist**: Generate a checklist file at `FEATURE_DIR/checklists/requirements.md` using the checklist template structure with these validation items:
+
+ ```markdown
+ # Specification Quality Checklist: [FEATURE NAME]
+
+ **Purpose**: Validate specification completeness and quality before proceeding to planning
+ **Created**: [DATE]
+ **Feature**: [Link to spec.md]
+
+ ## Content Quality
+
+ - [ ] No implementation details (languages, frameworks, APIs)
+ - [ ] Focused on user value and business needs
+ - [ ] Written for non-technical stakeholders
+ - [ ] All mandatory sections completed
+
+ ## Requirement Completeness
+
+ - [ ] No [NEEDS CLARIFICATION] markers remain
+ - [ ] Requirements are testable and unambiguous
+ - [ ] Success criteria are measurable
+ - [ ] Success criteria are technology-agnostic (no implementation details)
+ - [ ] All acceptance scenarios are defined
+ - [ ] Edge cases are identified
+ - [ ] Scope is clearly bounded
+ - [ ] Dependencies and assumptions identified
+
+ ## Feature Readiness
+
+ - [ ] All functional requirements have clear acceptance criteria
+ - [ ] User scenarios cover primary flows
+ - [ ] Feature meets measurable outcomes defined in Success Criteria
+ - [ ] No implementation details leak into specification
+
+ ## Notes
+
+ - Items marked incomplete require spec updates before `/speckit.clarify` or `/speckit.plan`
+ ```
+
+ b. **Run Validation Check**: Review the spec against each checklist item:
+ - For each item, determine if it passes or fails
+ - Document specific issues found (quote relevant spec sections)
+
+ c. **Handle Validation Results**:
+
+ - **If all items pass**: Mark checklist complete and proceed to step 6
+
+ - **If items fail (excluding [NEEDS CLARIFICATION])**:
+ 1. List the failing items and specific issues
+ 2. Update the spec to address each issue
+ 3. Re-run validation until all items pass (max 3 iterations)
+ 4. If still failing after 3 iterations, document remaining issues in checklist notes and warn user
+
+ - **If [NEEDS CLARIFICATION] markers remain**:
+ 1. Extract all [NEEDS CLARIFICATION: ...] markers from the spec
+ 2. **LIMIT CHECK**: If more than 3 markers exist, keep only the 3 most critical (by scope/security/UX impact) and make informed guesses for the rest
+ 3. For each clarification needed (max 3), present options to user in this format:
+
+ ```markdown
+ ## Question [N]: [Topic]
+
+ **Context**: [Quote relevant spec section]
+
+ **What we need to know**: [Specific question from NEEDS CLARIFICATION marker]
+
+ **Suggested Answers**:
+
+ | Option | Answer | Implications |
+ |--------|--------|--------------|
+ | A | [First suggested answer] | [What this means for the feature] |
+ | B | [Second suggested answer] | [What this means for the feature] |
+ | C | [Third suggested answer] | [What this means for the feature] |
+ | Custom | Provide your own answer | [Explain how to provide custom input] |
+
+ **Your choice**: _[Wait for user response]_
+ ```
+
+ 4. **CRITICAL - Table Formatting**: Ensure markdown tables are properly formatted:
+ - Use consistent spacing with pipes aligned
+ - Each cell should have spaces around content: `| Content |` not `|Content|`
+ - Header separator must have at least 3 dashes: `|--------|`
+ - Test that the table renders correctly in markdown preview
+ 5. Number questions sequentially (Q1, Q2, Q3 - max 3 total)
+ 6. Present all questions together before waiting for responses
+ 7. Wait for user to respond with their choices for all questions (e.g., "Q1: A, Q2: Custom - [details], Q3: B")
+ 8. Update the spec by replacing each [NEEDS CLARIFICATION] marker with the user's selected or provided answer
+ 9. Re-run validation after all clarifications are resolved
+
+ d. **Update Checklist**: After each validation iteration, update the checklist file with current pass/fail status
+
+7. Report completion with branch name, spec file path, checklist results, and readiness for the next phase (`/speckit.clarify` or `/speckit.plan`).
+
+**NOTE:** The script creates and checks out the new branch and initializes the spec file before writing.
+
+## General Guidelines
+
+## Quick Guidelines
+
+- Focus on **WHAT** users need and **WHY**.
+- Avoid HOW to implement (no tech stack, APIs, code structure).
+- Written for business stakeholders, not developers.
+- DO NOT create any checklists that are embedded in the spec. That will be a separate command.
+
+### Section Requirements
+
+- **Mandatory sections**: Must be completed for every feature
+- **Optional sections**: Include only when relevant to the feature
+- When a section doesn't apply, remove it entirely (don't leave as "N/A")
+
+### For AI Generation
+
+When creating this spec from a user prompt:
+
+1. **Make informed guesses**: Use context, industry standards, and common patterns to fill gaps
+2. **Document assumptions**: Record reasonable defaults in the Assumptions section
+3. **Limit clarifications**: Maximum 3 [NEEDS CLARIFICATION] markers - use only for critical decisions that:
+ - Significantly impact feature scope or user experience
+ - Have multiple reasonable interpretations with different implications
+ - Lack any reasonable default
+4. **Prioritize clarifications**: scope > security/privacy > user experience > technical details
+5. **Think like a tester**: Every vague requirement should fail the "testable and unambiguous" checklist item
+6. **Common areas needing clarification** (only if no reasonable default exists):
+ - Feature scope and boundaries (include/exclude specific use cases)
+ - User types and permissions (if multiple conflicting interpretations possible)
+ - Security/compliance requirements (when legally/financially significant)
+
+**Examples of reasonable defaults** (don't ask about these):
+
+- Data retention: Industry-standard practices for the domain
+- Performance targets: Standard web/mobile app expectations unless specified
+- Error handling: User-friendly messages with appropriate fallbacks
+- Authentication method: Standard session-based or OAuth2 for web apps
+- Integration patterns: RESTful APIs unless specified otherwise
+
+### Success Criteria Guidelines
+
+Success criteria must be:
+
+1. **Measurable**: Include specific metrics (time, percentage, count, rate)
+2. **Technology-agnostic**: No mention of frameworks, languages, databases, or tools
+3. **User-focused**: Describe outcomes from user/business perspective, not system internals
+4. **Verifiable**: Can be tested/validated without knowing implementation details
+
+**Good examples**:
+
+- "Users can complete checkout in under 3 minutes"
+- "System supports 10,000 concurrent users"
+- "95% of searches return results in under 1 second"
+- "Task completion rate improves by 40%"
+
+**Bad examples** (implementation-focused):
+
+- "API response time is under 200ms" (too technical, use "Users see results instantly")
+- "Database can handle 1000 TPS" (implementation detail, use user-facing metric)
+- "React components render efficiently" (framework-specific)
+- "Redis cache hit rate above 80%" (technology-specific)
diff --git a/.claude/commands/speckit.tasks.md b/.claude/commands/speckit.tasks.md
new file mode 100644
index 0000000..f64e86e
--- /dev/null
+++ b/.claude/commands/speckit.tasks.md
@@ -0,0 +1,137 @@
+---
+description: Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts.
+handoffs:
+ - label: Analyze For Consistency
+ agent: speckit.analyze
+ prompt: Run a project analysis for consistency
+ send: true
+ - label: Implement Project
+ agent: speckit.implement
+ prompt: Start the implementation in phases
+ send: true
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+1. **Setup**: Run `.specify/scripts/bash/check-prerequisites.sh --json` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. **Load design documents**: Read from FEATURE_DIR:
+ - **Required**: plan.md (tech stack, libraries, structure), spec.md (user stories with priorities)
+ - **Optional**: data-model.md (entities), contracts/ (API endpoints), research.md (decisions), quickstart.md (test scenarios)
+ - Note: Not all projects have all documents. Generate tasks based on what's available.
+
+3. **Execute task generation workflow**:
+ - Load plan.md and extract tech stack, libraries, project structure
+ - Load spec.md and extract user stories with their priorities (P1, P2, P3, etc.)
+ - If data-model.md exists: Extract entities and map to user stories
+ - If contracts/ exists: Map endpoints to user stories
+ - If research.md exists: Extract decisions for setup tasks
+ - Generate tasks organized by user story (see Task Generation Rules below)
+ - Generate dependency graph showing user story completion order
+ - Create parallel execution examples per user story
+ - Validate task completeness (each user story has all needed tasks, independently testable)
+
+4. **Generate tasks.md**: Use `.specify/templates/tasks-template.md` as structure, fill with:
+ - Correct feature name from plan.md
+ - Phase 1: Setup tasks (project initialization)
+ - Phase 2: Foundational tasks (blocking prerequisites for all user stories)
+ - Phase 3+: One phase per user story (in priority order from spec.md)
+ - Each phase includes: story goal, independent test criteria, tests (if requested), implementation tasks
+ - Final Phase: Polish & cross-cutting concerns
+ - All tasks must follow the strict checklist format (see Task Generation Rules below)
+ - Clear file paths for each task
+ - Dependencies section showing story completion order
+ - Parallel execution examples per story
+ - Implementation strategy section (MVP first, incremental delivery)
+
+5. **Report**: Output path to generated tasks.md and summary:
+ - Total task count
+ - Task count per user story
+ - Parallel opportunities identified
+ - Independent test criteria for each story
+ - Suggested MVP scope (typically just User Story 1)
+ - Format validation: Confirm ALL tasks follow the checklist format (checkbox, ID, labels, file paths)
+
+Context for task generation: $ARGUMENTS
+
+The tasks.md should be immediately executable - each task must be specific enough that an LLM can complete it without additional context.
+
+## Task Generation Rules
+
+**CRITICAL**: Tasks MUST be organized by user story to enable independent implementation and testing.
+
+**Tests are OPTIONAL**: Only generate test tasks if explicitly requested in the feature specification or if user requests TDD approach.
+
+### Checklist Format (REQUIRED)
+
+Every task MUST strictly follow this format:
+
+```text
+- [ ] [TaskID] [P?] [Story?] Description with file path
+```
+
+**Format Components**:
+
+1. **Checkbox**: ALWAYS start with `- [ ]` (markdown checkbox)
+2. **Task ID**: Sequential number (T001, T002, T003...) in execution order
+3. **[P] marker**: Include ONLY if task is parallelizable (different files, no dependencies on incomplete tasks)
+4. **[Story] label**: REQUIRED for user story phase tasks only
+ - Format: [US1], [US2], [US3], etc. (maps to user stories from spec.md)
+ - Setup phase: NO story label
+ - Foundational phase: NO story label
+ - User Story phases: MUST have story label
+ - Polish phase: NO story label
+5. **Description**: Clear action with exact file path
+
+**Examples**:
+
+- ✅ CORRECT: `- [ ] T001 Create project structure per implementation plan`
+- ✅ CORRECT: `- [ ] T005 [P] Implement authentication middleware in src/middleware/auth.py`
+- ✅ CORRECT: `- [ ] T012 [P] [US1] Create User model in src/models/user.py`
+- ✅ CORRECT: `- [ ] T014 [US1] Implement UserService in src/services/user_service.py`
+- ❌ WRONG: `- [ ] Create User model` (missing ID and Story label)
+- ❌ WRONG: `T001 [US1] Create model` (missing checkbox)
+- ❌ WRONG: `- [ ] [US1] Create User model` (missing Task ID)
+- ❌ WRONG: `- [ ] T001 [US1] Create model` (missing file path)
+
+### Task Organization
+
+1. **From User Stories (spec.md)** - PRIMARY ORGANIZATION:
+ - Each user story (P1, P2, P3...) gets its own phase
+ - Map all related components to their story:
+ - Models needed for that story
+ - Services needed for that story
+ - Endpoints/UI needed for that story
+ - If tests requested: Tests specific to that story
+ - Mark story dependencies (most stories should be independent)
+
+2. **From Contracts**:
+ - Map each contract/endpoint → to the user story it serves
+ - If tests requested: Each contract → contract test task [P] before implementation in that story's phase
+
+3. **From Data Model**:
+ - Map each entity to the user story(ies) that need it
+ - If entity serves multiple stories: Put in earliest story or Setup phase
+ - Relationships → service layer tasks in appropriate story phase
+
+4. **From Setup/Infrastructure**:
+ - Shared infrastructure → Setup phase (Phase 1)
+ - Foundational/blocking tasks → Foundational phase (Phase 2)
+ - Story-specific setup → within that story's phase
+
+### Phase Structure
+
+- **Phase 1**: Setup (project initialization)
+- **Phase 2**: Foundational (blocking prerequisites - MUST complete before user stories)
+- **Phase 3+**: User Stories in priority order (P1, P2, P3...)
+ - Within each story: Tests (if requested) → Models → Services → Endpoints → Integration
+ - Each phase should be a complete, independently testable increment
+- **Final Phase**: Polish & Cross-Cutting Concerns
diff --git a/.claude/commands/speckit.taskstoissues.md b/.claude/commands/speckit.taskstoissues.md
new file mode 100644
index 0000000..0799191
--- /dev/null
+++ b/.claude/commands/speckit.taskstoissues.md
@@ -0,0 +1,30 @@
+---
+description: Convert existing tasks into actionable, dependency-ordered GitHub issues for the feature based on available design artifacts.
+tools: ['github/github-mcp-server/issue_write']
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+1. Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+1. From the executed script, extract the path to **tasks**.
+1. Get the Git remote by running:
+
+```bash
+git config --get remote.origin.url
+```
+
+> [!CAUTION]
+> ONLY PROCEED TO NEXT STEPS IF THE REMOTE IS A GITHUB URL
+
+1. For each task in the list, use the GitHub MCP server to create a new issue in the repository that is representative of the Git remote.
+
+> [!CAUTION]
+> UNDER NO CIRCUMSTANCES EVER CREATE ISSUES IN REPOSITORIES THAT DO NOT MATCH THE REMOTE URL
diff --git a/.claude/commands/watch-prs.md b/.claude/commands/watch-prs.md
new file mode 100644
index 0000000..7f215cf
--- /dev/null
+++ b/.claude/commands/watch-prs.md
@@ -0,0 +1,57 @@
+---
+description: Watch the current task's open PR(s) and handle review comments (the PR-watch loop)
+---
+
+Watch the open PR(s) for the current task and follow this loop until I tell you to stop (or the PRs are merged/closed):
+
+1. **Poll** each PR for new review comments and conversation comments.
+
+2. **Ping me** about each new comment, asking whether I'm handling it / am done, then **wait 60 seconds** for my reply.
+
+3. If I don't reply within 60s, keep watching. Once the **same comment has been unaddressed for 30 minutes**, start working it (step 4).
+
+4. **When you START working a comment, react 👀 (`eyes`) on it** so I can see it's in progress:
+ - Review (inline) comment: `gh api repos/{owner}/{repo}/pulls/comments/{COMMENT_ID}/reactions -f content=eyes`
+ - Conversation (issue) comment: `gh api repos/{owner}/{repo}/issues/comments/{COMMENT_ID}/reactions -f content=eyes`
+
+5. **Address it** — make the change. Act automatically; **pause only at the 3 autonomy gates**: release→master merge (G1), any deletion (G2), anything irreversible (G3).
+ - **If you need an answer from me to proceed:** reply asking, and **keep the 👀** — do **not** add 👍. (A 👀 that stays means "in progress / waiting on your answer.")
+
+6. **Only when the comment is fully addressed AND no further info is needed:** reply on its thread with the solution (what you changed and why), then **remove the 👀 and add 👍**:
+ - Add 👍 — inline: `gh api repos/{owner}/{repo}/pulls/comments/{COMMENT_ID}/reactions -f content=+1` · conversation: `gh api repos/{owner}/{repo}/issues/comments/{COMMENT_ID}/reactions -f content=+1`
+ - Remove 👀 — find its id `gh api repos/{owner}/{repo}/pulls/comments/{COMMENT_ID}/reactions --jq '.[]|select(.content=="eyes").id'` then `gh api -X DELETE repos/{owner}/{repo}/pulls/comments/{COMMENT_ID}/reactions/{REACTION_ID}` (issue comments: swap `pulls`→`issues`).
+
+Signals: **👀 = in progress / I need your answer** · **👍 (with the 👀 removed) = addressed, nothing more needed**.
+
+**Labels drive the review / test / QA lifecycle** (`/way-of-working` §5) — watch and set them:
+
+- **While you're actively pushing to a PR** (opening it, addressing comments, adding tests),
+ it carries **`claude-is-working`** — NOT `ready-for-manual-review`. They're **mutually
+ exclusive**; never leave `ready-for-manual-review` on a PR you're still changing.
+ `gh pr edit <num> --add-label claude-is-working`
+- **When you hand off to the CEO** (done pushing, ready for review), **swap the labels**:
+ `gh pr edit <num> --remove-label claude-is-working --add-label ready-for-manual-review`
+- **When the CEO adds `ready-for-changes`** (reviewed → wants the changes applied), **swap to
+ `claude-is-working`**, address **all** the review comments (👀 → fix → 👍 per comment), push,
+ then **swap back to `ready-for-manual-review`** for re-review:
+ `gh pr edit <num> --remove-label ready-for-changes,ready-for-manual-review --add-label claude-is-working`
+- **Never add tests before** the CEO adds **`ready-for-unit-tests`**. Poll for it —
+ `gh pr view <num> --json labels --jq '.labels[].name'` — and when it appears, **swap back to
+ `claude-is-working`**, **add the backend unit tests** to that PR, commit, push, then remove
+ `claude-is-working`. (Frontend is never tested.)
+- When **all** child PRs are merged into the release branch, add **`ready-for-manual-test`**
+ (the QA cue): `gh pr edit <release-pr> --add-label ready-for-manual-test`.
+- **Keep watching** through all of this — don't stop just because comments went quiet; stop
+ only when the CEO says so or the PR is merged/closed.
+
+**When the release branch is assembled and manual testing is signalled**, run the
+**pre-merge gate** (`/way-of-working` §8): green CI + a requirements audit on the release
+branch, fix any blocker there, then prepare the release → master merge (G1). **On a
+release → master merge**, do the post-merge smoke check (§9) and prepare cleanup (§10, G2 —
+confirm first).
+
+This is the repo's default PR-watch protocol (enabled via the `SessionStart` hook in `.claude/settings.json`).
+
+> **Not** Claude Code's built-in **Remote Control** (driving a session from your phone via
+> claude.ai). That's a separate, unrelated feature configured in settings
+> (`remoteControlAtStartup`) — this file is only the GitHub PR-watch loop.
diff --git a/.claude/commands/way-of-working.md b/.claude/commands/way-of-working.md
new file mode 100644
index 0000000..c3a9b21
--- /dev/null
+++ b/.claude/commands/way-of-working.md
@@ -0,0 +1,398 @@
+# Way of Working — Canonical Delivery Lifecycle
+
+The single source of truth for how every task and every plan is delivered on the Nzmly
+platform. The `task-orchestrator` and all role agents follow this. When anything below
+conflicts with an older instruction, **this file wins**.
+
+Invoke `/way-of-working` to reload it. The PR-watch loop lives in `/watch-prs`. (Not to be
+confused with Claude Code's built-in **Remote Control** = driving a session from your phone,
+a separate settings feature.)
+
+---
+
+## North Star (the mandate)
+
+We optimize, in priority order, for:
+
+1. **Cleanliness & maintainability** — small, coherent PRs; one concern each; no dead code; reads like the surrounding code.
+2. **Scalability & performance** — every plan is stress-tested at large scale; N+1s, hot paths, and unbounded queries are caught in review, not prod.
+3. **Speed of development** — we get there fast by **parallelizing aggressively** (many agents, even multiple staff engineers at once), not by cutting corners.
+
+Treat the user as the **CEO** and yourself as the **CTPO**. Default to action within the
+autonomy gates below; escalate only the three things that are genuinely the CEO's call.
+
+---
+
+## Autonomy model — auto, pause at 3 gates
+
+Run the whole lifecycle autonomously **except** these three gates, where you STOP and ask:
+
+| Gate | Why |
+|------|-----|
+| **G1 — Merge release → master** | Irreversible, ships to prod. The CEO/team merges; you prepare and ask. |
+| **G2 — Any deletion** | Deleting branches, worktrees, files, DB columns, data. Always confirm the exact targets first. |
+| **G3 — Anything irreversible / outward-facing** | Force-push that could lose others' commits, force-merge, destructive migration, sending external mail, anything you can't undo. |
+
+These gates have a **best-effort hook backstop**: `.claude/hooks/guard-destructive-git.cjs`
+(wired via `.claude/settings.json`, `PreToolUse`/Bash) pauses for confirmation on bare
+force-push (G3), branch/worktree/remote deletions (G2), and `gh pr merge` / push-to-master
+(G1) — for me and every parallel sub-agent. It is a backstop, **not airtight and not a
+substitute for judgment**: it pattern-matches command text, so indirect execution (a wrapper
+script, an alias, exotic quoting) can slip past, and it **fails open** if it errors.
+`--force-with-lease` passes through. The real guarantee is **branch protection on
+`master`/release + human review** — the hook just catches the obvious slips.
+
+Everything else is automatic: branching, pushing feature branches, opening PRs, rebasing
+children on a merge, addressing review comments after the grace window, and **preparing**
+cleanup (the deletion itself is G2).
+
+> PR merges into the **release branch** are done by the team on GitHub — you *react* to
+> them (rebase the chain), you do not perform them.
+
+> **Never push commits to the release branch directly** — no build commits, no audit
+> fixes, no hotfixes, no copy tweaks. Every change to the release branch lands through a
+> **reviewed child PR targeting it**, like any build PR. The only exception is the §6
+> rebase (master→release), which force-pushes the **same already-reviewed content** onto
+> a new base and introduces no new changes.
+
+---
+
+## Two lanes
+
+Every piece of work is either a **Plan (RFC)** or a **Task (build)**. Plans precede
+non-trivial builds. Both produce PRs.
+
+```
+Idea ──► PLAN lane (RFC PR) ──approved──► TASK lane (release branch + build PRs) ──► master
+```
+
+---
+
+## PLAN lane — every plan is an RFC PR
+
+A plan is never just chat. It is a document (`docs/plans/YYYY-MM-DD-<feature>.md`, dated +
+meaningfully named) shipped as its own **RFC PR targeting master**. The RFC PR contains
+**only the plan doc — never implementation code**; the build ships in separate task PRs
+that never depend on it. So the plan PR's fate is decoupled: **close it unmerged** (it was
+a discussion artifact) **or merge it as durable business knowledge** (a dated entry in the
+`docs/plans/` knowledge base). Either way it never blocks delivery.
+
+### Draft 1 — Business first, no code
+
+The first draft is **business only**. It must contain:
+
+- **Problem & goal** — what we're solving and why it matters to the business.
+- **Scenarios** — concrete end-to-end narratives ("A merchant whose EGP payout fails
+ re-saves their bank details and retries; the system…"). Cover happy path, edge cases,
+ failure/abuse cases. Scenarios are the heart of draft 1.
+- **Success metrics & non-goals.**
+
+No tables, no schema, no APIs yet. **Get the business draft approved by the CEO before
+touching the technical part.**
+
+### Draft 2 — Technical (only after business approval)
+
+Add the technical design. **For every database table you introduce or change:**
+
+- **What it is** and **why it's needed** (1–2 sentences).
+- **A concrete example row** (realistic values).
+- **The relationships** — draw them as an ASCII ERD and state cardinality in words
+ (e.g., "one `product` has many `productPage` (≤10); each `productPage` has many
+ `productPageBlock`").
+
+Template:
+
+```
+### Table: productPage (`prpg_`)
+Why: a product can present more than one landing layout; this row is one such layout.
+Example:
+ | id | productId | defaultKey | title | createdAt |
+ |---------------|----------------|------------|----------------|-----------|
+ | prpg_01HX… | prod_01HW… | default | "Summer launch"| 2026-06-30|
+Relations:
+ product (1) ───< productPage (N, ≤10) ───< productPageBlock (N)
+ │
+ └─ defaultKey unique per product ⇒ exactly one default
+```
+
+Also include: API surface, event flow, migration/rollback notes, and an initial
+**Deployment Steps** stub (see below).
+
+**Impacted surface (must be confirmed).** List every module / app / lib / shared entity the
+change will touch — e.g. `dash-api/payouts`, `libs/payout`, `comms-hub` templates,
+`frontend/dashboard/modules/payouts`. Explicitly flag anything **shared or
+high-blast-radius** (entities, auth, money/ledger, events consumed by other apps). **Get the
+CEO to confirm the impacted surface before any build starts** — surprises here are the
+expensive ones.
+
+### Plan review — multi-angle, parallel, same agent many times
+
+Once the plan (business + technical) is drafted, review it **before** any build:
+
+1. **Business part → `product-owner`** agent. Validates scenarios, scope, metrics, edge
+ cases, and that the business goal is actually met.
+2. **Technical part → tech leads** (`tech-lead-backend` / `tech-lead-frontend`). But do
+ **not** run a single review — fan out **multiple instances of the same tech-lead
+ agent in parallel**, each with a different lens:
+
+ - **Small scale** (single store, low volume — is it over-engineered?)
+ - **Large scale** (millions of rows, high concurrency — does it hold?)
+ - **Performance** (N+1, indexes, hot paths, caching)
+ - **Security** (authz, ownership, injection, data exposure, abuse)
+ - **DevOps / deployability** (migrations, env vars, rollback, zero-downtime)
+ - **Production readiness** (observability, idempotency, failure modes)
+ - **Consistency with recent feature work** (does it match how we've been building lately?)
+ - **Best practices / expert eye** (clean architecture, naming, simplicity)
+
+ Collect all lenses, dedupe, and synthesize into one findings list. Address findings,
+ then re-review until clean. Push the revised plan to the RFC PR and keep the
+ review-watch loop running on it (same `/watch-prs` watch as build PRs).
+
+ > If launching many heavy review agents in parallel hits a transient rate-limit, fall
+ > back to **one consolidated agent covering all lenses** in a single pass.
+
+A plan is "locked" only after the CEO approves the reviewed draft 2.
+
+---
+
+## TASK lane — every task ships as PRs
+
+### 1. Branch topology
+
+- **Always branch from latest `master`.** Fetch first.
+- **Every task gets a `release/<feature>` branch** cut from latest master — **even a one-PR
+ task**. **Nothing merges straight to master.** Every build PR branches off the **release
+ branch's latest tip**, stays **≤15 files, one concern each**, and **targets the release
+ branch**. The release branch merges to master **once, at the end**, after the pre-merge
+ audit (§8).
+ - A one-PR task = a release branch with a single child PR — small, but it still flows
+ through the release-level gates (`ready-for-manual-test` + audit) before master.
+- **Fast-path — trivial changes only:** a change touching **only** `.claude/**`, `docs/**`,
+ or `*.md` (governance / process / docs — **no product code**) MAY skip the release branch
+ and ship as a **single PR targeting `master`**. It still gets `claude-is-working` →
+ `ready-for-manual-review` and CEO review, but no `ready-for-manual-test` and no unit-test
+ label (nothing to test). **If any product code is touched, it's not trivial** → full
+ release-branch flow.
+- **Always work in git worktrees** (`isolation: "worktree"` for agents) so the main
+ checkout stays clean and parallel work never collides.
+
+### 2. Parallelize to finish fast
+
+This is a hard expectation, not a nice-to-have:
+
+- Break the task into the **smallest independent slices** that can progress concurrently.
+- Launch **as many parallel agents as possible — including multiple `staff-*-engineer`
+ instances at once** — one per slice, each in its own worktree so they never conflict.
+- Cross-domain: backend slices that the frontend depends on go first (or are stubbed by
+ contract); independent slices run fully in parallel.
+- Favor **quality and readability** in every slice; surface **performance and security**
+ concerns by default.
+
+### 3. Build, then push, then PR
+
+- Implement the **production code only for the slice — NO tests yet** (tests come after the
+ CEO's manual review; see §5).
+- **Open the PR as soon as you start pushing, labeled `claude-is-working`** (hands-on —
+ you're still committing). Opening PRs is authorized by this workflow — do it automatically,
+ no gate.
+- **When the slice is done and you're handing it to the CEO** (no more pushes coming), **swap
+ the label: remove `claude-is-working`, add `ready-for-manual-review`.** Never leave
+ `ready-for-manual-review` on a PR you're still pushing to — the two are mutually exclusive.
+- PR description: what changed, why, which acceptance criteria it covers, and the
+ base branch (**always the task's `release/<feature>` branch**).
+- **PR title format — every PR:** `type(feature-name) x/y - app-name - title`
+ - `type` — `feat` / `fix` / `chore` / `refactor` / `docs` / `release` / …
+ - `(feature-name)` — the kebab-case feature slug (matches `release/<feature>`).
+ - `x/y` — this PR's number **within the task** over the task's **total PR count**
+ (a one-PR task = `1/1`).
+ - `app-name` — the primary app/area: `dash-api`, `shop-api`, `admin-api`, `comms-hub`,
+ `job-worker`, `store-webhook`, `dashboard`, `storefront`, `storefront-v2`, … ;
+ cross-cutting/process → `platform`.
+ - `title` — short imperative summary.
+ - Examples: `feat(egp-payout-retry) 2/5 - dash-api - flag payout setting on failure` ·
+ `fix(store-theming) 1/1 - storefront-v2 - correct RTL link icons`.
+ - The **release → master** PR uses `release(feature-name) - platform - <title>` (no `x/y`).
+
+### 4. Watch the PRs (`/watch-prs`)
+
+Run `/watch-prs` under `/loop` for the whole set of open PRs. It handles, per the
+watch protocol:
+
+- **Comments / changes / merges** detection.
+- **Per-comment ping + 60s grace:** on each new comment, ping the CEO asking whether
+ they're handling it, then wait **60 seconds** for a reply.
+- **30-minute auto-address:** if a comment is still unaddressed **30 minutes** after it
+ appeared, take it over — **react 👀 (in-progress)**, then:
+ - **Question →** answer it on the PR thread.
+ - **Change request →** make the update (delegate to the staff engineer), push, reply.
+ Only when it's **fully addressed and no further info is needed**, reply with the solution,
+ **remove the 👀 and add 👍**. If you **need the CEO's answer**, reply asking and **keep the
+ 👀** (no 👍 yet).
+- **Rebase-on-merge** (see §6).
+- **`ready-for-unit-tests` label** — the CEO adds it after finishing the manual review →
+ you're hands-on again, so **swap `ready-for-manual-review` → `claude-is-working`** and
+ **add the backend unit tests** to the PR (§5), commit, push; when the tests are in, remove
+ `claude-is-working`. Until the label appears, **never touch tests**; just keep handling
+ comments.
+- **`ready-for-changes` label** — the CEO adds it when they've finished reviewing and want
+ the requested changes applied. On it: **swap `ready-for-manual-review` → `claude-is-working`**,
+ address **all** the review comments (👀 → fix → 👍 + reply per comment), push, then **swap
+ back to `ready-for-manual-review`** for re-review and remove `ready-for-changes`. This is the
+ explicit "go work on my changes" trigger; the 30-min auto-take-over is only a fallback.
+- **Label discipline** — whenever you **resume pushing** to a PR (addressing a comment,
+ adding tests), set **`claude-is-working`** and remove `ready-for-manual-review`; **swap
+ back** when you hand off. The two are mutually exclusive — one is "hands-on", the other is
+ "your turn."
+- **Keep watching** — don't wind down when comments go quiet. Stop only when the CEO says so
+ or the PR is merged/closed. (Signals: **👀 = in progress / I need your answer**;
+ **👍, with the 👀 removed, = addressed & nothing more needed**.)
+
+### 5. Backend tests come AFTER the CEO's manual review — label-driven
+
+Tests are **never** created before the CEO's manual GitHub review. The lifecycle is driven by
+three GitHub labels:
+
+| Label | Who adds it | When | What it triggers |
+|-------|-------------|------|------------------|
+| `ready-for-manual-review` | **you** (orchestrator/agent) | the implementation PR is done — production code only, no tests | the CEO starts the manual review |
+| `ready-for-changes` | **the CEO** | after reviewing, to have the requested changes applied | you swap to `claude-is-working`, address all comments, push, then swap back to `ready-for-manual-review` |
+| `ready-for-unit-tests` | **the CEO** | after finishing the review (approved, no more changes) | you add the **backend unit tests** to that PR, commit, push |
+| `ready-for-manual-test` | **you** (orchestrator/agent) | **all** child PRs are merged into the release branch | the QA / manual-testing round |
+
+Plus one **status** label: **`claude-is-working`** — present whenever you're actively pushing
+to a PR (building, addressing comments, adding tests). It is **mutually exclusive with
+`ready-for-manual-review`** — swap one for the other. **Never** leave `ready-for-manual-review`
+on a PR you're still changing.
+
+- The implementation PR ships **production code only — no tests**; open it labeled
+ `claude-is-working`, then **swap to `ready-for-manual-review`** when you hand off.
+- **Only** once the CEO adds `ready-for-unit-tests` do you add the `.spec.ts` backend tests
+ (the 15-file cap is waived for the test files). The **frontend is never tested**.
+- When the release branch is fully assembled (every child PR merged into it), add
+ `ready-for-manual-test`.
+
+### 6. Rebase algorithm — when something merges into the release branch
+
+When a child PR is merged into the release branch, the chain must be re-based **in this
+order**:
+
+```
+1. Check master. Did master advance since the release branch was cut/last synced?
+ └─ YES → rebase the RELEASE branch onto latest master, resolve conflicts,
+ force-push the release branch. ← do this FIRST
+2. Rebase every still-open CHILD PR branch onto the updated release-branch tip,
+ resolve conflicts, force-push each child. ← only AFTER step 1
+```
+
+Always master → release first, then release → children. Force-pushes that could drop
+someone else's commits are a **G3** gate — confirm before such a push; prefer
+`--force-with-lease` (it can't clobber others' commits and passes the gate).
+
+**Squash merges:** if the merge into the release branch (or release → master) was a
+**squash**, a plain `git rebase` replays the now-duplicated commits and conflicts. Use
+`git rebase --onto origin/<new-base> <old-base> <branch>` so the squashed commits drop
+cleanly. (Squash also makes the merged child branch fully redundant → it goes to cleanup,
+not rebase.)
+
+**True stacks:** if child **B** branches off still-open child **A** (not off the release
+tip) and **A** gets new commits, rebase **B onto A**, not onto the release branch — then
+let the chain settle upward.
+
+### 7. Deployment Steps live in the release branch
+
+Maintain a single canonical **`Deployment Steps`** section in the release branch — in the
+plan doc at **`docs/plans/YYYY-MM-DD-<feature>.md`** (one home, not scattered across files).
+Keep it current as slices land. It must list:
+
+- **Env vars** to add/change (name, which app/service, example value, secret?).
+- **Migrations** to run, in order, and any backfill.
+- **Feature flags / config** to flip.
+- **External setup** (webhook subscriptions, third-party dashboards, DNS, queues).
+- **Rollback** notes.
+
+Every slice that needs an env var or migration **updates this section in the same PR**.
+
+**Parallel migrations:** when several engineers add migrations concurrently, their
+`YYYYMMDDHHMMSS-*.js` timestamps can collide or imply the wrong run order. Record the
+intended order in Deployment Steps and bump timestamps so they apply in dependency order.
+
+### 8. Pre-merge gate — audit the release branch BEFORE merging to master
+
+Once **all child PRs are merged into the release branch**, add the **`ready-for-manual-test`**
+label (the QA / manual-testing cue). The requirements audit happens **before** the
+release → master merge, not after — so master only ever receives a release branch that
+already passed. This is a gate:
+
+1. **Review-clean** — every build PR was manually reviewed (CEO added `ready-for-unit-tests`)
+ and now has its **backend unit tests in**, **no unresolved review threads**, and a **green
+ CI / lint / build** pipeline; the watch loop has settled (no open review items).
+2. **Audit the full release diff against the original requirements / locked plan** — launch
+ review agents in parallel, multi-lens (requirements-coverage, security / IDOR,
+ production-readiness, performance):
+ - Backend → `tech-lead-backend` (+ `staff-backend-engineer` for deep checks).
+ - Frontend → `tech-lead-frontend` / `frontend-code-reviewer`.
+
+ > If many heavy parallel audit agents hit a transient rate-limit, fall back to **one
+ > consolidated multi-lens agent** in a single pass.
+
+ **Fix any blocker via a child PR targeting the release branch (never a direct push to
+ it) and re-audit until clean.** Only a clean audit earns the merge.
+3. **Prepare** the release → master merge and present it for **G1** approval. The team
+ merges on GitHub.
+
+### 9. After merge to master
+
+**Watch master** for the release → master merge (it is a watched ref too). Once it lands:
+
+- Do a quick **post-merge smoke check** that the shipped commit matches what was audited in
+ §8 (no surprise squash drift / dropped files), and report the result to the CEO.
+- Proceed to cleanup (§10).
+
+The heavy requirements audit already ran in §8 **before** the merge — §9 is just
+confirmation + handoff.
+
+### 10. Cleanup (G2 — confirm the targets first)
+
+After the release branch is merged to master (**watch master for this merge too**), and
+only after listing exactly what will be removed and getting confirmation:
+
+- Delete the **local feature/release branches** for this task.
+- Remove the **git worktrees** created for it (`.claude/worktrees/<feature>`,
+ `agent-*` worktrees spun up for its slices).
+- Prune merged remote-tracking refs.
+
+Never delete a branch/worktree that still has unpushed commits or an open PR.
+
+---
+
+## Lifecycle at a glance
+
+```
+PLAN: business draft (scenarios) ─► CEO approve ─► technical draft (tables explained)
+ ─► PO + multi-lens TL review (parallel) ─► CEO lock ─► RFC PR ──► master
+
+TASK: branch off master ─► cut release/<feature> (ALWAYS — even a 1-PR task)
+ ─► confirm impacted surface ─► split into slices ─► parallel staff engineers (worktrees)
+ ─► push + open PRs (CODE ONLY) + label ready-for-manual-review ─► /watch-prs (ping+60s, 30-min auto-address)
+ ─► CEO reviews → adds ready-for-unit-tests ─► add backend tests ─► rebase-on-merge
+ ─► all merged into release + label ready-for-manual-test ─► PRE-MERGE AUDIT + green CI ─► G1: release→master
+ ─► watch master + smoke-check ─► G2: clean branches + worktrees
+```
+
+## Quick rules
+
+- Every task → PRs. Every plan → an RFC PR (doc-only, `docs/plans/YYYY-MM-DD-*.md`; closeable unmerged or kept as business knowledge).
+- **Every task → a `release/<feature>` branch** (even one-PR tasks); nothing goes straight to master. Build PRs (≤15 files, one concern) branch off it and target it; only the release branch merges to master, once, after the audit.
+- **Never push to the release branch directly** — every change to it (audit fixes, hotfixes, copy tweaks included) arrives via a reviewed child PR. Only exception: the §6 master→release rebase force-push (same reviewed content, new base).
+- **Fast-path (trivial only):** a change touching **only** `.claude/**`/`docs/**`/`*.md` (no product code) may skip the release branch → **single PR to master** (still labeled + reviewed).
+- Branch from latest master; always in worktrees.
+- Plan's technical draft lists the **impacted modules** — CEO confirms before building.
+- Parallelize hard — multiple staff engineers at once, one slice each.
+- **Labels:** while pushing = `claude-is-working` (swap to `ready-for-manual-review` on hand-off). CEO adds **`ready-for-changes`** → apply the review comments (swap to `claude-is-working`, then back). CEO adds `ready-for-unit-tests` → add backend tests (cap waived). **No tests before manual review; no FE tests ever.**
+- When all child PRs are merged into the release branch → add `ready-for-manual-test` (QA cue).
+- Watch PRs with `/watch-prs`: ping each comment (60s grace); 30-min unaddressed → take over (👀 then 👍 + reply); keep watching until `ready-for-unit-tests` (add tests) and merge.
+- On merge: rebase master→release first, then release→children (`--onto` after a squash).
+- Deployment steps + env vars live in the release branch (`docs/plans/<feature>.md`).
+- **Audit the release diff vs requirements BEFORE the merge** (green CI required); fix via child PRs targeting the release branch.
+- Pause only at G1 (release→master), G2 (deletions), G3 (irreversible).
+- After merge: watch master, smoke-check, then G2 cleanup of branches + worktrees.
diff --git a/.gitignore b/.gitignore
index 75a1357..265b375 100644
--- a/.gitignore
+++ b/.gitignore
@@ -28,4 +28,11 @@ npm-debug.log*
yarn-debug.log*
yarn-error.log*
-/dist
\ No newline at end of file
+/distnode_modules
+.next
+.turbo
+dist
+*.tsbuildinfo
+apps/*/.next
+packages/*/dist
+**/.turbo
diff --git a/.npmrc b/.npmrc
new file mode 100644
index 0000000..d099685
--- /dev/null
+++ b/.npmrc
@@ -0,0 +1 @@
+verify-deps-before-run=false
diff --git a/CLAUDE.md b/CLAUDE.md
index 534e26a..a736d0e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,138 +1,96 @@
-# CLAUDE.md
+# CLAUDE.md — hookli monorepo
-Guidance for Claude Code (claude.ai/code) when working in this repository.
+Guidance for Claude Code (claude.ai/code) at the **root** of the hookli monorepo. Each
+workspace has its own `CLAUDE.md` with the rules for that workspace — read the one for the
+code you're touching. This file covers the whole repo.
## What this is
-**`hookli`** — a published npm library of commonly-used React hooks,
-written in TypeScript and bundled with **tsup** (CJS + ESM + `.d.ts`). No app, no
-framework — a pure hooks package consumed by other React/Next.js projects.
+A **pnpm + Turborepo monorepo** for **hookli** — a zero-dependency, typed React hooks library
+and its docs site. One repo, two workspaces, one source of truth.
-- Package name: `hookli`. Renamed 2026-07-11 from the old `@saif.dev/use-any-hook`
- (via short-lived `re-hooks`/`hookio` attempts — `hookio` was blocked by npm as too
- similar to the existing `hook.io`).
-- Entry: `src/index.ts` → `export * from "./hooks"`.
-- Docs site: https://use-any-hook-d92674ab.mintlify.app (still under the OLD slug — rebrand separately).
-- Peer deps: `react` / `react-dom` `^18.2.0`. Runtime deps: none.
+| Workspace | Path | What | Ships to |
+|---|---|---|---|
+| **Library** | `packages/hookli/` | the `hookli` npm package (folder-per-hook, tsup CJS+ESM+`.d.ts`, vitest) | **npm** |
+| **Docs** | `apps/docs/` | Next.js App Router docs + landing; imports the library via `workspace:*` | **Vercel** (`hookli.vercel.app`) |
+| *(brand)* | `packages/brand/` | *(planned)* shared tokens / tagline / URLs / banner | — |
-## Commands
+The docs consume the **local** library through the workspace symlink — no npm round-trip while
+developing; a change to a hook is visible in the docs immediately.
+
+## Commands (run from the root)
```bash
-yarn install # deps (yarn 1.x classic; a yarn.lock is committed)
-yarn build # tsup → dist/ (index.js CJS, index.mjs ESM, index.d.ts types)
-yarn test # vitest — colocated per-hook tests
-npx tsc --noEmit # typecheck only
-bash ralph/check.sh # quality gate: tsc --noEmit + vitest + tsup build
+pnpm install # install all workspaces (pnpm 11)
+pnpm dev # turbo: run every workspace's dev
+pnpm build # turbo: build library + docs (docs waits for the library)
+pnpm test # turbo: vitest across workspaces
+pnpm typecheck # turbo: tsc --noEmit across workspaces
+pnpm lint # turbo: eslint across workspaces
+bash ralph/check.sh # the gate — scoped to the workspace(s) that changed
+
+# target one workspace
+pnpm --filter hookli run build
+pnpm --filter hookli-docs run dev
```
-Tests run on **vitest** (colocated `*.test.ts` per hook) and **CI** runs the gate on every push/PR. The quality net is
-`tsc --noEmit` + `vitest` tests + a successful `tsup` build — that is exactly what `ralph/check.sh`
-enforces. If you add hooks, keep that gate green.
+> **pnpm 11 note:** `verifyDepsBeforeRun: false` is set in `pnpm-workspace.yaml` — esbuild/sharp
+> ship prebuilt binaries via optional deps, so their postinstall scripts aren't needed and the
+> pre-run deps-check must not hard-fail. Don't re-enable it.
## Layout
-Per-hook folders (usehooks-ts style), all kebab-case:
-
```
-src/
- index.ts # public entrypoint — re-exports ./hooks
- types.ts # shared type helpers (e.g. CustomHook<T>)
- hooks/
- index.ts # barrel — re-exports every hook folder
- use-toggle/
- index.ts # folder barrel — export * from "./use-toggle"
- use-toggle.ts # the hook (camelCase export `useToggle`)
- use-toggle.test.ts # vitest test, colocated
- use-local-storage/ … # one folder per hook
+hookli/ # repo root (github.com/saifmohamedsv/hookli)
+├── CLAUDE.md # ← you are here (whole-repo)
+├── .claude/ # git-safety hooks, settings, commands, agents
+├── ralph/ # the gated self-driving loop (scoped gate)
+├── packages/hookli/ # the library → packages/hookli/CLAUDE.md
+├── apps/docs/ # the docs site → apps/docs/CLAUDE.md (+ AGENTS.md)
+├── pnpm-workspace.yaml turbo.json package.json .npmrc
+└── LICENSE CONTRIBUTING.md SECURITY.md CODE_OF_CONDUCT.md
```
## Conventions
-Decisive rules — **one convention per topic, no alternatives.** Each shows the right way and
-the wrong way. (Documentation style borrowed from the Nzmly frontend `CLAUDE.md`.)
-
-### 1 — One folder per hook, kebab-case
-
-Each hook is a kebab-case **folder** under `src/hooks/` (usehooks-ts style, unified 2026-07-13)
-containing three files: the hook, its colocated test, and a folder barrel. Only file/folder
-names are kebab — the **export stays camelCase** `use<Name>`.
-
-```
-✅ src/hooks/use-toggle/use-toggle.ts (export const useToggle = …)
-✅ src/hooks/use-toggle/use-toggle.test.ts src/hooks/use-toggle/index.ts
-❌ src/hooks/use-toggle.hook.ts src/hooks/useToggle/useToggle.ts src/hooks/Toggle/…
-```
-
-### 2 — Register every hook in the barrel
-
-Add each new file to `src/hooks/index.ts` (which `src/index.ts` re-exports). A hook that isn't
-re-exported ships to nobody — the most common miss.
-
-```ts
-✅ export * from "./use-toggle"; ❌ // file added but not exported from the barrel
-```
-
-### 3 — Type the public API explicitly
+Each workspace owns its conventions — **read the workspace `CLAUDE.md` before editing there:**
+- **`packages/hookli/CLAUDE.md`** — one hook per `src/hooks/use-<name>/` folder (hook + vitest test
+ + `meta` + barrel), typed public API, SSR-safe, tsup build.
+- **`apps/docs/CLAUDE.md`** (+ `AGENTS.md`) — kebab-case files, Geist UI font (JetBrains Mono for code
+ only), token-only styling, a11y.
-Prefer a named `interface`/`type` for the return shape over an inferred anonymous object.
-Use generics where the hook is data-shaped (`useFetch<T>`, `useLocalStorage<T>`).
+Never let the two drift: shared facts (hook list, count, descriptions, version) come from the
+**library manifest**, not hand-maintained copies. See `packages/hookli/CLAUDE.md`.
-```ts
-✅ interface UseFetchResponse<T> { data: T | null; error: Error | null; loading: boolean }
-❌ export const useFetch = (url) => ({ data, error, loading }) // untyped, no generic
-```
-
-### 4 — SSR-safety is mandatory
+## Releasing (human-gated — do NOT automate)
-Consumers render on the server (Next.js). Never touch `window` / `document` / `navigator` /
-`localStorage` at module scope or during the initial render without a guard. Browser access
-belongs inside `useEffect` (client-only) or behind `typeof window !== "undefined"`.
+Publishing is the one irreversible action. **Never** `npm publish` / `npm version` / push a tag
+on your own. Release the library from its workspace:
-```ts
-✅ const [v] = useState(() => typeof window === "undefined" ? init : read());
-❌ const [v] = useState(() => localStorage.getItem(key)); // crashes on the server
+```bash
+pnpm --filter hookli run build # (prepublishOnly also runs tsup)
+cd packages/hookli && npm publish --otp=<code>
```
-### 5 — Clean up every subscription
-
-`addEventListener` / `setTimeout` / observers must be removed in the effect's cleanup return.
-
-### 6 — Document it in `README.md`
+## Deploying the docs (human-gated)
-Add the hook to the "Available hooks" list with a one-line description. Public API changes go in
-the README (and, once it exists, the docs site's `hook-docs` entry in `../hookli-docs`).
-
-### Build & typecheck stay green
-
-`bash ralph/check.sh` (`tsc --noEmit` + `vitest` + `tsup`) must pass before any commit.
-
-## Releasing (human-gated — do NOT automate)
-
-Publishing is the one irreversible, outward-facing action here. **Never** run
-`npm publish` / `yarn publish`, `npm version`, or push a git tag on your own — the version
-history (`1.3.x` commits) shows the maintainer drives releases by hand. Ship code and let
-a human cut the release.
+Vercel builds `apps/docs` (project **Root Directory = `apps/docs`**) against the workspace library.
+A push to `main` deploys. Don't push/deploy from an agent loop.
## Ralph — the gated self-driving loop
-`ralph/` holds a stateless, file-memory task loop (see `ralph/README.md` + `ralph/GUIDE.md`).
-All memory lives in `ralph/prd.json` (backlog), `ralph/progress.txt` (log), and git.
+`ralph/` runs one task per iteration and must pass `ralph/check.sh` — which is **scoped**: it gates
+only the workspace(s) whose files changed (library: typecheck+test+build · docs: lint+typecheck+build).
+It stops at the autonomy gates: no merge/push to `main`, no deletions, no publish/deploy.
```bash
-bash ralph/ralph-once.sh # one supervised iteration — start here
-bash ralph/afk-ralph.sh 10 # up to 10 autonomous iterations, stops when backlog drains
-bash ralph/approve.sh <task-id> # commit a review-first task the loop left in the tree
-bash ralph/check.sh # the gate the loop must pass before every commit
+bash ralph/ralph-once.sh # one supervised iteration
+bash ralph/afk-ralph.sh 10 # up to 10 autonomous iterations
+RALPH_MODEL=sonnet bash ralph/afk-ralph.sh 10 # override the model (default: opus)
```
-The loop does **exactly one task per iteration**, must pass `ralph/check.sh` before
-committing, and **stops** at the autonomy gates: no merge/push to `main`, no deletions, and
-**no publish/version/tag**. The backlog (`ralph/prd.json`) is currently seeded with the
-quality-pass tasks T1–T4 above.
-
## Safety hooks (`.claude/`)
-- `hooks/guard-destructive-git.cjs` — wired in `settings.json`; pauses for confirmation on
- destructive git (force-push, branch/remote deletion, push to `main`). Best-effort backstop.
-- `hooks/enforce-pr-body.cjs` — copied in but **not wired** (it expects a
- `.github/pull_request_template.md`). Enable it in `settings.json` if you adopt that template.
+- `hooks/guard-destructive-git.cjs` — wired in `settings.json`; pauses on destructive git
+ (force-push, branch/remote deletion, push to `main`).
+- `hooks/enforce-pr-body.cjs` — available; wire it in `settings.json` if you adopt a PR template.
diff --git a/apps/docs/.gitignore b/apps/docs/.gitignore
new file mode 100644
index 0000000..1472c43
--- /dev/null
+++ b/apps/docs/.gitignore
@@ -0,0 +1,45 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+
+# ralph runtime state (progress.txt IS tracked)
+/ralph/heartbeat.log
+/docs/REDESIGN-NOTES.md
diff --git a/apps/docs/AGENTS.md b/apps/docs/AGENTS.md
new file mode 100644
index 0000000..983abd3
--- /dev/null
+++ b/apps/docs/AGENTS.md
@@ -0,0 +1,118 @@
+<!-- BEGIN:nextjs-agent-rules -->
+# This is NOT the Next.js you know
+
+This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices.
+<!-- END:nextjs-agent-rules -->
+
+# hookli-docs
+
+The docs + landing site for **hookli** (`npm i hookli`) — a React hooks library by
+@saifmohamedsv (github.com/saifmohamedsv/hookli). This app is a sibling of the library
+repo (`../rehooks-app`), which is **read-only context** — never modify it from here.
+
+## Stack
+Next.js (App Router, TypeScript, Tailwind, npm). Hooks for live demos are imported from
+the **published `hookli` package** (in node_modules), not from relative paths.
+
+## Brand (v3 — dark-first, solid, no gradients)
+- The base is a **near-black neutral** (faint teal undertone), NOT a saturated fill. Surfaces are
+ defined by subtle elevation + hairline borders, and the brand hues are **accents, not backgrounds**:
+ ground `#0A1315` (page) → raised `#101D21` (cards) → overlay `#17282E` (hover/nested); hairline
+ borders via `border-slate-syntax/40`. Accent `#30C5CA` (Scooter) = links/focus/CTA/active; Prussian
+ `#003748` (`--color-brand`) = select brand moments only; ink `#FFFFFF`, muted `#94B0B8`.
+- Colors + fonts live as CSS variables in `app/globals.css` (`@theme`). Components reference the
+ resulting Tailwind tokens (`bg-ground`, `bg-ground-raised`, `bg-ground-overlay`, `text-accent`,
+ `text-fg`, `text-gray-body`, `border-*`) — **never** a raw hex or arbitrary value.
+- Wordmark: `hookli.` (lowercase, teal full stop) beside the hook mark (inline SVG from
+ `public/hookli-icon.svg`). Assets in `public/` (`hookli-banner.svg/.png`, `hookli-icon.svg`).
+- **Plus Jakarta Sans** for headings + body; monospace ONLY inside code surfaces (code block,
+ install command, API value/type cells, demo inputs). Inline SVG icons — never emoji as icons.
+
+## Conventions
+
+Modeled on the Nzmly frontend convention (see `~/Developer/platform/frontend/storefront-v2/CLAUDE.md`).
+Decisive rules — **one convention per topic, no alternatives.** Each shows the right way and the wrong way.
+
+### 1 — File & folder names are kebab-case (lowercase-first), always
+
+Every file and folder under `app/`, `components/`, and `lib/` is **kebab-case** — components included.
+The *export* inside is PascalCase (components) or camelCase (functions/data); the **file name never is**.
+This is the single rule the previous pass got backwards — do not "fix" files to PascalCase.
+
+```
+✅ components/hook-page.tsx (exports function HookPage)
+✅ components/code-block.tsx (exports function CodeBlock, CopyButton)
+✅ components/demos/use-toggle-demo.tsx lib/hooks-registry.ts lib/web-apis.tsx
+❌ components/HookPage.tsx components/CodeBlock.tsx components/demos/UseToggleDemo.tsx
+```
+
+App Router files keep their framework names (`page.tsx`, `layout.tsx`, `not-found.tsx`,
+`opengraph-image.tsx`, `sitemap.ts`, `robots.ts`); route folders are kebab-case (`app/docs/[slug]`).
+
+### 2 — Folders group by role, then by feature; barrel with index.ts
+
+- `app/` — routes and route-level files ONLY (page/layout/metadata/OG/sitemap/robots). No shared UI here.
+- `components/` — shared components, flat by default. When one concern grows several files, give it a
+ kebab-case subfolder (as `components/demos/` does) with an `index.ts` barrel re-exporting the public parts.
+- `components/demos/` — one demo module per hook (`use-<name>-demo.tsx`) + shared primitives (`ui.tsx`).
+- `lib/` — framework-agnostic modules: data/registry (`hooks-registry.ts`, `hook-docs.ts`, `hook-sources.ts`),
+ utilities (`web-apis.tsx`, `shiki.ts`), constants. Prefer a folder + `index.ts` when a concern spans files.
+
+```
+✅ lib/hooks-registry.ts (data) components/sidebar.tsx (UI) app/docs/[slug]/page.tsx (route)
+❌ app/components/sidebar.tsx lib/Sidebar.tsx components/site-config.ts placed in app/
+```
+
+### 3 — Component file anatomy
+
+- **Named exports only — never `export default`** (except the App Router files Next requires, e.g. `page.tsx`).
+- **Server by default.** Add `"use client"` as the *first line* only when the file needs state, effects,
+ event handlers, or browser APIs. Keep client components as leaves (demos, widgets, palette).
+- **Props:** inline type for 1–2 props; a named `type <Name>Props` above the component otherwise.
+- One primary component per file (named to match the file's kebab slug); private helpers live below it.
+
+```tsx
+✅ "use client"; ❌ export default function Card(p: any) { … }
+ import { useState } from "react"; ❌ // interactivity with no "use client"
+ type CounterProps = { start: number };
+ export function Counter({ start }: CounterProps) { … }
+```
+
+### 4 — Data / registry organization (single source of truth)
+
+- `lib/hooks-registry.ts` (`HOOKS` + helpers) is the ONLY hook list. Sidebar, pages, search, and counts
+ all derive from it — never redeclare the list or hardcode a count.
+- Per-hook page content in `lib/hook-docs.ts`; vendored implementation snapshots in `lib/hook-sources.ts`
+ (kept in sync with the installed `hookli` version).
+- **Live hooks import from the published `hookli` package** — never a relative path or the sibling repo.
+
+```ts
+✅ import { useToggle } from "hookli"; ✅ const count = HOOKS.length;
+❌ import { useToggle } from "../../rehooks-app/src"; ❌ const count = 11;
+```
+
+### 5 — Import order (one block; blank line only after the directive)
+
+1. `"use client"` (first line, blank line after). 2. Framework (`next/*`, `react`) then third-party
+(`hookli`, `shiki`). 3. Internal `@/` alias — `@/components/*` then `@/lib/*`. 4. Relative (`./*`).
+
+### 6 — Styling & tokens
+
+Style with Tailwind utilities bound to the `@theme` tokens (`bg-ground`, `bg-ground-raised`, `text-accent`,
+`text-fg`, `text-gray-body`, `border-*`, `font-sans`, `font-mono`). **Never** a hardcoded hex, an arbitrary
+color (`text-[#30c5ca]`), or an inline `style` color — add a token to `globals.css` first, then reference it.
+
+### 7 — Accessibility
+
+Decorative SVGs get `aria-hidden="true"`; interactive elements keep a visible keyboard focus ring;
+icon-only controls need an `aria-label`; respect `prefers-reduced-motion`.
+
+## Quality gate (before every commit)
+```bash
+bash ralph/check.sh # npm run lint + npx tsc --noEmit + npm run build
+```
+
+## Ralph loop
+This app is built by the Ralph loop: backlog in `ralph/prd.json`, durable log in
+`ralph/progress.txt`, operating manual in `ralph/prompt.md`, design source of truth in
+`docs/DESIGN.md`. One task per iteration, gate green before commit, no pushes/deploys/publishes.
diff --git a/apps/docs/CLAUDE.md b/apps/docs/CLAUDE.md
new file mode 100644
index 0000000..43c994c
--- /dev/null
+++ b/apps/docs/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md
diff --git a/apps/docs/README.md b/apps/docs/README.md
new file mode 100644
index 0000000..e12d8a9
--- /dev/null
+++ b/apps/docs/README.md
@@ -0,0 +1,118 @@
+# hookli-docs
+
+The documentation + landing site for **[hookli](https://www.npmjs.com/package/hookli)** —
+a small, typed, SSR-safe React hooks library by
+[@saifmohamedsv](https://github.com/saifmohamedsv/hookli).
+
+Every one of the library's 11 hooks gets its own page with a **live, interactive demo
+that imports from the published `hookli` npm package** — the site is running proof the
+library works, not just prose about it. Benchmark: [usehooks-ts.com](https://usehooks-ts.com).
+
+```bash
+npm i hookli
+```
+
+## Stack
+
+- **Next.js 16** (App Router, React 19) — statically generated
+- **TypeScript** (strict)
+- **Tailwind CSS v4** — theme tokens live in `app/globals.css` under `@theme`, no config file
+- **shiki** — build-time syntax highlighting (server/build only)
+- **next/font** — Plus Jakarta Sans (UI) + JetBrains Mono (code), self-hosted via `@fontsource/*`
+- No runtime UI dependencies beyond React; demos import hooks from **`hookli`** on npm.
+
+## Getting started
+
+```bash
+npm install
+npm run dev # dev server → http://localhost:3000
+npm run build # production build (static export of all routes)
+npm run start # serve the production build
+npm run lint # eslint
+```
+
+### Quality gate
+
+One script runs the full gate — **lint + typecheck + production build**. It must exit 0
+before any commit:
+
+```bash
+bash ralph/check.sh
+```
+
+## Sitemap
+
+| Route | What it is |
+|---|---|
+| `/` | Landing: hero → feature grid → live `useToggle` proof → hooks index → support teaser → CTA |
+| `/docs` | Docs index: intro, install, quick example, hook cards grouped by category |
+| `/docs/[slug]` | One page per hook (11, statically generated) — demo, usage, API, source, prev/next |
+| `/support` | Sponsor / star / contribute cards (payment links are placeholders) |
+| `*` (not found) | Branded 404 |
+
+## Project structure
+
+```
+app/ Routes & route-level files ONLY (no shared UI)
+ page.tsx Landing
+ docs/layout.tsx Sidebar shell for all docs pages
+ docs/page.tsx Docs index
+ docs/[slug]/page.tsx Thin routing wrapper → renders <HookPage> from registry data
+ support/page.tsx Support placeholder
+ layout.tsx Root metadata, fonts, Header + Footer
+ opengraph-image.tsx Brand OG image (next/og)
+ docs/[slug]/opengraph-image.tsx Per-hook OG card
+ apple-icon.tsx sitemap.ts robots.ts not-found.tsx globals.css
+
+components/ Shared UI, flat by default (kebab-case files, PascalCase exports)
+ hook-page.tsx THE data-driven template every hook page renders through
+ hook-demo.tsx code-block.tsx api-table.tsx on-this-page.tsx
+ header.tsx footer.tsx sidebar.tsx wordmark.tsx icons.tsx search-palette.tsx
+ ...landing sections (features-section, live-proof-section, hooks-index-section, ...)
+ demos/ One demo module per hook + shared demo primitives (ui.tsx)
+
+lib/ Framework-agnostic data & utilities
+ hooks-registry.ts SINGLE SOURCE OF TRUTH — the hook list (sidebar/pages/search/sitemap derive from it)
+ hook-docs.ts Per-hook page content (demo import, usage snippet, parameters, returns, types)
+ hook-sources.ts Vendored implementation snapshots (kept in sync with the installed hookli version)
+ web-apis.tsx term → MDN link chips for hook descriptions
+ shiki.ts og.tsx site.ts
+
+docs/DESIGN.md Design source of truth (brand tokens, IA, page anatomy)
+ralph/ Ralph build-loop backlog, progress log, gate script, operating manual
+```
+
+## Adding a new hook page
+
+Because everything is data-driven, a new hook needs **no new layout code** — only data
+and one demo component:
+
+1. **Registry** — add an entry to `HOOKS` in `lib/hooks-registry.ts`
+ (`slug`, `name`, `description`, `category`, `signature`). Sidebar, search, sitemap,
+ OG images, `generateStaticParams`, and the "N hooks" landing count all pick it up.
+2. **Page content** — add a matching entry to `HOOK_DOCS` in `lib/hook-docs.ts`
+ (the demo component, usage snippet, `parameters`, `returns`, and any `types`).
+ A slug with no entry falls back to a signature-only page automatically.
+3. **Demo** — create `components/demos/use-<name>-demo.tsx` (`"use client"`), importing the
+ hook from **`hookli`**. Gate any `window`/`localStorage`/`document` access behind a
+ `mounted` flag so `next build` prerender stays green. Reuse the primitives in
+ `components/demos/ui.tsx`.
+4. **Source snapshot** — add the hook's implementation to `lib/hook-sources.ts` (kept in
+ sync with the installed `hookli` version) so the page's **Hook** section shows real code.
+
+`app/docs/[slug]/page.tsx` and `components/hook-page.tsx` need no changes.
+
+## Conventions & brand
+
+Engineering conventions (kebab-case files, named exports, token-only styling, import order,
+barrels) are documented in [`AGENTS.md`](./AGENTS.md). The visual system (brand v3: dark-first
+Prussian/Scooter palette, tonal depth scale, typography) lives in
+[`docs/DESIGN.md`](./docs/DESIGN.md) and is implemented purely through the `@theme` tokens in
+`app/globals.css` — components reference tokens (`bg-ground`, `text-accent`), never raw hex.
+
+## How this site was built
+
+hookli-docs was built by the **Ralph loop** — an autonomous, one-task-per-iteration build
+loop. The backlog is `ralph/prd.json`, the durable log is `ralph/progress.txt`, and the
+operating manual is `ralph/prompt.md`. Every iteration ends only after `ralph/check.sh` is
+green.
diff --git a/apps/docs/app/apple-icon.tsx b/apps/docs/app/apple-icon.tsx
new file mode 100644
index 0000000..7f79ca4
--- /dev/null
+++ b/apps/docs/app/apple-icon.tsx
@@ -0,0 +1,36 @@
+import { ImageResponse } from "next/og";
+import { OG_COLORS } from "@/lib/og";
+
+/* Apple-touch-icon variant of public/hookli-icon.svg: the hook mark on a
+ full-bleed ground tile; iOS applies its own corner mask. */
+
+export const size = { width: 180, height: 180 };
+export const contentType = "image/png";
+
+export default function AppleIcon() {
+ return new ImageResponse(
+ (
+ <div
+ style={{
+ width: "100%",
+ height: "100%",
+ display: "flex",
+ alignItems: "center",
+ justifyContent: "center",
+ backgroundColor: OG_COLORS.ground,
+ }}
+ >
+ <svg width={80} height={102} viewBox="-13 -3 110 140" fill="none">
+ <path
+ d="M84 10 V82 A42 42 0 1 1 0 82 V58"
+ stroke={OG_COLORS.accent}
+ strokeWidth={26}
+ strokeLinecap="round"
+ />
+ <circle cx={42} cy={82} r={15} fill={OG_COLORS.fg} />
+ </svg>
+ </div>
+ ),
+ size,
+ );
+}
diff --git a/apps/docs/app/docs/[slug]/opengraph-image.tsx b/apps/docs/app/docs/[slug]/opengraph-image.tsx
new file mode 100644
index 0000000..e357035
--- /dev/null
+++ b/apps/docs/app/docs/[slug]/opengraph-image.tsx
@@ -0,0 +1,72 @@
+import { ImageResponse } from "next/og";
+import { notFound } from "next/navigation";
+import { CATEGORY_LABELS, getHook } from "@/lib/hooks-registry";
+import { OG_COLORS, OG_SIZE, OgWordmark, loadOgFonts } from "@/lib/og";
+
+export const alt = "hookli hook documentation";
+export const size = OG_SIZE;
+export const contentType = "image/png";
+
+export default async function Image({
+ params,
+}: {
+ params: Promise<{ slug: string }>;
+}) {
+ const { slug } = await params;
+ const hook = getHook(slug);
+ if (!hook) notFound();
+
+ return new ImageResponse(
+ (
+ <div
+ style={{
+ width: "100%",
+ height: "100%",
+ display: "flex",
+ flexDirection: "column",
+ justifyContent: "space-between",
+ padding: 72,
+ backgroundColor: OG_COLORS.ground,
+ fontFamily: "Plus Jakarta Sans",
+ }}
+ >
+ <OgWordmark fontSize={36} withMark />
+ <div style={{ display: "flex", flexDirection: "column", gap: 24 }}>
+ <div
+ style={{
+ fontSize: 26,
+ letterSpacing: 4,
+ textTransform: "uppercase",
+ color: OG_COLORS.gray,
+ }}
+ >
+ {CATEGORY_LABELS[hook.category]}
+ </div>
+ <div
+ style={{
+ fontFamily: "JetBrains Mono",
+ fontSize: 92,
+ fontWeight: 700,
+ color: OG_COLORS.accent,
+ }}
+ >
+ {hook.name}
+ </div>
+ <div style={{ fontSize: 34, color: OG_COLORS.gray }}>
+ {hook.description}
+ </div>
+ </div>
+ <div
+ style={{
+ fontFamily: "JetBrains Mono",
+ fontSize: 26,
+ color: OG_COLORS.slate,
+ }}
+ >
+ npm i hookli
+ </div>
+ </div>
+ ),
+ { ...size, fonts: await loadOgFonts() },
+ );
+}
diff --git a/apps/docs/app/docs/[slug]/page.tsx b/apps/docs/app/docs/[slug]/page.tsx
new file mode 100644
index 0000000..daf24b2
--- /dev/null
+++ b/apps/docs/app/docs/[slug]/page.tsx
@@ -0,0 +1,43 @@
+import type { Metadata } from "next";
+import { notFound } from "next/navigation";
+import { HookPage } from "@/components/hook-page";
+import { HOOKS, getHook } from "@/lib/hooks-registry";
+
+/* Thin route wrapper — all layout lives in the single data-driven HookPage
+ template (T16). This file owns only routing concerns (params, static params,
+ metadata). Adding a hook needs no changes here. */
+
+export function generateStaticParams() {
+ return HOOKS.map(({ slug }) => ({ slug }));
+}
+
+export async function generateMetadata({
+ params,
+}: {
+ params: Promise<{ slug: string }>;
+}): Promise<Metadata> {
+ const { slug } = await params;
+ const hook = getHook(slug);
+ if (!hook) return {};
+ return {
+ title: hook.name,
+ description: hook.description,
+ openGraph: {
+ title: hook.name,
+ description: hook.description,
+ url: `/docs/${slug}`,
+ },
+ };
+}
+
+export default async function HookRoute({
+ params,
+}: {
+ params: Promise<{ slug: string }>;
+}) {
+ const { slug } = await params;
+ const hook = getHook(slug);
+ if (!hook) notFound();
+
+ return <HookPage hook={hook} />;
+}
diff --git a/apps/docs/app/docs/layout.tsx b/apps/docs/app/docs/layout.tsx
new file mode 100644
index 0000000..f459cb0
--- /dev/null
+++ b/apps/docs/app/docs/layout.tsx
@@ -0,0 +1,17 @@
+import { MobileDocsNav, Sidebar } from "@/components/sidebar";
+
+export default function DocsLayout({
+ children,
+}: Readonly<{
+ children: React.ReactNode;
+}>) {
+ return (
+ <div className="mx-auto flex w-full max-w-7xl flex-1 flex-col px-4 sm:px-6">
+ <MobileDocsNav />
+ <div className="flex flex-1">
+ <Sidebar />
+ <main className="min-w-0 flex-1 py-10 md:pl-10">{children}</main>
+ </div>
+ </div>
+ );
+}
diff --git a/apps/docs/app/docs/page.tsx b/apps/docs/app/docs/page.tsx
new file mode 100644
index 0000000..f0c3c26
--- /dev/null
+++ b/apps/docs/app/docs/page.tsx
@@ -0,0 +1,97 @@
+import type { Metadata } from "next";
+import { CodeBlock } from "@/components/code-block";
+import { HookCard } from "@/components/hook-card";
+import { InstallCommand } from "@/components/install-command";
+import {
+ CATEGORY_LABELS,
+ CATEGORY_ORDER,
+ HOOKS,
+ hooksByCategory,
+} from "@/lib/hooks-registry";
+import { TAGLINE } from "@/lib/site";
+
+export const metadata: Metadata = {
+ title: "Docs",
+ description: `${TAGLINE} Documentation for all ${HOOKS.length} hooks.`,
+ openGraph: {
+ title: "Docs",
+ description: `${TAGLINE} Documentation for all ${HOOKS.length} hooks.`,
+ url: "/docs",
+ },
+};
+
+const QUICK_EXAMPLE = `
+import { useToggle } from "hookli";
+
+function Details() {
+ const [open, toggle] = useToggle(false);
+
+ return (
+ <section>
+ <button onClick={toggle}>{open ? "Hide" : "Show"} details</button>
+ {open && <p>Rendered only while open.</p>}
+ </section>
+ );
+}
+`;
+
+export default function DocsIndexPage() {
+ return (
+ <div className="flex flex-col">
+ <h1 className="text-3xl sm:text-4xl">Documentation</h1>
+ <p className="mt-4 max-w-2xl leading-relaxed text-gray-body">
+ hookli is {HOOKS.length} React hooks for the state, DOM, and data
+ chores every app repeats — typed end to end, SSR-safe, and free of
+ dependencies. Every hook on this site runs live on its page, so you
+ can try it before you install it.
+ </p>
+
+ <h2 className="mt-12 text-2xl">Quick start</h2>
+ <ol className="mt-4 grid gap-3 sm:grid-cols-3">
+ <li className="surface flex flex-col rounded-xl p-5">
+ <span className="flex size-7 items-center justify-center rounded-full bg-accent/10 text-sm font-semibold text-accent ring-1 ring-inset ring-accent/20">1</span>
+ <h3 className="mt-4 text-base font-semibold">Install</h3>
+ <p className="mt-1 text-sm leading-relaxed text-gray-body">Add hookli to your React app.</p>
+ <InstallCommand className="mt-3" />
+ </li>
+ <li className="surface flex flex-col rounded-xl p-5">
+ <span className="flex size-7 items-center justify-center rounded-full bg-accent/10 text-sm font-semibold text-accent ring-1 ring-inset ring-accent/20">2</span>
+ <h3 className="mt-4 text-base font-semibold">Import</h3>
+ <p className="mt-1 text-sm leading-relaxed text-gray-body">Pull in exactly the hook you need.</p>
+ <code className="surface mt-3 block overflow-x-auto rounded-lg px-3 py-2 font-mono text-xs">
+ <span className="text-accent">import</span> {"{ useToggle }"} <span className="text-accent">from</span> <span className="text-gray-body">"hookli"</span>
+ </code>
+ </li>
+ <li className="surface flex flex-col rounded-xl p-5">
+ <span className="flex size-7 items-center justify-center rounded-full bg-accent/10 text-sm font-semibold text-accent ring-1 ring-inset ring-accent/20">3</span>
+ <h3 className="mt-4 text-base font-semibold">Use it</h3>
+ <p className="mt-1 text-sm leading-relaxed text-gray-body">Call it in a component — no providers, no config.</p>
+ </li>
+ </ol>
+
+ <h2 className="mt-12 text-2xl">Quick example</h2>
+ <p className="mt-3 max-w-2xl leading-relaxed text-gray-body">
+ Import a hook and use it — no providers, no setup.
+ </p>
+ <CodeBlock
+ code={QUICK_EXAMPLE}
+ title="details.tsx"
+ className="mt-4 max-w-2xl"
+ />
+
+ <h2 className="mt-12 text-2xl">Hooks</h2>
+ {CATEGORY_ORDER.map((category) => (
+ <section key={category} className="mt-8" aria-label={CATEGORY_LABELS[category]}>
+ <h3 className="text-xs font-semibold uppercase tracking-wider text-slate-syntax">
+ {CATEGORY_LABELS[category]}
+ </h3>
+ <div className="mt-3 grid gap-3 sm:grid-cols-2">
+ {hooksByCategory(category).map((hook) => (
+ <HookCard key={hook.slug} hook={hook} />
+ ))}
+ </div>
+ </section>
+ ))}
+ </div>
+ );
+}
diff --git a/apps/docs/app/globals.css b/apps/docs/app/globals.css
new file mode 100644
index 0000000..cf95454
--- /dev/null
+++ b/apps/docs/app/globals.css
@@ -0,0 +1,261 @@
+@import "tailwindcss";
+
+/* Brand v3 tokens — docs/DESIGN.md §1. Solid colors only, dark-first, no light theme.
+ Tonal depth (T19): #003748 is a brand MID-tone, so it's the SURFACE, not the page.
+ The page ground is a much darker near-black blue in the same hue family, letting
+ cards/panels visibly lift; a third step lifts nested/hover surfaces above the card. */
+@theme {
+ /* Near-black neutral base with a faint teal undertone — surfaces are defined by
+ subtle elevation + hairline borders, NOT by saturated fills. Prussian (#003748)
+ and Scooter (#30c5ca) are reserved as ACCENTS, not backgrounds. */
+ --color-ground: #0a1315; /* page */
+ --color-ground-raised: #101d21; /* cards / panels — a subtle lift off the page */
+ --color-ground-overlay: #17282e; /* hover / nested / code-line highlight */
+ --color-brand: #003748; /* Prussian — for select brand moments only */
+ --color-accent: #30c5ca; /* Scooter — links, focus, CTA, active state */
+ --color-slate-syntax: #4a7a8c; /* hairline borders (used at /40) + code comments */
+ --color-gray-body: #94b0b8; /* secondary text */
+ --color-fg: #ffffff;
+}
+
+/* Referenced at runtime from the next/font variables on <html>. */
+@theme inline {
+ --font-sans: var(--font-geist), ui-sans-serif, system-ui, -apple-system,
+ "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+ --font-mono: var(--font-jetbrains-mono), ui-monospace, "SF Mono", Menlo,
+ Consolas, monospace;
+}
+
+:root {
+ color-scheme: dark;
+
+ /* Shiki css-variables theme → brand tokens (docs/DESIGN.md §1, §5 CodeBlock).
+ Background stays transparent — the CodeBlock frame owns the surface. */
+ --shiki-foreground: var(--color-fg);
+ --shiki-background: transparent;
+ --shiki-token-keyword: var(--color-accent);
+ --shiki-token-function: var(--color-fg);
+ --shiki-token-constant: var(--color-fg);
+ --shiki-token-string: var(--color-gray-body);
+ --shiki-token-string-expression: var(--color-gray-body);
+ --shiki-token-parameter: var(--color-gray-body);
+ --shiki-token-punctuation: var(--color-gray-body);
+ --shiki-token-comment: var(--color-slate-syntax);
+ --shiki-token-link: var(--color-accent);
+}
+
+body {
+ background-color: var(--color-ground);
+ color: var(--color-fg);
+}
+
+@layer base {
+ h1,
+ h2,
+ h3,
+ h4,
+ h5,
+ h6 {
+ font-family: var(--font-sans);
+ font-weight: 600;
+ letter-spacing: -0.021em;
+ text-wrap: balance;
+ }
+
+ /* Larger headings get tighter tracking — the premium display-type look. */
+ h1 {
+ letter-spacing: -0.035em;
+ }
+ h2 {
+ letter-spacing: -0.028em;
+ }
+
+ body {
+ text-rendering: optimizeLegibility;
+ font-feature-settings: "cv01", "ss01";
+ }
+
+ :focus-visible {
+ outline: 2px solid var(--color-accent);
+ outline-offset: 2px;
+ }
+
+ ::selection {
+ background-color: color-mix(in srgb, var(--color-accent) 25%, transparent);
+ }
+
+ code {
+ font-family: var(--font-mono);
+ }
+}
+
+/* ── Elevation system ─────────────────────────────────────────────────────
+ Near-black-on-near-black means depth can't come from a drop shadow alone —
+ it comes from a hairline border, a 1px top highlight (light catching the top
+ edge), and a soft ambient shadow. `.surface` is the static card treatment;
+ `.surface-lift` adds a 150–200ms ease-out hover raise for interactive cards. */
+@layer components {
+ .surface {
+ background-color: var(--color-ground-raised);
+ border: 1px solid color-mix(in srgb, var(--color-slate-syntax) 26%, transparent);
+ box-shadow:
+ inset 0 1px 0 0 color-mix(in srgb, var(--color-fg) 6%, transparent),
+ 0 1px 2px 0 color-mix(in srgb, black 40%, transparent),
+ 0 12px 28px -18px color-mix(in srgb, black 70%, transparent);
+ }
+
+ .surface-lift {
+ transition:
+ transform 180ms ease-out,
+ border-color 180ms ease-out,
+ box-shadow 180ms ease-out;
+ }
+
+ .surface-lift:hover {
+ transform: translateY(-3px);
+ border-color: color-mix(in srgb, var(--color-accent) 45%, transparent);
+ box-shadow:
+ inset 0 1px 0 0 color-mix(in srgb, var(--color-fg) 9%, transparent),
+ 0 2px 4px 0 color-mix(in srgb, black 40%, transparent),
+ 0 20px 44px -20px color-mix(in srgb, black 85%, transparent);
+ }
+}
+
+/* ── Load reveal ──────────────────────────────────────────────────────────
+ A subtle fade-and-rise for hero + landing sections. `both` fill holds the
+ start state before the (optional) delay and the end state after, so there's
+ no flash. The reduced-motion guard zeroes duration AND delay, snapping
+ straight to the visible end state. */
+@keyframes reveal {
+ from {
+ opacity: 0;
+ transform: translateY(10px);
+ }
+ to {
+ opacity: 1;
+ transform: translateY(0);
+ }
+}
+
+.reveal {
+ animation: reveal 600ms cubic-bezier(0.22, 1, 0.36, 1) both;
+}
+
+.reveal-d1 {
+ animation-delay: 80ms;
+}
+.reveal-d2 {
+ animation-delay: 160ms;
+}
+.reveal-d3 {
+ animation-delay: 240ms;
+}
+.reveal-d4 {
+ animation-delay: 320ms;
+}
+
+/* Copy-button feedback: the check icon pops in when the copy succeeds
+ (components/copy-button.tsx). Neutralised under reduced-motion. */
+@keyframes copy-pop {
+ from {
+ transform: scale(0.4);
+ opacity: 0;
+ }
+ to {
+ transform: scale(1);
+ opacity: 1;
+ }
+}
+
+.copy-pop {
+ animation: copy-pop 200ms cubic-bezier(0.34, 1.56, 0.64, 1);
+}
+
+/* Subtle inner shadow at the top of a code pane, separating it from the
+ filename caption above (premium code-block chrome). */
+.code-pane {
+ box-shadow: inset 0 10px 12px -12px color-mix(in srgb, black 85%, transparent);
+}
+
+/* Hero backdrop: a faint radial glow behind the mark + a hairline grid, both
+ token-derived and masked so they fade out toward the edges. Decorative only
+ (aria-hidden on the element). */
+.hero-glow {
+ background: radial-gradient(
+ 60% 55% at 50% 38%,
+ color-mix(in srgb, var(--color-accent) 14%, transparent),
+ transparent 70%
+ );
+}
+
+.hero-grid {
+ background-image:
+ linear-gradient(
+ to right,
+ color-mix(in srgb, var(--color-slate-syntax) 12%, transparent) 1px,
+ transparent 1px
+ ),
+ linear-gradient(
+ to bottom,
+ color-mix(in srgb, var(--color-slate-syntax) 12%, transparent) 1px,
+ transparent 1px
+ );
+ background-size: 56px 56px;
+ mask-image: radial-gradient(60% 60% at 50% 40%, black, transparent 75%);
+}
+
+/* Usage-snippet gutter + highlighted hook-call line (T16 usehooks-ts anatomy).
+ `display: grid` on <code> drops shiki's inter-line "\n" text nodes so each
+ .line is a full-width row — line numbers and the call-line tint align. */
+.line-numbers code {
+ display: grid;
+ counter-reset: line;
+}
+
+.line-numbers .line {
+ counter-increment: line;
+}
+
+.line-numbers .line::before {
+ content: counter(line);
+ display: inline-block;
+ width: 1rem;
+ margin-right: 1.25rem;
+ text-align: right;
+ color: var(--color-slate-syntax);
+ user-select: none;
+}
+
+.highlighted-line {
+ background-color: color-mix(in srgb, var(--color-accent) 12%, transparent);
+ box-shadow: inset 2px 0 0 0 var(--color-accent);
+}
+
+/* Floating donate button (components/donate-button.tsx): a gentle idle bob so
+ the support CTA quietly draws the eye. Neutralised by the reduced-motion
+ guard below. */
+@keyframes donate-bob {
+ 0%,
+ 100% {
+ transform: translateY(0);
+ }
+ 50% {
+ transform: translateY(-4px);
+ }
+}
+
+.donate-float {
+ animation: donate-bob 3.5s ease-in-out infinite;
+}
+
+@media (prefers-reduced-motion: reduce) {
+ *,
+ *::before,
+ *::after {
+ animation-duration: 0.01ms !important;
+ animation-delay: 0ms !important;
+ animation-iteration-count: 1 !important;
+ transition-duration: 0.01ms !important;
+ scroll-behavior: auto !important;
+ }
+}
diff --git a/apps/docs/app/layout.tsx b/apps/docs/app/layout.tsx
new file mode 100644
index 0000000..7379cef
--- /dev/null
+++ b/apps/docs/app/layout.tsx
@@ -0,0 +1,70 @@
+import type { Metadata, Viewport } from "next";
+import { Geist, JetBrains_Mono } from "next/font/google";
+import "./globals.css";
+import { Header } from "@/components/header";
+import { Footer } from "@/components/footer";
+import { DonateButton } from "@/components/donate-button";
+import { SITE_URL, TAGLINE } from "@/lib/site";
+
+const jetbrainsMono = JetBrains_Mono({
+ variable: "--font-jetbrains-mono",
+ subsets: ["latin"],
+});
+
+/* Premium UI/body face: Geist — Vercel's typeface, purpose-built for developer
+ products. Professional and precise (replaces the friendlier Plus Jakarta).
+ Code stays on JetBrains Mono. */
+const geist = Geist({
+ variable: "--font-geist",
+ subsets: ["latin"],
+ weight: ["400", "500", "600", "700"],
+});
+
+export const metadata: Metadata = {
+ metadataBase: new URL(SITE_URL),
+ title: {
+ template: "hookli — %s",
+ default: "hookli — simple React hooks",
+ },
+ description: TAGLINE,
+ openGraph: {
+ type: "website",
+ siteName: "hookli",
+ url: "/",
+ title: {
+ template: "hookli — %s",
+ default: "hookli — simple React hooks",
+ },
+ description: TAGLINE,
+ },
+ twitter: {
+ card: "summary_large_image",
+ },
+ icons: {
+ icon: "/hookli-icon.svg",
+ },
+};
+
+export const viewport: Viewport = {
+ // Mobile browser chrome — matches --color-ground (globals.css). A theme-color
+ // meta tag requires a literal hex; keep this in sync with the ground token.
+ themeColor: "#04191f",
+ colorScheme: "dark",
+};
+
+export default function RootLayout({
+ children,
+}: Readonly<{
+ children: React.ReactNode;
+}>) {
+ return (
+ <html lang="en" className={`${geist.variable} ${jetbrainsMono.variable} h-full antialiased`}>
+ <body className="flex min-h-full flex-col bg-ground font-sans text-fg">
+ <Header />
+ {children}
+ <Footer />
+ <DonateButton />
+ </body>
+ </html>
+ );
+}
diff --git a/apps/docs/app/not-found.tsx b/apps/docs/app/not-found.tsx
new file mode 100644
index 0000000..bf2475b
--- /dev/null
+++ b/apps/docs/app/not-found.tsx
@@ -0,0 +1,40 @@
+import type { Metadata } from "next";
+import Link from "next/link";
+import { ArrowRightIcon } from "@/components/icons";
+
+export const metadata: Metadata = {
+ title: "Page not found",
+ description: "This page doesn't exist. The hooks all do.",
+};
+
+export default function NotFound() {
+ return (
+ <main className="flex flex-1 flex-col items-center justify-center px-4 py-24 text-center sm:px-6">
+ <p className="text-xs font-semibold uppercase tracking-wider text-gray-body">
+ 404 — page not found
+ </p>
+ <h1 className="mt-4 text-4xl sm:text-5xl">
+ not found<span className="text-accent">.</span>
+ </h1>
+ <p className="mt-6 w-full max-w-md text-lg text-gray-body">
+ Nothing renders at this URL. The hooks all exist, though — and every
+ one runs live in the docs.
+ </p>
+ <div className="mt-10 flex flex-col items-center gap-4 sm:flex-row">
+ <Link
+ href="/docs"
+ className="flex min-h-11 items-center gap-2 rounded-md bg-accent px-5 text-sm font-semibold text-ground transition-opacity duration-200 hover:opacity-90"
+ >
+ Browse the docs
+ <ArrowRightIcon className="size-4" />
+ </Link>
+ <Link
+ href="/"
+ className="flex min-h-11 items-center gap-2 rounded-md px-5 text-sm text-gray-body transition-colors duration-200 hover:text-fg"
+ >
+ Back home
+ </Link>
+ </div>
+ </main>
+ );
+}
diff --git a/apps/docs/app/opengraph-image.tsx b/apps/docs/app/opengraph-image.tsx
new file mode 100644
index 0000000..74bde91
--- /dev/null
+++ b/apps/docs/app/opengraph-image.tsx
@@ -0,0 +1,42 @@
+import { ImageResponse } from "next/og";
+import { OG_COLORS, OG_SIZE, OgWordmark, loadOgFonts } from "@/lib/og";
+import { TAGLINE } from "@/lib/site";
+
+export const alt = "hookli. — Simple React hooks. Typed. SSR-safe. Zero dependencies.";
+export const size = OG_SIZE;
+export const contentType = "image/png";
+
+export default async function Image() {
+ return new ImageResponse(
+ (
+ <div
+ style={{
+ width: "100%",
+ height: "100%",
+ display: "flex",
+ flexDirection: "column",
+ alignItems: "center",
+ justifyContent: "center",
+ gap: 44,
+ backgroundColor: OG_COLORS.ground,
+ fontFamily: "Plus Jakarta Sans",
+ }}
+ >
+ <OgWordmark fontSize={112} withMark />
+ <div style={{ fontSize: 34, color: OG_COLORS.gray }}>{TAGLINE}</div>
+ <div
+ style={{
+ position: "absolute",
+ bottom: 48,
+ fontFamily: "JetBrains Mono",
+ fontSize: 26,
+ color: OG_COLORS.slate,
+ }}
+ >
+ npm i hookli
+ </div>
+ </div>
+ ),
+ { ...size, fonts: await loadOgFonts() },
+ );
+}
diff --git a/apps/docs/app/page.tsx b/apps/docs/app/page.tsx
new file mode 100644
index 0000000..7b0e4b6
--- /dev/null
+++ b/apps/docs/app/page.tsx
@@ -0,0 +1,72 @@
+import Link from "next/link";
+import { HookMark, Wordmark } from "@/components/wordmark";
+import { InstallCommand } from "@/components/install-command";
+import { ArrowRightIcon, GitHubIcon } from "@/components/icons";
+import { FeaturesSection } from "@/components/features-section";
+import { LiveProofSection } from "@/components/live-proof-section";
+import { HooksIndexSection } from "@/components/hooks-index-section";
+import { SupportSection } from "@/components/support-section";
+import { BottomCtaSection } from "@/components/bottom-cta-section";
+import { HOOKS } from "@/lib/hooks-registry";
+import { GITHUB_URL, TAGLINE } from "@/lib/site";
+
+const HERO_FACTS = [
+ `${HOOKS.length} typed hooks`,
+ "Zero dependencies",
+ "SSR-safe",
+ "ESM + CJS",
+];
+
+export default function Home() {
+ return (
+ <main className="flex flex-1 flex-col">
+ <section className="relative overflow-hidden border-b border-slate-syntax/40">
+ <div aria-hidden="true" className="pointer-events-none absolute inset-0 hero-grid" />
+ <div aria-hidden="true" className="pointer-events-none absolute inset-0 hero-glow" />
+ <div className="relative mx-auto flex max-w-3xl flex-col items-center px-4 py-20 text-center sm:px-6 sm:py-28">
+ <p className="reveal inline-flex items-center gap-2 rounded-full border border-slate-syntax/40 bg-ground-raised/60 px-3 py-1 text-xs font-medium text-gray-body backdrop-blur">
+ <span aria-hidden="true" className="size-1.5 rounded-full bg-accent" />
+ Zero-dependency React hooks
+ </p>
+ <h1 className="reveal reveal-d1 mt-8 flex flex-col items-center gap-6">
+ <HookMark className="h-16 w-auto sm:h-20" />
+ <Wordmark size="xl" />
+ </h1>
+ <p className="reveal reveal-d2 mt-6 w-full max-w-md text-lg text-gray-body">{TAGLINE}</p>
+ <InstallCommand className="reveal reveal-d3 mt-9" />
+ <div className="reveal reveal-d3 mt-6 flex flex-col items-center gap-3 sm:flex-row sm:gap-4">
+ <Link
+ href="/docs"
+ className="flex min-h-11 items-center gap-2 rounded-md bg-accent px-5 text-sm font-semibold text-ground shadow-lg shadow-accent/20 transition-[opacity,box-shadow] duration-200 ease-out hover:opacity-90 hover:shadow-accent/30"
+ >
+ Explore the docs
+ <ArrowRightIcon className="size-4" />
+ </Link>
+ <a
+ href={GITHUB_URL}
+ target="_blank"
+ rel="noopener noreferrer"
+ className="flex min-h-11 items-center gap-2 rounded-md px-5 text-sm text-gray-body transition-colors duration-200 hover:text-fg"
+ >
+ <GitHubIcon className="size-4" />
+ Star on GitHub
+ </a>
+ </div>
+ <ul className="reveal reveal-d4 mt-12 flex flex-wrap items-center justify-center gap-x-5 gap-y-2 text-xs text-slate-syntax">
+ {HERO_FACTS.map((fact) => (
+ <li key={fact} className="flex items-center gap-2">
+ <span aria-hidden="true" className="size-1 rounded-full bg-slate-syntax" />
+ {fact}
+ </li>
+ ))}
+ </ul>
+ </div>
+ </section>
+ <FeaturesSection />
+ <LiveProofSection />
+ <HooksIndexSection />
+ <SupportSection />
+ <BottomCtaSection />
+ </main>
+ );
+}
diff --git a/apps/docs/app/robots.ts b/apps/docs/app/robots.ts
new file mode 100644
index 0000000..77a1b9b
--- /dev/null
+++ b/apps/docs/app/robots.ts
@@ -0,0 +1,9 @@
+import type { MetadataRoute } from "next";
+import { SITE_URL } from "@/lib/site";
+
+export default function robots(): MetadataRoute.Robots {
+ return {
+ rules: { userAgent: "*", allow: "/" },
+ sitemap: `${SITE_URL}/sitemap.xml`,
+ };
+}
diff --git a/apps/docs/app/sitemap.ts b/apps/docs/app/sitemap.ts
new file mode 100644
index 0000000..c64f69f
--- /dev/null
+++ b/apps/docs/app/sitemap.ts
@@ -0,0 +1,28 @@
+import type { MetadataRoute } from "next";
+import { HOOKS } from "@/lib/hooks-registry";
+import { SITE_URL } from "@/lib/site";
+
+export default function sitemap(): MetadataRoute.Sitemap {
+ const lastModified = new Date();
+ return [
+ { url: SITE_URL, lastModified, changeFrequency: "monthly", priority: 1 },
+ {
+ url: `${SITE_URL}/docs`,
+ lastModified,
+ changeFrequency: "monthly",
+ priority: 0.9,
+ },
+ ...HOOKS.map(({ slug }) => ({
+ url: `${SITE_URL}/docs/${slug}`,
+ lastModified,
+ changeFrequency: "monthly" as const,
+ priority: 0.8,
+ })),
+ {
+ url: `${SITE_URL}/support`,
+ lastModified,
+ changeFrequency: "yearly",
+ priority: 0.4,
+ },
+ ];
+}
diff --git a/apps/docs/app/support/page.tsx b/apps/docs/app/support/page.tsx
new file mode 100644
index 0000000..2b68059
--- /dev/null
+++ b/apps/docs/app/support/page.tsx
@@ -0,0 +1,156 @@
+import type { Metadata } from "next";
+import {
+ ArrowRightIcon,
+ GitHubIcon,
+ GitHubSponsorsIcon,
+ GitPullRequestIcon,
+ HeartIcon,
+ KofiIcon,
+ StarIcon,
+} from "@/components/icons";
+import { GITHUB_URL, KOFI_URL, SPONSOR_URL } from "@/lib/site";
+
+export const metadata: Metadata = {
+ title: "Support",
+ description:
+ "Support hookli — star the repo, contribute a hook, or sponsor the project (coming soon).",
+ openGraph: {
+ title: "Support",
+ description:
+ "Support hookli — star the repo, contribute a hook, or sponsor the project (coming soon).",
+ url: "/support",
+ },
+};
+
+const CONTRIBUTE_WAYS = [
+ {
+ title: "Report a bug",
+ body: "Found a hook misbehaving? A minimal repro in an issue is the most valuable thing you can send.",
+ label: "Open an issue",
+ href: `${GITHUB_URL}/issues`,
+ },
+ {
+ title: "Improve the docs",
+ body: "Typos, unclear copy, a demo that could prove more — small docs PRs are the friendliest way in.",
+ label: "Browse pull requests",
+ href: `${GITHUB_URL}/pulls`,
+ },
+ {
+ title: "Add a hook",
+ body: "Propose the hook you keep rewriting in every project. Open an issue first so we can agree on the API before you build.",
+ label: "Start a proposal",
+ href: `${GITHUB_URL}/issues`,
+ },
+];
+
+export default function SupportPage() {
+ return (
+ <main className="mx-auto w-full max-w-3xl flex-1 px-4 py-16 sm:px-6">
+ <h1 className="text-3xl sm:text-4xl">Support hookli</h1>
+ <p className="mt-4 max-w-2xl leading-relaxed text-gray-body">
+ hookli is free, open source, and ISC-licensed — built and maintained in
+ the open. If it saved you from rewriting another debounce hook, here
+ are three ways to give back.
+ </p>
+
+ <section
+ id="star"
+ aria-labelledby="star-heading"
+ className="surface mt-12 scroll-mt-20 rounded-xl p-6 sm:p-8"
+ >
+ <span className="flex size-11 items-center justify-center rounded-lg bg-accent/10 text-accent ring-1 ring-inset ring-accent/20">
+ <StarIcon className="size-6" />
+ </span>
+ <h2 id="star-heading" className="mt-4 text-xl">
+ Star the repo
+ </h2>
+ <p className="mt-2 max-w-xl text-sm leading-relaxed text-gray-body">
+ Free, takes two seconds, and genuinely matters: stars are how the
+ next contributor finds the project.
+ </p>
+ <a
+ href={GITHUB_URL}
+ target="_blank"
+ rel="noopener noreferrer"
+ className="mt-5 flex min-h-11 w-fit items-center gap-2 rounded-md bg-accent px-5 text-sm font-semibold text-ground transition-opacity duration-200 hover:opacity-90"
+ >
+ <GitHubIcon className="size-4" />
+ Star on GitHub
+ </a>
+ </section>
+
+ <section
+ id="contribute"
+ aria-labelledby="contribute-heading"
+ className="surface mt-8 scroll-mt-20 rounded-xl p-6 sm:p-8"
+ >
+ <span className="flex size-11 items-center justify-center rounded-lg bg-accent/10 text-accent ring-1 ring-inset ring-accent/20">
+ <GitPullRequestIcon className="size-6" />
+ </span>
+ <h2 id="contribute-heading" className="mt-4 text-xl">
+ Contribute
+ </h2>
+ <p className="mt-2 max-w-xl text-sm leading-relaxed text-gray-body">
+ Every hook ships typed, SSR-safe, and dependency-free — contributions
+ are held to the same bar, and reviewed quickly.
+ </p>
+ <ul className="mt-6 flex flex-col gap-5">
+ {CONTRIBUTE_WAYS.map((way) => (
+ <li key={way.title}>
+ <h3 className="text-base font-semibold">{way.title}</h3>
+ <p className="mt-1 max-w-xl text-sm leading-relaxed text-gray-body">
+ {way.body}
+ </p>
+ <a
+ href={way.href}
+ target="_blank"
+ rel="noopener noreferrer"
+ className="mt-1 flex min-h-11 w-fit items-center gap-2 text-sm text-accent transition-opacity duration-200 hover:opacity-80"
+ >
+ {way.label}
+ <ArrowRightIcon className="size-4" />
+ </a>
+ </li>
+ ))}
+ </ul>
+ </section>
+
+ <section
+ id="sponsor"
+ aria-labelledby="sponsor-heading"
+ className="surface mt-8 scroll-mt-20 rounded-xl p-6 sm:p-8"
+ >
+ <span className="flex size-11 items-center justify-center rounded-lg bg-accent/10 text-accent ring-1 ring-inset ring-accent/20">
+ <HeartIcon className="size-6" />
+ </span>
+ <h2 id="sponsor-heading" className="mt-4 text-xl">
+ Sponsor
+ </h2>
+ <p className="mt-2 max-w-xl text-sm leading-relaxed text-gray-body">
+ If hookli saves you time, consider sponsoring — it funds ongoing
+ maintenance and new hooks. Any amount genuinely helps.
+ </p>
+ <div className="mt-5 flex flex-wrap gap-3">
+ <a
+ href={SPONSOR_URL}
+ target="_blank"
+ rel="noopener noreferrer"
+ className="flex min-h-11 items-center gap-2 rounded-md bg-accent px-5 text-sm font-medium text-ground transition-opacity duration-200 hover:opacity-90"
+ >
+ <GitHubSponsorsIcon className="size-4" />
+ GitHub Sponsors
+ </a>
+ <a
+ href={KOFI_URL}
+ target="_blank"
+ rel="noopener noreferrer"
+ className="flex min-h-11 items-center gap-2 rounded-md border border-slate-syntax/40 px-5 text-sm text-fg transition-colors duration-200 hover:border-slate-syntax hover:bg-ground-overlay"
+ >
+ <KofiIcon className="size-4" aria-hidden="true" />
+ Buy me a coffee
+ </a>
+ </div>
+ </section>
+ </main>
+ );
+}
diff --git a/apps/docs/components/api-table.tsx b/apps/docs/components/api-table.tsx
new file mode 100644
index 0000000..84ecf05
--- /dev/null
+++ b/apps/docs/components/api-table.tsx
@@ -0,0 +1,74 @@
+export type ApiRow = {
+ name: string;
+ type: string;
+ defaultValue?: string;
+ description: string;
+};
+
+/* Parameters / Returns tables on hook pages (docs/DESIGN.md §4). Parameters
+ pass `withDefault`; Returns omit it. Horizontal scroll keeps 375px clean. */
+export function ApiTable({
+ rows,
+ withDefault = false,
+ className = "",
+}: {
+ rows: readonly ApiRow[];
+ withDefault?: boolean;
+ className?: string;
+}) {
+ return (
+ <div
+ className={`surface overflow-x-auto rounded-xl ${className}`}
+ >
+ <table className="w-full text-left text-sm">
+ <thead>
+ <tr className="border-b border-slate-syntax/40">
+ <th scope="col" className="px-4 py-3 text-xs text-gray-body">
+ Name
+ </th>
+ <th scope="col" className="px-4 py-3 text-xs text-gray-body">
+ Type
+ </th>
+ {withDefault && (
+ <th scope="col" className="px-4 py-3 text-xs text-gray-body">
+ Default
+ </th>
+ )}
+ <th scope="col" className="px-4 py-3 text-xs text-gray-body">
+ Description
+ </th>
+ </tr>
+ </thead>
+ <tbody>
+ {rows.map((row) => (
+ <tr
+ key={row.name}
+ className="border-b border-slate-syntax/40 align-top last:border-b-0"
+ >
+ <td className="whitespace-nowrap px-4 py-3 font-mono text-accent">
+ {row.name}
+ </td>
+ <td className="whitespace-nowrap px-4 py-3 font-mono text-gray-body">
+ {row.type}
+ </td>
+ {withDefault && (
+ <td className="whitespace-nowrap px-4 py-3">
+ {row.defaultValue ? (
+ <span className="inline-block rounded border border-slate-syntax/50 bg-ground px-2 py-0.5 font-mono text-xs text-accent">
+ {row.defaultValue}
+ </span>
+ ) : (
+ <span className="font-mono text-gray-body">—</span>
+ )}
+ </td>
+ )}
+ <td className="min-w-48 px-4 py-3 text-gray-body">
+ {row.description}
+ </td>
+ </tr>
+ ))}
+ </tbody>
+ </table>
+ </div>
+ );
+}
diff --git a/apps/docs/components/bottom-cta-section.tsx b/apps/docs/components/bottom-cta-section.tsx
new file mode 100644
index 0000000..1340db2
--- /dev/null
+++ b/apps/docs/components/bottom-cta-section.tsx
@@ -0,0 +1,23 @@
+import Link from "next/link";
+import { ArrowRightIcon } from "@/components/icons";
+import { InstallCommand } from "@/components/install-command";
+
+/* Landing bottom CTA (docs/DESIGN.md §3.6): repeat the install command and
+ the docs CTA for readers who scrolled the whole page. */
+export function BottomCtaSection() {
+ return (
+ <section className="border-t border-slate-syntax/40">
+ <div className="mx-auto flex w-full max-w-5xl flex-col items-center px-4 py-20 text-center sm:px-6">
+ <h2 className="text-3xl">Stop rewriting the same hooks.</h2>
+ <InstallCommand className="mt-8" />
+ <Link
+ href="/docs"
+ className="mt-6 flex min-h-11 items-center gap-2 rounded-md bg-accent px-5 text-sm font-semibold text-ground transition-opacity duration-200 hover:opacity-90"
+ >
+ Explore the docs
+ <ArrowRightIcon className="size-4" />
+ </Link>
+ </div>
+ </section>
+ );
+}
diff --git a/apps/docs/components/code-block.tsx b/apps/docs/components/code-block.tsx
new file mode 100644
index 0000000..90ba019
--- /dev/null
+++ b/apps/docs/components/code-block.tsx
@@ -0,0 +1,81 @@
+import { CopyButton } from "@/components/copy-button";
+import { highlight, type CodeLang } from "@/lib/shiki";
+
+/* Frameless highlighted code — the pane inside CodeBlock, also used bare as the
+ Code tab of HookDemo (whose frame already owns the surface). Usage snippets
+ pass `lineNumbers` + `highlightLine` for the usehooks-ts gutter treatment
+ (T16); the styles live in globals.css keyed off shiki's .line class. */
+export async function HighlightedCode({
+ code,
+ lang = "tsx",
+ lineNumbers = false,
+ highlightLine,
+ className = "",
+}: {
+ code: string;
+ lang?: CodeLang;
+ lineNumbers?: boolean;
+ highlightLine?: number;
+ className?: string;
+}) {
+ const html = await highlight(code, lang, { lineNumbers, highlightLine });
+
+ return (
+ <div
+ className={`overflow-x-auto p-4 text-sm leading-relaxed [&_pre]:outline-none ${className}`}
+ dangerouslySetInnerHTML={{ __html: html }}
+ />
+ );
+}
+
+/* Server component — highlighting happens at build/render time, zero client JS
+ beyond the CopyButton. Frame per docs/DESIGN.md §4: ground-raised, slate/40
+ border, 12px radius. */
+export function CodeBlock({
+ code,
+ lang = "tsx",
+ title,
+ lineNumbers = false,
+ highlightLine,
+ className = "",
+}: {
+ code: string;
+ lang?: CodeLang;
+ title?: string;
+ lineNumbers?: boolean;
+ highlightLine?: number;
+ className?: string;
+}) {
+ return (
+ <figure
+ className={`surface overflow-hidden rounded-xl ${className}`}
+ >
+ <figcaption className="flex items-center justify-between gap-2 border-b border-slate-syntax/40 py-1 pl-4 pr-1">
+ <span className="flex min-w-0 items-center gap-2">
+ <span
+ aria-hidden="true"
+ className="size-1.5 shrink-0 rounded-full bg-accent/70"
+ />
+ <span className="truncate font-mono text-xs text-gray-body">
+ {title ?? lang}
+ </span>
+ </span>
+ <span className="flex shrink-0 items-center gap-1">
+ {title && (
+ <span className="rounded border border-slate-syntax/40 px-1.5 py-0.5 font-mono text-[10px] font-medium uppercase tracking-wider text-slate-syntax">
+ {lang}
+ </span>
+ )}
+ <CopyButton text={code.trim()} label={`Copy ${title ?? "code"}`} />
+ </span>
+ </figcaption>
+ <HighlightedCode
+ code={code}
+ lang={lang}
+ lineNumbers={lineNumbers}
+ highlightLine={highlightLine}
+ className="code-pane"
+ />
+ </figure>
+ );
+}
diff --git a/apps/docs/components/copy-button.tsx b/apps/docs/components/copy-button.tsx
new file mode 100644
index 0000000..9cfbb70
--- /dev/null
+++ b/apps/docs/components/copy-button.tsx
@@ -0,0 +1,52 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import { CheckIcon, CopyIcon } from "@/components/icons";
+
+export function CopyButton({
+ text,
+ label = "Copy to clipboard",
+ className = "",
+}: {
+ text: string;
+ label?: string;
+ className?: string;
+}) {
+ const [copied, setCopied] = useState(false);
+ const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+ useEffect(() => {
+ return () => {
+ if (timeoutRef.current) clearTimeout(timeoutRef.current);
+ };
+ }, []);
+
+ async function copy() {
+ try {
+ await navigator.clipboard.writeText(text);
+ } catch {
+ return; // Clipboard unavailable (permissions / insecure context).
+ }
+ setCopied(true);
+ if (timeoutRef.current) clearTimeout(timeoutRef.current);
+ timeoutRef.current = setTimeout(() => setCopied(false), 2000);
+ }
+
+ return (
+ <button
+ type="button"
+ onClick={copy}
+ aria-label={label}
+ className={`flex size-11 items-center justify-center rounded-md text-gray-body transition-colors duration-200 hover:bg-slate-syntax/20 hover:text-fg ${className}`}
+ >
+ {copied ? (
+ <CheckIcon className="copy-pop size-4 text-accent" />
+ ) : (
+ <CopyIcon className="size-4" />
+ )}
+ <span aria-live="polite" className="sr-only">
+ {copied ? "Copied to clipboard" : ""}
+ </span>
+ </button>
+ );
+}
diff --git a/apps/docs/components/demo-error-boundary.tsx b/apps/docs/components/demo-error-boundary.tsx
new file mode 100644
index 0000000..a85af2f
--- /dev/null
+++ b/apps/docs/components/demo-error-boundary.tsx
@@ -0,0 +1,39 @@
+"use client";
+
+import { Component, type ReactNode } from "react";
+
+/* Class component on purpose — error boundaries have no hook equivalent.
+ Wraps every hook-page demo so a crashing demo never kills the page
+ (docs/DESIGN.md §5). */
+export class DemoErrorBoundary extends Component<
+ { children: ReactNode },
+ { hasError: boolean }
+> {
+ state = { hasError: false };
+
+ static getDerivedStateFromError() {
+ return { hasError: true };
+ }
+
+ render() {
+ if (this.state.hasError) {
+ return (
+ <div className="flex flex-col items-center gap-3 text-center">
+ <p className="text-sm text-fg">This demo crashed.</p>
+ <p className="text-sm text-gray-body">
+ The rest of the page is unaffected.
+ </p>
+ <button
+ type="button"
+ onClick={() => this.setState({ hasError: false })}
+ className="min-h-11 rounded-md border border-slate-syntax/40 px-4 text-sm text-fg transition-colors duration-200 hover:border-slate-syntax"
+ >
+ Re-run demo
+ </button>
+ </div>
+ );
+ }
+
+ return this.props.children;
+ }
+}
diff --git a/apps/docs/components/demos/ui.tsx b/apps/docs/components/demos/ui.tsx
new file mode 100644
index 0000000..f1481e4
--- /dev/null
+++ b/apps/docs/components/demos/ui.tsx
@@ -0,0 +1,63 @@
+"use client";
+
+import { useId } from "react";
+
+/* Shared primitives for docs-page demos (T7+). Same visual language as the
+ T6 useToggle demo: ground surface, slate borders, mono labels, 44px targets. */
+
+export function DemoInput({
+ label,
+ ...props
+}: { label: string } & Omit<
+ React.InputHTMLAttributes<HTMLInputElement>,
+ "id" | "className"
+>) {
+ const id = useId();
+
+ return (
+ <div className="flex w-full flex-col gap-1.5">
+ <label htmlFor={id} className="font-mono text-xs text-gray-body">
+ {label}
+ </label>
+ <input
+ id={id}
+ {...props}
+ className="min-h-11 w-full rounded-md border border-slate-syntax/40 bg-ground px-3 font-mono text-sm text-fg transition-colors duration-200 placeholder:text-slate-syntax focus:border-accent focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/40"
+ />
+ </div>
+ );
+}
+
+export function DemoButton({
+ children,
+ ...props
+}: { children: React.ReactNode } & Omit<
+ React.ButtonHTMLAttributes<HTMLButtonElement>,
+ "className" | "type"
+>) {
+ return (
+ <button
+ type="button"
+ {...props}
+ className="inline-flex min-h-11 items-center gap-2 rounded-md border border-slate-syntax/40 px-4 font-mono text-sm text-gray-body transition-colors duration-200 hover:border-slate-syntax hover:text-fg disabled:cursor-not-allowed disabled:opacity-40 disabled:hover:border-slate-syntax/40 disabled:hover:text-gray-body aria-expanded:border-accent/60 aria-expanded:text-accent aria-pressed:border-accent/60 aria-pressed:bg-accent/10 aria-pressed:text-accent"
+ >
+ {children}
+ </button>
+ );
+}
+
+/* One label/value row; render inside a <dl>. */
+export function DemoReadout({
+ label,
+ children,
+}: {
+ label: string;
+ children: React.ReactNode;
+}) {
+ return (
+ <div className="flex items-baseline justify-between gap-4 border-b border-slate-syntax/20 py-2 last:border-b-0">
+ <dt className="shrink-0 font-mono text-xs text-gray-body">{label}</dt>
+ <dd className="truncate font-mono text-sm text-fg">{children}</dd>
+ </div>
+ );
+}
diff --git a/apps/docs/components/demos/use-boolean-demo.tsx b/apps/docs/components/demos/use-boolean-demo.tsx
new file mode 100644
index 0000000..6822a47
--- /dev/null
+++ b/apps/docs/components/demos/use-boolean-demo.tsx
@@ -0,0 +1,28 @@
+"use client";
+
+import { useBoolean } from "hookli";
+import { DemoButton, DemoReadout } from "./ui";
+
+/* Docs-page demo (DH1): exercises the convenience setters returned alongside the
+ value — toggle plus the explicit setTrue/setFalse. Mirrors the usage snippet
+ in lib/hook-docs.ts — keep in sync. */
+export function UseBooleanDocDemo() {
+ const { value, setTrue, setFalse, toggle } = useBoolean(false);
+
+ return (
+ <div className="flex flex-col items-center gap-5">
+ <dl className="w-full max-w-xs">
+ <DemoReadout label="value">
+ <span className={value ? "text-accent" : "text-gray-body"}>
+ {String(value)}
+ </span>
+ </DemoReadout>
+ </dl>
+ <div className="flex flex-wrap justify-center gap-3">
+ <DemoButton onClick={toggle}>toggle</DemoButton>
+ <DemoButton onClick={setTrue}>setTrue</DemoButton>
+ <DemoButton onClick={setFalse}>setFalse</DemoButton>
+ </div>
+ </div>
+ );
+}
diff --git a/apps/docs/components/demos/use-click-any-where-demo.tsx b/apps/docs/components/demos/use-click-any-where-demo.tsx
new file mode 100644
index 0000000..790dbc0
--- /dev/null
+++ b/apps/docs/components/demos/use-click-any-where-demo.tsx
@@ -0,0 +1,42 @@
+"use client";
+
+import { useState } from "react";
+import { useClickAnyWhere } from "hookli";
+import { DemoReadout } from "./ui";
+
+/* Docs-page demo (DH7): useClickAnyWhere subscribes to click on the window and
+ forwards the latest handler on every dispatch. The listener lives in an
+ effect and cleans up on unmount, so the demo is SSR-safe. Mirrors the usage
+ snippet in lib/hook-docs.ts — keep in sync. */
+export function UseClickAnyWhereDocDemo() {
+ const [count, setCount] = useState(0);
+ const [position, setPosition] = useState<{ x: number; y: number } | null>(
+ null,
+ );
+
+ useClickAnyWhere((event) => {
+ setCount((prev) => prev + 1);
+ setPosition({ x: event.clientX, y: event.clientY });
+ });
+
+ return (
+ <div className="flex w-full max-w-sm flex-col items-center gap-5">
+ <div
+ className="flex h-24 w-full items-center justify-center rounded-md border border-slate-syntax/40 bg-ground text-center text-sm text-gray-body"
+ aria-live="polite"
+ >
+ Click anywhere on the page
+ </div>
+ <dl className="w-full">
+ <DemoReadout label="clicks">{count}</DemoReadout>
+ <DemoReadout label="last position">
+ {position ? `${position.x}, ${position.y}` : "—"}
+ </DemoReadout>
+ </dl>
+ <p className="text-xs text-gray-body">
+ Fires for every click in the document — handy for dismissing popovers or
+ logging outside interactions without wiring a ref.
+ </p>
+ </div>
+ );
+}
diff --git a/apps/docs/components/demos/use-click-outside-demo.tsx b/apps/docs/components/demos/use-click-outside-demo.tsx
new file mode 100644
index 0000000..75aef55
--- /dev/null
+++ b/apps/docs/components/demos/use-click-outside-demo.tsx
@@ -0,0 +1,75 @@
+"use client";
+
+import { useRef, useState } from "react";
+import { useClickOutside } from "hookli";
+import { ChevronDownIcon } from "@/components/icons";
+import { DemoButton, DemoReadout } from "./ui";
+
+const ACTIONS = ["Rename", "Duplicate", "Share"] as const;
+
+/* Mirrors the usage snippet in lib/hook-docs.ts — keep in sync. The hook fires
+ its callback on EVERY outside mousedown, so the open guard lives in the
+ callback, not the hook. min-h reserves room for the absolute menu inside the
+ overflow-hidden HookDemo frame. */
+export function UseClickOutsideDocDemo() {
+ const menuRef = useRef<HTMLDivElement>(null);
+ const [open, setOpen] = useState(false);
+ const [lastEvent, setLastEvent] = useState("nothing yet");
+
+ useClickOutside(menuRef, () => {
+ if (open) {
+ setOpen(false);
+ setLastEvent("closed by outside click");
+ }
+ });
+
+ return (
+ <div className="flex min-h-60 w-full max-w-sm flex-col gap-4">
+ <div ref={menuRef} className="relative self-start">
+ <DemoButton
+ onClick={() => setOpen((prev) => !prev)}
+ aria-expanded={open}
+ aria-haspopup="menu"
+ >
+ Actions
+ <ChevronDownIcon
+ className={`size-4 transition-transform duration-200 motion-reduce:transition-none ${
+ open ? "rotate-180" : ""
+ }`}
+ aria-hidden="true"
+ />
+ </DemoButton>
+ {open && (
+ <ul
+ role="menu"
+ aria-label="Demo actions"
+ className="absolute left-0 top-full z-10 mt-2 w-44 rounded-md border border-slate-syntax/40 bg-ground p-1"
+ >
+ {ACTIONS.map((action) => (
+ <li key={action} role="none">
+ <button
+ type="button"
+ role="menuitem"
+ onClick={() => {
+ setLastEvent(`ran “${action.toLowerCase()}”`);
+ setOpen(false);
+ }}
+ className="flex min-h-11 w-full items-center rounded px-3 text-left font-mono text-sm text-gray-body transition-colors duration-200 hover:bg-ground-raised hover:text-fg focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent/40"
+ >
+ {action}
+ </button>
+ </li>
+ ))}
+ </ul>
+ )}
+ </div>
+ <dl>
+ <DemoReadout label="menu">{open ? "open" : "closed"}</DemoReadout>
+ <DemoReadout label="last event">{lastEvent}</DemoReadout>
+ </dl>
+ <p className="font-mono text-xs text-slate-syntax">
+ Open the menu, then click anywhere outside it.
+ </p>
+ </div>
+ );
+}
diff --git a/apps/docs/components/demos/use-copy-to-clipboard-demo.tsx b/apps/docs/components/demos/use-copy-to-clipboard-demo.tsx
new file mode 100644
index 0000000..6e9f28b
--- /dev/null
+++ b/apps/docs/components/demos/use-copy-to-clipboard-demo.tsx
@@ -0,0 +1,58 @@
+"use client";
+
+import { useState } from "react";
+import { useCopyToClipboard } from "hookli";
+import { CheckIcon, CopyIcon } from "@/components/icons";
+import { DemoButton, DemoInput, DemoReadout } from "./ui";
+
+/* Docs-page demo (DH9): copies the input's text via the async Clipboard API and
+ reports the last copied value. SSR-safe — navigator.clipboard is only touched
+ inside the copy callback, never during render. Mirrors the usage snippet in
+ lib/hook-docs.ts — keep in sync. */
+export function UseCopyToClipboardDocDemo() {
+ const [copiedText, copy] = useCopyToClipboard();
+ const [text, setText] = useState("npm i hookli");
+ const [status, setStatus] = useState<"idle" | "ok" | "fail">("idle");
+
+ async function handleCopy() {
+ const ok = await copy(text);
+ setStatus(ok ? "ok" : "fail");
+ }
+
+ return (
+ <div className="flex w-full max-w-sm flex-col gap-4">
+ <DemoInput
+ label="text to copy"
+ value={text}
+ onChange={(event) => {
+ setText(event.target.value);
+ setStatus("idle");
+ }}
+ placeholder="Type something to copy"
+ autoComplete="off"
+ />
+ <div className="flex items-center justify-between gap-4">
+ <p className="text-xs text-gray-body" aria-live="polite">
+ {status === "ok"
+ ? "Copied — paste it anywhere."
+ : status === "fail"
+ ? "Clipboard unavailable in this context."
+ : "Copy, then paste to confirm it worked."}
+ </p>
+ <DemoButton onClick={handleCopy} disabled={text.length === 0}>
+ {status === "ok" ? (
+ <CheckIcon className="size-4 text-accent" />
+ ) : (
+ <CopyIcon className="size-4" />
+ )}
+ {status === "ok" ? "Copied" : "Copy"}
+ </DemoButton>
+ </div>
+ <dl>
+ <DemoReadout label="copiedText">
+ {copiedText === null ? "null" : `"${copiedText}"`}
+ </DemoReadout>
+ </dl>
+ </div>
+ );
+}
diff --git a/apps/docs/components/demos/use-countdown-demo.tsx b/apps/docs/components/demos/use-countdown-demo.tsx
new file mode 100644
index 0000000..73ec63f
--- /dev/null
+++ b/apps/docs/components/demos/use-countdown-demo.tsx
@@ -0,0 +1,23 @@
+"use client";
+
+import { useCountdown } from "hookli";
+import { DemoButton } from "./ui";
+
+/* Docs-page demo (DH1): a 10→0 countdown that stops itself at countStop. The
+ timer lives in an effect, so it is SSR-safe. Mirrors the usage snippet in
+ lib/hook-docs.ts — keep in sync. */
+export function UseCountdownDocDemo() {
+ const [count, { startCountdown, stopCountdown, resetCountdown }] =
+ useCountdown({ countStart: 10, intervalMs: 1000 });
+
+ return (
+ <div className="flex flex-col items-center gap-5">
+ <p className="font-mono text-5xl tabular-nums text-fg">{count}</p>
+ <div className="flex flex-wrap justify-center gap-3">
+ <DemoButton onClick={startCountdown}>Start</DemoButton>
+ <DemoButton onClick={stopCountdown}>Pause</DemoButton>
+ <DemoButton onClick={resetCountdown}>Reset</DemoButton>
+ </div>
+ </div>
+ );
+}
diff --git a/apps/docs/components/demos/use-counter-demo.tsx b/apps/docs/components/demos/use-counter-demo.tsx
new file mode 100644
index 0000000..7012d5a
--- /dev/null
+++ b/apps/docs/components/demos/use-counter-demo.tsx
@@ -0,0 +1,29 @@
+"use client";
+
+import { useCounter } from "hookli";
+import { DemoButton, DemoReadout } from "./ui";
+
+/* Docs-page demo (DH1): the full action set — increment/decrement, a direct
+ setCount jump, and reset back to the initial value. Mirrors the usage snippet
+ in lib/hook-docs.ts — keep in sync. */
+export function UseCounterDocDemo() {
+ const { count, increment, decrement, reset, setCount } = useCounter(0);
+
+ return (
+ <div className="flex flex-col items-center gap-5">
+ <dl className="w-full max-w-xs">
+ <DemoReadout label="count">{count}</DemoReadout>
+ </dl>
+ <div className="flex flex-wrap justify-center gap-3">
+ <DemoButton onClick={decrement} aria-label="Decrement">
+ −1
+ </DemoButton>
+ <DemoButton onClick={increment} aria-label="Increment">
+ +1
+ </DemoButton>
+ <DemoButton onClick={() => setCount(10)}>set 10</DemoButton>
+ <DemoButton onClick={reset}>reset</DemoButton>
+ </div>
+ </div>
+ );
+}
diff --git a/apps/docs/components/demos/use-dark-mode-demo.tsx b/apps/docs/components/demos/use-dark-mode-demo.tsx
new file mode 100644
index 0000000..5dd09b2
--- /dev/null
+++ b/apps/docs/components/demos/use-dark-mode-demo.tsx
@@ -0,0 +1,82 @@
+"use client";
+
+import { useSyncExternalStore } from "react";
+import { useDarkMode } from "hookli";
+import { MoonIcon, SunIcon } from "@/components/icons";
+import { DemoReadout } from "./ui";
+
+/* Hydration gate: false on the server and during hydration, true after. */
+const emptySubscribe = () => () => {};
+function useMounted() {
+ return useSyncExternalStore(
+ emptySubscribe,
+ () => true,
+ () => false,
+ );
+}
+
+/* Mirrors the usage snippet in lib/hook-docs.ts — keep in sync.
+ The hook persists to localStorage("theme") and toggles a `dark` class on
+ <body>; this site doesn't style that class, so the mode is scoped to the
+ preview panel below. GOTCHA: the hook's initial state reads localStorage on
+ the client, so styling waits for mount to avoid a hydration mismatch. */
+export function UseDarkModeDocDemo() {
+ const { isDarkMode, toggleDarkMode } = useDarkMode();
+ const mounted = useMounted();
+ const dark = mounted && isDarkMode;
+
+ return (
+ <div className="flex w-full max-w-sm flex-col gap-4">
+ <div
+ className={`rounded-lg border p-4 transition-colors duration-200 ${
+ dark
+ ? "border-slate-syntax/40 bg-ground"
+ : "border-slate-300 bg-slate-50"
+ }`}
+ >
+ <div className="flex items-center justify-between gap-4">
+ <p
+ className={`font-mono text-sm ${dark ? "text-fg" : "text-ground"}`}
+ >
+ {dark ? "Dark mode" : "Light mode"}
+ </p>
+ <button
+ type="button"
+ onClick={toggleDarkMode}
+ aria-pressed={dark}
+ aria-label="Toggle dark mode"
+ className={`flex size-11 items-center justify-center rounded-md border transition-colors duration-200 ${
+ dark
+ ? "border-slate-syntax/40 text-fg hover:border-slate-syntax"
+ : "border-slate-300 text-ground hover:border-slate-400"
+ }`}
+ >
+ {dark ? (
+ <MoonIcon className="size-5" />
+ ) : (
+ <SunIcon className="size-5" />
+ )}
+ </button>
+ </div>
+ <p
+ className={`mt-2 text-xs ${
+ dark ? "text-gray-body" : "text-slate-syntax"
+ }`}
+ >
+ This panel is scoped to the demo — the docs stay dark either way.
+ </p>
+ </div>
+ <dl>
+ <DemoReadout label="isDarkMode">{String(dark)}</DemoReadout>
+ <DemoReadout label={`localStorage("theme")`}>
+ {dark ? "dark" : "light"}
+ </DemoReadout>
+ </dl>
+ <p className="text-xs text-gray-body">
+ The choice persists — reload and the panel keeps its mode. The hook
+ also toggles a <code className="text-fg">dark</code> class on{" "}
+ <code className="text-fg">{"<body>"}</code> for CSS-driven themes.
+ </p>
+ </div>
+ );
+}
diff --git a/apps/docs/components/demos/use-debounce-callback-demo.tsx b/apps/docs/components/demos/use-debounce-callback-demo.tsx
new file mode 100644
index 0000000..8751461
--- /dev/null
+++ b/apps/docs/components/demos/use-debounce-callback-demo.tsx
@@ -0,0 +1,43 @@
+"use client";
+
+import { useState } from "react";
+import { useDebounceCallback } from "hookli";
+import { DemoButton, DemoInput, DemoReadout } from "./ui";
+
+/* Mirrors the usage snippet in lib/hook-docs.ts — keep in sync. */
+export function UseDebounceCallbackDocDemo() {
+ const [text, setText] = useState("");
+ const [keystrokes, setKeystrokes] = useState(0);
+ const [runs, setRuns] = useState(0);
+ const [lastRun, setLastRun] = useState("");
+
+ const search = useDebounceCallback((query: string) => {
+ setRuns((n) => n + 1);
+ setLastRun(query);
+ }, 600);
+
+ return (
+ <div className="flex w-full max-w-sm flex-col gap-4">
+ <DemoInput
+ label="Search"
+ value={text}
+ onChange={(event) => {
+ setText(event.target.value);
+ setKeystrokes((n) => n + 1);
+ search(event.target.value);
+ }}
+ placeholder="Runs 600 ms after your last keystroke"
+ autoComplete="off"
+ />
+ <dl>
+ <DemoReadout label="keystrokes">{keystrokes}</DemoReadout>
+ <DemoReadout label="callback runs">{runs}</DemoReadout>
+ <DemoReadout label="last searched">{lastRun || "—"}</DemoReadout>
+ </dl>
+ <div className="flex flex-wrap gap-2">
+ <DemoButton onClick={() => search.flush()}>Flush now</DemoButton>
+ <DemoButton onClick={() => search.cancel()}>Cancel pending</DemoButton>
+ </div>
+ </div>
+ );
+}
diff --git a/apps/docs/components/demos/use-debounce-demo.tsx b/apps/docs/components/demos/use-debounce-demo.tsx
new file mode 100644
index 0000000..53eb2f3
--- /dev/null
+++ b/apps/docs/components/demos/use-debounce-demo.tsx
@@ -0,0 +1,35 @@
+"use client";
+
+import { useState } from "react";
+import { useDebounce } from "hookli";
+import { DemoInput, DemoReadout } from "./ui";
+
+/* Mirrors the usage snippet in lib/hook-docs.ts — keep in sync. */
+export function UseDebounceDocDemo() {
+ const [text, setText] = useState("");
+ const debounced = useDebounce(text, 500);
+ const settling = text !== debounced;
+
+ return (
+ <div className="flex w-full max-w-sm flex-col gap-4">
+ <DemoInput
+ label="Type quickly"
+ value={text}
+ onChange={(event) => setText(event.target.value)}
+ placeholder="The right value shows up 500 ms after you stop"
+ autoComplete="off"
+ />
+ <dl>
+ <DemoReadout label="value">{text || "—"}</DemoReadout>
+ <DemoReadout label="debounced">{debounced || "—"}</DemoReadout>
+ </dl>
+ <p className="font-mono text-xs" aria-live="polite">
+ {settling ? (
+ <span className="text-accent">debouncing…</span>
+ ) : (
+ <span className="text-slate-syntax">settled</span>
+ )}
+ </p>
+ </div>
+ );
+}
diff --git a/apps/docs/components/demos/use-debounce-value-demo.tsx b/apps/docs/components/demos/use-debounce-value-demo.tsx
new file mode 100644
index 0000000..759aa9f
--- /dev/null
+++ b/apps/docs/components/demos/use-debounce-value-demo.tsx
@@ -0,0 +1,49 @@
+"use client";
+
+import { useState } from "react";
+import { useDebounceValue } from "hookli";
+import { DemoButton, DemoInput, DemoReadout } from "./ui";
+
+/* Mirrors the usage snippet in lib/hook-docs.ts — keep in sync. */
+export function UseDebounceValueDocDemo() {
+ const [text, setText] = useState("");
+ const [debounced, setValue] = useDebounceValue("", 500);
+ const pending = text !== debounced;
+
+ return (
+ <div className="flex w-full max-w-sm flex-col gap-4">
+ <DemoInput
+ label="Search query"
+ value={text}
+ onChange={(event) => {
+ setText(event.target.value);
+ setValue(event.target.value);
+ }}
+ placeholder="Type — the debounced copy settles 500 ms later"
+ autoComplete="off"
+ />
+ <dl>
+ <DemoReadout label="live">{text || "—"}</DemoReadout>
+ <DemoReadout label="debounced">{debounced || "—"}</DemoReadout>
+ </dl>
+ <div className="flex flex-wrap gap-2">
+ <DemoButton onClick={() => setValue.flush()}>Flush now</DemoButton>
+ <DemoButton
+ onClick={() => {
+ setValue.cancel();
+ setText(debounced);
+ }}
+ >
+ Cancel pending
+ </DemoButton>
+ </div>
+ <p className="font-mono text-xs" aria-live="polite">
+ {pending ? (
+ <span className="text-accent">pending — waiting for a pause…</span>
+ ) : (
+ <span className="text-slate-syntax">settled</span>
+ )}
+ </p>
+ </div>
+ );
+}
diff --git a/apps/docs/components/demos/use-document-title-demo.tsx b/apps/docs/components/demos/use-document-title-demo.tsx
new file mode 100644
index 0000000..99612ec
--- /dev/null
+++ b/apps/docs/components/demos/use-document-title-demo.tsx
@@ -0,0 +1,57 @@
+"use client";
+
+import { useState } from "react";
+import { useDocumentTitle } from "hookli";
+import { DemoButton, DemoInput, DemoReadout } from "./ui";
+
+/* Docs-page demo (DH4): the title text drives document.title live — watch the
+ browser tab. The child sets the title with preserveTitleOnUnmount: false, so
+ unmounting it restores the title captured on mount. Mirrors the usage snippet
+ in lib/hook-docs.ts — keep in sync. SSR-safe: the hook no-ops during server
+ rendering and syncs in a layout effect once mounted. */
+function TitleSetter({ title }: { title: string }) {
+ useDocumentTitle(title, { preserveTitleOnUnmount: false });
+
+ return (
+ <dl className="w-full">
+ <DemoReadout label="document.title">
+ <span className="text-accent">{title || "(empty)"}</span>
+ </DemoReadout>
+ </dl>
+ );
+}
+
+export function UseDocumentTitleDocDemo() {
+ const [title, setTitle] = useState("Look up at the tab ✦");
+ const [applied, setApplied] = useState(true);
+
+ return (
+ <div className="flex w-full max-w-sm flex-col gap-5">
+ <DemoInput
+ label="title"
+ value={title}
+ onChange={(e) => setTitle(e.target.value)}
+ placeholder="Type a page title"
+ />
+ <div className="min-h-14">
+ {applied ? (
+ <TitleSetter title={title} />
+ ) : (
+ <p className="font-mono text-sm text-gray-body">
+ title restored to the site default
+ </p>
+ )}
+ </div>
+ <DemoButton
+ onClick={() => setApplied((prev) => !prev)}
+ aria-pressed={applied}
+ >
+ {applied ? "Restore original" : "Apply title"}
+ </DemoButton>
+ <p className="text-xs text-gray-body">
+ Type above and the browser tab updates as you go. Restoring unmounts the
+ hook, which puts back the title it captured on mount.
+ </p>
+ </div>
+ );
+}
diff --git a/apps/docs/components/demos/use-event-callback-demo.tsx b/apps/docs/components/demos/use-event-callback-demo.tsx
new file mode 100644
index 0000000..7eec181
--- /dev/null
+++ b/apps/docs/components/demos/use-event-callback-demo.tsx
@@ -0,0 +1,52 @@
+"use client";
+
+import { useState } from "react";
+import { useEventCallback } from "hookli";
+import { DemoButton, DemoReadout } from "./ui";
+
+/* Docs-page demo (DH3): the callback returned by useEventCallback keeps one
+ stable identity for the component's whole life, yet always closes over the
+ newest count. Increment a few times, then Capture — the captured value jumps
+ to the current count (latest closure) while "identity" stays stable (the ref
+ never changed). SSR-safe: no browser APIs. Mirrors lib/hook-docs.ts. */
+export function UseEventCallbackDocDemo() {
+ const [count, setCount] = useState(0);
+ const [captured, setCaptured] = useState<number | null>(null);
+
+ const readLatest = useEventCallback(() => count);
+
+ // Snapshot the very first callback; useEventCallback returns one stable
+ // reference for the component's life, so this stays === readLatest forever.
+ const [firstCallback] = useState(() => readLatest);
+ const stable = firstCallback === readLatest;
+
+ return (
+ <div className="flex w-full flex-col items-center gap-5">
+ <p className="font-mono text-5xl tabular-nums text-fg">{count}</p>
+ <dl className="w-full max-w-xs">
+ <DemoReadout label="captured">
+ {captured === null ? "—" : captured}
+ </DemoReadout>
+ <DemoReadout label="callback identity">
+ {stable ? "stable" : "changed"}
+ </DemoReadout>
+ </dl>
+ <div className="flex flex-wrap justify-center gap-3">
+ <DemoButton onClick={() => setCount((prev) => prev + 1)}>
+ Increment
+ </DemoButton>
+ <DemoButton onClick={() => setCaptured(readLatest())}>
+ Capture latest
+ </DemoButton>
+ <DemoButton
+ onClick={() => {
+ setCount(0);
+ setCaptured(null);
+ }}
+ >
+ Reset
+ </DemoButton>
+ </div>
+ </div>
+ );
+}
diff --git a/apps/docs/components/demos/use-event-listener-demo.tsx b/apps/docs/components/demos/use-event-listener-demo.tsx
new file mode 100644
index 0000000..09f73c2
--- /dev/null
+++ b/apps/docs/components/demos/use-event-listener-demo.tsx
@@ -0,0 +1,47 @@
+"use client";
+
+import { useRef, useState, type RefObject } from "react";
+import { useEventListener } from "hookli";
+import { DemoReadout } from "./ui";
+
+/* Docs-page demo (DH3): one subscription on the window (global keydown) and one
+ scoped to a ref (clicks inside the panel only) — the two targeting modes of
+ useEventListener. Listeners live in an effect and clean up on unmount, so the
+ demo is SSR-safe and leak-free. Mirrors lib/hook-docs.ts — keep in sync. */
+export function UseEventListenerDocDemo() {
+ const panelRef = useRef<HTMLDivElement>(null);
+ const [lastKey, setLastKey] = useState("—");
+ const [keyCount, setKeyCount] = useState(0);
+ const [clicks, setClicks] = useState(0);
+
+ useEventListener("keydown", (event) => {
+ setLastKey(event.key === " " ? "Space" : event.key);
+ setKeyCount((prev) => prev + 1);
+ });
+
+ // useEventListener's element overload wants a strict RefObject<T>; React 19's
+ // useRef(null) is RefObject<T | null>. The listener effect guards for null, so
+ // narrowing here is safe.
+ useEventListener(
+ "click",
+ () => setClicks((prev) => prev + 1),
+ panelRef as RefObject<HTMLDivElement>,
+ );
+
+ return (
+ <div className="flex w-full flex-col items-center gap-5">
+ <div
+ ref={panelRef}
+ tabIndex={0}
+ className="flex h-28 w-full max-w-md cursor-pointer items-center justify-center rounded-md border border-slate-syntax/40 bg-ground px-4 text-center font-mono text-sm text-gray-body transition-colors duration-200 hover:border-slate-syntax focus:border-accent focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/40"
+ >
+ Click here, or press any key
+ </div>
+ <dl className="w-full max-w-xs">
+ <DemoReadout label="last key (window)">{lastKey}</DemoReadout>
+ <DemoReadout label="key presses">{keyCount}</DemoReadout>
+ <DemoReadout label="panel clicks">{clicks}</DemoReadout>
+ </dl>
+ </div>
+ );
+}
diff --git a/apps/docs/components/demos/use-fetch-demo.tsx b/apps/docs/components/demos/use-fetch-demo.tsx
new file mode 100644
index 0000000..98f8d56
--- /dev/null
+++ b/apps/docs/components/demos/use-fetch-demo.tsx
@@ -0,0 +1,78 @@
+"use client";
+
+import { useState } from "react";
+import { useFetch } from "hookli";
+import { DemoButton, DemoReadout } from "./ui";
+
+type Post = { id: number; title: string; body: string };
+
+const API_BASE = "https://jsonplaceholder.typicode.com";
+const POST_IDS = [1, 2, 3] as const;
+/* jsonplaceholder has no post 0 — responds 404, which the hook turns into
+ an Error("HTTP error! status: 404"). */
+const BROKEN_URL = `${API_BASE}/posts/0`;
+
+const postUrl = (id: number) => `${API_BASE}/posts/${id}`;
+
+/* Mirrors the usage snippet in lib/hook-docs.ts — keep in sync. The hook
+ refetches when url changes but never resets loading/error/data between
+ requests, so the parent remounts this reader via key={url} to give every
+ request fresh hook state. */
+function PostReader({ url }: { url: string }) {
+ const { data, error, loading } = useFetch<Post>(url);
+
+ return (
+ <>
+ <dl>
+ <DemoReadout label="loading">{String(loading)}</DemoReadout>
+ <DemoReadout label="error">
+ {error ? error.message : "null"}
+ </DemoReadout>
+ <DemoReadout label="data">
+ {data ? `#${data.id} ${data.title}` : "null"}
+ </DemoReadout>
+ </dl>
+ <p className="min-h-16 font-mono text-xs leading-relaxed" aria-live="polite">
+ {loading ? (
+ <span className="text-accent">fetching…</span>
+ ) : error ? (
+ <span className="text-gray-body">
+ request failed — {error.message}
+ </span>
+ ) : data ? (
+ <span className="text-slate-syntax">{data.body}</span>
+ ) : null}
+ </p>
+ </>
+ );
+}
+
+export function UseFetchDocDemo() {
+ const [url, setUrl] = useState(postUrl(POST_IDS[0]));
+
+ return (
+ <div className="flex w-full max-w-sm flex-col gap-4">
+ <div className="flex flex-wrap gap-2">
+ {POST_IDS.map((id) => (
+ <DemoButton
+ key={id}
+ aria-pressed={url === postUrl(id)}
+ onClick={() => setUrl(postUrl(id))}
+ >
+ Post {id}
+ </DemoButton>
+ ))}
+ <DemoButton
+ aria-pressed={url === BROKEN_URL}
+ onClick={() => setUrl(BROKEN_URL)}
+ >
+ 404
+ </DemoButton>
+ </div>
+ <dl>
+ <DemoReadout label="url">{url.replace(API_BASE, "…")}</DemoReadout>
+ </dl>
+ <PostReader key={url} url={url} />
+ </div>
+ );
+}
diff --git a/apps/docs/components/demos/use-form-demo.tsx b/apps/docs/components/demos/use-form-demo.tsx
new file mode 100644
index 0000000..7d9b2e8
--- /dev/null
+++ b/apps/docs/components/demos/use-form-demo.tsx
@@ -0,0 +1,42 @@
+"use client";
+
+import { useForm } from "hookli";
+import { DemoButton, DemoInput } from "./ui";
+
+/* Mirrors the usage snippet in lib/hook-docs.ts — keep in sync. */
+export function UseFormDocDemo() {
+ const { values, handleChange, resetForm } = useForm({ name: "", email: "" });
+
+ return (
+ <div className="flex w-full max-w-sm flex-col gap-4">
+ <form
+ className="flex flex-col gap-4"
+ onSubmit={(event) => event.preventDefault()}
+ >
+ <DemoInput
+ label="name"
+ name="name"
+ value={values.name}
+ onChange={handleChange}
+ placeholder="Ada Lovelace"
+ autoComplete="off"
+ />
+ <DemoInput
+ label="email"
+ name="email"
+ type="email"
+ value={values.email}
+ onChange={handleChange}
+ placeholder="ada@example.com"
+ autoComplete="off"
+ />
+ <div>
+ <DemoButton onClick={resetForm}>Reset</DemoButton>
+ </div>
+ </form>
+ <pre className="overflow-x-auto rounded-md border border-slate-syntax/20 bg-ground p-3 font-mono text-xs leading-relaxed text-gray-body">
+ {JSON.stringify(values, null, 2)}
+ </pre>
+ </div>
+ );
+}
diff --git a/apps/docs/components/demos/use-geo-location-demo.tsx b/apps/docs/components/demos/use-geo-location-demo.tsx
new file mode 100644
index 0000000..1ed7b4c
--- /dev/null
+++ b/apps/docs/components/demos/use-geo-location-demo.tsx
@@ -0,0 +1,49 @@
+"use client";
+
+import { useState } from "react";
+import { useGeoLocation } from "hookli";
+import { DemoButton, DemoReadout } from "./ui";
+
+/* Mirrors the usage snippet in lib/hook-docs.ts — keep in sync. The hook
+ asks the browser for a position the moment it mounts — including the
+ permission prompt — so it stays unmounted until the button is clicked;
+ never auto-request on page load. */
+function CoordinatesReader() {
+ const { location, error } = useGeoLocation();
+
+ return (
+ <dl>
+ <DemoReadout label="status">
+ {error ? "error" : location ? "located" : "locating…"}
+ </DemoReadout>
+ <DemoReadout label="latitude">
+ {location ? location.coords.latitude.toFixed(4) : "null"}
+ </DemoReadout>
+ <DemoReadout label="longitude">
+ {location ? location.coords.longitude.toFixed(4) : "null"}
+ </DemoReadout>
+ <DemoReadout label="error">{error ? error.message : "null"}</DemoReadout>
+ </dl>
+ );
+}
+
+export function UseGeoLocationDocDemo() {
+ const [requested, setRequested] = useState(false);
+
+ return (
+ <div className="flex w-full max-w-sm flex-col gap-4">
+ {requested ? (
+ <CoordinatesReader />
+ ) : (
+ <p className="font-mono text-xs leading-relaxed text-slate-syntax">
+ Nothing runs until you click — your browser may then ask for
+ permission. Denying it is part of the demo: the hook reports it via
+ error instead of throwing.
+ </p>
+ )}
+ <DemoButton onClick={() => setRequested((prev) => !prev)}>
+ {requested ? "Reset" : "Request my location"}
+ </DemoButton>
+ </div>
+ );
+}
diff --git a/apps/docs/components/demos/use-hover-demo.tsx b/apps/docs/components/demos/use-hover-demo.tsx
new file mode 100644
index 0000000..d05e73a
--- /dev/null
+++ b/apps/docs/components/demos/use-hover-demo.tsx
@@ -0,0 +1,43 @@
+"use client";
+
+import { useRef, type RefObject } from "react";
+import { useHover } from "hookli";
+import { DemoReadout } from "./ui";
+
+/* Docs-page demo (DH7): useHover wires mouseenter/mouseleave on the ref'd
+ element and reports a boolean. Listeners live in an effect and clean up on
+ unmount, so the demo is SSR-safe (starts false on the server). Mirrors the
+ usage snippet in lib/hook-docs.ts — keep in sync. */
+export function UseHoverDocDemo() {
+ const boxRef = useRef<HTMLDivElement>(null);
+ // useHover wants a strict RefObject<T>; React 19's useRef(null) is
+ // RefObject<T | null>. The listener effect guards for null, so this is safe.
+ const isHovered = useHover(boxRef as RefObject<HTMLDivElement>);
+
+ return (
+ <div className="flex w-full max-w-sm flex-col items-center gap-5">
+ <div
+ ref={boxRef}
+ className={`flex h-28 w-full items-center justify-center rounded-md border text-sm transition-colors duration-200 ${
+ isHovered
+ ? "border-accent/60 bg-accent/10 text-accent"
+ : "border-slate-syntax/40 bg-ground text-gray-body"
+ }`}
+ aria-live="polite"
+ >
+ {isHovered ? "Pointer is over me" : "Hover this panel"}
+ </div>
+ <dl className="w-full">
+ <DemoReadout label="isHovered">
+ <span className={isHovered ? "text-accent" : "text-gray-body"}>
+ {String(isHovered)}
+ </span>
+ </DemoReadout>
+ </dl>
+ <p className="text-xs text-gray-body">
+ Hover state is pointer-only — pair it with focus styling so keyboard
+ users get the same affordance.
+ </p>
+ </div>
+ );
+}
diff --git a/apps/docs/components/demos/use-infinite-scroll-demo.tsx b/apps/docs/components/demos/use-infinite-scroll-demo.tsx
new file mode 100644
index 0000000..31061c9
--- /dev/null
+++ b/apps/docs/components/demos/use-infinite-scroll-demo.tsx
@@ -0,0 +1,86 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useInfiniteScroll } from "hookli";
+import { DemoButton, DemoReadout } from "./ui";
+
+const BATCH_SIZE = 8;
+const MAX_ITEMS = 32;
+
+function makeBatch(start: number): string[] {
+ return Array.from(
+ { length: BATCH_SIZE },
+ (_, i) => `mock item #${String(start + i + 1).padStart(2, "0")}`,
+ );
+}
+
+/* Mirrors the usage snippet in lib/hook-docs.ts — keep in sync. The hook
+ watches the WINDOW scroll (within 500px of the document bottom), not a
+ container — the scoped list here only keeps the page height stable while
+ batches append. fetchMoreData must return a promise; isFetching stays true
+ until it resolves. */
+export function UseInfiniteScrollDocDemo() {
+ const [items, setItems] = useState<string[]>(() => makeBatch(0));
+ const listRef = useRef<HTMLUListElement>(null);
+ const done = items.length >= MAX_ITEMS;
+
+ const fetchMoreData = useCallback(() => {
+ if (done) return Promise.resolve();
+ return new Promise<void>((resolve) => {
+ setTimeout(() => {
+ setItems((prev) =>
+ prev.length >= MAX_ITEMS
+ ? prev
+ : [...prev, ...makeBatch(prev.length)],
+ );
+ resolve();
+ }, 600);
+ });
+ }, [done]);
+
+ const isFetching = useInfiniteScroll(fetchMoreData);
+
+ /* Keep the newest batch visible inside the scoped list. */
+ useEffect(() => {
+ const list = listRef.current;
+ if (list) list.scrollTop = list.scrollHeight;
+ }, [items]);
+
+ return (
+ <div className="flex w-full max-w-sm flex-col gap-4">
+ <ul
+ ref={listRef}
+ className="max-h-48 overflow-y-auto rounded-md border border-slate-syntax/40 bg-ground p-2"
+ >
+ {items.map((item) => (
+ <li
+ key={item}
+ className="border-b border-slate-syntax/20 px-2 py-2.5 font-mono text-sm text-gray-body last:border-b-0"
+ >
+ {item}
+ </li>
+ ))}
+ </ul>
+ <dl>
+ <DemoReadout label="loaded">
+ {items.length} / {MAX_ITEMS}
+ </DemoReadout>
+ <DemoReadout label="isFetching">{String(isFetching)}</DemoReadout>
+ </dl>
+ <p className="font-mono text-xs" aria-live="polite">
+ {isFetching ? (
+ <span className="text-accent">loading next batch…</span>
+ ) : done ? (
+ <span className="text-slate-syntax">
+ all {MAX_ITEMS} items loaded — reset to go again
+ </span>
+ ) : (
+ <span className="text-slate-syntax">
+ scroll the page toward its bottom to load more
+ </span>
+ )}
+ </p>
+ <DemoButton onClick={() => setItems(makeBatch(0))}>Reset</DemoButton>
+ </div>
+ );
+}
diff --git a/apps/docs/components/demos/use-intersection-observer-demo.tsx b/apps/docs/components/demos/use-intersection-observer-demo.tsx
new file mode 100644
index 0000000..ff1af9f
--- /dev/null
+++ b/apps/docs/components/demos/use-intersection-observer-demo.tsx
@@ -0,0 +1,60 @@
+"use client";
+
+import { useState } from "react";
+import { useIntersectionObserver } from "hookli";
+import { DemoReadout } from "./ui";
+
+/* Docs-page demo (DH7): scroll the target in and out of a scoped viewport. The
+ scroll container is passed as `root`, so intersection is measured against the
+ panel, not the page. The observer is created in an effect and disconnected on
+ cleanup, so the demo is SSR-safe. Mirrors lib/hook-docs.ts — keep in sync. */
+export function UseIntersectionObserverDocDemo() {
+ // root must be a live element; hold it in state so the observer re-creates
+ // once the scroll container mounts (options.root is an effect dependency).
+ const [root, setRoot] = useState<HTMLElement | null>(null);
+
+ const { ref, isIntersecting, entry } = useIntersectionObserver({
+ root,
+ threshold: 0.5,
+ });
+
+ const ratio = entry ? Math.round(entry.intersectionRatio * 100) : 0;
+
+ return (
+ <div className="flex w-full max-w-sm flex-col gap-4">
+ <div
+ ref={setRoot}
+ className="h-40 overflow-y-auto rounded-md border border-slate-syntax/40 bg-ground p-4"
+ >
+ <p className="pb-40 text-center text-xs text-slate-syntax">
+ scroll down ↓
+ </p>
+ <div
+ ref={ref}
+ className={`flex h-20 items-center justify-center rounded-md border text-sm transition-colors duration-200 ${
+ isIntersecting
+ ? "border-accent/60 bg-accent/10 text-accent"
+ : "border-slate-syntax/40 text-gray-body"
+ }`}
+ >
+ {isIntersecting ? "In view" : "Target"}
+ </div>
+ <p className="pt-40 text-center text-xs text-slate-syntax">
+ ↑ scroll up
+ </p>
+ </div>
+ <dl className="w-full">
+ <DemoReadout label="isIntersecting">
+ <span className={isIntersecting ? "text-accent" : "text-gray-body"}>
+ {String(isIntersecting)}
+ </span>
+ </DemoReadout>
+ <DemoReadout label="intersectionRatio">{ratio}%</DemoReadout>
+ </dl>
+ <p className="text-xs text-gray-body">
+ Ideal for lazy-loading, scroll-spy nav and infinite lists — the target
+ crosses the 50% threshold to flip the flag.
+ </p>
+ </div>
+ );
+}
diff --git a/apps/docs/components/demos/use-interval-demo.tsx b/apps/docs/components/demos/use-interval-demo.tsx
new file mode 100644
index 0000000..f7b2038
--- /dev/null
+++ b/apps/docs/components/demos/use-interval-demo.tsx
@@ -0,0 +1,46 @@
+"use client";
+
+import { useState } from "react";
+import { useInterval } from "hookli";
+import { DemoButton, DemoReadout } from "./ui";
+
+/* Docs-page demo (DH2): a tick counter driven by useInterval. Passing delay as
+ null is the hook's built-in pause — it clears the timer, so nothing leaks.
+ The speed buttons swap the interval live. SSR-safe (the timer lives in an
+ effect). Mirrors the usage snippet in lib/hook-docs.ts — keep in sync. */
+export function UseIntervalDocDemo() {
+ const [ticks, setTicks] = useState(0);
+ const [delay, setDelay] = useState<number | null>(1000);
+
+ useInterval(() => setTicks((prev) => prev + 1), delay);
+
+ const running = delay !== null;
+
+ return (
+ <div className="flex flex-col items-center gap-5">
+ <p className="font-mono text-5xl tabular-nums text-fg">{ticks}</p>
+ <dl className="w-full max-w-xs">
+ <DemoReadout label="delay">{running ? `${delay} ms` : "null"}</DemoReadout>
+ <DemoReadout label="status">{running ? "running" : "paused"}</DemoReadout>
+ </dl>
+ <div className="flex flex-wrap justify-center gap-3">
+ <DemoButton
+ onClick={() => setDelay(running ? null : 1000)}
+ aria-pressed={!running}
+ >
+ {running ? "Pause" : "Resume"}
+ </DemoButton>
+ <DemoButton onClick={() => setDelay(500)} aria-pressed={delay === 500}>
+ 0.5s
+ </DemoButton>
+ <DemoButton onClick={() => setDelay(1000)} aria-pressed={delay === 1000}>
+ 1s
+ </DemoButton>
+ <DemoButton onClick={() => setDelay(2000)} aria-pressed={delay === 2000}>
+ 2s
+ </DemoButton>
+ <DemoButton onClick={() => setTicks(0)}>Reset</DemoButton>
+ </div>
+ </div>
+ );
+}
diff --git a/apps/docs/components/demos/use-is-client-demo.tsx b/apps/docs/components/demos/use-is-client-demo.tsx
new file mode 100644
index 0000000..3a2438e
--- /dev/null
+++ b/apps/docs/components/demos/use-is-client-demo.tsx
@@ -0,0 +1,34 @@
+"use client";
+
+import { useIsClient } from "hookli";
+import { DemoReadout } from "./ui";
+
+/* Docs-page demo (DH4): useIsClient is false during server render and the first
+ hydration pass, then flips to true once mounted in the browser. Rendering the
+ value directly is the whole point — it proves the hook without any browser
+ API. Mirrors the usage snippet in lib/hook-docs.ts — keep in sync. */
+export function UseIsClientDocDemo() {
+ const isClient = useIsClient();
+
+ return (
+ <div className="flex w-full max-w-sm flex-col items-center gap-5">
+ <div
+ className="flex h-20 w-full items-center justify-center rounded-md border border-accent/60 bg-accent/10 font-mono text-sm text-accent"
+ aria-live="polite"
+ >
+ {isClient ? "Running in the browser" : "Server / first render"}
+ </div>
+ <dl className="w-full">
+ <DemoReadout label="isClient">
+ <span className={isClient ? "text-accent" : "text-gray-body"}>
+ {String(isClient)}
+ </span>
+ </DemoReadout>
+ </dl>
+ <p className="text-xs text-gray-body">
+ The panel starts as the server markup, then swaps after hydration — gate
+ browser-only UI (portals, media queries) on this so the two renders match.
+ </p>
+ </div>
+ );
+}
diff --git a/apps/docs/components/demos/use-is-mounted-demo.tsx b/apps/docs/components/demos/use-is-mounted-demo.tsx
new file mode 100644
index 0000000..7282276
--- /dev/null
+++ b/apps/docs/components/demos/use-is-mounted-demo.tsx
@@ -0,0 +1,72 @@
+"use client";
+
+import { useState } from "react";
+import { useIsMounted } from "hookli";
+import { DemoButton, DemoReadout } from "./ui";
+
+/* Docs-page demo (DH4): the classic async-guard. The child kicks off a delayed
+ "request"; when it resolves it checks isMounted() before touching state.
+ Unmount the child mid-flight and the pending update is skipped safely instead
+ of warning. Mirrors the usage snippet in lib/hook-docs.ts — keep in sync.
+ SSR-safe: setTimeout only runs from a click handler, never on render. */
+function AsyncChild({ onSkip }: { onSkip: () => void }) {
+ const isMounted = useIsMounted();
+ const [status, setStatus] = useState<"idle" | "loading" | "done">("idle");
+ const [result, setResult] = useState("—");
+
+ function start() {
+ setStatus("loading");
+ setResult("—");
+ window.setTimeout(() => {
+ if (isMounted()) {
+ setResult(`resolved at ${new Date().toLocaleTimeString()}`);
+ setStatus("done");
+ } else {
+ onSkip();
+ }
+ }, 1500);
+ }
+
+ return (
+ <div className="flex w-full flex-col items-center gap-4 rounded-md border border-accent/60 bg-accent/10 p-4">
+ <p className="font-mono text-sm text-accent">child mounted</p>
+ <dl className="w-full">
+ <DemoReadout label="status">{status}</DemoReadout>
+ <DemoReadout label="result">{result}</DemoReadout>
+ </dl>
+ <DemoButton onClick={start} disabled={status === "loading"}>
+ {status === "loading" ? "Resolving…" : "Start async task"}
+ </DemoButton>
+ </div>
+ );
+}
+
+export function UseIsMountedDocDemo() {
+ const [mounted, setMounted] = useState(true);
+ const [skips, setSkips] = useState(0);
+
+ return (
+ <div className="flex w-full max-w-sm flex-col items-center gap-5">
+ <div className="flex min-h-40 w-full items-center justify-center">
+ {mounted ? (
+ <AsyncChild onSkip={() => setSkips((prev) => prev + 1)} />
+ ) : (
+ <p className="font-mono text-sm text-gray-body">child unmounted</p>
+ )}
+ </div>
+ <dl className="w-full">
+ <DemoReadout label="guarded skips">{skips}</DemoReadout>
+ </dl>
+ <DemoButton
+ onClick={() => setMounted((prev) => !prev)}
+ aria-pressed={mounted}
+ >
+ {mounted ? "Unmount child" : "Mount child"}
+ </DemoButton>
+ <p className="text-xs text-gray-body">
+ Start the task, then unmount before it resolves — the update is skipped,
+ not warned. Leave it mounted and the result lands as usual.
+ </p>
+ </div>
+ );
+}
diff --git a/apps/docs/components/demos/use-isomorphic-layout-effect-demo.tsx b/apps/docs/components/demos/use-isomorphic-layout-effect-demo.tsx
new file mode 100644
index 0000000..d21ca97
--- /dev/null
+++ b/apps/docs/components/demos/use-isomorphic-layout-effect-demo.tsx
@@ -0,0 +1,46 @@
+"use client";
+
+import { useRef, useState } from "react";
+import { useIsomorphicLayoutEffect } from "hookli";
+import { DemoButton, DemoReadout } from "./ui";
+
+/* Docs-page demo (DH3): measure a DOM node before the browser paints. The width
+ is read synchronously in a layout effect, so the "measured" readout always
+ matches the box on screen — no flash of a stale value. On the server the hook
+ falls back to useEffect (measured starts at 0, populates after mount), which
+ keeps `next build` prerendering safely. Width is not animated on purpose so
+ the measurement stays truthful. Mirrors lib/hook-docs.ts — keep in sync. */
+const WIDTHS = [25, 50, 100] as const;
+
+export function UseIsomorphicLayoutEffectDocDemo() {
+ const boxRef = useRef<HTMLDivElement>(null);
+ const [pct, setPct] = useState<(typeof WIDTHS)[number]>(50);
+ const [measured, setMeasured] = useState(0);
+
+ useIsomorphicLayoutEffect(() => {
+ if (boxRef.current) setMeasured(boxRef.current.offsetWidth);
+ }, [pct]);
+
+ return (
+ <div className="flex w-full flex-col items-center gap-5">
+ <div className="w-full max-w-md">
+ <div
+ ref={boxRef}
+ style={{ width: `${pct}%` }}
+ className="h-12 rounded-md border border-accent/60 bg-accent/10"
+ />
+ </div>
+ <dl className="w-full max-w-xs">
+ <DemoReadout label="target">{pct}%</DemoReadout>
+ <DemoReadout label="measured">{measured} px</DemoReadout>
+ </dl>
+ <div className="flex flex-wrap justify-center gap-3">
+ {WIDTHS.map((w) => (
+ <DemoButton key={w} onClick={() => setPct(w)} aria-pressed={pct === w}>
+ {w}%
+ </DemoButton>
+ ))}
+ </div>
+ </div>
+ );
+}
diff --git a/apps/docs/components/demos/use-local-storage-demo.tsx b/apps/docs/components/demos/use-local-storage-demo.tsx
new file mode 100644
index 0000000..e29b896
--- /dev/null
+++ b/apps/docs/components/demos/use-local-storage-demo.tsx
@@ -0,0 +1,30 @@
+"use client";
+
+import { useLocalStorage } from "hookli";
+import { DemoButton, DemoInput } from "./ui";
+
+/* Mirrors the usage snippet in lib/hook-docs.ts — keep in sync.
+ NOTE: pass a primitive initialValue — the hook's sync effect depends on it
+ by reference, so a fresh object literal per render would loop. */
+export function UseLocalStorageDocDemo() {
+ const { value, setStoredValue } = useLocalStorage("hookli-docs-note", "");
+
+ return (
+ <div className="flex w-full max-w-sm flex-col gap-4">
+ <DemoInput
+ label="note"
+ value={value}
+ onChange={(event) => setStoredValue(event.target.value)}
+ placeholder="Write something, then reload the page"
+ autoComplete="off"
+ />
+ <div className="flex items-center justify-between gap-4">
+ <p className="text-xs text-gray-body">
+ Stored under <code className="text-fg">hookli-docs-note</code> — it
+ survives a reload.
+ </p>
+ <DemoButton onClick={() => setStoredValue("")}>Clear</DemoButton>
+ </div>
+ </div>
+ );
+}
diff --git a/apps/docs/components/demos/use-local-storage-with-expiry-demo.tsx b/apps/docs/components/demos/use-local-storage-with-expiry-demo.tsx
new file mode 100644
index 0000000..0d3c185
--- /dev/null
+++ b/apps/docs/components/demos/use-local-storage-with-expiry-demo.tsx
@@ -0,0 +1,106 @@
+"use client";
+
+import { useCallback, useEffect, useState } from "react";
+import { useLocalStorageWithExpiry } from "hookli";
+import { DemoButton, DemoInput, DemoReadout } from "./ui";
+
+const KEY = "hookli-docs-expiry";
+const TTL_MS = 10_000;
+
+/* Mirrors the usage snippet in lib/hook-docs.ts — keep in sync.
+ GOTCHA: the hook checks expiry only when it reads (mount / key change), so
+ the demo remounts the reader when the countdown hits zero — that re-read is
+ what evicts the item and returns null. */
+export function UseLocalStorageWithExpiryDocDemo() {
+ const [session, setSession] = useState(0);
+ const expire = useCallback(() => setSession((s) => s + 1), []);
+
+ return <ExpiryDemo key={session} onExpire={expire} />;
+}
+
+function ExpiryDemo({ onExpire }: { onExpire: () => void }) {
+ const { value, setStoredValue } = useLocalStorageWithExpiry(KEY, "", TTL_MS);
+ const [draft, setDraft] = useState("");
+ const [remainingMs, setRemainingMs] = useState<number | null>(null);
+
+ /* The countdown reads the stored expiry timestamp from localStorage on each
+ tick, so it also resumes for an item saved before a page reload. */
+ useEffect(() => {
+ const readExpiry = () => {
+ const raw = window.localStorage.getItem(KEY);
+ if (!raw) return null;
+ try {
+ const item = JSON.parse(raw) as { expiry?: number } | null;
+ return item && typeof item.expiry === "number" ? item.expiry : null;
+ } catch {
+ return null;
+ }
+ };
+ const id = setInterval(() => {
+ const expiry = readExpiry();
+ if (expiry === null) {
+ setRemainingMs(null);
+ return;
+ }
+ const left = expiry - Date.now();
+ if (left <= 0) {
+ onExpire();
+ return;
+ }
+ setRemainingMs(left);
+ }, 100);
+ return () => clearInterval(id);
+ }, [onExpire]);
+
+ const save = () => {
+ if (!draft.trim()) return;
+ setStoredValue(draft);
+ };
+
+ return (
+ <div className="flex w-full max-w-sm flex-col gap-4">
+ <DemoInput
+ label="value"
+ value={draft}
+ onChange={(event) => setDraft(event.target.value)}
+ placeholder="Type, save, watch it expire"
+ autoComplete="off"
+ />
+ <div className="flex items-center gap-4">
+ <DemoButton onClick={save}>Save for 10s</DemoButton>
+ </div>
+ <dl>
+ <DemoReadout label="stored value">
+ {value === null ? "null" : value || "—"}
+ </DemoReadout>
+ <DemoReadout label="expires in">
+ {remainingMs !== null ? `${(remainingMs / 1000).toFixed(1)}s` : "—"}
+ </DemoReadout>
+ </dl>
+ {remainingMs !== null && (
+ <div
+ aria-hidden="true"
+ className="h-1 overflow-hidden rounded-full bg-slate-syntax/20"
+ >
+ <div
+ className="h-full bg-accent"
+ style={{ width: `${Math.min(100, (remainingMs / TTL_MS) * 100)}%` }}
+ />
+ </div>
+ )}
+ <p className="font-mono text-xs" aria-live="polite">
+ {value === null ? (
+ <span className="text-accent">
+ expired — item removed from localStorage
+ </span>
+ ) : remainingMs !== null ? (
+ <span className="text-slate-syntax">
+ persisted under {KEY} with a 10s TTL
+ </span>
+ ) : (
+ <span className="text-slate-syntax">nothing stored yet</span>
+ )}
+ </p>
+ </div>
+ );
+}
diff --git a/apps/docs/components/demos/use-map-demo.tsx b/apps/docs/components/demos/use-map-demo.tsx
new file mode 100644
index 0000000..69ea301
--- /dev/null
+++ b/apps/docs/components/demos/use-map-demo.tsx
@@ -0,0 +1,79 @@
+"use client";
+
+import { useState } from "react";
+import { useMap } from "hookli";
+import { XIcon } from "@/components/icons";
+import { DemoButton, DemoInput } from "./ui";
+
+/* Docs-page demo (DH1): a tiny key/value editor over a Map held in state. Set
+ writes or updates an entry, each row removes itself, Reset empties the map.
+ Mirrors the usage snippet in lib/hook-docs.ts — keep in sync. */
+export function UseMapDocDemo() {
+ const [map, { set, remove, reset }] = useMap<string, string>([
+ ["theme", "dark"],
+ ["lang", "en"],
+ ]);
+ const [key, setKey] = useState("");
+ const [value, setValue] = useState("");
+
+ const commit = () => {
+ const trimmedKey = key.trim();
+ if (!trimmedKey) return;
+ set(trimmedKey, value.trim());
+ setKey("");
+ setValue("");
+ };
+
+ const entries = [...map.entries()];
+
+ return (
+ <div className="flex w-full max-w-sm flex-col gap-4">
+ <div className="flex items-end gap-2">
+ <DemoInput
+ label="key"
+ value={key}
+ placeholder="key"
+ onChange={(event) => setKey(event.target.value)}
+ onKeyDown={(event) => event.key === "Enter" && commit()}
+ />
+ <DemoInput
+ label="value"
+ value={value}
+ placeholder="value"
+ onChange={(event) => setValue(event.target.value)}
+ onKeyDown={(event) => event.key === "Enter" && commit()}
+ />
+ <DemoButton onClick={commit}>Set</DemoButton>
+ </div>
+
+ {entries.length > 0 ? (
+ <ul className="flex flex-col gap-1.5">
+ {entries.map(([entryKey, entryValue]) => (
+ <li
+ key={entryKey}
+ className="flex items-center justify-between gap-3 rounded-md border border-slate-syntax/40 bg-ground px-3 py-2"
+ >
+ <span className="min-w-0 truncate font-mono text-sm text-fg">
+ <span className="text-accent">{entryKey}</span>
+ <span className="text-slate-syntax"> : </span>
+ <span className="text-gray-body">{entryValue || "—"}</span>
+ </span>
+ <button
+ type="button"
+ onClick={() => remove(entryKey)}
+ aria-label={`Remove ${entryKey}`}
+ className="inline-flex size-8 shrink-0 items-center justify-center rounded-md text-gray-body transition-colors duration-200 hover:text-fg focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent/40"
+ >
+ <XIcon className="size-4" />
+ </button>
+ </li>
+ ))}
+ </ul>
+ ) : (
+ <p className="font-mono text-sm text-gray-body">Map is empty.</p>
+ )}
+
+ <DemoButton onClick={reset}>Reset</DemoButton>
+ </div>
+ );
+}
diff --git a/apps/docs/components/demos/use-media-query-demo.tsx b/apps/docs/components/demos/use-media-query-demo.tsx
new file mode 100644
index 0000000..f0ae3f0
--- /dev/null
+++ b/apps/docs/components/demos/use-media-query-demo.tsx
@@ -0,0 +1,43 @@
+"use client";
+
+import { useMediaQuery } from "hookli";
+import { DemoReadout } from "./ui";
+
+/* Docs-page demo (DH8): live-evaluates a few common media queries. Each is a
+ fixed useMediaQuery call (call order never changes, so the Rules of Hooks
+ hold). SSR-safe — the hook returns its defaultValue (false) on the server and
+ reconciles with window.matchMedia after mount. Resize the window across 768px
+ to watch the first row flip. Mirrors lib/hook-docs.ts — keep in sync. */
+export function UseMediaQueryDocDemo() {
+ const isWide = useMediaQuery("(min-width: 768px)");
+ const isLandscape = useMediaQuery("(orientation: landscape)");
+ const prefersDark = useMediaQuery("(prefers-color-scheme: dark)");
+ const prefersReducedMotion = useMediaQuery(
+ "(prefers-reduced-motion: reduce)",
+ );
+
+ const rows = [
+ { query: "(min-width: 768px)", matches: isWide },
+ { query: "(orientation: landscape)", matches: isLandscape },
+ { query: "(prefers-color-scheme: dark)", matches: prefersDark },
+ { query: "(prefers-reduced-motion: reduce)", matches: prefersReducedMotion },
+ ];
+
+ return (
+ <div className="flex w-full max-w-sm flex-col gap-4">
+ <dl className="w-full">
+ {rows.map(({ query, matches }) => (
+ <DemoReadout key={query} label={query}>
+ <span className={matches ? "text-accent" : "text-gray-body"}>
+ {String(matches)}
+ </span>
+ </DemoReadout>
+ ))}
+ </dl>
+ <p className="text-xs text-gray-body">
+ Resize the window across 768px — the first row flips live as the query
+ starts and stops matching.
+ </p>
+ </div>
+ );
+}
diff --git a/apps/docs/components/demos/use-mouse-position-demo.tsx b/apps/docs/components/demos/use-mouse-position-demo.tsx
new file mode 100644
index 0000000..fab7076
--- /dev/null
+++ b/apps/docs/components/demos/use-mouse-position-demo.tsx
@@ -0,0 +1,58 @@
+"use client";
+
+import { useRef } from "react";
+import { useMousePosition } from "hookli";
+import { DemoReadout } from "./ui";
+
+/* Mirrors the usage snippet in lib/hook-docs.ts — keep in sync. The hook
+ listens on window mousemove and reports coordinates relative to the ref'd
+ element, so values keep updating (and can go negative) outside the panel —
+ overflow-hidden clips the crosshair once it leaves. */
+export function UseMousePositionDocDemo() {
+ const panelRef = useRef<HTMLDivElement>(null);
+ const { x, y } = useMousePosition(panelRef);
+
+ return (
+ <div className="flex w-full max-w-sm flex-col gap-4">
+ <div
+ ref={panelRef}
+ className="relative h-40 overflow-hidden rounded-md border border-slate-syntax/40 bg-ground"
+ >
+ {x !== null && y !== null ? (
+ <>
+ <span
+ aria-hidden="true"
+ className="absolute inset-y-0 w-px bg-accent/30"
+ style={{ left: `${x}px` }}
+ />
+ <span
+ aria-hidden="true"
+ className="absolute inset-x-0 h-px bg-accent/30"
+ style={{ top: `${y}px` }}
+ />
+ <span
+ aria-hidden="true"
+ className="absolute size-2 -translate-x-1/2 -translate-y-1/2 rounded-full bg-accent"
+ style={{ left: `${x}px`, top: `${y}px` }}
+ />
+ </>
+ ) : (
+ <p className="absolute inset-0 flex items-center justify-center font-mono text-xs text-slate-syntax">
+ move your cursor over this panel
+ </p>
+ )}
+ </div>
+ <dl>
+ <DemoReadout label="x">
+ {x === null ? "—" : `${Math.round(x)}px`}
+ </DemoReadout>
+ <DemoReadout label="y">
+ {y === null ? "—" : `${Math.round(y)}px`}
+ </DemoReadout>
+ </dl>
+ <p className="font-mono text-xs text-slate-syntax">
+ Coordinates are measured from the panel's top-left corner.
+ </p>
+ </div>
+ );
+}
diff --git a/apps/docs/components/demos/use-read-local-storage-demo.tsx b/apps/docs/components/demos/use-read-local-storage-demo.tsx
new file mode 100644
index 0000000..7c698dc
--- /dev/null
+++ b/apps/docs/components/demos/use-read-local-storage-demo.tsx
@@ -0,0 +1,45 @@
+"use client";
+
+import { useState } from "react";
+import { useReadLocalStorage } from "hookli";
+import { DemoInput, DemoReadout } from "./ui";
+
+/* Mirrors the usage snippet in lib/hook-docs.ts — keep in sync.
+ useReadLocalStorage only READS the key. The input writes with the raw Web
+ Storage API and dispatches the `local-storage` event the hook listens for, so
+ the read-only value updates live in this tab (a real `storage` event does the
+ same across other tabs). */
+const KEY = "hookli-docs-theme";
+
+export function UseReadLocalStorageDocDemo() {
+ const stored = useReadLocalStorage<string>(KEY);
+ const [draft, setDraft] = useState("");
+
+ const write = (value: string) => {
+ setDraft(value);
+ window.localStorage.setItem(KEY, JSON.stringify(value));
+ window.dispatchEvent(new StorageEvent("local-storage", { key: KEY }));
+ };
+
+ return (
+ <div className="flex w-full max-w-sm flex-col gap-4">
+ <DemoInput
+ label="writer (raw localStorage)"
+ value={draft}
+ onChange={(event) => write(event.target.value)}
+ placeholder="Type — the reader mirrors it"
+ autoComplete="off"
+ />
+ <dl>
+ <DemoReadout label="useReadLocalStorage">{stored ?? "null"}</DemoReadout>
+ </dl>
+ <p className="text-xs text-gray-body">
+ The hook never writes — it observes{" "}
+ <code className="text-fg">{KEY}</code> and re-renders on{" "}
+ <code className="text-fg">storage</code> and{" "}
+ <code className="text-fg">local-storage</code> events, including from
+ other tabs.
+ </p>
+ </div>
+ );
+}
diff --git a/apps/docs/components/demos/use-resize-observer-demo.tsx b/apps/docs/components/demos/use-resize-observer-demo.tsx
new file mode 100644
index 0000000..d8b0717
--- /dev/null
+++ b/apps/docs/components/demos/use-resize-observer-demo.tsx
@@ -0,0 +1,57 @@
+"use client";
+
+import { useRef, useState, type RefObject } from "react";
+import { useResizeObserver } from "hookli";
+import { DemoButton, DemoReadout } from "./ui";
+
+const WIDTHS = [40, 65, 100] as const;
+
+/* Docs-page demo (DH7): the buttons (and the native drag handle) resize the
+ box; ResizeObserver reports the freshly measured content-box size. The
+ observer is created in an effect and disconnected on cleanup, so the demo is
+ SSR-safe (width/height start undefined). Mirrors lib/hook-docs.ts — sync. */
+export function UseResizeObserverDocDemo() {
+ const boxRef = useRef<HTMLDivElement>(null);
+ const [widthPct, setWidthPct] = useState<number>(65);
+
+ // useResizeObserver wants a strict RefObject<T>; React 19's useRef(null) is
+ // RefObject<T | null>. The observer effect guards for null, so this is safe.
+ const { width, height } = useResizeObserver(
+ boxRef as RefObject<HTMLDivElement>,
+ );
+
+ return (
+ <div className="flex w-full max-w-sm flex-col gap-4">
+ <div className="flex flex-wrap gap-2">
+ {WIDTHS.map((pct) => (
+ <DemoButton
+ key={pct}
+ aria-pressed={widthPct === pct}
+ onClick={() => setWidthPct(pct)}
+ >
+ {pct}%
+ </DemoButton>
+ ))}
+ </div>
+ <div
+ ref={boxRef}
+ className="flex min-h-20 resize items-center justify-center overflow-auto rounded-md border border-accent/60 bg-accent/10 p-4 text-center text-sm text-accent transition-[width] duration-200"
+ style={{ width: `${widthPct}%` }}
+ >
+ drag my corner ↘
+ </div>
+ <dl className="w-full">
+ <DemoReadout label="width">
+ {width === undefined ? "—" : `${Math.round(width)}px`}
+ </DemoReadout>
+ <DemoReadout label="height">
+ {height === undefined ? "—" : `${Math.round(height)}px`}
+ </DemoReadout>
+ </dl>
+ <p className="text-xs text-gray-body">
+ Reports element size without a window resize — the values track both the
+ preset buttons and the native drag handle.
+ </p>
+ </div>
+ );
+}
diff --git a/apps/docs/components/demos/use-screen-demo.tsx b/apps/docs/components/demos/use-screen-demo.tsx
new file mode 100644
index 0000000..ca7bc01
--- /dev/null
+++ b/apps/docs/components/demos/use-screen-demo.tsx
@@ -0,0 +1,40 @@
+"use client";
+
+import { useScreen } from "hookli";
+import { DemoReadout } from "./ui";
+
+/* Docs-page demo (DH8): reads window.screen after mount and refreshes it on
+ every window resize. SSR-safe — the hook returns null on the server and until
+ hydration, so every readout falls back to a dash. Mirrors lib/hook-docs.ts. */
+export function UseScreenDocDemo() {
+ const screen = useScreen();
+
+ return (
+ <div className="flex w-full max-w-sm flex-col gap-4">
+ <dl className="w-full">
+ <DemoReadout label="width">
+ {screen ? `${screen.width}px` : "—"}
+ </DemoReadout>
+ <DemoReadout label="height">
+ {screen ? `${screen.height}px` : "—"}
+ </DemoReadout>
+ <DemoReadout label="availWidth">
+ {screen ? `${screen.availWidth}px` : "—"}
+ </DemoReadout>
+ <DemoReadout label="availHeight">
+ {screen ? `${screen.availHeight}px` : "—"}
+ </DemoReadout>
+ <DemoReadout label="colorDepth">
+ {screen ? `${screen.colorDepth}-bit` : "—"}
+ </DemoReadout>
+ <DemoReadout label="orientation">
+ {screen?.orientation ? screen.orientation.type : "—"}
+ </DemoReadout>
+ </dl>
+ <p className="text-xs text-gray-body">
+ Mirrors the physical screen, not the viewport — the values stay put when
+ you resize the window but track a move between displays.
+ </p>
+ </div>
+ );
+}
diff --git a/apps/docs/components/demos/use-script-demo.tsx b/apps/docs/components/demos/use-script-demo.tsx
new file mode 100644
index 0000000..177c53e
--- /dev/null
+++ b/apps/docs/components/demos/use-script-demo.tsx
@@ -0,0 +1,72 @@
+"use client";
+
+import { useState } from "react";
+import { useMediaQuery, useScript } from "hookli";
+import { DemoButton, DemoReadout } from "./ui";
+
+/* A tiny, dependency-free library on a public CDN: loading it defines
+ window.confetti, which is real proof the script became "ready". */
+const CONFETTI_SRC =
+ "https://cdn.jsdelivr.net/npm/canvas-confetti@1.9.3/dist/confetti.browser.min.js";
+
+type ConfettiWindow = Window & {
+ confetti?: (options?: { particleCount?: number; spread?: number }) => void;
+};
+
+const STATUS_TONE: Record<string, string> = {
+ idle: "text-gray-body",
+ loading: "text-accent",
+ ready: "text-accent",
+ error: "text-fg",
+};
+
+/* Docs-page demo (DH9): loads an external <script> on demand and tracks its load
+ status. SSR-safe and never auto-loads — the src stays null until the button
+ click, so the build prerenders and page load stay network-free. Mirrors the
+ usage snippet in lib/hook-docs.ts — keep in sync. */
+export function UseScriptDocDemo() {
+ const [src, setSrc] = useState<string | null>(null);
+ const status = useScript(src, { removeOnUnmount: true });
+ const reducedMotion = useMediaQuery("(prefers-reduced-motion: reduce)");
+
+ function celebrate() {
+ const confetti = (window as ConfettiWindow).confetti;
+ if (confetti) confetti({ particleCount: 90, spread: 70 });
+ }
+
+ return (
+ <div className="flex w-full max-w-sm flex-col gap-4">
+ <dl>
+ <DemoReadout label="status">
+ <span className={STATUS_TONE[status] ?? "text-fg"}>{status}</span>
+ </DemoReadout>
+ <DemoReadout label="window.confetti">
+ {status === "ready" ? "function" : "undefined"}
+ </DemoReadout>
+ </dl>
+ <div className="flex flex-wrap items-center gap-3">
+ <DemoButton
+ onClick={() => setSrc(CONFETTI_SRC)}
+ disabled={src !== null}
+ >
+ {status === "loading" ? "Loading…" : "Load confetti script"}
+ </DemoButton>
+ <DemoButton
+ onClick={celebrate}
+ disabled={status !== "ready" || reducedMotion}
+ >
+ Celebrate
+ </DemoButton>
+ </div>
+ <p className="text-xs text-gray-body">
+ {status === "ready"
+ ? reducedMotion
+ ? "Script loaded — the celebration is disabled while reduced motion is on."
+ : "Script loaded — window.confetti is now callable."
+ : status === "error"
+ ? "The script failed to load (offline or blocked)."
+ : "The <script> tag mounts only when you click — nothing loads on page open."}
+ </p>
+ </div>
+ );
+}
diff --git a/apps/docs/components/demos/use-scroll-lock-demo.tsx b/apps/docs/components/demos/use-scroll-lock-demo.tsx
new file mode 100644
index 0000000..fe82a38
--- /dev/null
+++ b/apps/docs/components/demos/use-scroll-lock-demo.tsx
@@ -0,0 +1,54 @@
+"use client";
+
+import { useState } from "react";
+import { useScrollLock } from "hookli";
+import { DemoButton, DemoReadout } from "./ui";
+
+/* Docs-page demo (DH7): autoLock is OFF and the lock is scoped to this panel
+ (never the page body), so nothing locks on mount — SSR-safe and no surprise
+ page freeze. Lock, then try to scroll the list: overflow flips to hidden.
+ Mirrors the usage snippet in lib/hook-docs.ts — keep in sync. */
+export function UseScrollLockDocDemo() {
+ // lockTarget must be a live element; hold it in state so the hook resolves
+ // the panel once it mounts rather than defaulting to <body>.
+ const [panel, setPanel] = useState<HTMLElement | null>(null);
+
+ const { isLocked, lock, unlock } = useScrollLock({
+ autoLock: false,
+ lockTarget: panel ?? undefined,
+ });
+
+ return (
+ <div className="flex w-full max-w-sm flex-col gap-4">
+ <DemoButton aria-pressed={isLocked} onClick={isLocked ? unlock : lock}>
+ {isLocked ? "Unlock scroll" : "Lock scroll"}
+ </DemoButton>
+ <div
+ ref={setPanel}
+ className="h-40 overflow-y-auto rounded-md border border-slate-syntax/40 bg-ground p-4"
+ >
+ <ul className="flex flex-col gap-2 text-sm text-gray-body">
+ {Array.from({ length: 12 }, (_, i) => (
+ <li
+ key={i}
+ className="rounded border border-slate-syntax/20 px-3 py-2"
+ >
+ Row {i + 1}
+ </li>
+ ))}
+ </ul>
+ </div>
+ <dl className="w-full">
+ <DemoReadout label="isLocked">
+ <span className={isLocked ? "text-accent" : "text-gray-body"}>
+ {String(isLocked)}
+ </span>
+ </DemoReadout>
+ </dl>
+ <p className="text-xs text-gray-body">
+ Lock the panel, then try scrolling the list — perfect for freezing the
+ page behind an open modal or drawer.
+ </p>
+ </div>
+ );
+}
diff --git a/apps/docs/components/demos/use-session-storage-demo.tsx b/apps/docs/components/demos/use-session-storage-demo.tsx
new file mode 100644
index 0000000..4124170
--- /dev/null
+++ b/apps/docs/components/demos/use-session-storage-demo.tsx
@@ -0,0 +1,32 @@
+"use client";
+
+import { useSessionStorage } from "hookli";
+import { DemoButton, DemoInput } from "./ui";
+
+/* Mirrors the usage snippet in lib/hook-docs.ts — keep in sync.
+ Pass a primitive initialValue — the hook re-reads it in its effect deps. */
+export function UseSessionStorageDocDemo() {
+ const [value, setValue, removeValue] = useSessionStorage(
+ "hookli-docs-draft",
+ "",
+ );
+
+ return (
+ <div className="flex w-full max-w-sm flex-col gap-4">
+ <DemoInput
+ label="draft"
+ value={value}
+ onChange={(event) => setValue(event.target.value)}
+ placeholder="Type, then reload — it's still here"
+ autoComplete="off"
+ />
+ <div className="flex items-center justify-between gap-4">
+ <p className="text-xs text-gray-body">
+ Stored under <code className="text-fg">hookli-docs-draft</code> —
+ survives a reload, cleared when the tab closes.
+ </p>
+ <DemoButton onClick={() => removeValue()}>Clear</DemoButton>
+ </div>
+ </div>
+ );
+}
diff --git a/apps/docs/components/demos/use-step-demo.tsx b/apps/docs/components/demos/use-step-demo.tsx
new file mode 100644
index 0000000..9b8abfc
--- /dev/null
+++ b/apps/docs/components/demos/use-step-demo.tsx
@@ -0,0 +1,45 @@
+"use client";
+
+import { useStep } from "hookli";
+import { DemoButton, DemoReadout } from "./ui";
+
+const MAX_STEP = 4;
+
+/* Docs-page demo (DH1): a 1-indexed stepper. Back/Next disable at the bounds via
+ canGoToPrevStep/canGoToNextStep. Mirrors the usage snippet in lib/hook-docs.ts
+ — keep in sync. */
+export function UseStepDocDemo() {
+ const [
+ step,
+ { goToNextStep, goToPrevStep, canGoToNextStep, canGoToPrevStep, reset },
+ ] = useStep(MAX_STEP);
+
+ return (
+ <div className="flex flex-col items-center gap-5">
+ <div className="flex items-center gap-2" aria-hidden="true">
+ {Array.from({ length: MAX_STEP }, (_, i) => (
+ <span
+ key={i}
+ className={`size-3 rounded-full transition-colors duration-200 ${
+ i + 1 <= step ? "bg-accent" : "bg-slate-syntax/50"
+ }`}
+ />
+ ))}
+ </div>
+ <dl className="w-full max-w-xs">
+ <DemoReadout label="step">
+ {step} / {MAX_STEP}
+ </DemoReadout>
+ </dl>
+ <div className="flex flex-wrap justify-center gap-3">
+ <DemoButton onClick={goToPrevStep} disabled={!canGoToPrevStep}>
+ Back
+ </DemoButton>
+ <DemoButton onClick={goToNextStep} disabled={!canGoToNextStep}>
+ Next
+ </DemoButton>
+ <DemoButton onClick={reset}>Reset</DemoButton>
+ </div>
+ </div>
+ );
+}
diff --git a/apps/docs/components/demos/use-ternary-dark-mode-demo.tsx b/apps/docs/components/demos/use-ternary-dark-mode-demo.tsx
new file mode 100644
index 0000000..6da9aaa
--- /dev/null
+++ b/apps/docs/components/demos/use-ternary-dark-mode-demo.tsx
@@ -0,0 +1,76 @@
+"use client";
+
+import { useSyncExternalStore } from "react";
+import { useTernaryDarkMode } from "hookli";
+import { DemoButton, DemoReadout } from "./ui";
+
+/* Hydration gate: false on the server and during hydration, true after. The
+ resolved isDarkMode reads the OS media query, so styling waits for mount to
+ avoid a mismatch. */
+const emptySubscribe = () => () => {};
+function useMounted() {
+ return useSyncExternalStore(
+ emptySubscribe,
+ () => true,
+ () => false,
+ );
+}
+
+const MODES = ["light", "system", "dark"] as const;
+
+/* Docs-page demo (DH9): a three-state theme preference — light / system / dark —
+ persisted to localStorage and resolved against the OS color scheme. The mode
+ is scoped to the preview panel, so the docs stay dark either way. Mirrors the
+ usage snippet in lib/hook-docs.ts — keep in sync. */
+export function UseTernaryDarkModeDocDemo() {
+ const { isDarkMode, ternaryDarkMode, setTernaryDarkMode, toggleTernaryDarkMode } =
+ useTernaryDarkMode({ localStorageKey: "hookli-docs-ternary-theme" });
+ const mounted = useMounted();
+ const dark = mounted && isDarkMode;
+
+ return (
+ <div className="flex w-full max-w-sm flex-col gap-4">
+ <div
+ role="group"
+ aria-label="Theme preference"
+ className="flex gap-2"
+ >
+ {MODES.map((mode) => (
+ <button
+ key={mode}
+ type="button"
+ onClick={() => setTernaryDarkMode(mode)}
+ aria-pressed={ternaryDarkMode === mode}
+ className="min-h-11 flex-1 rounded-md border border-slate-syntax/40 px-3 font-mono text-sm capitalize text-gray-body transition-colors duration-200 hover:border-slate-syntax hover:text-fg aria-pressed:border-accent/60 aria-pressed:bg-accent/10 aria-pressed:text-accent"
+ >
+ {mode}
+ </button>
+ ))}
+ </div>
+ <div
+ className={`rounded-lg border p-4 transition-colors duration-200 ${
+ dark
+ ? "border-slate-syntax/40 bg-ground"
+ : "border-slate-300 bg-slate-50"
+ }`}
+ >
+ <p className={`font-mono text-sm ${dark ? "text-fg" : "text-ground"}`}>
+ {dark ? "Resolved: dark" : "Resolved: light"}
+ </p>
+ <p className={`mt-2 text-xs ${dark ? "text-gray-body" : "text-slate-syntax"}`}>
+ “system” follows your OS setting — the other two force a mode.
+ </p>
+ </div>
+ <dl>
+ <DemoReadout label="ternaryDarkMode">{ternaryDarkMode}</DemoReadout>
+ <DemoReadout label="isDarkMode">{String(dark)}</DemoReadout>
+ </dl>
+ <div className="flex items-center justify-between gap-4">
+ <p className="text-xs text-gray-body">
+ The choice persists — reload and the panel keeps its mode.
+ </p>
+ <DemoButton onClick={toggleTernaryDarkMode}>Cycle</DemoButton>
+ </div>
+ </div>
+ );
+}
diff --git a/apps/docs/components/demos/use-timeout-demo.tsx b/apps/docs/components/demos/use-timeout-demo.tsx
new file mode 100644
index 0000000..cf5053a
--- /dev/null
+++ b/apps/docs/components/demos/use-timeout-demo.tsx
@@ -0,0 +1,51 @@
+"use client";
+
+import { useState } from "react";
+import { useTimeout } from "hookli";
+import { DemoButton, DemoReadout } from "./ui";
+
+/* Docs-page demo (DH2): a one-shot delayed reveal. Arm sets the delay so
+ useTimeout schedules the callback; the callback reveals the message and sets
+ delay back to null so the timer disarms and can be re-armed. Cancel sets
+ delay to null while pending — the built-in clearTimeout. SSR-safe (the timer
+ lives in an effect). Mirrors the usage snippet in lib/hook-docs.ts. */
+export function UseTimeoutDocDemo() {
+ const [delay, setDelay] = useState<number | null>(null);
+ const [fired, setFired] = useState(false);
+
+ useTimeout(() => {
+ setFired(true);
+ setDelay(null);
+ }, delay);
+
+ const pending = delay !== null;
+
+ return (
+ <div className="flex flex-col items-center gap-5">
+ <p
+ role="status"
+ aria-live="polite"
+ className="flex min-h-16 w-full max-w-xs items-center justify-center rounded-md border border-slate-syntax/40 bg-ground px-4 text-center font-mono text-sm text-fg"
+ >
+ {fired ? "Timeout fired" : pending ? "Waiting 2s…" : "Idle — arm the timeout"}
+ </p>
+ <dl className="w-full max-w-xs">
+ <DemoReadout label="delay">{pending ? `${delay} ms` : "null"}</DemoReadout>
+ </dl>
+ <div className="flex flex-wrap justify-center gap-3">
+ <DemoButton
+ onClick={() => {
+ setFired(false);
+ setDelay(2000);
+ }}
+ disabled={pending}
+ >
+ Arm (2s)
+ </DemoButton>
+ <DemoButton onClick={() => setDelay(null)} disabled={!pending}>
+ Cancel
+ </DemoButton>
+ </div>
+ </div>
+ );
+}
diff --git a/apps/docs/components/demos/use-toggle-demo.tsx b/apps/docs/components/demos/use-toggle-demo.tsx
new file mode 100644
index 0000000..b868f09
--- /dev/null
+++ b/apps/docs/components/demos/use-toggle-demo.tsx
@@ -0,0 +1,54 @@
+"use client";
+
+import { useToggle } from "hookli";
+import { DemoButton } from "./ui";
+
+/* Live proof for the landing page: same logic as the LightSwitch sample shown
+ beside it (components/live-proof-section.tsx), imported from the published
+ `hookli` package — styling classes are the only addition. */
+export function UseToggleDemo() {
+ const [on, toggle] = useToggle(false);
+
+ return <Switch on={on} onToggle={toggle} />;
+}
+
+/* Docs-page reference demo (T6): exercises the full tuple — toggle plus the
+ explicit setter. Mirrors the usage snippet in lib/hook-docs.ts — keep in sync. */
+export function UseToggleDocDemo() {
+ const [on, toggle, setOn] = useToggle(false);
+
+ return (
+ <div className="flex flex-col items-center gap-5">
+ <Switch on={on} onToggle={toggle} />
+ <div className="flex gap-3">
+ <DemoButton onClick={() => setOn(true)}>Set on</DemoButton>
+ <DemoButton onClick={() => setOn(false)}>Set off</DemoButton>
+ </div>
+ </div>
+ );
+}
+
+function Switch({ on, onToggle }: { on: boolean; onToggle: () => void }) {
+ return (
+ <button
+ type="button"
+ onClick={onToggle}
+ aria-pressed={on}
+ className="group flex min-h-11 items-center gap-3 rounded-full border border-slate-syntax/40 bg-ground py-2 pl-2 pr-5 transition-colors duration-200 hover:border-slate-syntax"
+ >
+ <span
+ aria-hidden="true"
+ className={`flex h-7 w-12 items-center rounded-full p-1 transition-colors duration-200 ${
+ on ? "bg-accent" : "bg-slate-syntax/60"
+ }`}
+ >
+ <span
+ className={`size-5 rounded-full bg-ground transition-transform duration-200 ${
+ on ? "translate-x-5" : "translate-x-0"
+ }`}
+ />
+ </span>
+ <span className="font-mono text-sm text-fg">{on ? "On" : "Off"}</span>
+ </button>
+ );
+}
diff --git a/apps/docs/components/demos/use-unmount-demo.tsx b/apps/docs/components/demos/use-unmount-demo.tsx
new file mode 100644
index 0000000..405178b
--- /dev/null
+++ b/apps/docs/components/demos/use-unmount-demo.tsx
@@ -0,0 +1,46 @@
+"use client";
+
+import { useState } from "react";
+import { useUnmount } from "hookli";
+import { DemoButton, DemoReadout } from "./ui";
+
+/* Docs-page demo (DH3): a child registers a cleanup with useUnmount; toggling
+ the parent state unmounts it, firing the callback exactly once. The counter
+ proves the cleanup runs on every unmount, not on re-render. SSR-safe: no
+ browser APIs. Mirrors the usage snippet in lib/hook-docs.ts — keep in sync. */
+function CleanupChild({ onUnmount }: { onUnmount: () => void }) {
+ useUnmount(onUnmount);
+
+ return (
+ <div className="flex h-16 w-full items-center justify-center rounded-md border border-accent/60 bg-accent/10 font-mono text-sm text-accent">
+ mounted — cleanup armed
+ </div>
+ );
+}
+
+export function UseUnmountDocDemo() {
+ const [mounted, setMounted] = useState(true);
+ const [cleanups, setCleanups] = useState(0);
+
+ return (
+ <div className="flex w-full flex-col items-center gap-5">
+ <div className="flex h-16 w-full max-w-md items-center justify-center">
+ {mounted ? (
+ <CleanupChild onUnmount={() => setCleanups((prev) => prev + 1)} />
+ ) : (
+ <p className="font-mono text-sm text-gray-body">unmounted</p>
+ )}
+ </div>
+ <dl className="w-full max-w-xs">
+ <DemoReadout label="status">{mounted ? "mounted" : "unmounted"}</DemoReadout>
+ <DemoReadout label="cleanups run">{cleanups}</DemoReadout>
+ </dl>
+ <DemoButton
+ onClick={() => setMounted((prev) => !prev)}
+ aria-pressed={mounted}
+ >
+ {mounted ? "Unmount" : "Mount"}
+ </DemoButton>
+ </div>
+ );
+}
diff --git a/apps/docs/components/demos/use-window-size-demo.tsx b/apps/docs/components/demos/use-window-size-demo.tsx
new file mode 100644
index 0000000..7054fb1
--- /dev/null
+++ b/apps/docs/components/demos/use-window-size-demo.tsx
@@ -0,0 +1,41 @@
+"use client";
+
+import { useWindowSize } from "hookli";
+import { DemoReadout } from "./ui";
+
+/* Tailwind's default breakpoint ladder, largest first, for the derived label. */
+const BREAKPOINTS = [
+ { label: "2xl", min: 1536 },
+ { label: "xl", min: 1280 },
+ { label: "lg", min: 1024 },
+ { label: "md", min: 768 },
+ { label: "sm", min: 640 },
+] as const;
+
+function breakpointFor(width: number): string {
+ if (width === 0) return "—";
+ return BREAKPOINTS.find((bp) => width >= bp.min)?.label ?? "xs";
+}
+
+/* Docs-page demo (DH8): tracks the viewport's { width, height } and updates on
+ every resize event. SSR-safe — both values start at 0 before hydration, so
+ the readouts fall back to a dash. Mirrors lib/hook-docs.ts — keep in sync. */
+export function UseWindowSizeDocDemo() {
+ const { width, height } = useWindowSize();
+
+ return (
+ <div className="flex w-full max-w-sm flex-col gap-4">
+ <dl className="w-full">
+ <DemoReadout label="width">{width ? `${width}px` : "—"}</DemoReadout>
+ <DemoReadout label="height">{height ? `${height}px` : "—"}</DemoReadout>
+ <DemoReadout label="breakpoint">
+ <span className="text-accent">{breakpointFor(width)}</span>
+ </DemoReadout>
+ </dl>
+ <p className="text-xs text-gray-body">
+ Resize the window — both values update on every resize event, and the
+ breakpoint label tracks Tailwind’s default ladder.
+ </p>
+ </div>
+ );
+}
diff --git a/apps/docs/components/donate-button.tsx b/apps/docs/components/donate-button.tsx
new file mode 100644
index 0000000..3da2e6e
--- /dev/null
+++ b/apps/docs/components/donate-button.tsx
@@ -0,0 +1,26 @@
+"use client";
+
+import { KofiIcon } from "@/components/icons";
+import { KOFI_URL } from "@/lib/site";
+
+/* Persistent floating support CTA (bottom-right, every route — mounted once in
+ app/layout.tsx). Collapsed it's a 56px accent circle; on hover/focus it
+ expands to reveal the label. A gentle idle bob draws the eye — the global
+ prefers-reduced-motion guard (globals.css) neutralises it. Opens Ko-fi in a
+ new tab. */
+export function DonateButton() {
+ return (
+ <a
+ href={KOFI_URL}
+ target="_blank"
+ rel="noopener noreferrer"
+ aria-label="Support hookli — buy me a coffee on Ko-fi"
+ className="donate-float group fixed bottom-5 right-5 z-50 flex h-14 items-center gap-0 overflow-hidden rounded-full bg-accent pl-4 pr-4 font-semibold text-ground shadow-lg shadow-accent/30 ring-1 ring-inset ring-fg/10 transition-[padding,box-shadow] duration-200 ease-out hover:gap-2.5 hover:pr-5 hover:shadow-xl hover:shadow-accent/40 focus-visible:gap-2.5 focus-visible:pr-5"
+ >
+ <KofiIcon className="size-6 shrink-0" />
+ <span className="max-w-0 whitespace-nowrap text-sm opacity-0 transition-[max-width,opacity] duration-200 ease-out group-hover:max-w-40 group-hover:opacity-100 group-focus-visible:max-w-40 group-focus-visible:opacity-100">
+ Buy me a coffee
+ </span>
+ </a>
+ );
+}
diff --git a/apps/docs/components/feature-card.tsx b/apps/docs/components/feature-card.tsx
new file mode 100644
index 0000000..e9e6af4
--- /dev/null
+++ b/apps/docs/components/feature-card.tsx
@@ -0,0 +1,19 @@
+export function FeatureCard({
+ icon,
+ title,
+ body,
+}: {
+ icon: React.ReactNode;
+ title: string;
+ body: string;
+}) {
+ return (
+ <div className="surface surface-lift rounded-xl p-6">
+ <span className="flex size-11 items-center justify-center rounded-lg bg-accent/10 text-accent ring-1 ring-inset ring-accent/20">
+ {icon}
+ </span>
+ <h3 className="mt-5 text-lg font-semibold">{title}</h3>
+ <p className="mt-2 text-sm leading-relaxed text-gray-body">{body}</p>
+ </div>
+ );
+}
diff --git a/apps/docs/components/features-section.tsx b/apps/docs/components/features-section.tsx
new file mode 100644
index 0000000..0924777
--- /dev/null
+++ b/apps/docs/components/features-section.tsx
@@ -0,0 +1,54 @@
+import { FeatureCard } from "@/components/feature-card";
+import { SectionHeading } from "@/components/section-heading";
+import { BlocksIcon, BracesIcon, FeatherIcon, LeafIcon, PackageIcon, ServerIcon } from "@/components/icons";
+import { HOOKS } from "@/lib/hooks-registry";
+
+const FEATURES = [
+ {
+ icon: <FeatherIcon className="size-6" />,
+ title: "Zero dependencies",
+ body: "The only thing you install is the hooks. No runtime deps, no transitive surprises, nothing to audit twice.",
+ },
+ {
+ icon: <BracesIcon className="size-6" />,
+ title: "TypeScript-first",
+ body: "Written in TypeScript, shipped with full definitions. Generics and inference just work — no @types hunt.",
+ },
+ {
+ icon: <ServerIcon className="size-6" />,
+ title: "SSR-safe",
+ body: "Browser APIs are guarded behind effects, so Next.js and friends prerender without a single window crash.",
+ },
+ {
+ icon: <LeafIcon className="size-6" />,
+ title: "Tree-shakable",
+ body: "Import one hook, ship one hook. Bundlers drop everything you don't use.",
+ },
+ {
+ icon: <PackageIcon className="size-6" />,
+ title: "ESM + CJS",
+ body: "Dual builds out of the box — modern bundlers, legacy tooling, and everything in between.",
+ },
+ {
+ icon: <BlocksIcon className="size-6" />,
+ title: `${HOOKS.length} hooks & counting`,
+ body: "State, storage, DOM, and data — the hooks you rewrite in every project, done once and typed.",
+ },
+];
+
+export function FeaturesSection() {
+ return (
+ <section className="mx-auto w-full max-w-5xl px-4 py-20 sm:px-6">
+ <SectionHeading
+ eyebrow="Why hookli"
+ title="The hooks you keep rewriting"
+ subtitle="Small enough to read in an afternoon, solid enough to ship everywhere."
+ />
+ <div className="mt-12 grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
+ {FEATURES.map((feature) => (
+ <FeatureCard key={feature.title} {...feature} />
+ ))}
+ </div>
+ </section>
+ );
+}
diff --git a/apps/docs/components/footer.tsx b/apps/docs/components/footer.tsx
new file mode 100644
index 0000000..a235485
--- /dev/null
+++ b/apps/docs/components/footer.tsx
@@ -0,0 +1,50 @@
+import Link from "next/link";
+import { Wordmark } from "./wordmark";
+import { GITHUB_URL, NPM_URL } from "@/lib/site";
+
+export function Footer() {
+ return (
+ <footer className="border-t border-slate-syntax/40">
+ <div className="mx-auto flex w-full max-w-6xl flex-col gap-8 px-4 py-10 sm:px-6 md:flex-row md:items-center md:justify-between">
+ <div className="flex flex-col gap-3">
+ <Link href="/" aria-label="hookli — home" className="w-fit rounded-md">
+ <Wordmark size="sm" />
+ </Link>
+ <code className="w-fit rounded-md border border-slate-syntax/40 bg-ground-raised px-3 py-1.5 text-sm text-gray-body">
+ npm i <span className="text-accent">hookli</span>
+ </code>
+ </div>
+ <nav
+ aria-label="Footer"
+ className="flex flex-wrap items-center gap-x-2 gap-y-1 text-sm"
+ >
+ <a
+ href={NPM_URL}
+ target="_blank"
+ rel="noopener noreferrer"
+ className="flex min-h-11 items-center rounded-md px-2 text-gray-body transition-colors duration-200 hover:text-fg"
+ >
+ npm
+ </a>
+ <a
+ href={GITHUB_URL}
+ target="_blank"
+ rel="noopener noreferrer"
+ className="flex min-h-11 items-center rounded-md px-2 text-gray-body transition-colors duration-200 hover:text-fg"
+ >
+ GitHub
+ </a>
+ <Link
+ href="/support"
+ className="flex min-h-11 items-center rounded-md px-2 text-gray-body transition-colors duration-200 hover:text-fg"
+ >
+ Support
+ </Link>
+ <span className="flex min-h-11 items-center px-2 text-gray-body">
+ ISC License
+ </span>
+ </nav>
+ </div>
+ </footer>
+ );
+}
diff --git a/apps/docs/components/header.tsx b/apps/docs/components/header.tsx
new file mode 100644
index 0000000..de5f62a
--- /dev/null
+++ b/apps/docs/components/header.tsx
@@ -0,0 +1,45 @@
+import Link from "next/link";
+import { HookMark, Wordmark } from "./wordmark";
+import { GitHubIcon } from "./icons";
+import { SearchPalette } from "./search-palette";
+import { GITHUB_URL } from "@/lib/site";
+
+export function Header() {
+ return (
+ <header className="sticky top-0 z-40 border-b border-slate-syntax/40 bg-ground/90 backdrop-blur">
+ <div className="mx-auto flex h-14 w-full max-w-6xl items-center justify-between px-4 sm:px-6">
+ {/* Left: logo + primary nav */}
+ <nav aria-label="Main" className="flex items-center gap-6">
+ <Link
+ href="/"
+ aria-label="hookli — home"
+ className="flex min-h-11 items-center gap-2 rounded-md"
+ >
+ <HookMark className="h-5 w-auto" />
+ <Wordmark size="sm" />
+ </Link>
+ <Link
+ href="/docs"
+ className="flex min-h-11 items-center text-sm text-gray-body transition-colors duration-200 hover:text-fg"
+ >
+ Docs
+ </Link>
+ </nav>
+
+ {/* Right: search + GitHub */}
+ <div className="flex items-center gap-1">
+ <SearchPalette />
+ <a
+ href={GITHUB_URL}
+ target="_blank"
+ rel="noopener noreferrer"
+ aria-label="hookli on GitHub"
+ className="flex size-11 items-center justify-center rounded-md text-gray-body transition-colors duration-200 hover:text-fg"
+ >
+ <GitHubIcon className="size-5" />
+ </a>
+ </div>
+ </div>
+ </header>
+ );
+}
diff --git a/apps/docs/components/hook-card.tsx b/apps/docs/components/hook-card.tsx
new file mode 100644
index 0000000..abff1fd
--- /dev/null
+++ b/apps/docs/components/hook-card.tsx
@@ -0,0 +1,18 @@
+import Link from "next/link";
+import type { HookEntry } from "@/lib/hooks-registry";
+
+export function HookCard({ hook }: { hook: HookEntry }) {
+ return (
+ <Link
+ href={`/docs/${hook.slug}`}
+ className="surface surface-lift group flex flex-col gap-1 rounded-xl p-4"
+ >
+ <span className="text-sm font-semibold transition-colors duration-200 group-hover:text-accent">
+ {hook.name}
+ </span>
+ <span className="text-sm leading-relaxed text-gray-body">
+ {hook.description}
+ </span>
+ </Link>
+ );
+}
diff --git a/apps/docs/components/hook-demo.tsx b/apps/docs/components/hook-demo.tsx
new file mode 100644
index 0000000..26095b9
--- /dev/null
+++ b/apps/docs/components/hook-demo.tsx
@@ -0,0 +1,109 @@
+"use client";
+
+import { useId, useRef, useState } from "react";
+import { DemoErrorBoundary } from "@/components/demo-error-boundary";
+
+const TABS = [
+ { id: "preview", label: "Preview" },
+ { id: "code", label: "Code" },
+] as const;
+
+type TabId = (typeof TABS)[number]["id"];
+
+/* The frame every hook page's live demo renders in (docs/DESIGN.md §4):
+ Preview/Code tabs, ground-raised card, error boundary around the demo. Both
+ panels stay mounted so demo state survives tab switches. `code` arrives
+ pre-rendered from the server page — shiki never ships to the client. */
+export function HookDemo({
+ preview,
+ code,
+ className = "",
+}: {
+ preview: React.ReactNode;
+ code: React.ReactNode;
+ className?: string;
+}) {
+ const [active, setActive] = useState<TabId>("preview");
+ const tabRefs = useRef<Map<TabId, HTMLButtonElement>>(new Map());
+ const baseId = useId();
+
+ function activate(tab: TabId) {
+ setActive(tab);
+ tabRefs.current.get(tab)?.focus();
+ }
+
+ function onKeyDown(event: React.KeyboardEvent) {
+ const index = TABS.findIndex((tab) => tab.id === active);
+ if (event.key === "ArrowRight") {
+ event.preventDefault();
+ activate(TABS[(index + 1) % TABS.length].id);
+ } else if (event.key === "ArrowLeft") {
+ event.preventDefault();
+ activate(TABS[(index - 1 + TABS.length) % TABS.length].id);
+ } else if (event.key === "Home") {
+ event.preventDefault();
+ activate(TABS[0].id);
+ } else if (event.key === "End") {
+ event.preventDefault();
+ activate(TABS[TABS.length - 1].id);
+ }
+ }
+
+ return (
+ <div
+ className={`surface overflow-hidden rounded-xl ${className}`}
+ >
+ <div className="flex items-center justify-between border-b border-slate-syntax/40 px-2">
+ <div
+ role="tablist"
+ aria-label="Demo view"
+ onKeyDown={onKeyDown}
+ className="flex"
+ >
+ {TABS.map((tab) => (
+ <button
+ key={tab.id}
+ ref={(el) => {
+ if (el) tabRefs.current.set(tab.id, el);
+ }}
+ type="button"
+ role="tab"
+ id={`${baseId}-tab-${tab.id}`}
+ aria-selected={active === tab.id}
+ aria-controls={`${baseId}-panel-${tab.id}`}
+ tabIndex={active === tab.id ? 0 : -1}
+ onClick={() => setActive(tab.id)}
+ className={`-mb-px min-h-11 border-b-2 px-4 text-xs transition-colors duration-200 ${
+ active === tab.id
+ ? "border-accent text-fg"
+ : "border-transparent text-gray-body hover:text-fg"
+ }`}
+ >
+ {tab.label}
+ </button>
+ ))}
+ </div>
+ <span className="hidden px-2 text-xs text-gray-body sm:inline">
+ live · imported from hookli
+ </span>
+ </div>
+ <div
+ role="tabpanel"
+ id={`${baseId}-panel-preview`}
+ aria-labelledby={`${baseId}-tab-preview`}
+ hidden={active !== "preview"}
+ className="flex min-h-[180px] items-center justify-center p-8"
+ >
+ <DemoErrorBoundary>{preview}</DemoErrorBoundary>
+ </div>
+ <div
+ role="tabpanel"
+ id={`${baseId}-panel-code`}
+ aria-labelledby={`${baseId}-tab-code`}
+ hidden={active !== "code"}
+ >
+ {code}
+ </div>
+ </div>
+ );
+}
diff --git a/apps/docs/components/hook-page.tsx b/apps/docs/components/hook-page.tsx
new file mode 100644
index 0000000..a1a44f8
--- /dev/null
+++ b/apps/docs/components/hook-page.tsx
@@ -0,0 +1,170 @@
+import Link from "next/link";
+import { ApiTable } from "@/components/api-table";
+import { CodeBlock, HighlightedCode } from "@/components/code-block";
+import { HookCard } from "@/components/hook-card";
+import { HookDemo } from "@/components/hook-demo";
+import { ArrowRightIcon, ExternalLinkIcon } from "@/components/icons";
+import { OnThisPage, type TocItem } from "@/components/on-this-page";
+import { getHookDoc } from "@/lib/hook-docs";
+import { getHookSource, hookSourceUrl } from "@/lib/hook-sources";
+import { CATEGORY_LABELS, HOOKS, relatedHooks, type HookEntry } from "@/lib/hooks-registry";
+import { GITHUB_URL } from "@/lib/site";
+import { linkifyWebApis } from "@/lib/web-apis";
+
+/* THE hook-page template (T16 usehooks-ts anatomy parity). Every page under
+ app/docs/[slug] is this one component driven by the registry + HOOK_DOCS +
+ hook-sources data — no per-hook layout exists. Adding a hook needs only a
+ registry entry, a HOOK_DOCS entry and one demo component.
+
+ Anatomy: category → title → linked one-liner → Demo → Usage (line-numbered,
+ hook-call line highlighted) → API (signature, Parameters w/ default chips,
+ Returns, type-alias tables) → Hook (vendored source) → pager. A right-rail
+ On-This-Page TOC + support slot sits alongside from xl up. */
+
+const headingClass = "scroll-mt-24 text-2xl";
+
+export function HookPage({ hook }: { hook: HookEntry }) {
+ const doc = getHookDoc(hook.slug);
+ const source = getHookSource(hook.slug);
+
+ const index = HOOKS.findIndex((entry) => entry.slug === hook.slug);
+ const prev = index > 0 ? HOOKS[index - 1] : undefined;
+ const next = index < HOOKS.length - 1 ? HOOKS[index + 1] : undefined;
+ const related = relatedHooks(hook.slug);
+
+ /* Highlight the line that actually calls the hook in the Usage snippet. */
+ const usageLines = doc?.usage.trim().split("\n") ?? [];
+ const callIndex = usageLines.findIndex((line) => line.includes(`${hook.name}(`));
+ const highlightLine = callIndex >= 0 ? callIndex + 1 : undefined;
+
+ const toc: TocItem[] = [
+ ...(doc ? [{ id: "demo", label: "Demo" }] : []),
+ ...(doc ? [{ id: "usage", label: "Usage" }] : []),
+ { id: "api", label: "API" },
+ ...(source ? [{ id: "hook", label: "Hook" }] : []),
+ ];
+
+ return (
+ <div className="flex gap-10">
+ <article className="min-w-0 max-w-3xl flex-1">
+ <p className="text-xs font-semibold uppercase tracking-wider text-slate-syntax">{CATEGORY_LABELS[hook.category]}</p>
+ <h1 className="mt-2 text-3xl sm:text-4xl">{hook.name}</h1>
+ <p className="mt-4 leading-relaxed text-gray-body">{linkifyWebApis(hook.description)}</p>
+
+ {doc && (
+ <>
+ <h2 id="demo" className={`mt-10 ${headingClass}`}>
+ Demo
+ </h2>
+ <HookDemo className="mt-4" preview={<doc.demo />} code={<HighlightedCode code={doc.usage} />} />
+
+ <h2 id="usage" className={`mt-12 ${headingClass}`}>
+ Usage
+ </h2>
+ <CodeBlock code={doc.usage} lang="tsx" title={`${hook.slug}.tsx`} lineNumbers highlightLine={highlightLine} className="mt-4" />
+ </>
+ )}
+
+ <h2 id="api" className={`mt-12 ${headingClass}`}>
+ API
+ </h2>
+ <CodeBlock code={hook.signature} lang="ts" title={`${hook.name}.d.ts`} className="mt-4" />
+
+ {doc && (
+ <>
+ <h3 className="mt-8 scroll-mt-24 text-lg">Parameters</h3>
+ {doc.parameters.length > 0 ? <ApiTable rows={doc.parameters} withDefault className="mt-4" /> : <p className="mt-4 text-sm text-gray-body">This hook takes no parameters.</p>}
+
+ <h3 className="mt-8 scroll-mt-24 text-lg">Returns</h3>
+ {doc.returns.length > 0 ? <ApiTable rows={doc.returns} className="mt-4" /> : <p className="mt-4 text-sm text-gray-body">This hook returns nothing.</p>}
+
+ {doc.typeAliases?.map((alias) => (
+ <div key={alias.name} className="mt-8">
+ <h3 className="scroll-mt-24 font-mono text-lg text-fg">{alias.name}</h3>
+ {alias.description && <p className="mt-2 text-sm text-gray-body">{alias.description}</p>}
+ <ApiTable rows={alias.rows} className="mt-4" />
+ </div>
+ ))}
+ </>
+ )}
+
+ {source && (
+ <>
+ <h2 id="hook" className={`mt-12 ${headingClass}`}>
+ Hook
+ </h2>
+ <p className="mt-4 text-sm text-gray-body">The implementation, straight from hookli. Copy it, or install the package.</p>
+ <CodeBlock code={source.source} lang="tsx" title={source.path} lineNumbers className="mt-4" />
+ <p className="mt-4 text-sm">
+ <a
+ href={hookSourceUrl(source.path)}
+ target="_blank"
+ rel="noopener noreferrer"
+ className="inline-flex min-h-11 items-center gap-1.5 rounded-md text-accent underline-offset-4 hover:underline"
+ >
+ View source on GitHub
+ <ExternalLinkIcon className="size-4" aria-hidden="true" />
+ </a>
+ </p>
+ </>
+ )}
+
+ {!source && (
+ <p className="mt-12 text-sm">
+ <a href={GITHUB_URL} target="_blank" rel="noopener noreferrer" className="inline-flex min-h-11 items-center gap-1.5 rounded-md text-accent underline-offset-4 hover:underline">
+ View source on GitHub
+ <ExternalLinkIcon className="size-4" aria-hidden="true" />
+ </a>
+ </p>
+ )}
+
+ {related.length > 0 && (
+ <section aria-label="Related hooks" className="mt-14">
+ <h2 className="text-xs font-semibold uppercase tracking-[0.14em] text-slate-syntax">Related hooks</h2>
+ <div className="mt-4 grid gap-3 sm:grid-cols-2">
+ {related.map((entry) => (
+ <HookCard key={entry.slug} hook={entry} />
+ ))}
+ </div>
+ </section>
+ )}
+
+ <nav aria-label="Adjacent hooks" className="mt-12 flex items-center justify-between gap-4 border-t border-slate-syntax/40 pt-6">
+ {prev ? (
+ <Link href={`/docs/${prev.slug}`} className="inline-flex min-h-11 items-center gap-2 rounded-md text-sm text-gray-body transition-colors duration-200 hover:text-fg">
+ <ArrowRightIcon className="size-4 rotate-180" aria-hidden="true" />
+ {prev.name}
+ </Link>
+ ) : (
+ <span aria-hidden="true" />
+ )}
+ {next ? (
+ <Link href={`/docs/${next.slug}`} className="inline-flex min-h-11 items-center gap-2 rounded-md text-sm text-gray-body transition-colors duration-200 hover:text-fg">
+ {next.name}
+ <ArrowRightIcon className="size-4" aria-hidden="true" />
+ </Link>
+ ) : (
+ <span aria-hidden="true" />
+ )}
+ </nav>
+ </article>
+
+ <aside className="hidden w-56 shrink-0 xl:block">
+ <div className="sticky top-24 flex flex-col gap-8">
+ <OnThisPage items={toc} />
+
+ {/* Support slot — placeholder consistent with T12 (no real payment
+ links; the real donation surface lives on /support). */}
+ <div className="surface rounded-xl p-4">
+ <p className="text-sm font-semibold text-fg">Support hookli</p>
+ <p className="mt-1 text-xs leading-relaxed text-gray-body">Free and open source. Star it or help it grow.</p>
+ <Link href="/support" className="mt-3 inline-flex min-h-11 items-center gap-1 text-sm text-accent underline-offset-4 hover:underline">
+ Ways to support
+ <ArrowRightIcon className="size-4" aria-hidden="true" />
+ </Link>
+ </div>
+ </div>
+ </aside>
+ </div>
+ );
+}
diff --git a/apps/docs/components/hooks-index-section.tsx b/apps/docs/components/hooks-index-section.tsx
new file mode 100644
index 0000000..ce9ecd3
--- /dev/null
+++ b/apps/docs/components/hooks-index-section.tsx
@@ -0,0 +1,34 @@
+import { HookCard } from "@/components/hook-card";
+import { SectionHeading } from "@/components/section-heading";
+import {
+ CATEGORY_LABELS,
+ CATEGORY_ORDER,
+ HOOKS,
+ hooksByCategory,
+} from "@/lib/hooks-registry";
+
+/* Landing hooks-index strip (docs/DESIGN.md §3.4): every hook as a compact
+ linked card, grouped by category — same HookCard as the /docs index. */
+export function HooksIndexSection() {
+ return (
+ <section className="mx-auto w-full max-w-5xl px-4 py-20 sm:px-6">
+ <SectionHeading
+ eyebrow="The library"
+ title={`All ${HOOKS.length} hooks`}
+ subtitle="Each one documented with a live demo — try it before you install it."
+ />
+ {CATEGORY_ORDER.map((category) => (
+ <div key={category} className="mt-12">
+ <h3 className="text-xs font-semibold uppercase tracking-wider text-slate-syntax">
+ {CATEGORY_LABELS[category]}
+ </h3>
+ <div className="mt-3 grid gap-3 sm:grid-cols-2 lg:grid-cols-3">
+ {hooksByCategory(category).map((hook) => (
+ <HookCard key={hook.slug} hook={hook} />
+ ))}
+ </div>
+ </div>
+ ))}
+ </section>
+ );
+}
diff --git a/apps/docs/components/icons.tsx b/apps/docs/components/icons.tsx
new file mode 100644
index 0000000..8da0572
--- /dev/null
+++ b/apps/docs/components/icons.tsx
@@ -0,0 +1,230 @@
+/* Inline lucide-style SVG icons — 24×24 viewBox, stroke="currentColor",
+ stroke-width 1.5, no fill (docs/DESIGN.md §1 Iconography). Never emoji. */
+
+type IconProps = React.SVGProps<SVGSVGElement>;
+
+function Icon({ children, ...props }: IconProps) {
+ return (
+ <svg
+ viewBox="0 0 24 24"
+ fill="none"
+ stroke="currentColor"
+ strokeWidth={1.5}
+ strokeLinecap="round"
+ strokeLinejoin="round"
+ aria-hidden="true"
+ {...props}
+ >
+ {children}
+ </svg>
+ );
+}
+
+export function ExternalLinkIcon(props: IconProps) {
+ return (
+ <Icon {...props}>
+ <path d="M15 3h6v6" />
+ <path d="M10 14 21 3" />
+ <path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6" />
+ </Icon>
+ );
+}
+
+export function GitHubIcon(props: IconProps) {
+ return (
+ <Icon {...props}>
+ <path d="M15 22v-4a4.8 4.8 0 0 0-1-3.5c3 0 6-2 6-5.5.08-1.25-.27-2.48-1-3.5.28-1.15.28-2.35 0-3.5 0 0-1 0-3 1.5-2.64-.5-5.36-.5-8 0C6 2 5 2 5 2c-.3 1.15-.3 2.35 0 3.5A5.403 5.403 0 0 0 4 9c0 3.5 3 5.5 6 5.5-.39.49-.68 1.05-.85 1.65-.17.6-.22 1.23-.15 1.85v4" />
+ <path d="M9 18c-4.51 2-5-2-7-2" />
+ </Icon>
+ );
+}
+
+export function CopyIcon(props: IconProps) {
+ return (
+ <Icon {...props}>
+ <rect width="14" height="14" x="8" y="8" rx="2" ry="2" />
+ <path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2" />
+ </Icon>
+ );
+}
+
+export function CheckIcon(props: IconProps) {
+ return (
+ <Icon {...props}>
+ <path d="M20 6 9 17l-5-5" />
+ </Icon>
+ );
+}
+
+export function SunIcon(props: IconProps) {
+ return (
+ <Icon {...props}>
+ <circle cx="12" cy="12" r="4" />
+ <path d="M12 2v2" />
+ <path d="M12 20v2" />
+ <path d="m4.93 4.93 1.41 1.41" />
+ <path d="m17.66 17.66 1.41 1.41" />
+ <path d="M2 12h2" />
+ <path d="M20 12h2" />
+ <path d="m6.34 17.66-1.41 1.41" />
+ <path d="m19.07 4.93-1.41 1.41" />
+ </Icon>
+ );
+}
+
+export function MoonIcon(props: IconProps) {
+ return (
+ <Icon {...props}>
+ <path d="M12 3a6 6 0 0 0 9 9 9 9 0 1 1-9-9Z" />
+ </Icon>
+ );
+}
+
+export function ChevronDownIcon(props: IconProps) {
+ return (
+ <Icon {...props}>
+ <path d="m6 9 6 6 6-6" />
+ </Icon>
+ );
+}
+
+export function SearchIcon(props: IconProps) {
+ return (
+ <Icon {...props}>
+ <circle cx="11" cy="11" r="8" />
+ <path d="m21 21-4.3-4.3" />
+ </Icon>
+ );
+}
+
+export function ArrowRightIcon(props: IconProps) {
+ return (
+ <Icon {...props}>
+ <path d="M5 12h14" />
+ <path d="m12 5 7 7-7 7" />
+ </Icon>
+ );
+}
+
+export function FeatherIcon(props: IconProps) {
+ return (
+ <Icon {...props}>
+ <path d="M12.67 19a2 2 0 0 0 1.416-.588l6.154-6.172a6 6 0 0 0-8.49-8.49L5.586 9.914A2 2 0 0 0 5 11.328V18a1 1 0 0 0 1 1z" />
+ <path d="M16 8 2 22" />
+ <path d="M17.5 15H9" />
+ </Icon>
+ );
+}
+
+export function BracesIcon(props: IconProps) {
+ return (
+ <Icon {...props}>
+ <path d="M8 3H7a2 2 0 0 0-2 2v5a2 2 0 0 1-2 2 2 2 0 0 1 2 2v5c0 1.1.9 2 2 2h1" />
+ <path d="M16 21h1a2 2 0 0 0 2-2v-5c0-1.1.9-2 2-2a2 2 0 0 1-2-2V5a2 2 0 0 0-2-2h-1" />
+ </Icon>
+ );
+}
+
+export function ServerIcon(props: IconProps) {
+ return (
+ <Icon {...props}>
+ <rect width="20" height="8" x="2" y="2" rx="2" ry="2" />
+ <rect width="20" height="8" x="2" y="14" rx="2" ry="2" />
+ <path d="M6 6h.01" />
+ <path d="M6 18h.01" />
+ </Icon>
+ );
+}
+
+export function LeafIcon(props: IconProps) {
+ return (
+ <Icon {...props}>
+ <path d="M11 20A7 7 0 0 1 9.8 6.1C15.5 5 17 4.48 19 2c1 2 2 4.18 2 8 0 5.5-4.78 10-10 10Z" />
+ <path d="M2 21c0-3 1.85-5.36 5.08-6C9.5 14.52 12 13 13 12" />
+ </Icon>
+ );
+}
+
+export function PackageIcon(props: IconProps) {
+ return (
+ <Icon {...props}>
+ <path d="M21 8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73l7 4a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16Z" />
+ <path d="m3.3 7 8.7 5 8.7-5" />
+ <path d="M12 22V12" />
+ </Icon>
+ );
+}
+
+export function HeartIcon(props: IconProps) {
+ return (
+ <Icon {...props}>
+ <path d="M19 14c1.49-1.46 3-3.21 3-5.5A5.5 5.5 0 0 0 16.5 3c-1.76 0-3 .5-4.5 2-1.5-1.5-2.74-2-4.5-2A5.5 5.5 0 0 0 2 8.5c0 2.3 1.5 4.05 3 5.5l7 7Z" />
+ </Icon>
+ );
+}
+
+export function StarIcon(props: IconProps) {
+ return (
+ <Icon {...props}>
+ <path d="M11.525 2.295a.53.53 0 0 1 .95 0l2.31 4.679a2.123 2.123 0 0 0 1.595 1.16l5.166.756a.53.53 0 0 1 .294.904l-3.736 3.638a2.123 2.123 0 0 0-.611 1.878l.882 5.14a.53.53 0 0 1-.771.56l-4.618-2.428a2.122 2.122 0 0 0-1.973 0L6.396 21.01a.53.53 0 0 1-.77-.56l.881-5.139a2.122 2.122 0 0 0-.611-1.879L2.16 9.795a.53.53 0 0 1 .294-.906l5.165-.755a2.122 2.122 0 0 0 1.597-1.16z" />
+ </Icon>
+ );
+}
+
+export function GitPullRequestIcon(props: IconProps) {
+ return (
+ <Icon {...props}>
+ <circle cx="18" cy="18" r="3" />
+ <circle cx="6" cy="6" r="3" />
+ <path d="M13 6h3a2 2 0 0 1 2 2v7" />
+ <path d="M6 9v12" />
+ </Icon>
+ );
+}
+
+export function MenuIcon(props: IconProps) {
+ return (
+ <Icon {...props}>
+ <path d="M4 6h16" />
+ <path d="M4 12h16" />
+ <path d="M4 18h16" />
+ </Icon>
+ );
+}
+
+export function XIcon(props: IconProps) {
+ return (
+ <Icon {...props}>
+ <path d="M18 6 6 18" />
+ <path d="m6 6 12 12" />
+ </Icon>
+ );
+}
+
+export function BlocksIcon(props: IconProps) {
+ return (
+ <Icon {...props}>
+ <rect width="7" height="7" x="14" y="3" rx="1" />
+ <path d="M10 21V8a1 1 0 0 0-1-1H4a1 1 0 0 0-1 1v12a1 1 0 0 0 1 1h12a1 1 0 0 0 1-1v-5a1 1 0 0 0-1-1H3" />
+ </Icon>
+ );
+}
+
+export function KofiIcon(props: IconProps) {
+ return (
+ <Icon {...props}>
+ <path d="M6 2v2" />
+ <path d="M10 2v2" />
+ <path d="M14 2v2" />
+ <path d="M16 8a1 1 0 0 1 1 1v8a4 4 0 0 1-4 4H7a4 4 0 0 1-4-4V9a1 1 0 0 1 1-1h14a4 4 0 1 1 0 8h-1" />
+ </Icon>
+ );
+}
+
+export function GitHubSponsorsIcon(props: IconProps) {
+ return (
+ <svg viewBox="0 0 24 24" fill="currentColor" aria-hidden="true" {...props}>
+ <path d="M12 21.35l-1.45-1.32C5.4 15.36 2 12.28 2 8.5 2 5.42 4.42 3 7.5 3c1.74 0 3.41.81 4.5 2.09C13.09 3.81 14.76 3 16.5 3 19.58 3 22 5.42 22 8.5c0 3.78-3.4 6.86-8.55 11.54L12 21.35z" />
+ </svg>
+ );
+}
diff --git a/apps/docs/components/install-command.tsx b/apps/docs/components/install-command.tsx
new file mode 100644
index 0000000..58e918c
--- /dev/null
+++ b/apps/docs/components/install-command.tsx
@@ -0,0 +1,21 @@
+"use client";
+
+import { CopyButton } from "@/components/copy-button";
+
+const COMMAND = "npm i hookli";
+
+export function InstallCommand({ className = "" }: { className?: string }) {
+ return (
+ <div
+ className={`surface flex items-center gap-2 rounded-lg py-1 pl-4 pr-1 font-mono text-sm ${className}`}
+ >
+ <code className="whitespace-nowrap">
+ <span aria-hidden="true" className="select-none text-slate-syntax">
+ ${" "}
+ </span>
+ {COMMAND}
+ </code>
+ <CopyButton text={COMMAND} label="Copy npm install command" />
+ </div>
+ );
+}
diff --git a/apps/docs/components/live-proof-section.tsx b/apps/docs/components/live-proof-section.tsx
new file mode 100644
index 0000000..f659870
--- /dev/null
+++ b/apps/docs/components/live-proof-section.tsx
@@ -0,0 +1,47 @@
+import { CodeBlock } from "@/components/code-block";
+import { SectionHeading } from "@/components/section-heading";
+import { UseToggleDemo } from "@/components/demos/use-toggle-demo";
+
+/* The demo component mirrors this sample line for line (plus styling classes) —
+ keep the two in sync. See components/demos/use-toggle-demo.tsx. */
+const SAMPLE = `
+import { useToggle } from "hookli";
+
+export function LightSwitch() {
+ const [on, toggle] = useToggle(false);
+
+ return (
+ <button onClick={toggle} aria-pressed={on}>
+ {on ? "On" : "Off"}
+ </button>
+ );
+}
+`;
+
+export function LiveProofSection() {
+ return (
+ <section className="mx-auto w-full max-w-5xl px-4 py-20 sm:px-6">
+ <SectionHeading
+ eyebrow="Live proof"
+ title="This demo runs the code beside it"
+ subtitle={
+ <>
+ The preview imports <code className="text-sm">useToggle</code> straight from the published npm package — the same code you'd ship.
+ </>
+ }
+ />
+ <div className="mt-12 grid items-stretch gap-4 lg:grid-cols-2">
+ <CodeBlock code={SAMPLE} title="light-switch.tsx" />
+ <div className="surface flex min-h-[180px] flex-col overflow-hidden rounded-xl">
+ <p className="flex items-center gap-2 border-b border-slate-syntax/40 px-4 py-[15px] text-xs text-gray-body">
+ <span aria-hidden="true" className="size-1.5 rounded-full bg-accent/70" />
+ live · imported from hookli
+ </p>
+ <div className="flex flex-1 items-center justify-center p-8">
+ <UseToggleDemo />
+ </div>
+ </div>
+ </div>
+ </section>
+ );
+}
diff --git a/apps/docs/components/on-this-page.tsx b/apps/docs/components/on-this-page.tsx
new file mode 100644
index 0000000..1f6bc79
--- /dev/null
+++ b/apps/docs/components/on-this-page.tsx
@@ -0,0 +1,47 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+export type TocItem = { id: string; label: string };
+
+/* Right-rail "On this page" nav for hook pages (T16 usehooks-ts anatomy).
+ Scroll-spy via IntersectionObserver highlights the section nearest the top;
+ the rail itself is hidden below xl (the template only renders it there). */
+export function OnThisPage({ items }: { items: readonly TocItem[] }) {
+ const [active, setActive] = useState(items[0]?.id ?? "");
+
+ useEffect(() => {
+ const headings = items.map((item) => document.getElementById(item.id)).filter((el): el is HTMLElement => el !== null);
+ if (headings.length === 0) return;
+
+ const observer = new IntersectionObserver(
+ (entries) => {
+ const visible = entries.filter((entry) => entry.isIntersecting).sort((a, b) => a.boundingClientRect.top - b.boundingClientRect.top);
+ if (visible[0]) setActive(visible[0].target.id);
+ },
+ { rootMargin: "-80px 0px -70% 0px" },
+ );
+
+ headings.forEach((heading) => observer.observe(heading));
+ return () => observer.disconnect();
+ }, [items]);
+
+ return (
+ <nav aria-label="On this page">
+ <p className="text-xs font-semibold uppercase tracking-wider text-slate-syntax">On this page</p>
+ <ul className="mt-3 flex flex-col border-l border-slate-syntax/40">
+ {items.map((item) => (
+ <li key={item.id}>
+ <a
+ href={`#${item.id}`}
+ aria-current={active === item.id ? "location" : undefined}
+ className={`-ml-px block border-l-2 py-1 pl-4 text-sm transition-colors duration-200 ${active === item.id ? "border-accent text-fg" : "border-transparent text-gray-body hover:text-fg"}`}
+ >
+ {item.label}
+ </a>
+ </li>
+ ))}
+ </ul>
+ </nav>
+ );
+}
diff --git a/apps/docs/components/search-palette.tsx b/apps/docs/components/search-palette.tsx
new file mode 100644
index 0000000..84ced87
--- /dev/null
+++ b/apps/docs/components/search-palette.tsx
@@ -0,0 +1,217 @@
+"use client";
+
+import { useCallback, useEffect, useId, useRef, useState, useSyncExternalStore } from "react";
+import { createPortal } from "react-dom";
+import { useRouter } from "next/navigation";
+import { CATEGORY_LABELS, HOOKS, type HookEntry } from "@/lib/hooks-registry";
+import { SearchIcon } from "./icons";
+
+/* ⌘K command palette over the hook registry (docs/DESIGN.md §7). Client-only —
+ lowercase substring match on name/description/category is enough at this size;
+ no service, no index build. Combobox pattern: focus stays on the input and the
+ highlighted option is conveyed via aria-activedescendant; Tab cycles between
+ the input and the close button (the dialog's only tab stops). Full-screen
+ sheet below 640px, centered panel above. */
+
+const subscribeNoop = () => () => {};
+
+/* Server snapshot is false; useSyncExternalStore re-reads on the client without
+ tripping react-hooks/set-state-in-effect (see use-dark-mode-demo). */
+function useIsApplePlatform() {
+ return useSyncExternalStore(
+ subscribeNoop,
+ () => /Mac|iPhone|iPad/.test(navigator.platform),
+ () => false,
+ );
+}
+
+function matches(hook: HookEntry, query: string): boolean {
+ const q = query.trim().toLowerCase();
+ if (!q) return true;
+ return hook.name.toLowerCase().includes(q) || hook.description.toLowerCase().includes(q) || hook.category.includes(q) || CATEGORY_LABELS[hook.category].toLowerCase().includes(q);
+}
+
+export function SearchPalette() {
+ const router = useRouter();
+ const isApple = useIsApplePlatform();
+ const listboxId = useId();
+ const triggerRef = useRef<HTMLButtonElement>(null);
+ const inputRef = useRef<HTMLInputElement>(null);
+ const closeButtonRef = useRef<HTMLButtonElement>(null);
+
+ const [open, setOpen] = useState(false);
+ const [query, setQuery] = useState("");
+ const [activeIndex, setActiveIndex] = useState(0);
+
+ const results = HOOKS.filter((hook) => matches(hook, query));
+ /* Clamp instead of resetting when results shrink under the cursor. */
+ const active = Math.max(0, Math.min(activeIndex, results.length - 1));
+ const optionId = (hook: HookEntry) => `${listboxId}-${hook.slug}`;
+
+ const openPalette = useCallback(() => {
+ setQuery("");
+ setActiveIndex(0);
+ setOpen(true);
+ }, []);
+
+ const closePalette = useCallback(() => {
+ setOpen(false);
+ triggerRef.current?.focus();
+ }, []);
+
+ const select = useCallback(
+ (hook: HookEntry) => {
+ setOpen(false);
+ router.push(`/docs/${hook.slug}`);
+ },
+ [router],
+ );
+
+ /* Global ⌘K / Ctrl+K toggle. */
+ useEffect(() => {
+ function onKeyDown(event: KeyboardEvent) {
+ if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === "k") {
+ event.preventDefault();
+ if (open) {
+ closePalette();
+ } else {
+ openPalette();
+ }
+ }
+ }
+ window.addEventListener("keydown", onKeyDown);
+ return () => window.removeEventListener("keydown", onKeyDown);
+ }, [open, openPalette, closePalette]);
+
+ /* Scroll lock while the dialog is up. */
+ useEffect(() => {
+ if (!open) return;
+ const previous = document.body.style.overflow;
+ document.body.style.overflow = "hidden";
+ return () => {
+ document.body.style.overflow = previous;
+ };
+ }, [open]);
+
+ function moveActive(delta: number) {
+ if (results.length === 0) return;
+ const next = (active + delta + results.length) % results.length;
+ setActiveIndex(next);
+ document.getElementById(optionId(results[next]))?.scrollIntoView({ block: "nearest" });
+ }
+
+ function onInputKeyDown(event: React.KeyboardEvent<HTMLInputElement>) {
+ if (event.key === "ArrowDown") {
+ event.preventDefault();
+ moveActive(1);
+ } else if (event.key === "ArrowUp") {
+ event.preventDefault();
+ moveActive(-1);
+ } else if (event.key === "Enter") {
+ event.preventDefault();
+ if (results[active]) select(results[active]);
+ }
+ }
+
+ /* Escape + the two-stop focus trap live on the dialog so they work no matter
+ which of the tab stops holds focus. */
+ function onDialogKeyDown(event: React.KeyboardEvent<HTMLDivElement>) {
+ if (event.key === "Escape") {
+ event.preventDefault();
+ closePalette();
+ } else if (event.key === "Tab") {
+ event.preventDefault();
+ if (document.activeElement === inputRef.current) {
+ closeButtonRef.current?.focus();
+ } else {
+ inputRef.current?.focus();
+ }
+ }
+ }
+
+ return (
+ <>
+ <button
+ ref={triggerRef}
+ type="button"
+ onClick={openPalette}
+ aria-label="Search hooks"
+ aria-keyshortcuts={isApple ? "Meta+K" : "Control+K"}
+ className="flex size-11 items-center justify-center rounded-md text-gray-body transition-colors duration-200 hover:text-fg sm:w-auto sm:gap-2 sm:border sm:border-slate-syntax/60 sm:px-3 sm:hover:border-slate-syntax"
+ >
+ <SearchIcon className="size-5 sm:size-4" />
+ <span className="hidden text-sm sm:inline">Search</span>
+ <kbd className="hidden rounded border border-slate-syntax/60 px-1.5 py-0.5 font-mono text-xs text-slate-syntax sm:inline">{isApple ? "⌘" : "Ctrl"} K</kbd>
+ </button>
+
+ {open &&
+ createPortal(
+ <div className="fixed inset-0 z-50 flex flex-col bg-ground/80 backdrop-blur-sm sm:items-center sm:px-4 sm:pt-[15vh]" onMouseDown={closePalette}>
+ <div
+ role="dialog"
+ aria-modal="true"
+ aria-label="Search hooks"
+ onMouseDown={(event) => event.stopPropagation()}
+ onKeyDown={onDialogKeyDown}
+ className="flex h-full w-full flex-col bg-ground-raised sm:h-auto sm:max-w-lg sm:rounded-xl sm:border sm:border-slate-syntax/60 sm:shadow-2xl sm:shadow-black/40"
+ >
+ <div className="flex h-14 shrink-0 items-center gap-3 border-b border-slate-syntax/40 px-4">
+ <SearchIcon className="size-4 shrink-0 text-slate-syntax" />
+ <input
+ ref={inputRef}
+ autoFocus
+ type="text"
+ role="combobox"
+ aria-expanded="true"
+ aria-controls={listboxId}
+ aria-autocomplete="list"
+ aria-activedescendant={results[active] ? optionId(results[active]) : undefined}
+ value={query}
+ onChange={(event) => {
+ setQuery(event.target.value);
+ setActiveIndex(0);
+ }}
+ onKeyDown={onInputKeyDown}
+ placeholder="Search hooks…"
+ className="h-full w-full bg-transparent text-sm text-fg outline-none placeholder:text-slate-syntax"
+ />
+ <button ref={closeButtonRef} type="button" onClick={closePalette} aria-label="Close search" className="flex min-h-11 shrink-0 items-center rounded-md px-2">
+ <kbd className="rounded border border-slate-syntax/60 px-1.5 py-0.5 font-mono text-xs text-slate-syntax">esc</kbd>
+ </button>
+ </div>
+
+ <ul id={listboxId} role="listbox" aria-label="Hooks" className="flex-1 overflow-y-auto p-2 sm:max-h-80 sm:flex-none">
+ {results.map((hook, index) => (
+ <li
+ key={hook.slug}
+ id={optionId(hook)}
+ role="option"
+ aria-selected={index === active}
+ onMouseMove={() => setActiveIndex(index)}
+ onClick={() => select(hook)}
+ className={`flex min-h-11 cursor-pointer items-center gap-3 rounded-md px-3 transition-colors duration-150 ${index === active ? "bg-ground-overlay text-accent" : "text-gray-body"}`}
+ >
+ <span className="shrink-0 text-sm">{hook.name}</span>
+ <span className="truncate text-xs">{hook.description}</span>
+ <span className="ml-auto shrink-0 text-xs uppercase tracking-wider text-slate-syntax">{CATEGORY_LABELS[hook.category]}</span>
+ </li>
+ ))}
+ {results.length === 0 && (
+ <li role="presentation" className="px-3 py-10 text-center text-sm text-slate-syntax">
+ No hooks match “{query.trim()}”
+ </li>
+ )}
+ </ul>
+
+ <p className="hidden shrink-0 items-center gap-4 border-t border-slate-syntax/40 px-4 py-2.5 text-xs text-slate-syntax sm:flex">
+ <span>↑↓ navigate</span>
+ <span>↵ open</span>
+ <span>esc close</span>
+ </p>
+ </div>
+ </div>,
+ document.body,
+ )}
+ </>
+ );
+}
diff --git a/apps/docs/components/section-heading.tsx b/apps/docs/components/section-heading.tsx
new file mode 100644
index 0000000..dec0751
--- /dev/null
+++ b/apps/docs/components/section-heading.tsx
@@ -0,0 +1,25 @@
+type SectionHeadingProps = {
+ eyebrow: string;
+ title: string;
+ subtitle?: React.ReactNode;
+ className?: string;
+};
+
+/* Shared landing section header: a tracked accent eyebrow, a confident
+ text-3xl title, and an optional subtitle — one rhythm across every section. */
+export function SectionHeading({
+ eyebrow,
+ title,
+ subtitle,
+ className = "",
+}: SectionHeadingProps) {
+ return (
+ <div className={`mx-auto flex max-w-2xl flex-col items-center text-center ${className}`}>
+ <span className="text-xs font-semibold uppercase tracking-[0.16em] text-accent">
+ {eyebrow}
+ </span>
+ <h2 className="mt-3 text-3xl">{title}</h2>
+ {subtitle && <p className="mt-3 text-gray-body">{subtitle}</p>}
+ </div>
+ );
+}
diff --git a/apps/docs/components/sidebar.tsx b/apps/docs/components/sidebar.tsx
new file mode 100644
index 0000000..c8b6afe
--- /dev/null
+++ b/apps/docs/components/sidebar.tsx
@@ -0,0 +1,216 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+import Link from "next/link";
+import { usePathname } from "next/navigation";
+import {
+ CATEGORY_LABELS,
+ CATEGORY_ORDER,
+ getHook,
+ hooksByCategory,
+} from "@/lib/hooks-registry";
+import { MenuIcon, XIcon } from "./icons";
+
+/* Docs sidebar (docs/DESIGN.md §2, §5): sticky under the h-14 header, grouped
+ by category, active state from the pathname. Below md it collapses to
+ MobileDocsNav — a sticky trigger bar opening a left slide-over drawer. */
+export function Sidebar() {
+ const pathname = usePathname();
+
+ return (
+ <aside className="hidden w-56 shrink-0 border-r border-slate-syntax/40 md:block">
+ <nav
+ aria-label="Docs"
+ className="sticky top-14 max-h-[calc(100vh-3.5rem)] overflow-y-auto py-8 pr-6"
+ >
+ <DocsNavList pathname={pathname} />
+ </nav>
+ </aside>
+ );
+}
+
+/* Mobile-only (md:hidden) drawer navigation. Same two-piece dialog recipe as
+ SearchPalette: portal + overlay, scroll lock, Escape closes, focus returns
+ to the trigger; Tab is trapped inside the drawer. Links close on click —
+ no pathname effect needed (react-hooks/set-state-in-effect stays quiet). */
+export function MobileDocsNav() {
+ const pathname = usePathname();
+ const triggerRef = useRef<HTMLButtonElement>(null);
+ const drawerRef = useRef<HTMLDivElement>(null);
+ const [open, setOpen] = useState(false);
+
+ const currentLabel =
+ pathname === "/docs"
+ ? "Overview"
+ : (getHook(pathname.replace("/docs/", ""))?.name ?? "Docs");
+
+ function close() {
+ setOpen(false);
+ triggerRef.current?.focus();
+ }
+
+ /* Scroll lock while the drawer is up. */
+ useEffect(() => {
+ if (!open) return;
+ const previous = document.body.style.overflow;
+ document.body.style.overflow = "hidden";
+ return () => {
+ document.body.style.overflow = previous;
+ };
+ }, [open]);
+
+ function onDrawerKeyDown(event: React.KeyboardEvent<HTMLDivElement>) {
+ if (event.key === "Escape") {
+ event.preventDefault();
+ close();
+ return;
+ }
+ if (event.key !== "Tab") return;
+ const focusables =
+ drawerRef.current?.querySelectorAll<HTMLElement>("a[href], button");
+ if (!focusables || focusables.length === 0) return;
+ const first = focusables[0];
+ const last = focusables[focusables.length - 1];
+ if (event.shiftKey && document.activeElement === first) {
+ event.preventDefault();
+ last.focus();
+ } else if (!event.shiftKey && document.activeElement === last) {
+ event.preventDefault();
+ first.focus();
+ }
+ }
+
+ return (
+ <div className="sticky top-14 z-30 -mx-4 border-b border-slate-syntax/40 bg-ground/90 px-4 backdrop-blur sm:-mx-6 sm:px-6 md:hidden">
+ <button
+ ref={triggerRef}
+ type="button"
+ onClick={() => setOpen(true)}
+ aria-expanded={open}
+ aria-haspopup="dialog"
+ className="flex min-h-11 w-full items-center gap-2 text-sm text-gray-body transition-colors duration-200 hover:text-fg"
+ >
+ <MenuIcon className="size-4 shrink-0" />
+ <span className="text-slate-syntax">docs /</span>
+ <span className="truncate text-fg">{currentLabel}</span>
+ </button>
+
+ {open &&
+ createPortal(
+ <div
+ className="fixed inset-0 z-50 bg-ground/80 backdrop-blur-sm md:hidden"
+ onMouseDown={close}
+ >
+ <div
+ ref={drawerRef}
+ role="dialog"
+ aria-modal="true"
+ aria-label="Docs navigation"
+ onMouseDown={(event) => event.stopPropagation()}
+ onKeyDown={onDrawerKeyDown}
+ className="flex h-full w-72 max-w-[85vw] flex-col border-r border-slate-syntax/40 bg-ground-raised"
+ >
+ <div className="flex h-14 shrink-0 items-center justify-between border-b border-slate-syntax/40 pl-4 pr-2">
+ <span className="text-sm text-gray-body">Docs</span>
+ <button
+ autoFocus
+ type="button"
+ onClick={close}
+ aria-label="Close docs navigation"
+ className="flex size-11 items-center justify-center rounded-md text-gray-body transition-colors duration-200 hover:text-fg"
+ >
+ <XIcon className="size-5" />
+ </button>
+ </div>
+ <nav
+ aria-label="Docs"
+ className="flex-1 overflow-y-auto px-4 py-6"
+ >
+ <DocsNavList
+ pathname={pathname}
+ onNavigate={() => setOpen(false)}
+ />
+ </nav>
+ </div>
+ </div>,
+ document.body,
+ )}
+ </div>
+ );
+}
+
+/* Shared between the desktop sidebar and the mobile drawer. */
+function DocsNavList({
+ pathname,
+ onNavigate,
+}: {
+ pathname: string;
+ onNavigate?: () => void;
+}) {
+ return (
+ <>
+ <ul className="flex flex-col border-l border-slate-syntax/40">
+ <li>
+ <SidebarLink
+ href="/docs"
+ active={pathname === "/docs"}
+ onNavigate={onNavigate}
+ >
+ Overview
+ </SidebarLink>
+ </li>
+ </ul>
+ {CATEGORY_ORDER.map((category) => (
+ <div key={category} className="mt-7">
+ <h3 className="mb-2 pl-4 text-[11px] font-semibold uppercase tracking-[0.14em] text-slate-syntax">
+ {CATEGORY_LABELS[category]}
+ </h3>
+ <ul className="flex flex-col border-l border-slate-syntax/40">
+ {hooksByCategory(category).map((hook) => {
+ const href = `/docs/${hook.slug}`;
+ return (
+ <li key={hook.slug}>
+ <SidebarLink
+ href={href}
+ active={pathname === href}
+ onNavigate={onNavigate}
+ >
+ {hook.name}
+ </SidebarLink>
+ </li>
+ );
+ })}
+ </ul>
+ </div>
+ ))}
+ </>
+ );
+}
+
+function SidebarLink({
+ href,
+ active,
+ onNavigate,
+ children,
+}: {
+ href: string;
+ active: boolean;
+ onNavigate?: () => void;
+ children: React.ReactNode;
+}) {
+ return (
+ <Link
+ href={href}
+ onClick={onNavigate}
+ aria-current={active ? "page" : undefined}
+ className={`-ml-px flex min-h-11 items-center border-l-2 pl-4 text-sm transition-colors duration-200 md:min-h-9 ${
+ active
+ ? "border-accent font-medium text-fg"
+ : "border-transparent text-gray-body hover:border-slate-syntax hover:text-fg"
+ }`}
+ >
+ {children}
+ </Link>
+ );
+}
diff --git a/apps/docs/components/support-section.tsx b/apps/docs/components/support-section.tsx
new file mode 100644
index 0000000..c6e7bbd
--- /dev/null
+++ b/apps/docs/components/support-section.tsx
@@ -0,0 +1,70 @@
+import Link from "next/link";
+import { SectionHeading } from "@/components/section-heading";
+import { ArrowRightIcon, GitHubSponsorsIcon, GitPullRequestIcon, StarIcon } from "@/components/icons";
+import { GITHUB_URL, SPONSOR_URL } from "@/lib/site";
+
+const CARDS = [
+ {
+ icon: <StarIcon className="size-6" />,
+ title: "Star it",
+ body: "The fastest way to help — stars bring the contributors that keep hookli moving.",
+ label: "Star on GitHub",
+ href: GITHUB_URL,
+ external: true,
+ },
+ {
+ icon: <GitPullRequestIcon className="size-6" />,
+ title: "Contribute",
+ body: "Report a bug, sharpen the docs, or add the hook you keep rewriting anyway.",
+ label: "How to contribute",
+ href: "/support#contribute",
+ external: false,
+ },
+ {
+ icon: <GitHubSponsorsIcon className="size-6" />,
+ title: "Sponsor",
+ body: "Back ongoing maintenance and new hooks through GitHub Sponsors — any amount helps.",
+ label: "Become a sponsor",
+ href: SPONSOR_URL,
+ external: true,
+ },
+];
+
+export function SupportSection() {
+ return (
+ <section className="mx-auto w-full max-w-5xl px-4 py-20 sm:px-6">
+ <SectionHeading
+ eyebrow="Get involved"
+ title="Support hookli"
+ subtitle="hookli is free and ISC-licensed. It runs on stars, issues, pull requests, and sponsorships."
+ />
+ <div className="mt-12 grid gap-4 sm:grid-cols-3">
+ {CARDS.map((card) => {
+ const inner = (
+ <>
+ <span className="flex size-11 items-center justify-center rounded-lg bg-accent/10 text-accent ring-1 ring-inset ring-accent/20">
+ {card.icon}
+ </span>
+ <h3 className="mt-5 text-lg font-semibold">{card.title}</h3>
+ <p className="mt-2 flex-1 text-sm leading-relaxed text-gray-body">{card.body}</p>
+ <span className="mt-4 flex min-h-11 items-center gap-2 text-sm text-accent">
+ {card.label}
+ <ArrowRightIcon className="size-4 transition-transform duration-200 group-hover:translate-x-0.5" />
+ </span>
+ </>
+ );
+ const className = "surface surface-lift group flex flex-col rounded-xl p-6";
+ return card.external ? (
+ <a key={card.title} href={card.href} target="_blank" rel="noopener noreferrer" className={className}>
+ {inner}
+ </a>
+ ) : (
+ <Link key={card.title} href={card.href} className={className}>
+ {inner}
+ </Link>
+ );
+ })}
+ </div>
+ </section>
+ );
+}
diff --git a/apps/docs/components/wordmark.tsx b/apps/docs/components/wordmark.tsx
new file mode 100644
index 0000000..2c8da0f
--- /dev/null
+++ b/apps/docs/components/wordmark.tsx
@@ -0,0 +1,46 @@
+const sizeClasses = {
+ sm: "text-lg",
+ md: "text-2xl",
+ lg: "text-4xl sm:text-5xl",
+ xl: "text-5xl sm:text-6xl md:text-7xl",
+} as const;
+
+/* Brand v3 lockup — lowercase name in the brand sans, teal full stop.
+ Matches public/hookli-banner.svg; the old use(hookli) mono mark is retired. */
+export function Wordmark({
+ size = "md",
+ className = "",
+}: {
+ size?: keyof typeof sizeClasses;
+ className?: string;
+}) {
+ return (
+ <span
+ className={`whitespace-nowrap font-sans font-semibold tracking-tight text-fg ${sizeClasses[size]} ${className}`}
+ >
+ hookli
+ <span className="text-accent">.</span>
+ </span>
+ );
+}
+
+/* The brand mark from public/hookli-icon.svg without the tile: a hook cradling
+ a state dot. Size it via className (height + w-auto); colors come from tokens. */
+export function HookMark({ className = "" }: { className?: string }) {
+ return (
+ <svg
+ viewBox="-13 -3 110 140"
+ fill="none"
+ aria-hidden="true"
+ className={className}
+ >
+ <path
+ d="M84 10 V82 A42 42 0 1 1 0 82 V58"
+ stroke="var(--color-accent)"
+ strokeWidth="26"
+ strokeLinecap="round"
+ />
+ <circle cx="42" cy="82" r="15" fill="var(--color-fg)" />
+ </svg>
+ );
+}
diff --git a/apps/docs/docs/DESIGN.md b/apps/docs/docs/DESIGN.md
new file mode 100644
index 0000000..960321c
--- /dev/null
+++ b/apps/docs/docs/DESIGN.md
@@ -0,0 +1,209 @@
+# hookli-docs — Design Source of Truth
+
+Produced by T1 (2026-07-11). Every later task builds from this document without
+re-deciding. Benchmarks studied: **usehooks-ts.com** (landing formula, hook-page
+anatomy), **mantine.dev/hooks** (demo-first polish, category sidebar),
+**react-use** (cautionary tale: README-only docs → poor discoverability, no live
+demos). hookli-docs takes usehooks-ts's structure, Mantine's demo polish, and adds
+what all three lack on brand: a code-first hero that proves the library live.
+
+---
+
+## 1. Brand tokens
+
+Defined as CSS variables in `app/globals.css` and wired into Tailwind v4 via the
+`@theme` directive (Tailwind 4 has no `tailwind.config.ts` theme — tokens live in CSS).
+
+> **Brand v3 (2026-07-12).** Assets in `public/` (Prussian tile, teal hook cradling a
+> white state dot, `hookli.` wordmark) are the source; the token values below match them.
+
+| Token | Value | CSS var | Tailwind name | Use |
+|---|---|---|---|---|
+| Ground | `#04191F` | `--color-ground` | `ground` | Page background (near-black blue — the darkest step) |
+| Ground raised | `#003748` | `--color-ground-raised` | `ground-raised` | Cards, code frames, sidebar (Prussian Blue surface) |
+| Ground overlay | `#0A4557` | `--color-ground-overlay` | `ground-overlay` | Second elevation: nested / hover / active surfaces |
+| Accent | `#30C5CA` | `--color-accent` | `accent` | Links, CTAs, wordmark full stop, focus rings (Scooter) |
+| Syntax slate | `#4A7A8C` | `--color-slate-syntax` | `slate-syntax` | Borders, code comments, muted chrome |
+| Gray | `#8FB6C2` | `--color-gray-body` | `gray-body` | Secondary/body text (mist) |
+| Foreground | `#FFFFFF` | `--color-fg` | `fg` | Primary text/ink (AA on ground: 12.8:1) |
+| Accent-ink | `#003748` | — | `ground` | Text on accent-filled buttons (6.1:1 on accent) |
+
+Rules: **solid colors only — no gradients** on brand surfaces. Dark-first; no light
+theme in v1. Borders are `--color-slate-syntax` at 40% opacity (`border-slate-syntax/40`).
+Accent is used sparingly: one primary CTA per viewport, links, active nav states.
+`#8FB6C2` on `#003748` is 5.9:1 — safe for body text; never go darker than that for copy.
+
+### Typography
+- **Headings + wordmark + UI:** Plus Jakarta Sans (Avenir-class geometric) via
+ `next/font/local` from `@fontsource/plus-jakarta-sans` (400/600/700). CSS var
+ `--font-sans`; headings weight 600, `letter-spacing: -0.02em`.
+- **Code only:** JetBrains Mono (`--font-mono`) — code blocks, commands, identifiers,
+ signatures, API type cells, kbd. Monospace is never used for UI copy, nav, buttons,
+ or headings.
+- Wordmark treatment (component `Wordmark`): `hookli` lowercase in ink `#FFFFFF` +
+ full stop in accent `#30C5CA`, sans 600, `tracking-tight`. The mark (`HookMark`,
+ same file) is the icon's hook + dot without the tile. The old `use(hookli)` mono
+ lockup is retired.
+- Scale: h1 `text-4xl/5xl` sans 600 · h2 `text-2xl` sans 600 · h3 `text-lg` sans 600 ·
+ body `text-base` sans · small `text-sm`.
+
+### Iconography
+Inline SVG only, lucide-style (24×24 viewBox, `stroke="currentColor"`,
+`stroke-width={1.5}`, no fill). No emoji anywhere. If hand-rolling gets heavy,
+`lucide-react` is the one approved icon dependency.
+
+---
+
+## 2. Information architecture (sitemap)
+
+```
+/ Landing (hero → features → live proof → hooks index → support → CTA)
+/docs Docs index: intro, install, quick example, hook cards by category
+/docs/[slug] One page per hook (11 total, statically generated from registry)
+/support Donation placeholder + star/contribute cards
+/not-found Branded 404
+```
+
+- `lib/hooks-registry.ts` is the **single source of truth**: sidebar, `/docs` index,
+ `generateStaticParams`, search palette, landing "11 hooks" count, sitemap all derive
+ from it. Adding a hook = one registry entry + one demo component + one usage snippet.
+- `/docs` layout owns the sidebar (left, sticky, grouped by category, active state via
+ `usePathname`). Hook pages render inside it.
+- Header (global): Wordmark → `/`, `Docs` → `/docs`, search button (⌘K), GitHub icon
+ link → `https://github.com/saifmohamedsv/hookli`.
+- Footer (global): wordmark, `npm i hookli` mini-command, links: npm package, GitHub,
+ ISC license, `/support`.
+
+---
+
+## 3. Landing page — section order (final)
+
+1. **Hero** — the hook mark (`HookMark`) stacked above a big `hookli.` wordmark
+ (brand v3; the mono `use(hookli)` + cursor-blink treatment is retired).
+ Tagline: *"Simple React hooks. Typed. SSR-safe. Zero dependencies."*
+ Install box: `npm i hookli` with copy button (icon flips to check for 2s).
+ Primary CTA button (accent fill): **Explore the docs** → `/docs`.
+ Secondary text link: **Star on GitHub** → repo.
+2. **Feature grid** — 6 cards, 3×2 desktop / 2×3 tablet / 1-col mobile: Zero
+ dependencies, TypeScript-first, SSR-safe, Tree-shakable, ESM + CJS, 11 hooks &
+ counting. Each: SVG icon, sans title, one-sentence body.
+3. **Live proof** — split section: left = syntax-highlighted `useToggle` sample
+ (the exact code), right = that code running live (client component importing
+ from `hookli`). Header: "This demo is running the code beside it."
+4. **Hooks index strip** — all 11 hooks as compact cards (name mono + one-liner),
+ linking to their doc pages. Grouped by category headers.
+5. **Support teaser** — one row: star / contribute / sponsor-placeholder → `/support`.
+6. **Bottom CTA** — repeat install command + Explore the docs.
+
+---
+
+## 4. Hook page template (anatomy, top → bottom)
+
+Modeled on usehooks-ts's progressive disclosure + Mantine's demo-first ordering:
+
+1. **Breadcrumb-lite**: category label (small, gray).
+2. **Title**: hook name, mono h1. **Description**: 1–2 sentences, gray.
+3. **Live demo** (`HookDemo` frame): Preview/Code tabs, demo first. Frame =
+ `ground-raised` card, slate/40 border, 12px radius, min-height 180px. Error
+ boundary inside so a crashing demo never kills the page.
+4. **Usage**: heading + `CodeBlock` with the copyable snippet (same code as the
+ demo's Code tab).
+5. **API**: signature line in a code strip, then Parameters table
+ (Name / Type / Default / Description) and Returns table (Name / Type / Description).
+6. **Source link**: "View source on GitHub" → `https://github.com/saifmohamedsv/hookli`
+ (repo root — per-file deep links only if the path is verified).
+7. **Prev / Next** pager across the registry order.
+
+Right-side table of contents: added in T16 (`components/on-this-page.tsx`) — an "On this
+page" scroll-spy rail (Demo / Usage / API / Hook), hidden below `xl`, with a T12 support
+slot beneath it. Every hook page also embeds its implementation source (**Hook** section,
+`lib/hook-sources.ts`) with a view-on-GitHub link, per the usehooks-ts anatomy parity in T16.
+
+---
+
+## 5. Component inventory
+
+| Component | Type | Notes |
+|---|---|---|
+| `Header` | server | sticky, ground/90 + backdrop-blur, wordmark, nav, search trigger, GitHub |
+| `Footer` | server | links, license, mini install command |
+| `Wordmark` | server | `hookli.` lockup (ink + accent stop); `size` prop; also exports `HookMark` |
+| `Sidebar` | client | category groups, active link state, collapses to drawer <768px (T14) |
+| `HookDemo` | client | tabs Preview/Code, error boundary, consistent frame |
+| `DemoErrorBoundary` | client | class component, branded fallback |
+| `CodeBlock` | server | shiki (`css-variables` theme wired to brand tokens) + CopyButton |
+| `CopyButton` | client | clipboard API, check-icon feedback, `aria-live="polite"` |
+| `InstallCommand` | client | `$ npm i hookli` + CopyButton, used in hero/footer/docs index |
+| `FeatureCard` | server | icon + sans title + body |
+| `HookCard` | server | registry entry → linked card |
+| `ApiTable` | server | typed rows from the registry page data |
+| `SearchPalette` | client | ⌘K dialog over registry (T11) |
+| `Icons` | server | one file of inline lucide-style SVGs |
+
+Demos live in `components/demos/<slug>-demo.tsx`, one per hook, all `"use client"`.
+
+---
+
+## 6. Hook registry — canonical data (from `hookli@1.3.16` d.ts, verified)
+
+Categories (sidebar order): **state** → **effects** → **dom** → **data**.
+
+| Slug | Hook | Cat | Signature | One-liner | Demo concept |
+|---|---|---|---|---|---|
+| `use-toggle` | `useToggle` | state | `useToggle(initialValue?: boolean): [boolean, () => void, (v: boolean) => void]` | Boolean state with toggle and explicit set. | Switch + on/off readout (T6 reference) |
+| `use-form` | `useForm` | state | `useForm<T>(initialState: T): { values, handleChange, resetForm }` | Controlled form state with one change handler. | Live form → JSON values panel |
+| `use-local-storage` | `useLocalStorage` | state | `useLocalStorage<T>(key, initialValue): { value, setStoredValue }` | State persisted to localStorage. | Input that survives reload |
+| `use-local-storage-with-expiry` | `useLocalStorageWithExpiry` | state | `useLocalStorageWithExpiry<T>(key, initialValue, expiryMs): { value, setStoredValue }` | Persisted state with a TTL. | Value + countdown to expiry |
+| `use-dark-mode` | `useDarkMode` | state | `useDarkMode(): { isDarkMode, toggleDarkMode }` | Dark-mode boolean with toggle. | Scoped preview panel (never the site theme) |
+| `use-debounce` | `useDebounce` | effects | `useDebounce<T>(value: T, delay: number): T` | Debounces a changing value. | Type fast → debounced echo |
+| `use-click-outside` | `useClickOutside` | dom | `useClickOutside<T>(ref, callback): void` | Runs a callback on outside click. | Dropdown that closes on outside click |
+| `use-mouse-position` | `useMousePosition` | dom | `useMousePosition<T>(ref): { x, y }` | Cursor coordinates within an element. | Bounded tracking panel |
+| `use-infinite-scroll` | `useInfiniteScroll` | dom | `useInfiniteScroll(fetchMoreData): boolean` | Triggers loading near scroll end. | Scrollable list appending mock items |
+| `use-fetch` | `useFetch` | data | `useFetch<T>(url): { data, loading, error }` | Declarative fetch with status. | jsonplaceholder users + loading/error states |
+| `use-geo-location` | `useGeoLocation` | data | `useGeoLocation(): { location, error }` | Browser geolocation state. | Button-gated permission request, graceful denial |
+
+**SSR rule for every demo:** demos are client components; any hook touching
+`window`/`localStorage`/`document` renders behind a `mounted` flag
+(`useEffect`-set state) so `next build` prerender stays green. `useGeoLocation`
+mounts its hook-consuming subtree only after an explicit user click.
+
+---
+
+## 7. Search (T11 spec)
+
+Client-only command palette over the registry — no service, no index build.
+⌘K / Ctrl+K and header button open it; fuzzy-ish filter on name + description +
+category (lowercase substring match is enough for 11 items). Arrow keys navigate,
+Enter routes, Esc closes. Rendered in a portal; focus trap; `role="dialog"` +
+`aria-modal`; list uses `role="listbox"`/`option`. Full-screen sheet at <640px.
+
+---
+
+## 8. Interaction, motion, a11y standards
+
+- Focus: visible 2px accent ring (`outline-accent`, offset 2) on every interactive.
+- Touch targets ≥44×44px; icon buttons get padding to reach it.
+- Micro-interactions 150–300ms ease-out. `prefers-reduced-motion: reduce` kills all
+ animations and transitions (global CSS guard).
+- Contrast: body `#8FB6C2`+ on `#003748` (≥4.5:1); UI chrome may use slate.
+- Breakpoints checked every task: 375 / 768 / 1024 / 1440. No horizontal scroll at 375.
+- Code blocks: `overflow-x-auto`, never wrap-break code.
+
+---
+
+## 9. Next.js 16 build notes (verified against bundled docs)
+
+- `params` in dynamic routes/layouts/`generateMetadata` is a **Promise — `await` it**.
+- `themeColor`/`viewport` do **not** go in `metadata` — export `viewport` separately.
+- `next/image`: use `preload`, not the deprecated `priority`.
+- Tailwind v4: tokens via `@theme` in `globals.css`; no config-file theme.
+- Per-hook OG images via `app/docs/[slug]/opengraph-image.tsx` (ImageResponse);
+ `app/sitemap.ts` + `app/robots.ts` generated from the registry (T13).
+- Root `metadata`: title template `"hookli — %s"`, default `"hookli — simple React hooks"`.
+
+## 10. Dependency policy
+
+Approved when their task lands: **shiki** (T6, highlighting — build-time/server only),
+**lucide-react** (only if inline SVGs become a burden). Nothing else without a
+progress.txt note. Demos import from **`hookli`** (npm) — never relative paths into
+`../rehooks-app`.
diff --git a/apps/docs/eslint.config.mjs b/apps/docs/eslint.config.mjs
new file mode 100644
index 0000000..05e726d
--- /dev/null
+++ b/apps/docs/eslint.config.mjs
@@ -0,0 +1,18 @@
+import { defineConfig, globalIgnores } from "eslint/config";
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTs from "eslint-config-next/typescript";
+
+const eslintConfig = defineConfig([
+ ...nextVitals,
+ ...nextTs,
+ // Override default ignores of eslint-config-next.
+ globalIgnores([
+ // Default ignores of eslint-config-next:
+ ".next/**",
+ "out/**",
+ "build/**",
+ "next-env.d.ts",
+ ]),
+]);
+
+export default eslintConfig;
diff --git a/apps/docs/lib/hook-docs.ts b/apps/docs/lib/hook-docs.ts
new file mode 100644
index 0000000..5b0d0d2
--- /dev/null
+++ b/apps/docs/lib/hook-docs.ts
@@ -0,0 +1,2199 @@
+import type { ComponentType } from "react";
+import type { ApiRow } from "@/components/api-table";
+import { UseBooleanDocDemo } from "@/components/demos/use-boolean-demo";
+import { UseClickAnyWhereDocDemo } from "@/components/demos/use-click-any-where-demo";
+import { UseClickOutsideDocDemo } from "@/components/demos/use-click-outside-demo";
+import { UseCopyToClipboardDocDemo } from "@/components/demos/use-copy-to-clipboard-demo";
+import { UseCountdownDocDemo } from "@/components/demos/use-countdown-demo";
+import { UseCounterDocDemo } from "@/components/demos/use-counter-demo";
+import { UseDarkModeDocDemo } from "@/components/demos/use-dark-mode-demo";
+import { UseDebounceDocDemo } from "@/components/demos/use-debounce-demo";
+import { UseDebounceCallbackDocDemo } from "@/components/demos/use-debounce-callback-demo";
+import { UseDebounceValueDocDemo } from "@/components/demos/use-debounce-value-demo";
+import { UseDocumentTitleDocDemo } from "@/components/demos/use-document-title-demo";
+import { UseEventCallbackDocDemo } from "@/components/demos/use-event-callback-demo";
+import { UseEventListenerDocDemo } from "@/components/demos/use-event-listener-demo";
+import { UseFetchDocDemo } from "@/components/demos/use-fetch-demo";
+import { UseFormDocDemo } from "@/components/demos/use-form-demo";
+import { UseGeoLocationDocDemo } from "@/components/demos/use-geo-location-demo";
+import { UseHoverDocDemo } from "@/components/demos/use-hover-demo";
+import { UseInfiniteScrollDocDemo } from "@/components/demos/use-infinite-scroll-demo";
+import { UseIntersectionObserverDocDemo } from "@/components/demos/use-intersection-observer-demo";
+import { UseIntervalDocDemo } from "@/components/demos/use-interval-demo";
+import { UseIsClientDocDemo } from "@/components/demos/use-is-client-demo";
+import { UseIsMountedDocDemo } from "@/components/demos/use-is-mounted-demo";
+import { UseIsomorphicLayoutEffectDocDemo } from "@/components/demos/use-isomorphic-layout-effect-demo";
+import { UseLocalStorageDocDemo } from "@/components/demos/use-local-storage-demo";
+import { UseLocalStorageWithExpiryDocDemo } from "@/components/demos/use-local-storage-with-expiry-demo";
+import { UseMapDocDemo } from "@/components/demos/use-map-demo";
+import { UseMediaQueryDocDemo } from "@/components/demos/use-media-query-demo";
+import { UseMousePositionDocDemo } from "@/components/demos/use-mouse-position-demo";
+import { UseReadLocalStorageDocDemo } from "@/components/demos/use-read-local-storage-demo";
+import { UseResizeObserverDocDemo } from "@/components/demos/use-resize-observer-demo";
+import { UseScreenDocDemo } from "@/components/demos/use-screen-demo";
+import { UseScriptDocDemo } from "@/components/demos/use-script-demo";
+import { UseScrollLockDocDemo } from "@/components/demos/use-scroll-lock-demo";
+import { UseSessionStorageDocDemo } from "@/components/demos/use-session-storage-demo";
+import { UseStepDocDemo } from "@/components/demos/use-step-demo";
+import { UseTernaryDarkModeDocDemo } from "@/components/demos/use-ternary-dark-mode-demo";
+import { UseTimeoutDocDemo } from "@/components/demos/use-timeout-demo";
+import { UseToggleDocDemo } from "@/components/demos/use-toggle-demo";
+import { UseUnmountDocDemo } from "@/components/demos/use-unmount-demo";
+import { UseWindowSizeDocDemo } from "@/components/demos/use-window-size-demo";
+
+/* Per-hook page content layered on top of the registry entry (docs/DESIGN.md
+ §4): live demo component, usage snippet (shown in the HookDemo Code tab AND
+ the Usage section — one string, always identical), API tables. T7–T10 add
+ the remaining hooks; a slug without an entry renders the signature-only
+ scaffold. Data here must match the hookli@1.3.16 type declarations. */
+
+/* A named type referenced by the signature (e.g. GeolocationPosition), rendered
+ as its own Name/Type/Description table below the Returns table (T16). */
+export type TypeAlias = {
+ name: string;
+ description?: string;
+ rows: readonly ApiRow[];
+};
+
+export type HookDoc = {
+ demo: ComponentType;
+ usage: string;
+ parameters: readonly ApiRow[];
+ returns: readonly ApiRow[];
+ typeAliases?: readonly TypeAlias[];
+};
+
+/* Shared by the two debounce hooks (useDebounceValue + useDebounceCallback),
+ which both take DebounceOptions and return a DebouncedState. */
+const DEBOUNCE_OPTIONS_ALIAS: TypeAlias = {
+ name: "DebounceOptions",
+ description: "Controls how the debounced invocation is scheduled.",
+ rows: [
+ {
+ name: "leading",
+ type: "boolean",
+ defaultValue: "false",
+ description: "Invoke on the leading edge — run once immediately on the first call of a burst.",
+ },
+ {
+ name: "trailing",
+ type: "boolean",
+ defaultValue: "true",
+ description: "Invoke on the trailing edge — run after the burst settles.",
+ },
+ {
+ name: "maxWait",
+ type: "number",
+ description: "The maximum time the callback may be delayed before it is forced to run, even during a continuous burst.",
+ },
+ ],
+};
+
+const DEBOUNCED_STATE_ALIAS: TypeAlias = {
+ name: "DebouncedState<Args, R>",
+ description: "The debounced function, plus manual control methods.",
+ rows: [
+ {
+ name: "(...args)",
+ type: "(...args: Args) => R | undefined",
+ description: "Calling it schedules an invocation and returns the last computed result — undefined before the first run.",
+ },
+ {
+ name: "cancel",
+ type: "() => void",
+ description: "Cancels any pending trailing invocation.",
+ },
+ {
+ name: "flush",
+ type: "() => R | undefined",
+ description: "Immediately runs any pending invocation and returns its result.",
+ },
+ {
+ name: "isPending",
+ type: "() => boolean",
+ description: "Whether a trailing invocation is currently scheduled.",
+ },
+ ],
+};
+
+/* Options for the sessionStorage hook (serializer/deserializer + hydration). */
+const SESSION_STORAGE_OPTIONS_ALIAS: TypeAlias = {
+ name: "UseSessionStorageOptions<T>",
+ description: "Custom (de)serialization and hydration behaviour.",
+ rows: [
+ {
+ name: "serializer",
+ type: "(value: T) => string",
+ description: "Turn the value into the string stored under the key. Defaults to JSON.stringify.",
+ },
+ {
+ name: "deserializer",
+ type: "(value: string) => T",
+ description: "Parse the stored string back into a value. Defaults to JSON.parse.",
+ },
+ {
+ name: "initializeWithValue",
+ type: "boolean",
+ defaultValue: "true",
+ description: "Read sessionStorage synchronously on mount. Set false to defer to after hydration and avoid SSR mismatches.",
+ },
+ ],
+};
+
+/* Options for the read-only localStorage hook (deserializer + hydration). */
+const READ_LOCAL_STORAGE_OPTIONS_ALIAS: TypeAlias = {
+ name: "UseReadLocalStorageOptions<T>",
+ description: "Custom deserialization and hydration behaviour.",
+ rows: [
+ {
+ name: "deserializer",
+ type: "(value: string) => T",
+ description: "Parse the stored string into a value. Defaults to JSON.parse, falling back to the raw string.",
+ },
+ {
+ name: "initializeWithValue",
+ type: "boolean",
+ defaultValue: "true",
+ description: "Read localStorage synchronously on mount. Set false to defer to after hydration and avoid SSR mismatches.",
+ },
+ ],
+};
+
+/* Options + return shape for the three-state dark-mode hook (DH9). */
+const TERNARY_DARK_MODE_OPTIONS_ALIAS: TypeAlias = {
+ name: "UseTernaryDarkModeOptions",
+ description: "Optional starting mode and persistence key.",
+ rows: [
+ {
+ name: "defaultValue",
+ type: "TernaryDarkMode",
+ defaultValue: '"system"',
+ description: "The mode before anything is stored: \"system\", \"dark\" or \"light\".",
+ },
+ {
+ name: "localStorageKey",
+ type: "string",
+ defaultValue: '"hookli-ternary-dark-mode"',
+ description: "The localStorage key the choice is persisted under.",
+ },
+ ],
+};
+
+const TERNARY_DARK_MODE_RETURN_ALIAS: TypeAlias = {
+ name: "UseTernaryDarkModeReturn",
+ description: "The resolved mode plus setters.",
+ rows: [
+ {
+ name: "isDarkMode",
+ type: "boolean",
+ description: 'True when the mode is "dark", or "system" while the OS prefers dark.',
+ },
+ {
+ name: "ternaryDarkMode",
+ type: "TernaryDarkMode",
+ description: 'The stored preference: "system" | "dark" | "light".',
+ },
+ {
+ name: "setTernaryDarkMode",
+ type: "(value: TernaryDarkMode | ((prev: TernaryDarkMode) => TernaryDarkMode)) => void",
+ description: "Set the preference directly; accepts a value or an updater.",
+ },
+ {
+ name: "toggleTernaryDarkMode",
+ type: "() => void",
+ description: "Cycle the preference: light → system → dark → light.",
+ },
+ ],
+};
+
+/* Options for the external-script loader (DH9). */
+const SCRIPT_OPTIONS_ALIAS: TypeAlias = {
+ name: "UseScriptOptions",
+ description: "Flags controlling when the script loads and unloads.",
+ rows: [
+ {
+ name: "shouldPreventLoad",
+ type: "boolean",
+ defaultValue: "false",
+ description: "Keep the status \"idle\" without injecting the script — useful for deferring a load.",
+ },
+ {
+ name: "removeOnUnmount",
+ type: "boolean",
+ defaultValue: "false",
+ description: "Remove the injected <script> tag when the component unmounts.",
+ },
+ ],
+};
+
+const HOOK_DOCS: Partial<Record<string, HookDoc>> = {
+ "use-toggle": {
+ demo: UseToggleDocDemo,
+ usage: `
+import { useToggle } from "hookli";
+
+export function Demo() {
+ const [on, toggle, setOn] = useToggle(false);
+
+ return (
+ <div>
+ <button onClick={toggle}>{on ? "On" : "Off"}</button>
+ <button onClick={() => setOn(true)}>Set on</button>
+ <button onClick={() => setOn(false)}>Set off</button>
+ </div>
+ );
+}
+`,
+ parameters: [
+ {
+ name: "initialValue",
+ type: "boolean",
+ defaultValue: "false",
+ description: "The value the toggle starts from.",
+ },
+ ],
+ returns: [
+ {
+ name: "[0] value",
+ type: "boolean",
+ description: "The current boolean state.",
+ },
+ {
+ name: "[1] toggle",
+ type: "() => void",
+ description: "Flips the value.",
+ },
+ {
+ name: "[2] setValue",
+ type: "(value: boolean) => void",
+ description: "Sets the value explicitly.",
+ },
+ ],
+ },
+ "use-debounce": {
+ demo: UseDebounceDocDemo,
+ usage: `
+import { useState } from "react";
+import { useDebounce } from "hookli";
+
+export function Demo() {
+ const [text, setText] = useState("");
+ const debounced = useDebounce(text, 500);
+
+ return (
+ <div>
+ <input value={text} onChange={(e) => setText(e.target.value)} />
+ <p>Value: {text}</p>
+ <p>Debounced: {debounced}</p>
+ </div>
+ );
+}
+`,
+ parameters: [
+ {
+ name: "value",
+ type: "T",
+ description: "The value to debounce — any type works.",
+ },
+ {
+ name: "delay",
+ type: "number",
+ description: "Milliseconds the value must stay unchanged before the debounced value updates.",
+ },
+ ],
+ returns: [
+ {
+ name: "debouncedValue",
+ type: "T",
+ description: "Trails the input value, updating only after delay ms without a change.",
+ },
+ ],
+ },
+ "use-debounce-value": {
+ demo: UseDebounceValueDocDemo,
+ usage: `
+import { useState } from "react";
+import { useDebounceValue } from "hookli";
+
+export function Demo() {
+ const [text, setText] = useState("");
+ const [debounced, setValue] = useDebounceValue("", 500);
+
+ return (
+ <div>
+ <input
+ value={text}
+ onChange={(e) => {
+ setText(e.target.value);
+ setValue(e.target.value);
+ }}
+ />
+ <p>Debounced: {debounced}</p>
+ </div>
+ );
+}
+`,
+ parameters: [
+ {
+ name: "initialValue",
+ type: "T | (() => T)",
+ description: "The starting value, or a factory evaluated once on mount — the same lazy-initializer contract as useState.",
+ },
+ {
+ name: "delayMs",
+ type: "number",
+ defaultValue: "500",
+ description: "Milliseconds of inactivity before the debounced value catches up to the latest set value.",
+ },
+ {
+ name: "options",
+ type: "DebounceOptions & { equalityFn? }",
+ defaultValue: "{}",
+ description: "DebounceOptions plus an optional equalityFn (left, right) => boolean — when it reports the values equal, the debounced update is skipped. See the tables below.",
+ },
+ ],
+ returns: [
+ {
+ name: "[0] debouncedValue",
+ type: "T",
+ description: "The value that trails the setter, updating only after delayMs of quiet.",
+ },
+ {
+ name: "[1] setValue",
+ type: "DebouncedState<[T | ((prev: T) => T)], void>",
+ description: "A debounced setter accepting a value or updater; it also carries cancel, flush and isPending (see DebouncedState).",
+ },
+ ],
+ typeAliases: [DEBOUNCE_OPTIONS_ALIAS, DEBOUNCED_STATE_ALIAS],
+ },
+ "use-debounce-callback": {
+ demo: UseDebounceCallbackDocDemo,
+ usage: `
+import { useState } from "react";
+import { useDebounceCallback } from "hookli";
+
+export function Demo() {
+ const [query, setQuery] = useState("");
+
+ const search = useDebounceCallback((q: string) => {
+ console.log("searching", q);
+ }, 600);
+
+ return (
+ <input
+ value={query}
+ onChange={(e) => {
+ setQuery(e.target.value);
+ search(e.target.value);
+ }}
+ />
+ );
+}
+`,
+ parameters: [
+ {
+ name: "fn",
+ type: "(...args: Args) => R",
+ description: "The function to debounce. The returned function keeps a stable identity across renders but always invokes the latest fn.",
+ },
+ {
+ name: "delayMs",
+ type: "number",
+ defaultValue: "500",
+ description: "Milliseconds to wait after the last call before fn runs.",
+ },
+ {
+ name: "options",
+ type: "DebounceOptions",
+ defaultValue: "{}",
+ description: "Leading/trailing edge and maxWait behaviour. See the table below.",
+ },
+ ],
+ returns: [
+ {
+ name: "debounced",
+ type: "DebouncedState<Args, R>",
+ description: "A debounced version of fn with a stable identity, carrying cancel, flush and isPending. Any pending call is cancelled on unmount.",
+ },
+ ],
+ typeAliases: [DEBOUNCE_OPTIONS_ALIAS, DEBOUNCED_STATE_ALIAS],
+ },
+ "use-interval": {
+ demo: UseIntervalDocDemo,
+ usage: `
+import { useState } from "react";
+import { useInterval } from "hookli";
+
+export function Demo() {
+ const [count, setCount] = useState(0);
+ const [running, setRunning] = useState(true);
+
+ useInterval(() => setCount((prev) => prev + 1), running ? 1000 : null);
+
+ return (
+ <div>
+ <p>{count}</p>
+ <button onClick={() => setRunning((prev) => !prev)}>
+ {running ? "Pause" : "Resume"}
+ </button>
+ </div>
+ );
+}
+`,
+ parameters: [
+ {
+ name: "callback",
+ type: "() => void",
+ description: "Runs on every tick. Always fires the latest callback — the hook keeps a ref, so you never re-arm the timer just to close over fresh state.",
+ },
+ {
+ name: "delay",
+ type: "number | null",
+ description: "Milliseconds between ticks. Pass null to pause — the interval is cleared, so nothing runs until you set a number again.",
+ },
+ ],
+ returns: [],
+ },
+ "use-timeout": {
+ demo: UseTimeoutDocDemo,
+ usage: `
+import { useState } from "react";
+import { useTimeout } from "hookli";
+
+export function Demo() {
+ const [visible, setVisible] = useState(false);
+ const [delay, setDelay] = useState<number | null>(null);
+
+ useTimeout(() => {
+ setVisible(true);
+ setDelay(null);
+ }, delay);
+
+ return (
+ <div>
+ <button onClick={() => setDelay(2000)}>Reveal in 2s</button>
+ {visible && <p>Here!</p>}
+ </div>
+ );
+}
+`,
+ parameters: [
+ {
+ name: "callback",
+ type: "() => void",
+ description: "Runs once after the delay elapses. The hook keeps a ref to the latest callback, so it always fires with fresh state.",
+ },
+ {
+ name: "delay",
+ type: "number | null",
+ description: "Milliseconds to wait before firing. Pass null to disable — a change to null before the delay elapses cancels the pending timeout.",
+ },
+ ],
+ returns: [],
+ },
+ "use-isomorphic-layout-effect": {
+ demo: UseIsomorphicLayoutEffectDocDemo,
+ usage: `
+import { useRef, useState } from "react";
+import { useIsomorphicLayoutEffect } from "hookli";
+
+export function Demo() {
+ const boxRef = useRef<HTMLDivElement>(null);
+ const [width, setWidth] = useState(0);
+
+ useIsomorphicLayoutEffect(() => {
+ setWidth(boxRef.current?.offsetWidth ?? 0);
+ }, []);
+
+ return <div ref={boxRef}>Measured: {width}px</div>;
+}
+`,
+ parameters: [
+ {
+ name: "effect",
+ type: "EffectCallback",
+ description: "The effect to run — same contract as React's useLayoutEffect, including an optional cleanup return.",
+ },
+ {
+ name: "deps",
+ type: "DependencyList",
+ description: "Dependency array controlling when the effect re-runs. Omit to run after every render.",
+ },
+ ],
+ returns: [],
+ },
+ "use-event-callback": {
+ demo: UseEventCallbackDocDemo,
+ usage: `
+import { useState } from "react";
+import { useEventCallback } from "hookli";
+
+export function Demo() {
+ const [count, setCount] = useState(0);
+
+ const readLatest = useEventCallback(() => count);
+
+ return (
+ <div>
+ <button onClick={() => setCount((prev) => prev + 1)}>{count}</button>
+ <button onClick={() => alert(readLatest())}>Read latest</button>
+ </div>
+ );
+}
+`,
+ parameters: [
+ {
+ name: "fn",
+ type: "(...args: Args) => R",
+ description: "The function to keep current behind a stable reference. Calling during render throws — it is meant for event handlers and effects.",
+ },
+ ],
+ returns: [
+ {
+ name: "callback",
+ type: "(...args: Args) => R",
+ description: "A memoized callback with an unchanging identity that always forwards to the latest fn.",
+ },
+ ],
+ },
+ "use-unmount": {
+ demo: UseUnmountDocDemo,
+ usage: `
+import { useUnmount } from "hookli";
+
+export function Demo() {
+ useUnmount(() => {
+ console.log("cleanup on unmount");
+ });
+
+ return <p>Watch the console when I unmount.</p>;
+}
+`,
+ parameters: [
+ {
+ name: "fn",
+ type: "() => void",
+ description: "Called exactly once when the component unmounts. The latest closure is captured in a ref, so it always sees fresh values.",
+ },
+ ],
+ returns: [],
+ },
+ "use-is-client": {
+ demo: UseIsClientDocDemo,
+ usage: `
+import { useIsClient } from "hookli";
+
+export function Demo() {
+ const isClient = useIsClient();
+
+ if (!isClient) return <p>Rendering on the server…</p>;
+
+ return <p>Now running in the browser.</p>;
+}
+`,
+ parameters: [],
+ returns: [
+ {
+ name: "isClient",
+ type: "boolean",
+ description: "false during server rendering and the first hydration pass, then true once mounted in the browser. Gate browser-only UI on it to keep both renders identical.",
+ },
+ ],
+ },
+ "use-is-mounted": {
+ demo: UseIsMountedDocDemo,
+ usage: `
+import { useIsMounted } from "hookli";
+
+export function Demo() {
+ const isMounted = useIsMounted();
+
+ async function load() {
+ const data = await fetchData();
+ if (isMounted()) setData(data);
+ }
+
+ return <button onClick={load}>Load</button>;
+}
+`,
+ parameters: [],
+ returns: [
+ {
+ name: "isMounted",
+ type: "() => boolean",
+ description: "A stable getter that returns true while mounted and false after unmount. Call it inside async callbacks before setting state; its identity never changes, so it is safe to omit from dependency arrays.",
+ },
+ ],
+ },
+ "use-document-title": {
+ demo: UseDocumentTitleDocDemo,
+ usage: `
+import { useDocumentTitle } from "hookli";
+
+export function Demo() {
+ useDocumentTitle("Dashboard — hookli", {
+ preserveTitleOnUnmount: false,
+ });
+
+ return <h1>Dashboard</h1>;
+}
+`,
+ parameters: [
+ {
+ name: "title",
+ type: "string",
+ description: "The document title to apply. Written to document.title in a layout effect on the client and skipped during server rendering.",
+ },
+ {
+ name: "options",
+ type: "UseDocumentTitleOptions",
+ defaultValue: "{}",
+ description: "Behaviour options (see below).",
+ },
+ ],
+ returns: [],
+ typeAliases: [
+ {
+ name: "UseDocumentTitleOptions",
+ description: "Options controlling unmount behaviour.",
+ rows: [
+ {
+ name: "preserveTitleOnUnmount",
+ type: "boolean",
+ defaultValue: "true",
+ description: "When false, the title captured on mount is restored when the component unmounts. Defaults to true, which leaves the title in place.",
+ },
+ ],
+ },
+ ],
+ },
+ "use-event-listener": {
+ demo: UseEventListenerDocDemo,
+ usage: `
+import { useRef, useState } from "react";
+import { useEventListener } from "hookli";
+
+export function Demo() {
+ const ref = useRef<HTMLDivElement>(null);
+ const [lastKey, setLastKey] = useState("");
+
+ useEventListener("keydown", (event) => setLastKey(event.key));
+ useEventListener("click", () => console.log("clicked"), ref);
+
+ return <div ref={ref}>Last key: {lastKey}</div>;
+}
+`,
+ parameters: [
+ {
+ name: "eventName",
+ type: "K",
+ description: "The event to listen for, typed against the target's event map (window, document, media query, or element).",
+ },
+ {
+ name: "handler",
+ type: "(event) => void",
+ description: "Called with the typed event on every dispatch. Held in a ref, so updating it never detaches and re-attaches the listener.",
+ },
+ {
+ name: "element",
+ type: "RefObject<T>",
+ defaultValue: "window",
+ description: "Optional ref to the target. Defaults to window when omitted.",
+ },
+ {
+ name: "options",
+ type: "boolean | AddEventListenerOptions",
+ description: "Standard addEventListener options (capture, passive, once).",
+ },
+ ],
+ returns: [],
+ },
+ "use-form": {
+ demo: UseFormDocDemo,
+ usage: `
+import { useForm } from "hookli";
+
+export function Demo() {
+ const { values, handleChange, resetForm } = useForm({ name: "", email: "" });
+
+ return (
+ <form onSubmit={(e) => e.preventDefault()}>
+ <input name="name" value={values.name} onChange={handleChange} />
+ <input name="email" type="email" value={values.email} onChange={handleChange} />
+ <button type="button" onClick={resetForm}>Reset</button>
+ </form>
+ );
+}
+`,
+ parameters: [
+ {
+ name: "initialState",
+ type: "T",
+ description: "Initial field values. Keys must match the name attribute of each input.",
+ },
+ ],
+ returns: [
+ {
+ name: "values",
+ type: "T",
+ description: "The current form values.",
+ },
+ {
+ name: "handleChange",
+ type: "(event: ChangeEvent) => void",
+ description: "One change handler for every named input, textarea and select.",
+ },
+ {
+ name: "resetForm",
+ type: "() => void",
+ description: "Restores initialState.",
+ },
+ ],
+ },
+ "use-local-storage": {
+ demo: UseLocalStorageDocDemo,
+ usage: `
+import { useLocalStorage } from "hookli";
+
+export function Demo() {
+ const { value, setStoredValue } = useLocalStorage("note", "");
+
+ return (
+ <div>
+ <input value={value} onChange={(e) => setStoredValue(e.target.value)} />
+ <button type="button" onClick={() => setStoredValue("")}>Clear</button>
+ </div>
+ );
+}
+`,
+ parameters: [
+ {
+ name: "key",
+ type: "string",
+ description: "The localStorage key to read and write.",
+ },
+ {
+ name: "initialValue",
+ type: "T",
+ description: "Value used before hydration and when the key is empty. Prefer a stable reference — the sync effect depends on it.",
+ },
+ ],
+ returns: [
+ {
+ name: "value",
+ type: "T",
+ description: "The stored value. Server-rendered as initialValue, then synced from localStorage after mount.",
+ },
+ {
+ name: "setStoredValue",
+ type: "(value: T | ((val: T) => T)) => void",
+ description: "Persists to localStorage and updates state; accepts a value or an updater function.",
+ },
+ ],
+ },
+ "use-local-storage-with-expiry": {
+ demo: UseLocalStorageWithExpiryDocDemo,
+ usage: `
+import { useLocalStorageWithExpiry } from "hookli";
+
+export function Demo() {
+ const { value, setStoredValue } = useLocalStorageWithExpiry(
+ "draft",
+ "",
+ 10_000,
+ );
+
+ return (
+ <div>
+ <button onClick={() => setStoredValue("hello")}>Save for 10s</button>
+ <p>{value === null ? "Expired" : value || "Nothing stored"}</p>
+ </div>
+ );
+}
+`,
+ parameters: [
+ {
+ name: "key",
+ type: "string",
+ description: "The localStorage key to read and write.",
+ },
+ {
+ name: "initialValue",
+ type: "T",
+ description: "Value used before hydration and when nothing is stored under the key.",
+ },
+ {
+ name: "expiryMs",
+ type: "number",
+ description: "Time-to-live in milliseconds. Every write stores the value with a fresh expiry timestamp.",
+ },
+ ],
+ returns: [
+ {
+ name: "value",
+ type: "T | null",
+ description: "The stored value, or null once the item has expired. Expiry is checked when the hook reads — on mount or key change — at which point the item is removed.",
+ },
+ {
+ name: "setStoredValue",
+ type: "(value: T) => void",
+ description: "Persists the value to localStorage with a new expiry of now + expiryMs.",
+ },
+ ],
+ },
+ "use-session-storage": {
+ demo: UseSessionStorageDocDemo,
+ usage: `
+import { useSessionStorage } from "hookli";
+
+export function Demo() {
+ const [draft, setDraft, removeDraft] = useSessionStorage("draft", "");
+
+ return (
+ <div>
+ <input value={draft} onChange={(e) => setDraft(e.target.value)} />
+ <button type="button" onClick={removeDraft}>Clear</button>
+ </div>
+ );
+}
+`,
+ parameters: [
+ {
+ name: "key",
+ type: "string",
+ description: "The sessionStorage key to read and write.",
+ },
+ {
+ name: "initialValue",
+ type: "T | (() => T)",
+ description: "Value used before hydration and when the key is empty. Pass a function to compute it lazily.",
+ },
+ {
+ name: "options",
+ type: "UseSessionStorageOptions<T>",
+ defaultValue: "{}",
+ description: "Optional custom serializer/deserializer and hydration flag.",
+ },
+ ],
+ returns: [
+ {
+ name: "[0] value",
+ type: "T",
+ description: "The stored value. Server-rendered as initialValue, then hydrated from sessionStorage after mount.",
+ },
+ {
+ name: "[1] setValue",
+ type: "(value: T | ((prev: T) => T)) => void",
+ description: "Persists to sessionStorage and updates state; accepts a value or an updater. Syncs every hook using the key in this tab.",
+ },
+ {
+ name: "[2] removeValue",
+ type: "() => void",
+ description: "Removes the key from sessionStorage and resets state to initialValue.",
+ },
+ ],
+ typeAliases: [SESSION_STORAGE_OPTIONS_ALIAS],
+ },
+ "use-read-local-storage": {
+ demo: UseReadLocalStorageDocDemo,
+ usage: `
+import { useReadLocalStorage } from "hookli";
+
+export function Demo() {
+ const theme = useReadLocalStorage<string>("theme");
+
+ return <p>Saved theme: {theme ?? "none"}</p>;
+}
+`,
+ parameters: [
+ {
+ name: "key",
+ type: "string",
+ description: "The localStorage key to observe.",
+ },
+ {
+ name: "options",
+ type: "UseReadLocalStorageOptions<T>",
+ defaultValue: "{}",
+ description: "Optional custom deserializer and hydration flag.",
+ },
+ ],
+ returns: [
+ {
+ name: "value",
+ type: "T | null",
+ description: "The parsed value, or null when the key is absent. Re-renders when the key changes in another tab (storage event) or via a local-storage event dispatched in this tab.",
+ },
+ ],
+ typeAliases: [READ_LOCAL_STORAGE_OPTIONS_ALIAS],
+ },
+ "use-dark-mode": {
+ demo: UseDarkModeDocDemo,
+ usage: `
+import { useDarkMode } from "hookli";
+
+export function Demo() {
+ const { isDarkMode, toggleDarkMode } = useDarkMode();
+
+ return (
+ <div className={isDarkMode ? "panel-dark" : "panel-light"}>
+ <button onClick={toggleDarkMode}>
+ {isDarkMode ? "Switch to light" : "Switch to dark"}
+ </button>
+ </div>
+ );
+}
+`,
+ parameters: [],
+ returns: [
+ {
+ name: "isDarkMode",
+ type: "boolean",
+ description: 'Current mode. Initialized from localStorage("theme") on the client; false during SSR.',
+ },
+ {
+ name: "toggleDarkMode",
+ type: "() => void",
+ description: 'Flips the mode. An effect persists it to localStorage("theme") and toggles a "dark" class on <body>.',
+ },
+ ],
+ },
+ "use-ternary-dark-mode": {
+ demo: UseTernaryDarkModeDocDemo,
+ usage: `
+import { useTernaryDarkMode } from "hookli";
+
+export function Demo() {
+ const { isDarkMode, ternaryDarkMode, setTernaryDarkMode } =
+ useTernaryDarkMode();
+
+ return (
+ <div className={isDarkMode ? "panel-dark" : "panel-light"}>
+ <select
+ value={ternaryDarkMode}
+ onChange={(e) => setTernaryDarkMode(e.target.value)}
+ >
+ <option value="light">Light</option>
+ <option value="system">System</option>
+ <option value="dark">Dark</option>
+ </select>
+ </div>
+ );
+}
+`,
+ parameters: [
+ {
+ name: "options",
+ type: "UseTernaryDarkModeOptions",
+ defaultValue: "{}",
+ description: "Optional starting mode and localStorage key.",
+ },
+ ],
+ returns: [
+ {
+ name: "{ … }",
+ type: "UseTernaryDarkModeReturn",
+ description: "The resolved isDarkMode boolean, the stored ternary preference, and its setters.",
+ },
+ ],
+ typeAliases: [
+ {
+ name: "TernaryDarkMode",
+ description: "The three possible preferences.",
+ rows: [
+ {
+ name: "value",
+ type: '"system" | "dark" | "light"',
+ description: '"system" resolves against the OS; "dark"/"light" force a mode.',
+ },
+ ],
+ },
+ TERNARY_DARK_MODE_OPTIONS_ALIAS,
+ TERNARY_DARK_MODE_RETURN_ALIAS,
+ ],
+ },
+ "use-boolean": {
+ demo: UseBooleanDocDemo,
+ usage: `
+import { useBoolean } from "hookli";
+
+export function Demo() {
+ const { value, setTrue, setFalse, toggle } = useBoolean(false);
+
+ return (
+ <div>
+ <p>{value ? "On" : "Off"}</p>
+ <button onClick={toggle}>Toggle</button>
+ <button onClick={setTrue}>On</button>
+ <button onClick={setFalse}>Off</button>
+ </div>
+ );
+}
+`,
+ parameters: [
+ {
+ name: "defaultValue",
+ type: "boolean",
+ defaultValue: "false",
+ description: "The value the boolean starts from.",
+ },
+ ],
+ returns: [
+ {
+ name: "value",
+ type: "boolean",
+ description: "The current boolean value.",
+ },
+ {
+ name: "setValue",
+ type: "(value: boolean) => void",
+ description: "Sets the value directly.",
+ },
+ {
+ name: "setTrue",
+ type: "() => void",
+ description: "Sets the value to true.",
+ },
+ {
+ name: "setFalse",
+ type: "() => void",
+ description: "Sets the value to false.",
+ },
+ {
+ name: "toggle",
+ type: "() => void",
+ description: "Flips the value.",
+ },
+ ],
+ },
+ "use-counter": {
+ demo: UseCounterDocDemo,
+ usage: `
+import { useCounter } from "hookli";
+
+export function Demo() {
+ const { count, increment, decrement, reset, setCount } = useCounter(0);
+
+ return (
+ <div>
+ <p>{count}</p>
+ <button onClick={decrement}>-1</button>
+ <button onClick={increment}>+1</button>
+ <button onClick={() => setCount(10)}>Set 10</button>
+ <button onClick={reset}>Reset</button>
+ </div>
+ );
+}
+`,
+ parameters: [
+ {
+ name: "initialValue",
+ type: "number",
+ defaultValue: "0",
+ description: "The count the hook starts from; reset returns here.",
+ },
+ ],
+ returns: [
+ {
+ name: "count",
+ type: "number",
+ description: "The current count.",
+ },
+ {
+ name: "increment",
+ type: "() => void",
+ description: "Adds one to the count.",
+ },
+ {
+ name: "decrement",
+ type: "() => void",
+ description: "Subtracts one from the count.",
+ },
+ {
+ name: "reset",
+ type: "() => void",
+ description: "Restores the count to initialValue.",
+ },
+ {
+ name: "setCount",
+ type: "Dispatch<SetStateAction<number>>",
+ description: "Sets the count directly; accepts a value or an updater function.",
+ },
+ ],
+ },
+ "use-step": {
+ demo: UseStepDocDemo,
+ usage: `
+import { useStep } from "hookli";
+
+export function Demo() {
+ const [step, { goToNextStep, goToPrevStep, canGoToNextStep, canGoToPrevStep, reset }] =
+ useStep(4);
+
+ return (
+ <div>
+ <p>Step {step} of 4</p>
+ <button onClick={goToPrevStep} disabled={!canGoToPrevStep}>Back</button>
+ <button onClick={goToNextStep} disabled={!canGoToNextStep}>Next</button>
+ <button onClick={reset}>Reset</button>
+ </div>
+ );
+}
+`,
+ parameters: [
+ {
+ name: "maxStep",
+ type: "number",
+ description: "The highest reachable step (inclusive). Steps run from 1 to maxStep.",
+ },
+ ],
+ returns: [
+ {
+ name: "[0] step",
+ type: "number",
+ description: "The current step, 1-indexed.",
+ },
+ {
+ name: "[1] actions",
+ type: "UseStepActions",
+ description: "Controls for moving between steps — see below.",
+ },
+ ],
+ typeAliases: [
+ {
+ name: "UseStepActions",
+ description: "The second tuple element — the stepper controls.",
+ rows: [
+ {
+ name: "goToNextStep",
+ type: "() => void",
+ description: "Advances to the next step; a no-op at maxStep.",
+ },
+ {
+ name: "goToPrevStep",
+ type: "() => void",
+ description: "Goes back one step; a no-op at step 1.",
+ },
+ {
+ name: "reset",
+ type: "() => void",
+ description: "Resets back to step 1.",
+ },
+ {
+ name: "canGoToNextStep",
+ type: "boolean",
+ description: "Whether a next step is available.",
+ },
+ {
+ name: "canGoToPrevStep",
+ type: "boolean",
+ description: "Whether a previous step is available.",
+ },
+ {
+ name: "setStep",
+ type: "Dispatch<SetStateAction<number>>",
+ description: "Sets the step directly (1-indexed); throws if outside the 1..maxStep range.",
+ },
+ ],
+ },
+ ],
+ },
+ "use-countdown": {
+ demo: UseCountdownDocDemo,
+ usage: `
+import { useCountdown } from "hookli";
+
+export function Demo() {
+ const [count, { startCountdown, stopCountdown, resetCountdown }] = useCountdown({
+ countStart: 10,
+ intervalMs: 1000,
+ });
+
+ return (
+ <div>
+ <p>{count}</p>
+ <button onClick={startCountdown}>Start</button>
+ <button onClick={stopCountdown}>Pause</button>
+ <button onClick={resetCountdown}>Reset</button>
+ </div>
+ );
+}
+`,
+ parameters: [
+ {
+ name: "options",
+ type: "UseCountdownOptions",
+ description: "Configures the timer — start value, tick interval, direction and stop value. See below.",
+ },
+ ],
+ returns: [
+ {
+ name: "[0] count",
+ type: "number",
+ description: "The current count. Ticks by ±1 every intervalMs while running.",
+ },
+ {
+ name: "[1] actions",
+ type: "UseCountdownActions",
+ description: "Start, pause and reset controls — see below.",
+ },
+ ],
+ typeAliases: [
+ {
+ name: "UseCountdownOptions",
+ description: "The single options argument.",
+ rows: [
+ {
+ name: "countStart",
+ type: "number",
+ description: "The value the countdown starts from.",
+ },
+ {
+ name: "intervalMs",
+ type: "number",
+ description: "Milliseconds between ticks. Defaults to 1000.",
+ },
+ {
+ name: "isIncrement",
+ type: "boolean",
+ description: "Count up instead of down. Defaults to false.",
+ },
+ {
+ name: "countStop",
+ type: "number",
+ description: "The value at which the timer stops itself. Defaults to 0.",
+ },
+ ],
+ },
+ {
+ name: "UseCountdownActions",
+ description: "The second tuple element — the timer controls.",
+ rows: [
+ {
+ name: "startCountdown",
+ type: "() => void",
+ description: "Starts (or resumes) the timer.",
+ },
+ {
+ name: "stopCountdown",
+ type: "() => void",
+ description: "Pauses the timer without resetting the count.",
+ },
+ {
+ name: "resetCountdown",
+ type: "() => void",
+ description: "Stops the timer and resets the count to countStart.",
+ },
+ ],
+ },
+ ],
+ },
+ "use-map": {
+ demo: UseMapDocDemo,
+ usage: `
+import { useMap } from "hookli";
+
+export function Demo() {
+ const [map, { set, remove, reset }] = useMap<string, string>([
+ ["theme", "dark"],
+ ]);
+
+ return (
+ <div>
+ <button onClick={() => set("lang", "en")}>Set lang</button>
+ <button onClick={() => remove("theme")}>Remove theme</button>
+ <button onClick={reset}>Reset</button>
+ <ul>
+ {[...map.entries()].map(([key, value]) => (
+ <li key={key}>{key}: {value}</li>
+ ))}
+ </ul>
+ </div>
+ );
+}
+`,
+ parameters: [
+ {
+ name: "initialState",
+ type: "MapOrEntries<K, V>",
+ defaultValue: "new Map()",
+ description: "Initial entries as a Map or an array of [key, value] pairs.",
+ },
+ ],
+ returns: [
+ {
+ name: "[0] map",
+ type: "ReadOnlyMap<K, V>",
+ description: "A read-only view of the map — the mutating set/clear/delete methods are omitted; use the actions instead. get, has, size and iteration remain.",
+ },
+ {
+ name: "[1] actions",
+ type: "UseMapActions<K, V>",
+ description: "Stable helpers that replace the map with a fresh copy so React re-renders — see below.",
+ },
+ ],
+ typeAliases: [
+ {
+ name: "UseMapActions",
+ description: "The second tuple element — the map mutation helpers.",
+ rows: [
+ {
+ name: "set",
+ type: "(key: K, value: V) => void",
+ description: "Adds or updates one entry.",
+ },
+ {
+ name: "setAll",
+ type: "(entries: MapOrEntries<K, V>) => void",
+ description: "Replaces every entry with the given Map or [key, value] pairs.",
+ },
+ {
+ name: "remove",
+ type: "(key: K) => void",
+ description: "Deletes the entry for the given key.",
+ },
+ {
+ name: "reset",
+ type: "() => void",
+ description: "Empties the map.",
+ },
+ ],
+ },
+ ],
+ },
+ "use-click-outside": {
+ demo: UseClickOutsideDocDemo,
+ usage: `
+import { useRef, useState } from "react";
+import { useClickOutside } from "hookli";
+
+export function Demo() {
+ const menuRef = useRef<HTMLDivElement>(null);
+ const [open, setOpen] = useState(false);
+
+ useClickOutside(menuRef, () => setOpen(false));
+
+ return (
+ <div ref={menuRef}>
+ <button onClick={() => setOpen((prev) => !prev)}>Actions</button>
+ {open && (
+ <ul role="menu">
+ <li>Rename</li>
+ <li>Duplicate</li>
+ </ul>
+ )}
+ </div>
+ );
+}
+`,
+ parameters: [
+ {
+ name: "ref",
+ type: "RefObject<T>",
+ description: "Ref attached to the element that counts as inside — clicks within it (or its children) never fire the callback.",
+ },
+ {
+ name: "callback",
+ type: "() => void",
+ description: "Called on every mousedown outside the ref'd element — even while your UI is closed, so guard inside the callback if needed.",
+ },
+ ],
+ returns: [],
+ },
+ "use-mouse-position": {
+ demo: UseMousePositionDocDemo,
+ usage: `
+import { useRef } from "react";
+import { useMousePosition } from "hookli";
+
+export function Demo() {
+ const panelRef = useRef<HTMLDivElement>(null);
+ const { x, y } = useMousePosition(panelRef);
+
+ return (
+ <div ref={panelRef} style={{ height: 160 }}>
+ {x === null || y === null ? (
+ <p>Move your cursor</p>
+ ) : (
+ <p>
+ {Math.round(x)} × {Math.round(y)}
+ </p>
+ )}
+ </div>
+ );
+}
+`,
+ parameters: [
+ {
+ name: "ref",
+ type: "RefObject<T>",
+ description: "Ref attached to the element the coordinates are measured against.",
+ },
+ ],
+ returns: [
+ {
+ name: "x",
+ type: "number | null",
+ description: "Cursor X relative to the element's left edge; null until the first mousemove. Updates on every window mousemove, so it can go negative or exceed the element's width.",
+ },
+ {
+ name: "y",
+ type: "number | null",
+ description: "Cursor Y relative to the element's top edge; null until the first mousemove.",
+ },
+ ],
+ },
+ "use-infinite-scroll": {
+ demo: UseInfiniteScrollDocDemo,
+ usage: `
+import { useCallback, useState } from "react";
+import { useInfiniteScroll } from "hookli";
+
+const page = (start: number) =>
+ Array.from({ length: 10 }, (_, i) => \`Item \${start + i + 1}\`);
+
+export function Demo() {
+ const [items, setItems] = useState(() => page(0));
+
+ const fetchMoreData = useCallback(
+ () =>
+ new Promise<void>((resolve) => {
+ setItems((prev) => [...prev, ...page(prev.length)]);
+ resolve();
+ }),
+ [],
+ );
+
+ const isFetching = useInfiniteScroll(fetchMoreData);
+
+ return (
+ <div>
+ <ul>
+ {items.map((item) => (
+ <li key={item}>{item}</li>
+ ))}
+ </ul>
+ {isFetching && <p>Loading more…</p>}
+ </div>
+ );
+}
+`,
+ parameters: [
+ {
+ name: "fetchMoreData",
+ type: "() => Promise<void>",
+ description: "Called when the window scroll comes within 500px of the document bottom. Must return a promise — the hook stays in the fetching state until it resolves.",
+ },
+ ],
+ returns: [
+ {
+ name: "isFetching",
+ type: "boolean",
+ description: "True while a triggered fetchMoreData promise is pending; blocks re-triggering until it resolves.",
+ },
+ ],
+ },
+ "use-hover": {
+ demo: UseHoverDocDemo,
+ usage: `
+import { useRef } from "react";
+import { useHover } from "hookli";
+
+export function Demo() {
+ const boxRef = useRef<HTMLDivElement>(null);
+ const isHovered = useHover(boxRef);
+
+ return (
+ <div ref={boxRef}>
+ {isHovered ? "Pointer is over me" : "Hover this panel"}
+ </div>
+ );
+}
+`,
+ parameters: [
+ {
+ name: "elementRef",
+ type: "RefObject<T>",
+ description: "Ref to the element whose hover state to track. mouseenter/mouseleave are attached to it and cleaned up automatically.",
+ },
+ ],
+ returns: [
+ {
+ name: "isHovered",
+ type: "boolean",
+ description: "True while the pointer is over the element, false otherwise. Starts false on the server and until the first mouseenter.",
+ },
+ ],
+ },
+ "use-intersection-observer": {
+ demo: UseIntersectionObserverDocDemo,
+ usage: `
+import { useIntersectionObserver } from "hookli";
+
+export function Demo() {
+ const { ref, isIntersecting } = useIntersectionObserver({
+ threshold: 0.5,
+ });
+
+ return (
+ <div ref={ref}>
+ {isIntersecting ? "In view" : "Scroll me into view"}
+ </div>
+ );
+}
+`,
+ parameters: [
+ {
+ name: "options",
+ type: "UseIntersectionObserverOptions",
+ defaultValue: "{}",
+ description: "Observer thresholds, root, and behaviour flags. All optional.",
+ },
+ ],
+ returns: [
+ {
+ name: "ref",
+ type: "(node: Element | null) => void",
+ description: "Ref callback to attach to the element you want to observe.",
+ },
+ {
+ name: "isIntersecting",
+ type: "boolean",
+ description: "Whether the observed element currently intersects the root.",
+ },
+ {
+ name: "entry",
+ type: "IntersectionObserverEntry | null",
+ description: "The most recent observer entry (intersectionRatio, boundingClientRect…), or null before the first report.",
+ },
+ ],
+ typeAliases: [
+ {
+ name: "UseIntersectionObserverOptions",
+ description: "Configures the underlying IntersectionObserver.",
+ rows: [
+ {
+ name: "threshold",
+ type: "number | number[]",
+ defaultValue: "0",
+ description: "One or more visibility ratios at which to fire.",
+ },
+ {
+ name: "root",
+ type: "Element | Document | null",
+ defaultValue: "null",
+ description: "The element used as the viewport. Defaults to the browser viewport.",
+ },
+ {
+ name: "rootMargin",
+ type: "string",
+ defaultValue: '"0%"',
+ description: "Margin around the root, in CSS-margin syntax — grows or shrinks the trigger area.",
+ },
+ {
+ name: "freezeOnceVisible",
+ type: "boolean",
+ defaultValue: "false",
+ description: "Once the target is visible, stop observing and keep the visible state.",
+ },
+ {
+ name: "initialIsIntersecting",
+ type: "boolean",
+ defaultValue: "false",
+ description: "isIntersecting value used before the observer first reports.",
+ },
+ {
+ name: "onChange",
+ type: "(isIntersecting: boolean, entry: IntersectionObserverEntry) => void",
+ description: "Called with the latest entry whenever intersection changes.",
+ },
+ ],
+ },
+ {
+ name: "UseIntersectionObserverReturn",
+ description: "The ref callback plus the current intersection state.",
+ rows: [
+ {
+ name: "ref",
+ type: "(node: Element | null) => void",
+ description: "Attach to the element you want to observe.",
+ },
+ {
+ name: "isIntersecting",
+ type: "boolean",
+ description: "Whether the target currently intersects the root.",
+ },
+ {
+ name: "entry",
+ type: "IntersectionObserverEntry | null",
+ description: "The most recent observer entry, or null before the first report.",
+ },
+ ],
+ },
+ ],
+ },
+ "use-resize-observer": {
+ demo: UseResizeObserverDocDemo,
+ usage: `
+import { useRef } from "react";
+import { useResizeObserver } from "hookli";
+
+export function Demo() {
+ const boxRef = useRef<HTMLDivElement>(null);
+ const { width, height } = useResizeObserver(boxRef);
+
+ return (
+ <div ref={boxRef}>
+ {width === undefined ? "Measuring…" : \`\${Math.round(width)} × \${Math.round(height ?? 0)}\`}
+ </div>
+ );
+}
+`,
+ parameters: [
+ {
+ name: "ref",
+ type: "RefObject<T>",
+ description: "Ref to the element to measure. The observer attaches to ref.current.",
+ },
+ {
+ name: "options",
+ type: "UseResizeObserverOptions",
+ defaultValue: "{}",
+ description: "Which box to measure and an optional resize callback.",
+ },
+ ],
+ returns: [
+ {
+ name: "width",
+ type: "number | undefined",
+ description: "The element's measured width; undefined until the first observed layout.",
+ },
+ {
+ name: "height",
+ type: "number | undefined",
+ description: "The element's measured height; undefined until the first observed layout.",
+ },
+ ],
+ typeAliases: [
+ {
+ name: "UseResizeObserverOptions",
+ description: "Configures the underlying ResizeObserver.",
+ rows: [
+ {
+ name: "box",
+ type: "ResizeObserverBoxOptions",
+ defaultValue: '"content-box"',
+ description: "Which box model to measure: content-box, border-box or device-pixel-content-box.",
+ },
+ {
+ name: "onResize",
+ type: "(size: ResizeObserverSize) => void",
+ description: "Called with the freshly measured size on every resize.",
+ },
+ ],
+ },
+ {
+ name: "ResizeObserverSize",
+ description: "The size the hook returns; both values are undefined until the first measurement.",
+ rows: [
+ {
+ name: "width",
+ type: "number | undefined",
+ description: "Measured width in pixels.",
+ },
+ {
+ name: "height",
+ type: "number | undefined",
+ description: "Measured height in pixels.",
+ },
+ ],
+ },
+ ],
+ },
+ "use-scroll-lock": {
+ demo: UseScrollLockDocDemo,
+ usage: `
+import { useScrollLock } from "hookli";
+
+export function Modal({ onClose }: { onClose: () => void }) {
+ // Locks <body> scroll on mount, restores it on unmount.
+ useScrollLock();
+
+ return (
+ <div role="dialog" onClick={onClose}>
+ Scrolling behind this modal is frozen.
+ </div>
+ );
+}
+`,
+ parameters: [
+ {
+ name: "options",
+ type: "UseScrollLockOptions",
+ defaultValue: "{}",
+ description: "Auto-lock behaviour, the lock target, and scrollbar compensation.",
+ },
+ ],
+ returns: [
+ {
+ name: "isLocked",
+ type: "boolean",
+ description: "Whether the target's scroll is currently locked.",
+ },
+ {
+ name: "lock",
+ type: "() => void",
+ description: "Lock the target's scroll (sets overflow: hidden, optionally padding-compensated).",
+ },
+ {
+ name: "unlock",
+ type: "() => void",
+ description: "Restore the target's original scroll behaviour.",
+ },
+ ],
+ typeAliases: [
+ {
+ name: "UseScrollLockOptions",
+ description: "Controls what is locked and when.",
+ rows: [
+ {
+ name: "autoLock",
+ type: "boolean",
+ defaultValue: "true",
+ description: "Lock automatically on mount and restore on unmount.",
+ },
+ {
+ name: "lockTarget",
+ type: "HTMLElement | string",
+ defaultValue: "<body>",
+ description: "Element (or CSS selector) whose scroll to lock. Defaults to the document body.",
+ },
+ {
+ name: "widthReflow",
+ type: "boolean",
+ defaultValue: "true",
+ description: "Compensate for the removed scrollbar with padding so the layout does not shift.",
+ },
+ ],
+ },
+ {
+ name: "UseScrollLockReturn",
+ description: "The current lock state plus manual controls.",
+ rows: [
+ {
+ name: "isLocked",
+ type: "boolean",
+ description: "Whether the target's scroll is currently locked.",
+ },
+ {
+ name: "lock",
+ type: "() => void",
+ description: "Lock the target's scroll.",
+ },
+ {
+ name: "unlock",
+ type: "() => void",
+ description: "Restore the target's original scroll behaviour.",
+ },
+ ],
+ },
+ ],
+ },
+ "use-click-any-where": {
+ demo: UseClickAnyWhereDocDemo,
+ usage: `
+import { useState } from "react";
+import { useClickAnyWhere } from "hookli";
+
+export function Demo() {
+ const [clicks, setClicks] = useState(0);
+
+ useClickAnyWhere(() => setClicks((prev) => prev + 1));
+
+ return <p>Document clicks: {clicks}</p>;
+}
+`,
+ parameters: [
+ {
+ name: "handler",
+ type: "(event: MouseEvent) => void",
+ description: "Called with the MouseEvent on every document-wide click. The latest handler is always used — no stale closure.",
+ },
+ ],
+ returns: [],
+ },
+ "use-media-query": {
+ demo: UseMediaQueryDocDemo,
+ usage: `
+import { useMediaQuery } from "hookli";
+
+export function Demo() {
+ const isWide = useMediaQuery("(min-width: 768px)");
+
+ return <p>{isWide ? "Desktop layout" : "Mobile layout"}</p>;
+}
+`,
+ parameters: [
+ {
+ name: "query",
+ type: "string",
+ description: "A CSS media query string, e.g. \"(min-width: 768px)\" or \"(prefers-color-scheme: dark)\".",
+ },
+ {
+ name: "options",
+ type: "UseMediaQueryOptions",
+ defaultValue: "{}",
+ description: "SSR default and hydration behaviour. Optional.",
+ },
+ ],
+ returns: [
+ {
+ name: "matches",
+ type: "boolean",
+ description: "Whether the query currently matches. Re-renders on every matchMedia change event, and starts from defaultValue on the server.",
+ },
+ ],
+ typeAliases: [
+ {
+ name: "UseMediaQueryOptions",
+ description: "Configures the server value and mount behaviour.",
+ rows: [
+ {
+ name: "defaultValue",
+ type: "boolean",
+ defaultValue: "false",
+ description: "Value returned on the server and before hydration.",
+ },
+ {
+ name: "initializeWithValue",
+ type: "boolean",
+ defaultValue: "true",
+ description: "Read the real match synchronously on mount. Set false to always start from defaultValue and avoid a hydration mismatch.",
+ },
+ ],
+ },
+ ],
+ },
+ "use-screen": {
+ demo: UseScreenDocDemo,
+ usage: `
+import { useScreen } from "hookli";
+
+export function Demo() {
+ const screen = useScreen();
+
+ return <p>Screen: {screen ? \`\${screen.width}×\${screen.height}\` : "…"}</p>;
+}
+`,
+ parameters: [
+ {
+ name: "options",
+ type: "UseScreenOptions",
+ defaultValue: "{}",
+ description: "Hydration behaviour. Optional.",
+ },
+ ],
+ returns: [
+ {
+ name: "screen",
+ type: "Screen | null",
+ description: "The current window.screen (width, height, availWidth, colorDepth, orientation…), refreshed on every resize. null on the server and until hydration.",
+ },
+ ],
+ typeAliases: [
+ {
+ name: "UseScreenOptions",
+ description: "Configures mount behaviour.",
+ rows: [
+ {
+ name: "initializeWithValue",
+ type: "boolean",
+ defaultValue: "true",
+ description: "Read the real screen synchronously on mount. Set false to start as null and populate after hydration.",
+ },
+ ],
+ },
+ ],
+ },
+ "use-window-size": {
+ demo: UseWindowSizeDocDemo,
+ usage: `
+import { useWindowSize } from "hookli";
+
+export function Demo() {
+ const { width, height } = useWindowSize();
+
+ return <p>{width} × {height}</p>;
+}
+`,
+ parameters: [
+ {
+ name: "options",
+ type: "UseWindowSizeOptions",
+ defaultValue: "{}",
+ description: "Hydration behaviour. Optional.",
+ },
+ ],
+ returns: [
+ {
+ name: "width",
+ type: "number",
+ description: "The viewport's inner width in pixels. 0 on the server and until hydration.",
+ },
+ {
+ name: "height",
+ type: "number",
+ description: "The viewport's inner height in pixels. 0 on the server and until hydration.",
+ },
+ ],
+ typeAliases: [
+ {
+ name: "WindowSize",
+ description: "The viewport size reported by useWindowSize.",
+ rows: [
+ {
+ name: "width",
+ type: "number",
+ description: "The viewport's inner width in pixels.",
+ },
+ {
+ name: "height",
+ type: "number",
+ description: "The viewport's inner height in pixels.",
+ },
+ ],
+ },
+ {
+ name: "UseWindowSizeOptions",
+ description: "Configures mount behaviour.",
+ rows: [
+ {
+ name: "initializeWithValue",
+ type: "boolean",
+ defaultValue: "true",
+ description: "Read the real size synchronously on mount. Set false to start at 0 and populate after hydration.",
+ },
+ ],
+ },
+ ],
+ },
+ "use-copy-to-clipboard": {
+ demo: UseCopyToClipboardDocDemo,
+ usage: `
+import { useCopyToClipboard } from "hookli";
+
+export function Demo() {
+ const [copiedText, copy] = useCopyToClipboard();
+
+ return (
+ <button type="button" onClick={() => copy("npm i hookli")}>
+ {copiedText ? "Copied!" : "Copy"}
+ </button>
+ );
+}
+`,
+ parameters: [],
+ returns: [
+ {
+ name: "[0] copiedText",
+ type: "CopiedValue",
+ description: "The last successfully-copied string, or null before any copy or after a failed one.",
+ },
+ {
+ name: "[1] copy",
+ type: "CopyFn",
+ description: "Writes text to the clipboard. Resolves true on success, false when the API is unavailable or the write is rejected.",
+ },
+ ],
+ typeAliases: [
+ {
+ name: "CopiedValue",
+ rows: [
+ {
+ name: "value",
+ type: "string | null",
+ description: "The tracked copied text, or null.",
+ },
+ ],
+ },
+ {
+ name: "CopyFn",
+ rows: [
+ {
+ name: "value",
+ type: "(text: string) => Promise<boolean>",
+ description: "Copies text and reports whether the write succeeded.",
+ },
+ ],
+ },
+ ],
+ },
+ "use-script": {
+ demo: UseScriptDocDemo,
+ usage: `
+import { useScript } from "hookli";
+
+export function Demo() {
+ const status = useScript("https://example.com/widget.js");
+
+ if (status === "ready") return <p>Widget loaded.</p>;
+ return <p>Loading… ({status})</p>;
+}
+`,
+ parameters: [
+ {
+ name: "src",
+ type: "string | null",
+ description: "The script URL to load, or null to skip loading and stay idle.",
+ },
+ {
+ name: "options",
+ type: "UseScriptOptions",
+ defaultValue: "{}",
+ description: "Optional shouldPreventLoad and removeOnUnmount flags.",
+ },
+ ],
+ returns: [
+ {
+ name: "status",
+ type: "UseScriptStatus",
+ description: 'The current load status: "idle" | "loading" | "ready" | "error".',
+ },
+ ],
+ typeAliases: [
+ {
+ name: "UseScriptStatus",
+ rows: [
+ {
+ name: "value",
+ type: '"idle" | "loading" | "ready" | "error"',
+ description: "Lifecycle of the injected script tag.",
+ },
+ ],
+ },
+ SCRIPT_OPTIONS_ALIAS,
+ ],
+ },
+ "use-fetch": {
+ demo: UseFetchDocDemo,
+ usage: `
+import { useFetch } from "hookli";
+
+type Post = { id: number; title: string; body: string };
+
+export function Demo() {
+ const { data, loading, error } = useFetch<Post>(
+ "https://jsonplaceholder.typicode.com/posts/1",
+ );
+
+ if (loading) return <p>Loading…</p>;
+ if (error) return <p>Request failed: {error.message}</p>;
+
+ return <article>{data?.title}</article>;
+}
+`,
+ parameters: [
+ {
+ name: "url",
+ type: "string",
+ description: "The endpoint to GET. The request starts on mount and re-runs whenever the url changes.",
+ },
+ ],
+ returns: [
+ {
+ name: "data",
+ type: "T | null",
+ description: "The parsed JSON body; null until the first request succeeds. Kept from the previous url while a refetch is in flight.",
+ },
+ {
+ name: "error",
+ type: "Error | null",
+ description: 'Set on network failure or a non-ok response ("HTTP error! status: 404"). Never cleared by later requests — remount the component (e.g. key={url}) for fresh state.',
+ },
+ {
+ name: "loading",
+ type: "boolean",
+ description: "True until the first request settles. Not reset to true when the url changes — remount for a per-request loading flag.",
+ },
+ ],
+ },
+ "use-geo-location": {
+ demo: UseGeoLocationDocDemo,
+ usage: `
+import { useState } from "react";
+import { useGeoLocation } from "hookli";
+
+function Coordinates() {
+ const { location, error } = useGeoLocation();
+
+ if (error) return <p>{error.message}</p>;
+ if (!location) return <p>Locating…</p>;
+
+ const { latitude, longitude } = location.coords;
+ return <p>{latitude.toFixed(4)}, {longitude.toFixed(4)}</p>;
+}
+
+export function Demo() {
+ const [asked, setAsked] = useState(false);
+
+ // The hook may prompt for permission as soon as it mounts —
+ // keep it unmounted until a user gesture.
+ if (!asked) {
+ return <button onClick={() => setAsked(true)}>Where am I?</button>;
+ }
+ return <Coordinates />;
+}
+`,
+ parameters: [],
+ returns: [
+ {
+ name: "location",
+ type: "GeolocationPosition | null",
+ description: "hookli's trimmed position type — just coords.latitude and coords.longitude. Null until the first reading arrives.",
+ },
+ {
+ name: "error",
+ type: "GeolocationError | Error | null",
+ description: "Permission denials, unsupported browsers and failed lookups all land here — read .message for display. Requesting starts on mount, so mount the hook behind a user gesture.",
+ },
+ ],
+ typeAliases: [
+ {
+ name: "GeolocationPosition",
+ description: "hookli's trimmed reading — only the coordinates, not the full browser GeolocationPosition.",
+ rows: [
+ {
+ name: "coords.latitude",
+ type: "number",
+ description: "Latitude in decimal degrees.",
+ },
+ {
+ name: "coords.longitude",
+ type: "number",
+ description: "Longitude in decimal degrees.",
+ },
+ ],
+ },
+ {
+ name: "GeolocationError",
+ description: "Shape of a permission or lookup failure.",
+ rows: [
+ {
+ name: "code",
+ type: "number",
+ description: "Numeric error code mirrored from the browser's GeolocationPositionError.",
+ },
+ {
+ name: "message",
+ type: "string",
+ description: "Human-readable reason for the failure.",
+ },
+ ],
+ },
+ ],
+ },
+};
+
+export function getHookDoc(slug: string): HookDoc | undefined {
+ return HOOK_DOCS[slug];
+}
diff --git a/apps/docs/lib/hook-sources.ts b/apps/docs/lib/hook-sources.ts
new file mode 100644
index 0000000..022ade4
--- /dev/null
+++ b/apps/docs/lib/hook-sources.ts
@@ -0,0 +1,1694 @@
+import { GITHUB_URL } from "@/lib/site";
+
+/* Vendored implementation snapshots for the "Hook" section on every doc page
+ (T16 usehooks-ts anatomy). Reconstructed faithfully from the installed
+ hookli@1.4.0 bundle (node_modules/hookli/dist/index.mjs) with the exported
+ type signatures from index.d.ts — bundler artifacts (helper prelude, aliased
+ imports) removed so each entry reads as its original src/hooks/*.ts.
+ Keep in sync when the pinned hookli version changes. */
+
+export type HookSource = {
+ /* Repo-relative path, also the code-block filename. */
+ path: string;
+ source: string;
+};
+
+const REPO_BLOB = `${GITHUB_URL}/blob/main`;
+
+const HOOK_SOURCES: Partial<Record<string, HookSource>> = {
+ "use-toggle": {
+ path: "src/hooks/useToggle.hook.ts",
+ source: `import { useCallback, useState } from "react";
+
+export const useToggle = (
+ initialValue = false,
+): [boolean, () => void, (value: boolean) => void] => {
+ const [state, setState] = useState(initialValue);
+
+ const toggle = useCallback(() => {
+ setState((prevState) => !prevState);
+ }, []);
+
+ const setExplicit = useCallback((value: boolean) => {
+ setState(value);
+ }, []);
+
+ return [state, toggle, setExplicit];
+};
+`,
+ },
+ "use-form": {
+ path: "src/hooks/useForm.hook.ts",
+ source: `import { ChangeEvent, useState } from "react";
+
+interface UseFormValues {
+ [key: string]: string | number | boolean;
+}
+
+export const useForm = <T extends UseFormValues>(initialState: T) => {
+ const [values, setValues] = useState<T>(initialState);
+
+ const handleChange = (
+ event: ChangeEvent<
+ HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement
+ >,
+ ) => {
+ const { name, value } = event.target;
+ setValues((prevValues) => ({ ...prevValues, [name]: value }));
+ };
+
+ const resetForm = () => {
+ setValues(initialState);
+ };
+
+ return { values, handleChange, resetForm };
+};
+`,
+ },
+ "use-local-storage": {
+ path: "src/hooks/useLocalStorage.hook.ts",
+ source: `import { useEffect, useState } from "react";
+
+export const useLocalStorage = <T>(key: string, initialValue: T) => {
+ const [value, setValue] = useState<T>(initialValue);
+
+ useEffect(() => {
+ const item = window.localStorage.getItem(key);
+ const parsedValue = item ? JSON.parse(item) : initialValue;
+ setValue(parsedValue);
+ }, [key, initialValue]);
+
+ const setStoredValue = (newValue: T | ((val: T) => T)) => {
+ const updatedValue =
+ newValue instanceof Function ? newValue(value) : newValue;
+ window.localStorage.setItem(key, JSON.stringify(updatedValue));
+ setValue(updatedValue);
+ };
+
+ return { value, setStoredValue };
+};
+`,
+ },
+ "use-local-storage-with-expiry": {
+ path: "src/hooks/useLocalStorageWithExpiry.hook.ts",
+ source: `import { useEffect, useState } from "react";
+
+export const useLocalStorageWithExpiry = <T>(
+ key: string,
+ initialValue: T,
+ expiryMs: number,
+) => {
+ const read = (): T | null => {
+ if (typeof window === "undefined") return initialValue;
+
+ const raw = window.localStorage.getItem(key);
+ if (!raw) return initialValue;
+
+ try {
+ const item = JSON.parse(raw);
+ if (
+ item &&
+ typeof item.expiry === "number" &&
+ Date.now() > item.expiry
+ ) {
+ window.localStorage.removeItem(key);
+ return null;
+ }
+ return item.value;
+ } catch {
+ return initialValue;
+ }
+ };
+
+ const [value, setValue] = useState<T | null>(initialValue);
+
+ useEffect(() => {
+ setValue(read());
+ }, [key]);
+
+ const setStoredValue = (newValue: T) => {
+ setValue(newValue);
+ if (typeof window === "undefined") return;
+
+ const item = { value: newValue, expiry: Date.now() + expiryMs };
+ window.localStorage.setItem(key, JSON.stringify(item));
+ };
+
+ return { value, setStoredValue };
+};
+`,
+ },
+ "use-session-storage": {
+ path: "src/hooks/use-session-storage/use-session-storage.ts",
+ source: `import { useCallback, useEffect, useState } from "react";
+import { useEventCallback } from "../use-event-callback/use-event-callback";
+import { useEventListener } from "../use-event-listener/use-event-listener";
+
+interface UseSessionStorageOptions<T> {
+ serializer?: (value: T) => string;
+ deserializer?: (value: string) => T;
+ initializeWithValue?: boolean;
+}
+
+type UseSessionStorageReturn<T> = [
+ T,
+ (value: T | ((prev: T) => T)) => void,
+ () => void,
+];
+
+const IS_SERVER = typeof window === "undefined";
+
+export function useSessionStorage<T>(
+ key: string,
+ initialValue: T | (() => T),
+ options: UseSessionStorageOptions<T> = {},
+): UseSessionStorageReturn<T> {
+ const { initializeWithValue = true } = options;
+
+ const serializer = useCallback(
+ (value: T) => {
+ if (options.serializer) return options.serializer(value);
+ return JSON.stringify(value);
+ },
+ [options],
+ );
+
+ const deserializer = useCallback(
+ (value: string): T => {
+ if (options.deserializer) return options.deserializer(value);
+ const defaultValue =
+ initialValue instanceof Function ? initialValue() : initialValue;
+ if (value === "undefined") return defaultValue;
+ try {
+ return JSON.parse(value);
+ } catch {
+ return defaultValue;
+ }
+ },
+ [options, initialValue],
+ );
+
+ const readValue = useCallback((): T => {
+ const initial =
+ initialValue instanceof Function ? initialValue() : initialValue;
+ if (IS_SERVER) return initial;
+ try {
+ const raw = window.sessionStorage.getItem(key);
+ return raw ? deserializer(raw) : initial;
+ } catch {
+ return initial;
+ }
+ }, [initialValue, key, deserializer]);
+
+ const [storedValue, setStoredValue] = useState<T>(() =>
+ initializeWithValue
+ ? readValue()
+ : initialValue instanceof Function
+ ? initialValue()
+ : initialValue,
+ );
+
+ const setValue = useEventCallback((value: T | ((prev: T) => T)) => {
+ if (IS_SERVER) return;
+ try {
+ const newValue = value instanceof Function ? value(readValue()) : value;
+ window.sessionStorage.setItem(key, serializer(newValue));
+ setStoredValue(newValue);
+ window.dispatchEvent(new StorageEvent("session-storage", { key }));
+ } catch {
+ return;
+ }
+ });
+
+ const removeValue = useEventCallback(() => {
+ if (IS_SERVER) return;
+ const defaultValue =
+ initialValue instanceof Function ? initialValue() : initialValue;
+ window.sessionStorage.removeItem(key);
+ setStoredValue(defaultValue);
+ window.dispatchEvent(new StorageEvent("session-storage", { key }));
+ });
+
+ useEffect(() => {
+ setStoredValue(readValue());
+ }, [key]);
+
+ const handleStorageChange = useCallback(
+ (event: StorageEvent) => {
+ if (event.key && event.key !== key) return;
+ setStoredValue(readValue());
+ },
+ [key, readValue],
+ );
+
+ useEventListener("storage", handleStorageChange);
+ useEventListener("session-storage", handleStorageChange);
+
+ return [storedValue, setValue, removeValue];
+}
+`,
+ },
+ "use-read-local-storage": {
+ path: "src/hooks/use-read-local-storage/use-read-local-storage.ts",
+ source: `import { useCallback, useEffect, useState } from "react";
+import { useEventListener } from "../use-event-listener/use-event-listener";
+
+interface UseReadLocalStorageOptions<T> {
+ deserializer?: (value: string) => T;
+ initializeWithValue?: boolean;
+}
+
+const IS_SERVER = typeof window === "undefined";
+
+export function useReadLocalStorage<T>(
+ key: string,
+ options: UseReadLocalStorageOptions<T> = {},
+): T | null {
+ const { initializeWithValue = true } = options;
+
+ const deserializer = useCallback(
+ (value: string): T | undefined => {
+ if (options.deserializer) return options.deserializer(value);
+ if (value === "undefined") return undefined;
+ try {
+ return JSON.parse(value);
+ } catch {
+ return value as unknown as T;
+ }
+ },
+ [options],
+ );
+
+ const readValue = useCallback((): T | null => {
+ if (IS_SERVER) return null;
+ try {
+ const raw = window.localStorage.getItem(key);
+ return raw ? (deserializer(raw) as T) : null;
+ } catch {
+ return null;
+ }
+ }, [key, deserializer]);
+
+ const [storedValue, setStoredValue] = useState<T | null>(() =>
+ initializeWithValue ? readValue() : null,
+ );
+
+ useEffect(() => {
+ setStoredValue(readValue());
+ }, [key]);
+
+ const handleStorageChange = useCallback(
+ (event: StorageEvent) => {
+ if (event.key && event.key !== key) return;
+ setStoredValue(readValue());
+ },
+ [key, readValue],
+ );
+
+ useEventListener("storage", handleStorageChange);
+ useEventListener("local-storage", handleStorageChange);
+
+ return storedValue;
+}
+`,
+ },
+ "use-dark-mode": {
+ path: "src/hooks/useDarkMode.hook.ts",
+ source: `import { useEffect, useState } from "react";
+
+interface UseDarkModeState {
+ isDarkMode: boolean;
+ toggleDarkMode: () => void;
+}
+
+export const useDarkMode = (): UseDarkModeState => {
+ const [isDarkMode, setIsDarkMode] = useState(() => {
+ if (typeof window === "undefined") return false;
+ return window.localStorage.getItem("theme") === "dark";
+ });
+
+ const toggleDarkMode = () => setIsDarkMode((prevMode) => !prevMode);
+
+ useEffect(() => {
+ if (typeof document === "undefined") return;
+
+ const bodyElement = document.body;
+ const darkClass = "dark";
+
+ bodyElement.classList.toggle(darkClass, isDarkMode);
+ window.localStorage.setItem("theme", isDarkMode ? "dark" : "light");
+
+ return () => {
+ bodyElement.classList.remove(darkClass);
+ };
+ }, [isDarkMode]);
+
+ return { isDarkMode, toggleDarkMode };
+};
+`,
+ },
+ "use-boolean": {
+ path: "src/hooks/use-boolean/use-boolean.ts",
+ source: `import { useCallback, useState } from "react";
+
+export interface UseBooleanReturn {
+ value: boolean;
+ setValue: (value: boolean) => void;
+ setTrue: () => void;
+ setFalse: () => void;
+ toggle: () => void;
+}
+
+export const useBoolean = (defaultValue = false): UseBooleanReturn => {
+ const [value, setValue] = useState(defaultValue);
+
+ const setTrue = useCallback(() => setValue(true), []);
+ const setFalse = useCallback(() => setValue(false), []);
+ const toggle = useCallback(() => setValue((prev) => !prev), []);
+
+ return { value, setValue, setTrue, setFalse, toggle };
+};
+`,
+ },
+ "use-counter": {
+ path: "src/hooks/use-counter/use-counter.ts",
+ source: `import { Dispatch, SetStateAction, useCallback, useState } from "react";
+
+export interface UseCounterReturn {
+ count: number;
+ increment: () => void;
+ decrement: () => void;
+ reset: () => void;
+ setCount: Dispatch<SetStateAction<number>>;
+}
+
+export const useCounter = (initialValue = 0): UseCounterReturn => {
+ const [count, setCount] = useState(initialValue);
+
+ const increment = useCallback(() => setCount((prev) => prev + 1), []);
+ const decrement = useCallback(() => setCount((prev) => prev - 1), []);
+ const reset = useCallback(() => setCount(initialValue), [initialValue]);
+
+ return { count, increment, decrement, reset, setCount };
+};
+`,
+ },
+ "use-step": {
+ path: "src/hooks/use-step/use-step.ts",
+ source: `import { Dispatch, SetStateAction, useCallback, useMemo, useState } from "react";
+
+export interface UseStepActions {
+ goToNextStep: () => void;
+ goToPrevStep: () => void;
+ reset: () => void;
+ canGoToNextStep: boolean;
+ canGoToPrevStep: boolean;
+ setStep: Dispatch<SetStateAction<number>>;
+}
+
+export const useStep = (maxStep: number): [number, UseStepActions] => {
+ const [currentStep, setCurrentStep] = useState(1);
+
+ const canGoToNextStep = useMemo(
+ () => currentStep + 1 <= maxStep,
+ [currentStep, maxStep],
+ );
+ const canGoToPrevStep = useMemo(() => currentStep - 1 >= 1, [currentStep]);
+
+ const setStep = useCallback<Dispatch<SetStateAction<number>>>(
+ (step) => {
+ setCurrentStep((prev) => {
+ const newStep = step instanceof Function ? step(prev) : step;
+ if (newStep >= 1 && newStep <= maxStep) {
+ return newStep;
+ }
+ throw new Error("Step not valid");
+ });
+ },
+ [maxStep],
+ );
+
+ const goToNextStep = useCallback(() => {
+ setCurrentStep((prev) => (prev + 1 <= maxStep ? prev + 1 : prev));
+ }, [maxStep]);
+
+ const goToPrevStep = useCallback(() => {
+ setCurrentStep((prev) => (prev - 1 >= 1 ? prev - 1 : prev));
+ }, []);
+
+ const reset = useCallback(() => {
+ setCurrentStep(1);
+ }, []);
+
+ return [
+ currentStep,
+ { goToNextStep, goToPrevStep, canGoToNextStep, canGoToPrevStep, setStep, reset },
+ ];
+};
+`,
+ },
+ "use-countdown": {
+ path: "src/hooks/use-countdown/use-countdown.ts",
+ source: `import { useCallback, useEffect, useRef, useState } from "react";
+
+export interface UseCountdownOptions {
+ countStart: number;
+ intervalMs?: number;
+ isIncrement?: boolean;
+ countStop?: number;
+}
+
+export interface UseCountdownActions {
+ startCountdown: () => void;
+ stopCountdown: () => void;
+ resetCountdown: () => void;
+}
+
+export const useCountdown = ({
+ countStart,
+ intervalMs = 1000,
+ isIncrement = false,
+ countStop = 0,
+}: UseCountdownOptions): [number, UseCountdownActions] => {
+ const [count, setCount] = useState(countStart);
+ const [isRunning, setIsRunning] = useState(false);
+
+ const startCountdown = useCallback(() => setIsRunning(true), []);
+ const stopCountdown = useCallback(() => setIsRunning(false), []);
+ const resetCountdown = useCallback(() => {
+ setIsRunning(false);
+ setCount(countStart);
+ }, [countStart]);
+
+ const tick = useRef(() => {});
+ tick.current = () => {
+ setCount((prev) => (isIncrement ? prev + 1 : prev - 1));
+ };
+
+ useEffect(() => {
+ if (isRunning && count === countStop) {
+ setIsRunning(false);
+ }
+ }, [count, countStop, isRunning]);
+
+ useEffect(() => {
+ if (!isRunning) return;
+ const id = setInterval(() => tick.current(), intervalMs);
+ return () => clearInterval(id);
+ }, [isRunning, intervalMs]);
+
+ return [count, { startCountdown, stopCountdown, resetCountdown }];
+};
+`,
+ },
+ "use-map": {
+ path: "src/hooks/use-map/use-map.ts",
+ source: `import { useCallback, useState } from "react";
+
+export type MapOrEntries<K, V> = Map<K, V> | [K, V][];
+
+export interface UseMapActions<K, V> {
+ set: (key: K, value: V) => void;
+ setAll: (entries: MapOrEntries<K, V>) => void;
+ remove: (key: K) => void;
+ reset: () => void;
+}
+
+export type ReadOnlyMap<K, V> = Omit<Map<K, V>, "set" | "clear" | "delete">;
+
+export type UseMapReturn<K, V> = [ReadOnlyMap<K, V>, UseMapActions<K, V>];
+
+export function useMap<K, V>(
+ initialState: MapOrEntries<K, V> = new Map(),
+): UseMapReturn<K, V> {
+ const [map, setMap] = useState(() => new Map(initialState));
+
+ const set = useCallback((key: K, value: V) => {
+ setMap((prev) => {
+ const next = new Map(prev);
+ next.set(key, value);
+ return next;
+ });
+ }, []);
+
+ const setAll = useCallback((entries: MapOrEntries<K, V>) => {
+ setMap(new Map(entries));
+ }, []);
+
+ const remove = useCallback((key: K) => {
+ setMap((prev) => {
+ const next = new Map(prev);
+ next.delete(key);
+ return next;
+ });
+ }, []);
+
+ const reset = useCallback(() => {
+ setMap(new Map());
+ }, []);
+
+ return [map, { set, setAll, remove, reset }];
+}
+`,
+ },
+ "use-debounce": {
+ path: "src/hooks/useDebounce.hook.ts",
+ source: `import { useEffect, useState } from "react";
+
+export const useDebounce = <T>(value: T, delay: number): T => {
+ const [debouncedValue, setDebouncedValue] = useState<T>(value);
+
+ useEffect(() => {
+ const timer = setTimeout(() => {
+ setDebouncedValue(value);
+ }, delay);
+
+ return () => {
+ clearTimeout(timer);
+ };
+ }, [value, delay]);
+
+ return debouncedValue;
+};
+`,
+ },
+ "use-debounce-callback": {
+ path: "src/hooks/use-debounce-callback/use-debounce-callback.ts",
+ source: `import { useEffect, useMemo, useRef } from "react";
+import { useEventCallback } from "../use-event-callback/use-event-callback";
+import { useUnmount } from "../use-unmount/use-unmount";
+
+export interface DebounceOptions {
+ /** Invoke on the leading edge of the timeout. Defaults to \`false\`. */
+ leading?: boolean;
+ /** Invoke on the trailing edge of the timeout. Defaults to \`true\`. */
+ trailing?: boolean;
+ /** Maximum time the callback may be delayed before it is forced to run. */
+ maxWait?: number;
+}
+
+export interface DebouncedState<Args extends unknown[], R> {
+ (...args: Args): R | undefined;
+ cancel: () => void;
+ flush: () => R | undefined;
+ isPending: () => boolean;
+}
+
+export const useDebounceCallback = <Args extends unknown[], R>(
+ fn: (...args: Args) => R,
+ delayMs = 500,
+ options: DebounceOptions = {},
+): DebouncedState<Args, R> => {
+ const timeoutId = useRef<ReturnType<typeof setTimeout>>();
+ const maxTimeoutId = useRef<ReturnType<typeof setTimeout>>();
+ const lastArgs = useRef<Args>();
+ const lastResult = useRef<R>();
+ const lastInvokeTime = useRef(0);
+
+ const { leading = false, trailing = true, maxWait } = options;
+ const latestFn = useEventCallback(fn);
+
+ useEffect(() => {
+ lastInvokeTime.current = 0;
+ }, [delayMs, leading, trailing, maxWait]);
+
+ const debounced = useMemo(() => {
+ const invoke = (): R | undefined => {
+ const args = lastArgs.current;
+ if (!args) return undefined;
+ lastArgs.current = undefined;
+ lastInvokeTime.current = Date.now();
+ lastResult.current = latestFn(...args);
+ return lastResult.current;
+ };
+
+ const clearTimers = () => {
+ if (timeoutId.current !== undefined) {
+ clearTimeout(timeoutId.current);
+ timeoutId.current = undefined;
+ }
+ if (maxTimeoutId.current !== undefined) {
+ clearTimeout(maxTimeoutId.current);
+ maxTimeoutId.current = undefined;
+ }
+ };
+
+ const trailingEdge = () => {
+ clearTimers();
+ if (trailing && lastArgs.current) invoke();
+ else lastArgs.current = undefined;
+ };
+
+ const state = Object.assign(
+ (...args: Args): R | undefined => {
+ lastArgs.current = args;
+ const isFirstCall =
+ timeoutId.current === undefined && maxTimeoutId.current === undefined;
+ if (timeoutId.current !== undefined) clearTimeout(timeoutId.current);
+ if (leading && isFirstCall) invoke();
+ timeoutId.current = setTimeout(trailingEdge, delayMs);
+ if (maxWait !== undefined && maxTimeoutId.current === undefined) {
+ maxTimeoutId.current = setTimeout(() => {
+ clearTimers();
+ if (lastArgs.current) invoke();
+ }, maxWait);
+ }
+ return lastResult.current;
+ },
+ {
+ cancel: () => {
+ clearTimers();
+ lastArgs.current = undefined;
+ },
+ flush: (): R | undefined => {
+ if (timeoutId.current === undefined) return lastResult.current;
+ clearTimers();
+ return lastArgs.current ? invoke() : lastResult.current;
+ },
+ isPending: () =>
+ timeoutId.current !== undefined && lastArgs.current !== undefined,
+ },
+ );
+
+ return state;
+ }, [delayMs, leading, trailing, maxWait, latestFn]);
+
+ useUnmount(() => {
+ debounced.cancel();
+ });
+
+ return debounced;
+};
+`,
+ },
+ "use-debounce-value": {
+ path: "src/hooks/use-debounce-value/use-debounce-value.ts",
+ source: `import { useEffect, useRef, useState } from "react";
+import {
+ useDebounceCallback,
+ type DebounceOptions,
+ type DebouncedState,
+} from "../use-debounce-callback/use-debounce-callback";
+
+export type UseDebounceValueReturn<T> = [
+ T,
+ DebouncedState<[value: T | ((prev: T) => T)], void>,
+];
+
+export const useDebounceValue = <T>(
+ initialValue: T | (() => T),
+ delayMs = 500,
+ options: DebounceOptions & { equalityFn?: (left: T, right: T) => boolean } = {},
+): UseDebounceValueReturn<T> => {
+ const eq = options.equalityFn ?? ((left, right) => left === right);
+ const unwrap = (v: T | (() => T)): T =>
+ typeof v === "function" ? (v as () => T)() : v;
+
+ const [debouncedValue, setDebouncedValue] = useState<T>(() =>
+ unwrap(initialValue),
+ );
+ const previousValue = useRef(debouncedValue);
+
+ const updateDebouncedValue = useDebounceCallback(
+ (value: T | ((prev: T) => T)) => {
+ const next =
+ typeof value === "function"
+ ? (value as (prev: T) => T)(previousValue.current)
+ : value;
+ if (!eq(previousValue.current, next)) {
+ previousValue.current = next;
+ setDebouncedValue(next);
+ }
+ },
+ delayMs,
+ options,
+ );
+
+ useEffect(() => {
+ return () => updateDebouncedValue.cancel();
+ }, [updateDebouncedValue]);
+
+ return [debouncedValue, updateDebouncedValue];
+};
+`,
+ },
+ "use-interval": {
+ path: "src/hooks/use-interval/use-interval.ts",
+ source: `import { useEffect, useRef } from "react";
+
+export const useInterval = (callback: () => void, delay: number | null) => {
+ const savedCallback = useRef(callback);
+
+ useEffect(() => {
+ savedCallback.current = callback;
+ }, [callback]);
+
+ useEffect(() => {
+ if (delay === null) return;
+ const id = setInterval(() => savedCallback.current(), delay);
+ return () => clearInterval(id);
+ }, [delay]);
+};
+`,
+ },
+ "use-timeout": {
+ path: "src/hooks/use-timeout/use-timeout.ts",
+ source: `import { useEffect, useRef } from "react";
+
+export const useTimeout = (callback: () => void, delay: number | null) => {
+ const savedCallback = useRef(callback);
+
+ useEffect(() => {
+ savedCallback.current = callback;
+ }, [callback]);
+
+ useEffect(() => {
+ if (delay === null) return;
+ const id = setTimeout(() => savedCallback.current(), delay);
+ return () => clearTimeout(id);
+ }, [delay]);
+};
+`,
+ },
+ "use-isomorphic-layout-effect": {
+ path: "src/hooks/use-isomorphic-layout-effect/use-isomorphic-layout-effect.ts",
+ source: `import { useEffect, useLayoutEffect } from "react";
+
+/**
+ * useLayoutEffect that safely falls back to useEffect on the server, where
+ * useLayoutEffect would warn. Picks the layout effect only when a DOM exists.
+ */
+export const useIsomorphicLayoutEffect =
+ typeof window !== "undefined" ? useLayoutEffect : useEffect;
+`,
+ },
+ "use-event-callback": {
+ path: "src/hooks/use-event-callback/use-event-callback.ts",
+ source: `import { useCallback, useRef } from "react";
+import { useIsomorphicLayoutEffect } from "../use-isomorphic-layout-effect/use-isomorphic-layout-effect";
+
+export const useEventCallback = <Args extends unknown[], R>(
+ fn: (...args: Args) => R,
+) => {
+ const ref = useRef<(...args: Args) => R>(() => {
+ throw new Error("Cannot call an event handler while rendering.");
+ });
+
+ useIsomorphicLayoutEffect(() => {
+ ref.current = fn;
+ }, [fn]);
+
+ return useCallback((...args: Args) => ref.current(...args), [ref]);
+};
+`,
+ },
+ "use-unmount": {
+ path: "src/hooks/use-unmount/use-unmount.ts",
+ source: `import { useEffect, useRef } from "react";
+
+export const useUnmount = (fn: () => void) => {
+ const fnRef = useRef(fn);
+
+ // The latest closure every render, but only invoked on unmount.
+ fnRef.current = fn;
+
+ useEffect(() => () => fnRef.current(), []);
+};
+`,
+ },
+ "use-is-client": {
+ path: "src/hooks/use-is-client/use-is-client.ts",
+ source: `import { useEffect, useState } from "react";
+
+export const useIsClient = () => {
+ const [isClient, setIsClient] = useState(false);
+
+ useEffect(() => {
+ setIsClient(true);
+ }, []);
+
+ return isClient;
+};
+`,
+ },
+ "use-is-mounted": {
+ path: "src/hooks/use-is-mounted/use-is-mounted.ts",
+ source: `import { useCallback, useEffect, useRef } from "react";
+
+export const useIsMounted = () => {
+ const isMounted = useRef(false);
+
+ useEffect(() => {
+ isMounted.current = true;
+ return () => {
+ isMounted.current = false;
+ };
+ }, []);
+
+ return useCallback(() => isMounted.current, []);
+};
+`,
+ },
+ "use-document-title": {
+ path: "src/hooks/use-document-title/use-document-title.ts",
+ source: `import { useRef } from "react";
+import { useIsomorphicLayoutEffect } from "../use-isomorphic-layout-effect/use-isomorphic-layout-effect";
+import { useUnmount } from "../use-unmount/use-unmount";
+
+interface UseDocumentTitleOptions {
+ preserveTitleOnUnmount?: boolean;
+}
+
+export const useDocumentTitle = (
+ title: string,
+ options: UseDocumentTitleOptions = {},
+) => {
+ const { preserveTitleOnUnmount = true } = options;
+ const defaultTitle = useRef<string | null>(null);
+
+ useIsomorphicLayoutEffect(() => {
+ defaultTitle.current = window.document.title;
+ }, []);
+
+ useIsomorphicLayoutEffect(() => {
+ window.document.title = title;
+ }, [title]);
+
+ useUnmount(() => {
+ if (!preserveTitleOnUnmount && defaultTitle.current !== null) {
+ window.document.title = defaultTitle.current;
+ }
+ });
+};
+`,
+ },
+ "use-event-listener": {
+ path: "src/hooks/use-event-listener/use-event-listener.ts",
+ source: `import { RefObject, useEffect, useRef } from "react";
+import { useIsomorphicLayoutEffect } from "../use-isomorphic-layout-effect/use-isomorphic-layout-effect";
+
+function useEventListener<K extends keyof MediaQueryListEventMap>(
+ eventName: K,
+ handler: (event: MediaQueryListEventMap[K]) => void,
+ element: RefObject<MediaQueryList>,
+ options?: boolean | AddEventListenerOptions,
+): void;
+function useEventListener<K extends keyof WindowEventMap>(
+ eventName: K,
+ handler: (event: WindowEventMap[K]) => void,
+ element?: undefined,
+ options?: boolean | AddEventListenerOptions,
+): void;
+function useEventListener<K extends keyof DocumentEventMap>(
+ eventName: K,
+ handler: (event: DocumentEventMap[K]) => void,
+ element: RefObject<Document>,
+ options?: boolean | AddEventListenerOptions,
+): void;
+function useEventListener<
+ K extends keyof HTMLElementEventMap & keyof SVGElementEventMap,
+ T extends HTMLElement | SVGElement = HTMLDivElement,
+>(
+ eventName: K,
+ handler: (event: HTMLElementEventMap[K] | SVGElementEventMap[K]) => void,
+ element: RefObject<T>,
+ options?: boolean | AddEventListenerOptions,
+): void;
+function useEventListener(
+ eventName: string,
+ handler: (event: Event) => void,
+ element?: RefObject<HTMLElement | MediaQueryList | Document>,
+ options?: boolean | AddEventListenerOptions,
+) {
+ // Hold the handler in a ref so updating it never detaches the listener.
+ const savedHandler = useRef(handler);
+
+ useIsomorphicLayoutEffect(() => {
+ savedHandler.current = handler;
+ }, [handler]);
+
+ useEffect(() => {
+ const targetElement = element?.current ?? window;
+ if (!targetElement?.addEventListener) return;
+
+ const listener = (event: Event) => savedHandler.current(event);
+ targetElement.addEventListener(eventName, listener, options);
+
+ return () => {
+ targetElement.removeEventListener(eventName, listener, options);
+ };
+ }, [eventName, element, options]);
+}
+
+export { useEventListener };
+`,
+ },
+ "use-click-outside": {
+ path: "src/hooks/useClickOutside.hook.ts",
+ source: `import { Ref, useEffect } from "react";
+
+type ClickOutsideCallback = () => void;
+
+export const useClickOutside = <T extends HTMLElement>(
+ ref: Ref<T>,
+ callback: ClickOutsideCallback,
+) => {
+ useEffect(() => {
+ const handleClickOutside = (event: MouseEvent) => {
+ if (
+ ref &&
+ "current" in ref &&
+ !ref.current?.contains(event.target as Node)
+ ) {
+ callback();
+ }
+ };
+
+ document.addEventListener("mousedown", handleClickOutside);
+ return () => {
+ document.removeEventListener("mousedown", handleClickOutside);
+ };
+ }, [ref, callback]);
+};
+`,
+ },
+ "use-mouse-position": {
+ path: "src/hooks/useMousePosition.hook.ts",
+ source: `import { Ref, useEffect, useState } from "react";
+
+interface MousePosition {
+ x: number | null;
+ y: number | null;
+}
+
+export const useMousePosition = <T extends HTMLElement>(
+ ref: Ref<T>,
+): MousePosition => {
+ const [mousePosition, setMousePosition] = useState<MousePosition>({
+ x: null,
+ y: null,
+ });
+
+ useEffect(() => {
+ const updateMousePosition = (event: MouseEvent) => {
+ const { clientX, clientY } = event;
+ if (ref && "current" in ref && ref.current) {
+ const { left, top } = ref.current.getBoundingClientRect();
+ setMousePosition({ x: clientX - left, y: clientY - top });
+ }
+ };
+
+ window.addEventListener("mousemove", updateMousePosition);
+ return () => {
+ window.removeEventListener("mousemove", updateMousePosition);
+ };
+ }, [ref]);
+
+ return mousePosition;
+};
+`,
+ },
+ "use-infinite-scroll": {
+ path: "src/hooks/useInfiniteScroll.hook.ts",
+ source: `import { useEffect, useState } from "react";
+
+type FetchMoreData = () => Promise<void>;
+
+export const useInfiniteScroll = (fetchMoreData: FetchMoreData): boolean => {
+ const [isFetching, setIsFetching] = useState(false);
+
+ useEffect(() => {
+ const handleScroll = () => {
+ const isNearBottom =
+ window.innerHeight + window.scrollY >=
+ document.body.offsetHeight - 500;
+
+ if (isNearBottom && !isFetching) {
+ setIsFetching(true);
+ fetchMoreData().then(() => setIsFetching(false));
+ }
+ };
+
+ window.addEventListener("scroll", handleScroll);
+ return () => {
+ window.removeEventListener("scroll", handleScroll);
+ };
+ }, [fetchMoreData, isFetching]);
+
+ return isFetching;
+};
+`,
+ },
+ "use-hover": {
+ path: "src/hooks/use-hover/use-hover.ts",
+ source: `import { RefObject, useState } from "react";
+import { useEventListener } from "../use-event-listener/use-event-listener";
+
+export const useHover = <T extends HTMLElement = HTMLElement>(
+ elementRef: RefObject<T>,
+): boolean => {
+ const [isHovered, setIsHovered] = useState(false);
+
+ useEventListener("mouseenter", () => setIsHovered(true), elementRef);
+ useEventListener("mouseleave", () => setIsHovered(false), elementRef);
+
+ return isHovered;
+};
+`,
+ },
+ "use-intersection-observer": {
+ path: "src/hooks/use-intersection-observer/use-intersection-observer.ts",
+ source: `import { useCallback, useEffect, useRef, useState } from "react";
+
+interface UseIntersectionObserverOptions {
+ threshold?: number | number[];
+ root?: Element | Document | null;
+ rootMargin?: string;
+ freezeOnceVisible?: boolean;
+ initialIsIntersecting?: boolean;
+ onChange?: (
+ isIntersecting: boolean,
+ entry: IntersectionObserverEntry,
+ ) => void;
+}
+
+interface UseIntersectionObserverReturn {
+ ref: (node: Element | null) => void;
+ isIntersecting: boolean;
+ entry: IntersectionObserverEntry | null;
+}
+
+export const useIntersectionObserver = ({
+ threshold = 0,
+ root = null,
+ rootMargin = "0%",
+ freezeOnceVisible = false,
+ initialIsIntersecting = false,
+ onChange,
+}: UseIntersectionObserverOptions = {}): UseIntersectionObserverReturn => {
+ const [element, setElement] = useState<Element | null>(null);
+ const [isIntersecting, setIsIntersecting] = useState(initialIsIntersecting);
+ const [entry, setEntry] = useState<IntersectionObserverEntry | null>(null);
+
+ const onChangeRef = useRef(onChange);
+ onChangeRef.current = onChange;
+
+ const frozen = entry?.isIntersecting && freezeOnceVisible;
+
+ const ref = useCallback((node: Element | null) => {
+ setElement(node);
+ }, []);
+
+ useEffect(() => {
+ if (!element) return;
+ if (frozen) return;
+ if (typeof IntersectionObserver === "undefined") return;
+
+ const observer = new IntersectionObserver(
+ ([observerEntry]) => {
+ setEntry(observerEntry);
+ setIsIntersecting(observerEntry.isIntersecting);
+ onChangeRef.current?.(observerEntry.isIntersecting, observerEntry);
+ },
+ { threshold, root, rootMargin },
+ );
+
+ observer.observe(element);
+ return () => {
+ observer.disconnect();
+ };
+ }, [element, JSON.stringify(threshold), root, rootMargin, frozen]);
+
+ return { ref, isIntersecting, entry };
+};
+`,
+ },
+ "use-resize-observer": {
+ path: "src/hooks/use-resize-observer/use-resize-observer.ts",
+ source: `import { RefObject, useEffect, useRef, useState } from "react";
+
+interface ResizeObserverSize {
+ width: number | undefined;
+ height: number | undefined;
+}
+
+interface UseResizeObserverOptions {
+ box?: ResizeObserverBoxOptions;
+ onResize?: (size: ResizeObserverSize) => void;
+}
+
+export const useResizeObserver = <T extends HTMLElement = HTMLElement>(
+ ref: RefObject<T>,
+ options: UseResizeObserverOptions = {},
+): ResizeObserverSize => {
+ const { box = "content-box" } = options;
+ const [size, setSize] = useState<ResizeObserverSize>({
+ width: undefined,
+ height: undefined,
+ });
+
+ const onResizeRef = useRef(options.onResize);
+ onResizeRef.current = options.onResize;
+
+ const previous = useRef<ResizeObserverSize>({
+ width: undefined,
+ height: undefined,
+ });
+
+ useEffect(() => {
+ const element = ref.current;
+ if (!element) return;
+ if (typeof ResizeObserver === "undefined") return;
+
+ const observer = new ResizeObserver(([entry]) => {
+ if (!entry) return;
+
+ const boxSize =
+ box === "border-box"
+ ? entry.borderBoxSize
+ : box === "device-pixel-content-box"
+ ? entry.devicePixelContentBoxSize
+ : entry.contentBoxSize;
+
+ const measured = Array.isArray(boxSize) ? boxSize[0] : boxSize;
+ const width = measured ? measured.inlineSize : entry.contentRect.width;
+ const height = measured ? measured.blockSize : entry.contentRect.height;
+
+ if (
+ previous.current.width === width &&
+ previous.current.height === height
+ ) {
+ return;
+ }
+
+ const next = { width, height };
+ previous.current = next;
+ setSize(next);
+ onResizeRef.current?.(next);
+ });
+
+ observer.observe(element, { box });
+ return () => {
+ observer.disconnect();
+ };
+ }, [ref, box]);
+
+ return size;
+};
+`,
+ },
+ "use-scroll-lock": {
+ path: "src/hooks/use-scroll-lock/use-scroll-lock.ts",
+ source: `import { useCallback, useRef, useState } from "react";
+import { useIsomorphicLayoutEffect } from "../use-isomorphic-layout-effect/use-isomorphic-layout-effect";
+
+interface UseScrollLockOptions {
+ autoLock?: boolean;
+ lockTarget?: HTMLElement | string;
+ widthReflow?: boolean;
+}
+
+interface UseScrollLockReturn {
+ isLocked: boolean;
+ lock: () => void;
+ unlock: () => void;
+}
+
+interface OriginalStyle {
+ overflow: string;
+ paddingRight: string;
+}
+
+export const useScrollLock = (
+ options: UseScrollLockOptions = {},
+): UseScrollLockReturn => {
+ const { autoLock = true, lockTarget, widthReflow = true } = options;
+ const [isLocked, setIsLocked] = useState(false);
+ const target = useRef<HTMLElement | null>(null);
+ const originalStyle = useRef<OriginalStyle | null>(null);
+
+ const resolveTarget = useCallback((): HTMLElement | null => {
+ if (typeof document === "undefined") return null;
+ if (lockTarget instanceof HTMLElement) return lockTarget;
+ if (typeof lockTarget === "string") {
+ return document.querySelector<HTMLElement>(lockTarget);
+ }
+ return document.body;
+ }, [lockTarget]);
+
+ const lock = useCallback(() => {
+ const node = resolveTarget();
+ if (!node) return;
+
+ target.current = node;
+ originalStyle.current = {
+ overflow: node.style.overflow,
+ paddingRight: node.style.paddingRight,
+ };
+
+ if (widthReflow && typeof window !== "undefined") {
+ const scrollbarWidth = window.innerWidth - node.clientWidth;
+ if (scrollbarWidth > 0) {
+ const currentPadding =
+ parseInt(window.getComputedStyle(node).paddingRight, 10) || 0;
+ node.style.paddingRight = \`\${currentPadding + scrollbarWidth}px\`;
+ }
+ }
+
+ node.style.overflow = "hidden";
+ setIsLocked(true);
+ }, [resolveTarget, widthReflow]);
+
+ const unlock = useCallback(() => {
+ const node = target.current;
+ if (!node || !originalStyle.current) return;
+
+ node.style.overflow = originalStyle.current.overflow;
+ node.style.paddingRight = originalStyle.current.paddingRight;
+ originalStyle.current = null;
+ setIsLocked(false);
+ }, []);
+
+ useIsomorphicLayoutEffect(() => {
+ if (!autoLock) return;
+ lock();
+ return () => {
+ unlock();
+ };
+ }, [autoLock, lock, unlock]);
+
+ return { isLocked, lock, unlock };
+};
+`,
+ },
+ "use-click-any-where": {
+ path: "src/hooks/use-click-any-where/use-click-any-where.ts",
+ source: `import { useEventListener } from "../use-event-listener/use-event-listener";
+
+export const useClickAnyWhere = (
+ handler: (event: MouseEvent) => void,
+): void => {
+ useEventListener("click", handler);
+};
+`,
+ },
+ "use-media-query": {
+ path: "src/hooks/use-media-query/use-media-query.ts",
+ source: `import { useState } from "react";
+import { useIsomorphicLayoutEffect } from "../use-isomorphic-layout-effect/use-isomorphic-layout-effect";
+
+interface UseMediaQueryOptions {
+ defaultValue?: boolean;
+ initializeWithValue?: boolean;
+}
+
+const IS_SERVER = typeof window === "undefined";
+
+export function useMediaQuery(
+ query: string,
+ options: UseMediaQueryOptions = {},
+): boolean {
+ const { defaultValue = false, initializeWithValue = true } = options;
+
+ const getMatches = (mediaQuery: string): boolean => {
+ if (IS_SERVER) return defaultValue;
+ return window.matchMedia(mediaQuery).matches;
+ };
+
+ const [matches, setMatches] = useState<boolean>(() => {
+ if (initializeWithValue) return getMatches(query);
+ return defaultValue;
+ });
+
+ useIsomorphicLayoutEffect(() => {
+ if (IS_SERVER) return;
+ const matchMedia = window.matchMedia(query);
+ const handleChange = () => setMatches(matchMedia.matches);
+ handleChange();
+ matchMedia.addEventListener("change", handleChange);
+ return () => {
+ matchMedia.removeEventListener("change", handleChange);
+ };
+ }, [query]);
+
+ return matches;
+}
+`,
+ },
+ "use-screen": {
+ path: "src/hooks/use-screen/use-screen.ts",
+ source: `import { useState } from "react";
+import { useEventListener } from "../use-event-listener/use-event-listener";
+import { useIsomorphicLayoutEffect } from "../use-isomorphic-layout-effect/use-isomorphic-layout-effect";
+
+interface UseScreenOptions {
+ initializeWithValue?: boolean;
+}
+
+const IS_SERVER = typeof window === "undefined";
+
+export function useScreen(options: UseScreenOptions = {}): Screen | null {
+ const { initializeWithValue = true } = options;
+
+ const readScreen = (): Screen | null => {
+ if (IS_SERVER) return null;
+ return window.screen;
+ };
+
+ const [screen, setScreen] = useState<Screen | null>(() => {
+ if (initializeWithValue) return readScreen();
+ return null;
+ });
+
+ const handleSize = () => {
+ setScreen(readScreen());
+ };
+
+ useEventListener("resize", handleSize);
+
+ useIsomorphicLayoutEffect(() => {
+ handleSize();
+ }, []);
+
+ return screen;
+}
+`,
+ },
+ "use-window-size": {
+ path: "src/hooks/use-window-size/use-window-size.ts",
+ source: `import { useState } from "react";
+import { useEventListener } from "../use-event-listener/use-event-listener";
+import { useIsomorphicLayoutEffect } from "../use-isomorphic-layout-effect/use-isomorphic-layout-effect";
+
+interface WindowSize {
+ width: number;
+ height: number;
+}
+
+interface UseWindowSizeOptions {
+ initializeWithValue?: boolean;
+}
+
+const IS_SERVER = typeof window === "undefined";
+
+export function useWindowSize(options: UseWindowSizeOptions = {}): WindowSize {
+ const { initializeWithValue = true } = options;
+
+ const readSize = (): WindowSize => ({
+ width: window.innerWidth,
+ height: window.innerHeight,
+ });
+
+ const [windowSize, setWindowSize] = useState<WindowSize>(() => {
+ if (initializeWithValue && !IS_SERVER) return readSize();
+ return { width: 0, height: 0 };
+ });
+
+ const handleSize = () => {
+ if (IS_SERVER) return;
+ setWindowSize(readSize());
+ };
+
+ useEventListener("resize", handleSize);
+
+ useIsomorphicLayoutEffect(() => {
+ handleSize();
+ }, []);
+
+ return windowSize;
+}
+`,
+ },
+ "use-ternary-dark-mode": {
+ path: "src/hooks/use-ternary-dark-mode/use-ternary-dark-mode.ts",
+ source: `import { useCallback } from "react";
+import { useLocalStorage } from "../use-local-storage/use-local-storage";
+import { useMediaQuery } from "../use-media-query/use-media-query";
+
+type TernaryDarkMode = "system" | "dark" | "light";
+
+interface UseTernaryDarkModeOptions {
+ defaultValue?: TernaryDarkMode;
+ localStorageKey?: string;
+}
+
+interface UseTernaryDarkModeReturn {
+ isDarkMode: boolean;
+ ternaryDarkMode: TernaryDarkMode;
+ setTernaryDarkMode: (
+ value: TernaryDarkMode | ((prev: TernaryDarkMode) => TernaryDarkMode),
+ ) => void;
+ toggleTernaryDarkMode: () => void;
+}
+
+const COLOR_SCHEME_QUERY = "(prefers-color-scheme: dark)";
+const DEFAULT_STORAGE_KEY = "hookli-ternary-dark-mode";
+
+export function useTernaryDarkMode(
+ options: UseTernaryDarkModeOptions = {},
+): UseTernaryDarkModeReturn {
+ const { defaultValue = "system", localStorageKey = DEFAULT_STORAGE_KEY } =
+ options;
+ const isDarkOS = useMediaQuery(COLOR_SCHEME_QUERY);
+ const { value: ternaryDarkMode, setStoredValue: setTernaryDarkMode } =
+ useLocalStorage<TernaryDarkMode>(localStorageKey, defaultValue);
+
+ const isDarkMode =
+ ternaryDarkMode === "dark" || (ternaryDarkMode === "system" && isDarkOS);
+
+ const toggleTernaryDarkMode = useCallback(() => {
+ const cycle: TernaryDarkMode[] = ["light", "system", "dark"];
+ setTernaryDarkMode((prev) => {
+ const nextIndex = (cycle.indexOf(prev) + 1) % cycle.length;
+ return cycle[nextIndex];
+ });
+ }, [setTernaryDarkMode]);
+
+ return {
+ isDarkMode,
+ ternaryDarkMode,
+ setTernaryDarkMode,
+ toggleTernaryDarkMode,
+ };
+}
+`,
+ },
+ "use-copy-to-clipboard": {
+ path: "src/hooks/use-copy-to-clipboard/use-copy-to-clipboard.ts",
+ source: `import { useCallback, useState } from "react";
+
+type CopiedValue = string | null;
+type CopyFn = (text: string) => Promise<boolean>;
+type UseCopyToClipboardReturn = [CopiedValue, CopyFn];
+
+export function useCopyToClipboard(): UseCopyToClipboardReturn {
+ const [copiedText, setCopiedText] = useState<CopiedValue>(null);
+
+ const copy: CopyFn = useCallback(async (text) => {
+ if (typeof navigator === "undefined" || !navigator.clipboard) {
+ return false;
+ }
+
+ try {
+ await navigator.clipboard.writeText(text);
+ setCopiedText(text);
+ return true;
+ } catch {
+ setCopiedText(null);
+ return false;
+ }
+ }, []);
+
+ return [copiedText, copy];
+}
+`,
+ },
+ "use-script": {
+ path: "src/hooks/use-script/use-script.ts",
+ source: `import { useEffect, useState } from "react";
+
+type UseScriptStatus = "idle" | "loading" | "ready" | "error";
+
+interface UseScriptOptions {
+ shouldPreventLoad?: boolean;
+ removeOnUnmount?: boolean;
+}
+
+export function useScript(
+ src: string | null,
+ options?: UseScriptOptions,
+): UseScriptStatus {
+ const [status, setStatus] = useState<UseScriptStatus>(() => {
+ if (!src || options?.shouldPreventLoad) return "idle";
+ return "loading";
+ });
+
+ useEffect(() => {
+ if (!src || options?.shouldPreventLoad) {
+ setStatus("idle");
+ return;
+ }
+
+ let script = document.querySelector<HTMLScriptElement>(
+ \`script[src="\${src}"]\`,
+ );
+
+ if (script === null) {
+ script = document.createElement("script");
+ script.src = src;
+ script.async = true;
+ script.setAttribute("data-status", "loading");
+ document.body.appendChild(script);
+
+ const setAttributeFromEvent = (event: Event) => {
+ script?.setAttribute(
+ "data-status",
+ event.type === "load" ? "ready" : "error",
+ );
+ };
+
+ script.addEventListener("load", setAttributeFromEvent);
+ script.addEventListener("error", setAttributeFromEvent);
+ } else {
+ setStatus(
+ (script.getAttribute("data-status") as UseScriptStatus) ?? "loading",
+ );
+ }
+
+ const setStateFromEvent = (event: Event) => {
+ setStatus(event.type === "load" ? "ready" : "error");
+ };
+
+ script.addEventListener("load", setStateFromEvent);
+ script.addEventListener("error", setStateFromEvent);
+
+ return () => {
+ if (script) {
+ script.removeEventListener("load", setStateFromEvent);
+ script.removeEventListener("error", setStateFromEvent);
+ if (options?.removeOnUnmount) {
+ script.remove();
+ }
+ }
+ };
+ }, [src, options?.shouldPreventLoad, options?.removeOnUnmount]);
+
+ return status;
+}
+`,
+ },
+ "use-fetch": {
+ path: "src/hooks/useFetch.hook.ts",
+ source: `import { useEffect, useState } from "react";
+
+interface UseFetchResponse<T = any> {
+ data: T | null;
+ error: Error | null;
+ loading: boolean;
+}
+
+export const useFetch = <T>(url: string): UseFetchResponse<T> => {
+ const [data, setData] = useState<T | null>(null);
+ const [error, setError] = useState<Error | null>(null);
+ const [loading, setLoading] = useState(true);
+
+ useEffect(() => {
+ const fetchData = async () => {
+ try {
+ const response = await fetch(url);
+ if (!response.ok) {
+ throw new Error(\`HTTP error! status: \${response.status}\`);
+ }
+ const fetchedData = await response.json();
+ setData(fetchedData);
+ } catch (err) {
+ setError(err as Error);
+ } finally {
+ setLoading(false);
+ }
+ };
+
+ fetchData();
+ }, [url]);
+
+ return { data, error, loading };
+};
+`,
+ },
+ "use-geo-location": {
+ path: "src/hooks/useGeoLocation.hook.ts",
+ source: `import { useEffect, useState } from "react";
+
+interface GeolocationError {
+ code: number;
+ message: string;
+}
+
+type GeolocationPosition = {
+ coords: { latitude: number; longitude: number };
+};
+
+interface GeolocationState {
+ location: GeolocationPosition | null;
+ error: GeolocationError | Error | null;
+}
+
+export const useGeoLocation = (): GeolocationState => {
+ const [location, setLocation] = useState<GeolocationPosition | null>(null);
+ const [error, setError] = useState<GeolocationError | Error | null>(null);
+
+ useEffect(() => {
+ const getLocation = async () => {
+ try {
+ const position = await getCurrentPosition();
+ setLocation({
+ coords: {
+ latitude: position.coords.latitude,
+ longitude: position.coords.longitude,
+ },
+ });
+ } catch (err) {
+ setError(err as Error);
+ }
+ };
+
+ if (navigator.geolocation) {
+ navigator.permissions
+ .query({ name: "geolocation" })
+ .then((result) => {
+ if (result.state === "granted") {
+ getLocation();
+ } else if (result.state === "prompt") {
+ navigator.geolocation.getCurrentPosition(
+ () => getLocation(),
+ (err) => setError(err),
+ );
+ } else {
+ setError(new Error("Geolocation permission denied"));
+ }
+ })
+ .catch((err) => setError(err));
+ } else {
+ setError(new Error("Geolocation is not supported by this browser."));
+ }
+ }, []);
+
+ return { location, error };
+};
+
+function getCurrentPosition(): Promise<globalThis.GeolocationPosition> {
+ return new Promise((resolve, reject) => {
+ navigator.geolocation.getCurrentPosition(resolve, reject);
+ });
+}
+`,
+ },
+};
+
+export function getHookSource(slug: string): HookSource | undefined {
+ return HOOK_SOURCES[slug];
+}
+
+export function hookSourceUrl(path: string): string {
+ return `${REPO_BLOB}/${path}`;
+}
diff --git a/apps/docs/lib/hooks-registry.ts b/apps/docs/lib/hooks-registry.ts
new file mode 100644
index 0000000..3b8ccad
--- /dev/null
+++ b/apps/docs/lib/hooks-registry.ts
@@ -0,0 +1,55 @@
+/* The hook list is the LIBRARY manifest — the single source of truth
+ (`packages/hookli/hooks.manifest.json`, imported via the `hookli/manifest` subpath
+ export). Adding a hook in the library makes it appear here automatically; nothing is
+ hand-maintained. This file keeps the docs-side types, category order/labels and helpers. */
+import manifest from "hookli/manifest";
+
+export type HookCategory = "state" | "effects" | "dom" | "data";
+
+export type HookEntry = {
+ slug: string;
+ name: string;
+ description: string;
+ category: HookCategory;
+ signature: string;
+};
+
+export const HOOKS: readonly HookEntry[] = (manifest as { hooks: readonly HookEntry[] }).hooks;
+
+/* Sidebar / docs-index group order (docs/DESIGN.md §6). */
+export const CATEGORY_ORDER: readonly HookCategory[] = [
+ "state",
+ "effects",
+ "dom",
+ "data",
+] as const;
+
+export const CATEGORY_LABELS: Record<HookCategory, string> = {
+ state: "State",
+ effects: "Effects",
+ dom: "DOM",
+ data: "Data",
+};
+
+export function getHook(slug: string): HookEntry | undefined {
+ return HOOKS.find((hook) => hook.slug === slug);
+}
+
+export function hooksByCategory(category: HookCategory): HookEntry[] {
+ return HOOKS.filter((hook) => hook.category === category);
+}
+
+/* Sibling hooks to surface at the bottom of a hook page: same category first,
+ topped up in registry order so every page always shows `limit` suggestions. */
+export function relatedHooks(slug: string, limit = 3): HookEntry[] {
+ const current = getHook(slug);
+ if (!current) return [];
+ const sameCategory = HOOKS.filter(
+ (hook) => hook.category === current.category && hook.slug !== slug,
+ );
+ if (sameCategory.length >= limit) return sameCategory.slice(0, limit);
+ const fill = HOOKS.filter(
+ (hook) => hook.slug !== slug && !sameCategory.includes(hook),
+ );
+ return [...sameCategory, ...fill].slice(0, limit);
+}
diff --git a/apps/docs/lib/og.tsx b/apps/docs/lib/og.tsx
new file mode 100644
index 0000000..235c8df
--- /dev/null
+++ b/apps/docs/lib/og.tsx
@@ -0,0 +1,114 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+/* Shared machinery for the generated OG images (app/opengraph-image.tsx,
+ app/docs/[slug]/opengraph-image.tsx) and app/apple-icon.tsx. Satori can't
+ reach next/font's build cache (and doesn't read woff2), so the woffs come
+ from the @fontsource devDependencies. Brand tokens mirror app/globals.css
+ @theme — keep in sync. */
+
+export const OG_SIZE = { width: 1200, height: 630 };
+
+export const OG_COLORS = {
+ ground: "#003748",
+ accent: "#30c5ca",
+ slate: "#4a7a8c",
+ gray: "#8fb6c2",
+ fg: "#ffffff",
+} as const;
+
+const FONT_FILES = join(process.cwd(), "node_modules/@fontsource");
+
+export async function loadOgFonts() {
+ const [sansRegular, sansBold, monoRegular, monoBold] = await Promise.all([
+ readFile(
+ join(
+ FONT_FILES,
+ "plus-jakarta-sans/files/plus-jakarta-sans-latin-400-normal.woff",
+ ),
+ ),
+ readFile(
+ join(
+ FONT_FILES,
+ "plus-jakarta-sans/files/plus-jakarta-sans-latin-700-normal.woff",
+ ),
+ ),
+ readFile(
+ join(FONT_FILES, "jetbrains-mono/files/jetbrains-mono-latin-400-normal.woff"),
+ ),
+ readFile(
+ join(FONT_FILES, "jetbrains-mono/files/jetbrains-mono-latin-700-normal.woff"),
+ ),
+ ]);
+ return [
+ {
+ name: "Plus Jakarta Sans",
+ data: sansRegular,
+ style: "normal" as const,
+ weight: 400 as const,
+ },
+ {
+ name: "Plus Jakarta Sans",
+ data: sansBold,
+ style: "normal" as const,
+ weight: 700 as const,
+ },
+ {
+ name: "JetBrains Mono",
+ data: monoRegular,
+ style: "normal" as const,
+ weight: 400 as const,
+ },
+ {
+ name: "JetBrains Mono",
+ data: monoBold,
+ style: "normal" as const,
+ weight: 700 as const,
+ },
+ ];
+}
+
+/* The brand mark from public/hookli-icon.svg without the tile — a hook cradling
+ a state dot. Satori needs explicit svg dimensions; viewBox is 110×140. */
+export function OgMark({ height }: { height: number }) {
+ const width = Math.round((height * 110) / 140);
+ return (
+ <svg width={width} height={height} viewBox="-13 -3 110 140" fill="none">
+ <path
+ d="M84 10 V82 A42 42 0 1 1 0 82 V58"
+ stroke={OG_COLORS.accent}
+ strokeWidth={26}
+ strokeLinecap="round"
+ />
+ <circle cx={42} cy={82} r={15} fill={OG_COLORS.fg} />
+ </svg>
+ );
+}
+
+/* hookli. lockup — brand v3, same as components/wordmark. */
+export function OgWordmark({
+ fontSize,
+ withMark = false,
+}: {
+ fontSize: number;
+ withMark?: boolean;
+}) {
+ return (
+ <div style={{ display: "flex", alignItems: "center", gap: fontSize * 0.35 }}>
+ {withMark ? <OgMark height={fontSize * 1.05} /> : null}
+ <div
+ style={{
+ display: "flex",
+ fontFamily: "Plus Jakarta Sans",
+ fontSize,
+ fontWeight: 700,
+ letterSpacing: "-0.03em",
+ color: OG_COLORS.fg,
+ }}
+ >
+ hookli
+ <span style={{ color: OG_COLORS.accent }}>.</span>
+ </div>
+ </div>
+ );
+}
diff --git a/apps/docs/lib/shiki.ts b/apps/docs/lib/shiki.ts
new file mode 100644
index 0000000..3234def
--- /dev/null
+++ b/apps/docs/lib/shiki.ts
@@ -0,0 +1,43 @@
+import { codeToHtml, createCssVariablesTheme, type ShikiTransformer } from "shiki";
+
+/* Server-only highlighter. The css-variables theme emits var(--shiki-*) colors,
+ mapped to brand tokens in globals.css (docs/DESIGN.md §5 CodeBlock). */
+const cssVariablesTheme = createCssVariablesTheme({
+ name: "hookli",
+ variablePrefix: "--shiki-",
+});
+
+export type CodeLang = "tsx" | "ts" | "bash";
+
+export type HighlightOptions = {
+ /* Gutter line numbers (Usage snippets — T16 usehooks-ts anatomy). */
+ lineNumbers?: boolean;
+ /* 1-based line to emphasise — the hook-call line in a Usage snippet. */
+ highlightLine?: number;
+};
+
+export function highlight(
+ code: string,
+ lang: CodeLang = "tsx",
+ { lineNumbers = false, highlightLine }: HighlightOptions = {},
+) {
+ const transformers: ShikiTransformer[] = [];
+
+ if (lineNumbers) {
+ transformers.push({
+ pre(node) {
+ this.addClassToHast(node, "line-numbers");
+ },
+ });
+ }
+
+ if (highlightLine) {
+ transformers.push({
+ line(node, line) {
+ if (line === highlightLine) this.addClassToHast(node, "highlighted-line");
+ },
+ });
+ }
+
+ return codeToHtml(code.trim(), { lang, theme: cssVariablesTheme, transformers });
+}
diff --git a/apps/docs/lib/site.ts b/apps/docs/lib/site.ts
new file mode 100644
index 0000000..ca3649d
--- /dev/null
+++ b/apps/docs/lib/site.ts
@@ -0,0 +1,10 @@
+/* Canonical origin for metadataBase, sitemap and robots. Placeholder until the
+ human deploys — override with NEXT_PUBLIC_SITE_URL, no trailing slash. */
+export const SITE_URL =
+ process.env.NEXT_PUBLIC_SITE_URL ?? "https://hookli.vercel.app";
+export const GITHUB_URL = "https://github.com/saifmohamedsv/hookli";
+export const NPM_URL = "https://www.npmjs.com/package/hookli";
+export const SPONSOR_URL = "https://github.com/sponsors/saifmohamedsv";
+export const KOFI_URL = "https://ko-fi.com/saifmohamedsv";
+export const TAGLINE =
+ "Simple React hooks. Typed. SSR-safe. Zero dependencies.";
diff --git a/apps/docs/lib/web-apis.tsx b/apps/docs/lib/web-apis.tsx
new file mode 100644
index 0000000..20399b9
--- /dev/null
+++ b/apps/docs/lib/web-apis.tsx
@@ -0,0 +1,68 @@
+import { Fragment, type ReactNode } from "react";
+import { ExternalLinkIcon } from "@/components/icons";
+
+/* Web-API mentions inside hook descriptions become linked MDN chips (T16
+ usehooks-ts anatomy). Curated term → MDN map; matching is case-insensitive
+ and word-bounded so "fetch" links but "useFetch"/"fetchData" don't. */
+const WEB_APIS: Record<string, string> = {
+ localstorage:
+ "https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage",
+ geolocation:
+ "https://developer.mozilla.org/en-US/docs/Web/API/Geolocation_API",
+ fetch: "https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch",
+ scroll:
+ "https://developer.mozilla.org/en-US/docs/Web/API/Document/scroll_event",
+ mousedown:
+ "https://developer.mozilla.org/en-US/docs/Web/API/Element/mousedown_event",
+ mousemove:
+ "https://developer.mozilla.org/en-US/docs/Web/API/Element/mousemove_event",
+};
+
+/* Longest terms first so multi-word/compound names win over their substrings. */
+const TERM_PATTERN = new RegExp(
+ `\\b(${Object.keys(WEB_APIS)
+ .sort((a, b) => b.length - a.length)
+ .join("|")})\\b`,
+ "gi",
+);
+
+function ApiChip({ label, href }: { label: string; href: string }) {
+ return (
+ <a
+ href={href}
+ target="_blank"
+ rel="noopener noreferrer"
+ className="inline-flex items-center gap-0.5 whitespace-nowrap rounded border border-accent/40 bg-accent/10 px-1.5 align-baseline text-[0.92em] font-medium text-accent transition-colors duration-200 hover:bg-accent/20"
+ >
+ {label}
+ <ExternalLinkIcon className="size-3 shrink-0" aria-hidden="true" />
+ <span className="sr-only"> (MDN, opens in a new tab)</span>
+ </a>
+ );
+}
+
+/* Returns the text with recognised Web-API terms replaced by MDN chips. */
+export function linkifyWebApis(text: string): ReactNode {
+ const parts: ReactNode[] = [];
+ let last = 0;
+ let key = 0;
+
+ for (const match of text.matchAll(TERM_PATTERN)) {
+ const term = match[0];
+ const start = match.index ?? 0;
+ if (start > last) parts.push(text.slice(last, start));
+ const href = WEB_APIS[term.toLowerCase()];
+ parts.push(<ApiChip key={key++} label={term} href={href} />);
+ last = start + term.length;
+ }
+
+ if (last < text.length) parts.push(text.slice(last));
+
+ return (
+ <>
+ {parts.map((part, i) => (
+ <Fragment key={i}>{part}</Fragment>
+ ))}
+ </>
+ );
+}
diff --git a/apps/docs/next.config.ts b/apps/docs/next.config.ts
new file mode 100644
index 0000000..e9ffa30
--- /dev/null
+++ b/apps/docs/next.config.ts
@@ -0,0 +1,7 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+ /* config options here */
+};
+
+export default nextConfig;
diff --git a/apps/docs/package.json b/apps/docs/package.json
new file mode 100644
index 0000000..5dfbbfc
--- /dev/null
+++ b/apps/docs/package.json
@@ -0,0 +1,31 @@
+{
+ "name": "hookli-docs",
+ "version": "0.1.0",
+ "private": true,
+ "scripts": {
+ "dev": "next dev",
+ "build": "next build",
+ "start": "next start",
+ "lint": "eslint",
+ "typecheck": "tsc --noEmit"
+ },
+ "dependencies": {
+ "hookli": "workspace:*",
+ "next": "16.2.10",
+ "react": "19.2.4",
+ "react-dom": "19.2.4",
+ "shiki": "^4.3.1"
+ },
+ "devDependencies": {
+ "@fontsource/jetbrains-mono": "^5.2.8",
+ "@fontsource/plus-jakarta-sans": "^5.2.8",
+ "@tailwindcss/postcss": "^4",
+ "@types/node": "^20",
+ "@types/react": "^19",
+ "@types/react-dom": "^19",
+ "eslint": "^9",
+ "eslint-config-next": "16.2.10",
+ "tailwindcss": "^4",
+ "typescript": "^5"
+ }
+}
diff --git a/apps/docs/postcss.config.mjs b/apps/docs/postcss.config.mjs
new file mode 100644
index 0000000..61e3684
--- /dev/null
+++ b/apps/docs/postcss.config.mjs
@@ -0,0 +1,7 @@
+const config = {
+ plugins: {
+ "@tailwindcss/postcss": {},
+ },
+};
+
+export default config;
diff --git a/assets/variants/variant-4-refined.png b/apps/docs/public/hookli-banner.png
similarity index 100%
rename from assets/variants/variant-4-refined.png
rename to apps/docs/public/hookli-banner.png
diff --git a/assets/variants/variant-4-refined.svg b/apps/docs/public/hookli-banner.svg
similarity index 100%
rename from assets/variants/variant-4-refined.svg
rename to apps/docs/public/hookli-banner.svg
diff --git a/apps/docs/public/hookli-icon.svg b/apps/docs/public/hookli-icon.svg
new file mode 100644
index 0000000..fc0bb9b
--- /dev/null
+++ b/apps/docs/public/hookli-icon.svg
@@ -0,0 +1,9 @@
+<svg width="256" height="256" viewBox="0 0 256 256" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="hookli — a hook holding a state dot">
+ <!-- tile -->
+ <rect width="256" height="256" rx="56" fill="#003748"/>
+ <!-- hook: shaft, curl, upturned tip — one continuous stroke -->
+ <path d="M170 68 V140 A42 42 0 1 1 86 140 V116"
+ stroke="#30C5CA" stroke-width="26" stroke-linecap="round" fill="none"/>
+ <!-- the state dot, held by the hook -->
+ <circle cx="128" cy="140" r="15" fill="#FFFFFF"/>
+</svg>
diff --git a/apps/docs/tsconfig.json b/apps/docs/tsconfig.json
new file mode 100644
index 0000000..3a13f90
--- /dev/null
+++ b/apps/docs/tsconfig.json
@@ -0,0 +1,34 @@
+{
+ "compilerOptions": {
+ "target": "ES2017",
+ "lib": ["dom", "dom.iterable", "esnext"],
+ "allowJs": true,
+ "skipLibCheck": true,
+ "strict": true,
+ "noEmit": true,
+ "esModuleInterop": true,
+ "module": "esnext",
+ "moduleResolution": "bundler",
+ "resolveJsonModule": true,
+ "isolatedModules": true,
+ "jsx": "react-jsx",
+ "incremental": true,
+ "plugins": [
+ {
+ "name": "next"
+ }
+ ],
+ "paths": {
+ "@/*": ["./*"]
+ }
+ },
+ "include": [
+ "next-env.d.ts",
+ "**/*.ts",
+ "**/*.tsx",
+ ".next/types/**/*.ts",
+ ".next/dev/types/**/*.ts",
+ "**/*.mts"
+ ],
+ "exclude": ["node_modules"]
+}
diff --git a/apps/docs/types/hookli-manifest.d.ts b/apps/docs/types/hookli-manifest.d.ts
new file mode 100644
index 0000000..518dce5
--- /dev/null
+++ b/apps/docs/types/hookli-manifest.d.ts
@@ -0,0 +1,14 @@
+// Types for the library's `hookli/manifest` subpath export (a JSON file). Keeps the
+// docs' registry import resolvable without relying on JSON-subpath type inference.
+declare module "hookli/manifest" {
+ const manifest: {
+ hooks: Array<{
+ slug: string;
+ name: string;
+ description: string;
+ category: string;
+ signature: string;
+ }>;
+ };
+ export default manifest;
+}
diff --git a/assets/variants/compare.html b/assets/variants/compare.html
deleted file mode 100644
index cf9061a..0000000
--- a/assets/variants/compare.html
+++ /dev/null
@@ -1,95 +0,0 @@
-<title>hookli — banner variants
-
-
-
-
hookli — banner variants
-
Same mark, same Prussian #003748 / Scooter #30C5CA palette — three premium treatments. Variant 1 is what's live now. Tell me a number (or mix & match) and I'll ship it + sync the docs site.
-
-
-
-
1 Horizontal lockup live now
-
-
-
-
Balanced, familiar, works at any width. The safe premium choice.
-
-
-
-
-
2 Stacked hero
-
-
-
-
Mark leads, centered and airy — reads like an app hero / product splash. Most "brand-forward".
-
-
-
-
-
3 Editorial — ghost watermark
-
-
-
-
Left-aligned lockup with the mark blown up as a faint watermark — the most editorial / "design-studio" feel.
-
-
-
-
-
4 Refined — rule & meta
-
-
-
-
Same big lockup, but a teal rule + a monospace spec line instead of prose — crisp and technical.