banhaten 0.1.2 → 0.2.0

package/docs/design-system/gap-promotion-report.md

@@ -0,0 +1,166 @@
+# Gap promotion report
+
+This file is generated from background scenario gap metadata. A candidate appears when the same normalized need occurs in at least three distinct backgrounds. Heuristics cover common shells, navigation, tables, steps, composers, timelines, assets, and elevation; use `promotionKey` on a gap when an explicit cross-background grouping is more accurate.
+
+Scanned 194 gaps across 36 backgrounds. Found 8 promotion candidates at the 3-background threshold.
+
+## Application/workspace shell
+
+Key: `application-workspace-shell` · 20 backgrounds
+
+Backgrounds: `accounting-workspace-setup`, `acme-finance-advisor`, `ai-node-detail`, `audit-log`, `bauhow-room-planning`, `benefits-enrollment`, `data-source-browser`, `debt-payoff`, `delivery-tracking`, `hooch-storefront-dashboard`, `inference-providers`, `marcohr-people`, `order-shipment-timeline`, `people-add-member`, `quran-audio-add-employee`, `recent-orders`, `school-assignments`, `shipment-list`, `sku-management`, `stripe-demo-account`
+
+| Background | Gap | Kind | Status |
+| --- | --- | --- | --- |
+| `accounting-workspace-setup` | onboarding workspace shell (`setup-onboarding-shell`) | layout/composition pattern | missing |
+| `acme-finance-advisor` | finance advisor workspace shell (`acme-finance-workspace-shell`) | layout/composition pattern | missing |
+| `ai-node-detail` | node graph workspace shell (`node-graph-workspace-shell`) | layout/composition pattern | missing |
+| `audit-log` | audit browser workspace shell (`audit-browser-workspace-shell`) | layout/composition pattern | missing |
+| `bauhow-room-planning` | room-planning workspace shell (`room-planning-workspace-shell`) | layout/composition pattern | missing |
+| `benefits-enrollment` | benefits enrollment screen shell (`angled-benefits-screen-shell`) | layout/composition pattern | missing |
+| `data-source-browser` | desktop browser and app-shell scene (`desktop-browser-and-app-shell-scene`) | layout/composition pattern | missing |
+| `debt-payoff` | finance workspace shell (`finance-workspace-shell`) | layout/composition pattern | missing |
+| `delivery-tracking` | delivery tracking dashboard shell (`delivery-tracking-dashboard-shell`) | layout/composition pattern | missing |
+| `hooch-storefront-dashboard` | storefront dashboard workspace shell (`hooch-workspace-shell`) | layout/composition pattern | missing |
+| `inference-providers` | inference settings workspace shell (`settings-workspace-shell`) | layout/composition pattern | missing |
+| `marcohr-people` | HR workspace shell (`marcohr-workspace-shell`) | layout/composition pattern | missing |
+| `order-shipment-timeline` | cropped order workspace shell (`cropped-order-workspace-shell`) | layout/composition pattern | missing |
+| `people-add-member` | HR workspace shell (`people-hr-workspace-shell`) | layout/composition pattern | missing |
+| `quran-audio-add-employee` | people-and-culture workspace shell (`quran-audio-workspace-shell`) | layout/composition pattern | missing |
+| `recent-orders` | orders dashboard workspace shell (`recent-orders-workspace-shell`) | layout/composition pattern | missing |
+| `school-assignments` | school app workspace shell (`school-app-workspace-shell`) | layout/composition pattern | missing |
+| `shipment-list` | shipment management workspace shell (`shipment-list-workspace-shell`) | layout/composition pattern | missing |
+| `sku-management` | SKU management workspace shell (`sku-management-workspace-shell`) | layout/composition pattern | missing |
+| `stripe-demo-account` | payments dashboard shell (`payments-dashboard-shell`) | layout/composition pattern | missing |
+
+## Brand and product icon assets
+
+Key: `brand-icon-assets` · 16 backgrounds
+
+Backgrounds: `ai-growth-marketing`, `ai-node-detail`, `bauhow-room-planning`, `crm-intelligence`, `data-source-browser`, `debt-payoff`, `email-compose`, `inference-providers`, `investor-profile`, `model-overview`, `mora-attio-integration`, `order-shipment-timeline`, `profile-menu`, `refund-simulation`, `shipment-list`, `sku-management`
+
+| Background | Gap | Kind | Status |
+| --- | --- | --- | --- |
+| `ai-growth-marketing` | AI provider and company marks (`ai-provider-and-company-marks`) | icon asset | missing |
+| `ai-node-detail` | node and action icon assets (`node-directional-provider-icons`) | icon asset | approximation |
+| `bauhow-room-planning` | Bauhow brand and navigation glyphs (`room-planning-brand-glyphs`) | icon asset | approximation |
+| `crm-intelligence` | brand logo mark (`brand-logo-mark`) | icon asset | missing |
+| `data-source-browser` | Programa and vendor glyphs (`programa-and-vendor-glyphs`) | icon asset | missing |
+| `debt-payoff` | finance brand and navigation glyphs (`finance-brand-glyphs`) | icon asset | approximation |
+| `email-compose` | verified badge and model mark (`verified-badge-and-model-mark`) | icon asset | missing |
+| `inference-providers` | provider brand marks (`provider-brand-marks`) | icon asset | approximation |
+| `investor-profile` | verification and brand marks (`verification-and-brand-marks`) | icon asset | missing |
+| `model-overview` | Mistral logo (`mistral-logo`) | icon asset | missing |
+| `mora-attio-integration` | Mora and Attio brand marks (`mora-attio-brand-assets`) | icon asset | approximation |
+| `order-shipment-timeline` | carrier mark (`carrier-mark`) | icon asset | missing |
+| `profile-menu` | reference icon family (`reference-icon-family`) | icon asset | missing |
+| `refund-simulation` | customer identity glyph (`customer-identity-glyph`) | icon asset | missing |
+| `shipment-list` | carrier brand mark (`shipment-carrier-brand-mark`) | icon asset | approximation |
+| `sku-management` | product and assistant icon set (`sku-product-icons`) | icon asset | approximation |
+
+## Sidebar navigation
+
+Key: `sidebar-navigation` · 11 backgrounds
+
+Backgrounds: `acme-finance-advisor`, `ai-growth-marketing`, `audit-log`, `bauhow-room-planning`, `data-source-browser`, `debt-payoff`, `marcohr-people`, `people-add-member`, `shipment-list`, `sku-management`, `stripe-demo-account`
+
+| Background | Gap | Kind | Status |
+| --- | --- | --- | --- |
+| `acme-finance-advisor` | compact app sidebar navigation (`acme-sidebar-navigation`) | component | missing |
+| `ai-growth-marketing` | report sidebar navigation (`report-sidebar-navigation`) | component | missing |
+| `audit-log` | audit sidebar navigation (`audit-sidebar-navigation`) | component | missing |
+| `bauhow-room-planning` | planning sidebar navigation (`room-planning-sidebar-navigation`) | component | missing |
+| `data-source-browser` | sidebar navigation with pinned list (`sidebar-navigation-with-pinned-list`) | component | missing |
+| `debt-payoff` | planning sidebar navigation (`planning-sidebar-navigation`) | component | missing |
+| `marcohr-people` | HR sidebar navigation (`marcohr-sidebar-navigation`) | component | missing |
+| `people-add-member` | HR sidebar navigation (`people-sidebar-navigation`) | component | missing |
+| `shipment-list` | shipment sidebar navigation (`shipment-sidebar-navigation`) | component | missing |
+| `sku-management` | cropped app sidebar navigation (`sku-sidebar-navigation`) | component | missing |
+| `stripe-demo-account` | payments sidebar navigation (`payments-sidebar-navigation`) | component | missing |
+
+## Data table pattern
+
+Key: `data-table-pattern` · 10 backgrounds
+
+Backgrounds: `audit-log`, `debt-payoff`, `inference-providers`, `marcohr-people`, `people-add-member`, `recent-orders`, `school-assignments`, `share-of-voice`, `sku-management`, `stripe-demo-account`
+
+| Background | Gap | Kind | Status |
+| --- | --- | --- | --- |
+| `audit-log` | audit activity table (`audit-activity-table`) | component | missing |
+| `debt-payoff` | debt table and pagination (`debt-table-and-pagination`) | component | approximation |
+| `inference-providers` | expandable provider configuration table (`expandable-provider-table`) | component | missing |
+| `marcohr-people` | employee policy table (`marcohr-employee-table`) | component | approximation |
+| `people-add-member` | people table with status rows (`people-table-and-status-rows`) | component | approximation |
+| `recent-orders` | orders table controls and rows (`orders-table-region`) | component | approximation |
+| `school-assignments` | assignments table (`assignments-table`) | component | missing |
+| `share-of-voice` | analytics table density (`share-of-voice-analytics-table`) | component | approximation |
+| `sku-management` | SKU data table and pagination (`sku-data-table`) | component | approximation |
+| `stripe-demo-account` | metric table cards (`metric-table-cards`) | component | approximation |
+| `stripe-demo-account` | sales tabs and table (`sales-tabs-and-table`) | component | approximation |
+
+## Elevation/blur semantic effects
+
+Key: `elevation-effects` · 10 backgrounds
+
+Backgrounds: `ai-growth-marketing`, `audit-log`, `data-source-browser`, `email-compose`, `investor-profile`, `model-overview`, `profile-menu`, `refund-simulation`, `school-assignments`, `share-of-voice`
+
+| Background | Gap | Kind | Status |
+| --- | --- | --- | --- |
+| `ai-growth-marketing` | near-black overlay and chart glow (`near-black-overlay-and-chart-glow`) | token | missing |
+| `audit-log` | audit blur and elevation (`audit-blur-and-elevation`) | token | missing |
+| `data-source-browser` | browser chrome radius and elevation (`browser-chrome-radius-and-elevation`) | token | missing |
+| `email-compose` | large composer radius/elevation (`large-composer-radius-elevation`) | token | missing |
+| `investor-profile` | large card radius and soft elevation (`large-card-radius-and-soft-elevation`) | token | missing |
+| `model-overview` | backdrop blur and modal elevation (`backdrop-blur-and-modal-elevation`) | token | missing |
+| `profile-menu` | large radius and reflection elevation (`large-radius-and-reflection-elevation`) | token | missing |
+| `refund-simulation` | warm canvas and large elevation (`warm-canvas-and-large-elevation`) | token | missing |
+| `school-assignments` | warm dark backdrop and oversized shadow (`warm-dark-backdrop-and-oversized-shadow`) | token | missing |
+| `share-of-voice` | dark translucent elevation and reflection (`share-of-voice-dark-elevation`) | token | approximation |
+
+## Avatar image assets
+
+Key: `avatar-image-assets` · 9 backgrounds
+
+Backgrounds: `delivery-tracking`, `investor-profile`, `mcp-settings`, `profile-menu`, `recent-orders`, `refund-simulation`, `remove-model`, `school-assignments`, `stripe-demo-account`
+
+| Background | Gap | Kind | Status |
+| --- | --- | --- | --- |
+| `delivery-tracking` | courier avatar asset (`delivery-courier-avatar-asset`) | image asset | approximation |
+| `investor-profile` | avatar artwork (`avatar-artwork`) | image asset | missing |
+| `mcp-settings` | account avatar badge (`account-avatar-badge`) | image asset | missing |
+| `profile-menu` | avatar and hand cursor (`avatar-and-hand-cursor`) | image asset | missing |
+| `recent-orders` | brand mark and customer avatar (`recent-orders-brand-avatar-assets`) | image asset | approximation |
+| `refund-simulation` | agent blue mosaic avatar (`agent-blue-mosaic-avatar`) | image asset | missing |
+| `remove-model` | user and provider avatar crops (`remove-model-provider-assets`) | image asset | approximation |
+| `school-assignments` | teacher avatar (`teacher-avatar`) | image asset | missing |
+| `stripe-demo-account` | Stripe mark and account avatar (`stripe-brand-and-avatar-assets`) | image asset | approximation |
+
+## Progress/step indicator
+
+Key: `progress-step-indicator` · 5 backgrounds
+
+Backgrounds: `accounting-workspace-setup`, `benefits-enrollment`, `mcp-settings`, `quran-audio-add-employee`, `refund-simulation`
+
+| Background | Gap | Kind | Status |
+| --- | --- | --- | --- |
+| `accounting-workspace-setup` | step progress indicator (`setup-progress-indicator`) | component | approximation |
+| `benefits-enrollment` | enrollment progress header (`enrollment-progress-header`) | component | missing |
+| `mcp-settings` | numbered setup steps (`numbered-setup-steps`) | component | missing |
+| `quran-audio-add-employee` | three-step employee progress indicator (`quran-audio-progress-stepper`) | component | approximation |
+| `refund-simulation` | refund progress timeline (`refund-progress-timeline`) | component | missing |
+
+## Composer pattern
+
+Key: `composer-pattern` · 3 backgrounds
+
+Backgrounds: `acme-finance-advisor`, `email-compose`, `order-shipment-timeline`
+
+| Background | Gap | Kind | Status |
+| --- | --- | --- | --- |
+| `acme-finance-advisor` | advisor prompt composer (`acme-advisor-composer`) | component | approximation |
+| `email-compose` | compose modal shell (`compose-modal-shell`) | layout/composition pattern | missing |
+| `order-shipment-timeline` | note composer (`note-composer`) | component | missing |
+
+## Review rule
+
+A report entry is a prioritization signal, not automatic authorization to add a primitive. Review the mapped backgrounds, define the smallest stable API, migrate at least one real background, and remove the resolved gap metadata only after behavior, RTL, accessibility, and visual checks pass.

package/docs/design-system/icons.md

@@ -0,0 +1,69 @@
+# Icons
+
+The interactive icon explorer is available in the app under the `Icons` section.
+
+## Recommendation Posture
+
+Start the decision with five serious candidates:
+
+- `Lucide`: best default for modern product UI, especially if we want light, consistent, stroke-based icons.
+- `Tabler Icons`: best coverage-first option. It has a huge set, outline/fill coverage, and a familiar 24px grid.
+- `Material Symbols`: best if we want Google-style recognizability and many built-in style axes.
+- `Radix Icons`: best for very dense component UI where 15px icons need to stay crisp.
+- `Phosphor`: best if we want expressive weight control, including thin, bold, fill, and duotone variants.
+
+Keep `Simple Icons` as a separate brand-logo source. It should not be the primary UI icon family.
+
+## Packs To Review
+
+| Pack | Prefix | License | Best for | Variants to compare |
+| --- | --- | --- | --- | --- |
+| Google Material Symbols | `material-symbols` | Apache-2.0 | Google-style UI, broad coverage | Regular, Rounded, Sharp, Outline, Outline Rounded, Outline Sharp |
+| Google Material Icons Classic | `ic` | Apache-2.0 | Existing Material Icons familiarity | Filled/Baseline, Outlined, Rounded, Sharp, Two tone |
+| Material Design Icons by Pictogrammers | `mdi` | Apache-2.0 | Maximum utility coverage | Single broad style |
+| Radix Icons | `radix-icons` | MIT | Dense controls, primitives, menus | Single 15px style |
+| Lucide | `lucide` | ISC | Clean SaaS/product UI | Single outline style |
+| Heroicons | `heroicons` | MIT | Tailwind-friendly apps | Outline 24, Solid 24, Solid 20, Solid 16 |
+| Tabler Icons | `tabler` | MIT | Broad app coverage | Outline, filled where available |
+| Phosphor | `ph` | MIT | Adjustable visual tone | Thin, Light, Regular, Bold, Fill, Duotone |
+| Remix Icon | `ri` | Apache-2.0 | Neutral line/fill system icons | Line, Fill |
+| Bootstrap Icons | `bi` | MIT | Bootstrap-adjacent apps | Mixed outline/fill names |
+| Fluent UI System Icons | `fluent` | MIT | Microsoft-like UI language | Regular, Filled |
+| Carbon Icons | `carbon` | Apache-2.0 | Enterprise/data tools | Fixed source sizes in packages |
+| Ant Design Icons | `ant-design` | MIT | Enterprise React products | Outlined, Filled, TwoTone |
+| Octicons | `octicon` | MIT | Developer tools, GitHub-like UI | 16px and 24px source sizes |
+| Feather Icons | `feather` | MIT | Minimal legacy outline style | Single outline style |
+| Iconoir | `iconoir` | MIT | Broad modern outline set | Single outline style |
+| Flowbite Icons | `flowbite` | MIT | Tailwind/Flowbite apps | Outline, Solid |
+| Ionicons | `ion` | MIT | Mobile/app UI | Outline, Filled, Sharp |
+| Simple Icons | `simple-icons` | CC0-1.0 | Brand logos only | Single-color brand marks |
+
+## Decision Criteria
+
+- Button icon clarity at 16px and 20px.
+- Menu, dropdown, and table icon legibility in dense rows.
+- Visual match with `default`, `rounded`, and `sharp` appearances.
+- Variant usefulness: filled states, two-tone states, sharp geometry, or rounded geometry.
+- Coverage for navigation, data, files, users, settings, alerts, billing, integrations, and brand logos.
+- Licensing and attribution obligations. Keep source license notices in the project when redistributing SVG/source files.
+
+## Sources
+
+- Google Material Icons repository: https://github.com/google/material-design-icons
+- Iconify collection API: https://iconify.design/docs/api/collection.html
+- Radix Icons: https://github.com/radix-ui/icons
+- Lucide: https://github.com/lucide-icons/lucide
+- Heroicons: https://heroicons.com
+- Tabler Icons: https://github.com/tabler/tabler-icons
+- Phosphor Icons: https://github.com/phosphor-icons/core
+- Remix Icon: https://www.remixicon.com
+- Bootstrap Icons: https://icons.getbootstrap.com
+- Fluent UI System Icons: https://github.com/microsoft/fluentui-system-icons
+- Carbon Icons: https://carbondesignsystem.com/elements/icons/code
+- Ant Design Icons: https://www.npmjs.com/package/@ant-design/icons
+- Octicons: https://primer.github.io/design/components/icon
+- Feather Icons: https://github.com/feathericons/feather
+- Iconoir: https://github.com/iconoir-icons/iconoir
+- Flowbite Icons: https://flowbite.com/icons
+- Ionicons: https://github.com/ionic-team/ionicons
+- Simple Icons: https://github.com/simple-icons/simple-icons

package/docs/design-system/installation.md

@@ -0,0 +1,68 @@
+# Installation
+
+## Requirements
+
+Banhaten installs source into a React 18.2/19 project using Tailwind CSS 4. Use Node 18.18 or newer.
+
+```bash
+npx banhaten init
+npx banhaten add button input select
+```
+
+Run the package-manager command printed by the CLI. It detects npm, pnpm, Yarn, and Bun from `packageManager` or lockfiles.
+
+Dependency declarations are validated with npm-compatible semantic-version
+ranges. A consumer range is kept only when every version it allows satisfies the
+Banhaten requirement. If the Banhaten range is wholly contained by a broader
+consumer range, the CLI safely narrows the declaration in its existing package
+section, updates `package.json`, and prints an install command so the package
+manager can reconcile its lockfile. Partial overlaps, disjoint ranges, mutable
+tags, workspace protocols, aliases, Git URLs, and local file specs fail without
+writing. Banhaten deliberately does not treat a current lockfile resolution as a
+durable compatibility guarantee. When the manifest is already safe, the CLI also
+checks package versions inside the target project or declared workspace boundary.
+For npm lockfiles v2 and v3 it verifies the importer declarations and exact locked
+resolutions; stale, missing, incompatible, or opaque lock state keeps the install
+action visible. Machine-readable output exposes the same
+`{ required, command, cwd }` state, including the project or workspace directory
+where the command must run.
+
+## Vite
+
+Before writing, the CLI resolves a canonical install plan from
+`banhaten.config.json`, the TypeScript `@/*` path, and the Vite `@` alias. If
+TypeScript and Vite agree, that root is used even when another `src` directory
+exists. If only one side declares the alias, the CLI mirrors it to the other.
+Conflicting roots, multi-target TypeScript paths, destination-overlapping aliases,
+inherited TypeScript aliases without local `baseUrl`/`paths`, and Vite aliases
+that cannot be inspected statically fail without changing the project. When a
+supported Vite config exists, `init` also adds the Tailwind Vite plugin while
+preserving its existing structure.
+
+CLI commands use strict schemas. Unknown or duplicate flags, missing values, and
+unexpected positional arguments are rejected before project discovery. The
+install receipt pins the resolved destinations; changing roots later requires
+moving or removing the old generated files and receipt first.
+
+## Next.js and other frameworks
+
+Without Vite, the CLI installs Tailwind and writes the configured global stylesheet, aliases, `cn` utility, and direction hook. Import the generated global stylesheet from the framework root layout and ensure the `@/*` TypeScript alias resolves to the source directory.
+
+## Fonts and direction
+
+The generated stylesheet imports Inter weights 400–700 and IBM Plex Sans Arabic weights 400–700. Set document language and direction at the application boundary:
+
+```tsx
+<html lang="ar" dir="rtl" data-theme="blue" data-radius="default">
+```
+
+Wrap server-rendered component trees in `DirectionProvider` when request data already determines the direction; this keeps the first server and client snapshots identical. It is also the boundary for nested surfaces that differ from the document. Without it, components hydrate from a stable LTR snapshot and then synchronize from the document through one shared observer.
+
+## Updating safely
+
+```bash
+npx banhaten diff
+npx banhaten update
+```
+
+The receipt records generated hashes. Unmodified files update automatically. Locally modified files and token blocks stop without writing; pass `--force` only after reviewing the unified diff. Put product overrides outside the marked token block and product composition in wrapper components.

package/docs/design-system/launch-comparison-shadcn.md

@@ -0,0 +1,98 @@
+# Launch Comparison: Banhaten and shadcn/ui
+
+Reviewed against the official shadcn/ui CLI, registry, theming, and RTL documentation on 2026-07-10. shadcn/ui is the distribution and documentation benchmark—not Banhaten’s visual source.
+
+## Outcome
+
+Banhaten is a launch candidate with a distinct product contract: Arabic and English-first typography, inherited RTL by default, seven brand themes, three radius modes, stable primitives separated from larger Patterns, and a hard rule that distributable components consume canonical Banhaten tokens.
+
+The only intentionally unresolved visual exception is color contrast. The reviewed default-theme correction composes blue brand roles with the gray neutral ramp; the remaining source color pairs are documented rather than changed automatically. The Color Contrast page evaluates 742 theme/mode scenarios, reports 274 failures and 468 passes, and records the pair, score, threshold, state, swatches, recommendation, and best existing foreground candidate.
+
+## Benchmark Summary
+
+| Area | shadcn/ui benchmark | Banhaten launch answer | Status |
+| --- | --- | --- | --- |
+| Distribution | Source registry and CLI installation | Canonical Banhaten registry plus generated shadcn-compatible `registry.json` | Verified |
+| Component ownership | Copied source is consumer-owned | Receipt-backed generated ownership; local drift blocks updates unless explicitly forced | Stronger safety |
+| Registry dependencies | Dependency closure and typed registry items | Dependency graph, schema validation, mirror checks, and isolated compilation of all 67 items | Verified |
+| CLI | `init`, `add`, `view`, `docs`, migrations, presets | `init`, `add`, real `diff`, safe `update`, `list`, `search`, full `docs`, and `view` | Launch scope verified |
+| Framework setup | Multiple framework templates | Vite auto-configuration and framework-neutral/Next-style source installation | Verified |
+| Package managers | npm, pnpm, Yarn, Bun | Detection and install hints tested for all four | Verified |
+| Theming | CSS variables, dark mode, presets | Live semantic aliases, light/dark, seven brand themes, three radius modes | Verified |
+| Token contract | Optional CSS-variable path | CSS variables are mandatory; raw component colors, sizes, opacity, duration, z-index, shadow, and generic internal aliases fail CI | Banhaten-specific |
+| RTL | First-class RTL and install-time transformations | Authored logical layout, inherited direction hook/provider, Arabic font, explicit message catalogs, and RTL keyboard tests | Banhaten-specific |
+| Documentation | Live preview/code, component examples, API and CLI docs | Live registry previews, exact example source, extracted TypeScript props, token contract, accessibility contract, RTL, files, navigation/token search, and copy actions | Verified |
+| Components vs blocks | Components and larger blocks | Stable Components and broader Patterns; experiments and visual QA isolated under Lab | Verified |
+| Accessibility | Primitive semantics and per-component guidance | Native/Radix semantics, focus handling, dialog traps, tabs contract, reduced motion, forced colors, axe, Chromium/Firefox/WebKit tests | Verified except documented colors |
+| Release governance | Changelog and frequent CLI/schema evolution | Changelog, security, contributing, support matrix, stability tiers, deprecation, release gate, and roadmap | Verified |
+
+## Full Finding Register
+
+### Components and behavior
+
+- Removed sample titles, images, actions, close controls, dates, time rows, and no-op callbacks from production defaults. Examples now own demonstration content.
+- Added Item and controlled/uncontrolled Toggle Group APIs, including single/multiple selection and RTL-aware keyboard movement.
+- Repaired Command Bar search/clear/submit behavior, Table disabled/action behavior, File Upload progress semantics, Spinner reduced-motion behavior, and Date Picker presets/month-year interaction.
+- Standardized direction resolution for Alert, Pagination, Input OTP, Carousel, and Toast through explicit props, `DirectionProvider`, nearest `[dir]`, then document direction.
+- Corrected Arabic Pagination copy and kept product strings explicit rather than silently localizing demo text.
+- Added focused behavior tests; the component suite currently runs 171 tests.
+
+### Colors and tokens
+
+- Preserved every requested source color value and moved all failing combinations into the generated Color Contrast report.
+- Split system, typography, effects, component variables, dark effects, and
+  scoped aliases into owned `tokens/source/` fragments that compile to
+  `tokens/banhaten.tokens.json`.
+- Generated live `var(...)` alias graphs rather than flattened semantic values and verified custom-property closure.
+- Added named categorical chart semantics, spinner/skeleton/motion tokens, exact icon stroke tokens, Item tokens, default border/transition wiring, reduced motion, and forced-color focus rules.
+- Generated exact component token metadata from source. All 67 registry components have non-empty token contracts.
+- Deduplicated theme CSS against the default cascade without changing values, reducing generated CSS from 466,671 bytes to 154,130 bytes.
+- Documented the no-global-density decision and the semantic elevation hierarchy.
+
+### Usage and composition
+
+- Added installation, direction/localization, form recipes, density/elevation, support, roadmap, and release-policy guides.
+- Separated stable Components from broader Patterns and isolated Component Matrix, Theme Test, Theme Lab, and screenshot review under Lab/Visual QA.
+- Added explicit TypeScript prop source, token contract, accessibility contract, composition notes, RTL behavior, and registry file links to shared component documentation.
+- Added searchable/copyable token pages with computed values and `var(--token)` usage syntax.
+
+### Installation and registry
+
+- Added Inter and IBM Plex Sans Arabic weights 400–700 automatically and composed them through font-family tokens.
+- Removed dead `style` and `tsx` config fields; config now contains only settings the CLI honors.
+- Added real unified diff output and SHA-256 ownership receipts for base files, components, and the generated token block.
+- Prevented `add` and `update` from overwriting local edits without `--force`; transactions roll back on failure.
+- Kept CSS outside the marked Banhaten token block intact and protected edits inside the generated block.
+- Tested Vite, non-Vite/Next-style projects, dependency conflicts, JSONC aliases, unsupported Vite config rollback, npm, pnpm, Yarn, and Bun.
+- Generated a current shadcn-compatible registry and compiled every registry component in isolation.
+- Removed design-source ZIP archives from the published package while keeping the canonical JSON contract and required registry assets.
+
+### Documentation and presentation
+
+- Removed launch-blocking `noindex`, added description/social metadata, dynamic page titles, skip link, release status/version, and responsive searchable navigation.
+- Reframed the overview around quick start, token rules, safe updates, and the documented contrast exception.
+- Added focus trap, Escape, initial focus, and focus return to Customize and Component Matrix dialogs.
+- Completed Preview/Code tab IDs, `aria-controls`, `aria-labelledby`, roving focus, and keyboard navigation.
+- Renamed ambiguous “Copy Page” to “Copy page link” and added clipboard fallback.
+- Changed the CLI `docs` command from a path hint to the complete packaged component documentation plus metadata.
+
+### Verification and release
+
+- Browser checks cover Chromium, Firefox, and WebKit; visual baselines stay on Chromium for deterministic snapshots.
+- Automated checks cover LTR/RTL behavior, portals, focus return, docs navigation, mobile navigation, token copy/search, live theme overrides, the frozen contrast totals, reduced motion, forced colors, and serious/critical axe findings outside the intentionally documented color rule.
+- Bundle budgets, schema validation, token generation, token-only styling, registry mirrors, documentation coverage, CLI integration, isolated installs, package audit, and tarball contents are release gates.
+
+## Deliberate Differences, Not Missing Copies
+
+Banhaten does not copy shadcn’s preset marketplace, `create` templates, registry namespaces, programmatic registry API, or migration catalog for launch. Those are distribution-platform capabilities, not component-quality requirements. They belong on the roadmap only when Banhaten has a concrete consumer need and maintenance owner.
+
+Banhaten also does not support opting out of CSS variables: the canonical token graph is the mechanism that keeps themes, Arabic typography, accessibility modes, and every component aligned. That constraint is intentional and is the core of Banhaten’s visual independence.
+
+## Reference Benchmark
+
+- [shadcn/ui CLI](https://ui.shadcn.com/docs/cli)
+- [shadcn/ui registry schema](https://ui.shadcn.com/docs/registry/registry-json)
+- [shadcn/ui registry API](https://ui.shadcn.com/docs/registry/api-reference)
+- [shadcn/ui theming](https://ui.shadcn.com/docs/theming)
+- [shadcn/ui RTL](https://ui.shadcn.com/docs/rtl)
+- [shadcn/ui changelog](https://ui.shadcn.com/docs/changelog)

package/docs/design-system/registry-and-cli.md

@@ -0,0 +1,64 @@
+# Registry And CLI
+
+Banhaten maintains one authored registry catalog and publishes two compiled
+registry shapes.
+
+| Artifact | Purpose |
+| --- | --- |
+| `registry/catalog/` | Authored base and component-owned contracts plus the intentional publication order. |
+| `registry/index.json` | Compiled artifact consumed by the Banhaten CLI. Includes exhaustive module-aware runtime exports, non-exhaustive composition parts, files, examples, dependencies, RTL behavior, and design-system capabilities. |
+| `registry.json` | Generated shadcn-compatible export for tools that expect `https://ui.shadcn.com/schema/registry.json`. |
+
+Edit `registry/catalog/components/<id>.json` for a component or
+`registry/catalog/base.json` for shared installation metadata, then run
+`npm run registry:export` to compile `registry/index.json` and `registry.json`.
+
+`npm run package:check` verifies the actual npm tarball rather than the
+worktree: it extracts the archive, derives every required registry source and
+example from the packed index, checks byte-for-byte closure, then runs the
+packed CLI and installs the full component catalog into a clean project.
+
+Each component groups its exhaustive runtime value API under
+`supportedExports`, keyed by the exact registry source module that owns the
+installed import path. The release gate resolves those modules with TypeScript
+and rejects missing, stale, moved, type-only, or newly unlisted runtime values.
+Run `npm run registry:exports` only after reviewing an intentional runtime API
+change. The separate `parts` list is ordered component anatomy for examples and
+composition; it is deliberately non-exhaustive and every part must resolve to a
+supported runtime export.
+
+## Generated Files
+
+Installed files are generated source with receipt-backed ownership hashes. `banhaten add` and `banhaten update` replace a stale file automatically only when its current hash still matches the version Banhaten installed. A locally modified file stops the transaction and remains untouched unless the caller reviews `banhaten diff` and explicitly passes `--force`.
+
+The token stylesheet is generated-owned too. `init`, `add`, and `update` refresh the marked Banhaten token block while preserving CSS outside the block. Local edits inside the marked block receive the same drift protection; place product overrides after the block.
+
+## CLI Commands
+
+```bash
+npx banhaten init
+npx banhaten add button input select
+npx banhaten diff
+npx banhaten update button --force
+npx banhaten list --json
+npx banhaten search input
+npx banhaten docs button
+npx banhaten view button
+npx banhaten doctor
+```
+
+`doctor` is read-only. It reports installed-version drift, missing or modified
+managed files, missing agent guidance, deprecated ambiguous props, local raw
+control geometry, and native date/select controls that bypass the registry.
+
+The CLI resolves one unambiguous package-manager root before printing dependency install hints. Dependency requirements use `semver` containment rather than range overlap: already-narrow consumer ranges are preserved, broader ranges are narrowed only when the complete Banhaten range fits inside them, and partial/disjoint or non-semver declarations stop atomically. A narrowed manifest always produces an install hint; an unchanged manifest suppresses that action only when bounded installed packages and a supported npm lock agree. Other lock formats remain conservative and are reconciled by their selected package manager.
+
+## Schema Files
+
+Schema files live in `schema/`. The CLI copies them into `.banhaten/schema/` so generated `banhaten.config.json` can use a local `$schema` path instead of a fragile external domain:
+
+- `schema/config.schema.json`
+- `schema/registry.schema.json`
+- `schema/tokens.schema.json`
+
+Do not point package metadata or generated config at `banhaten.dev` unless that domain is live and serving the schema files.

package/docs/design-system/release-policy.md

@@ -0,0 +1,30 @@
+# Release Policy
+
+## Stability tiers
+
+| Tier | Promise | Documentation location |
+| --- | --- | --- |
+| Stable component | Supported public API, token contract, accessibility behavior, and migration notes | Components |
+| Pattern | Supported composition with a broader layout and product-integration contract | Patterns |
+| Lab | Evaluation or visual-QA surface; not a supported consumer API | Lab / Visual QA lab |
+
+## Versioning
+
+Banhaten uses semantic versioning. Before 1.0, a minor release may contain a breaking API change, but every breaking change still requires a changelog entry and migration instructions. Patch releases must remain backward compatible.
+
+Deprecations remain documented for at least one minor release before removal. Deprecated exports keep working during that window and include a replacement path.
+
+## Release gate
+
+A release candidate must pass:
+
+1. Canonical schema and token generation checks.
+2. The component token checker with no raw-value or unresolved-variable violations.
+3. CLI integration tests and isolated compilation for every registry component.
+4. LTR and RTL interaction tests, accessibility checks, production build, and bundle budgets.
+5. Documentation coverage for install, usage, examples, API, tokens, direction, accessibility, and migration impact.
+6. Color Contrast report regeneration. Contrast failures are documented; color values change only through an explicit design decision.
+
+## Ownership
+
+Every release has one maintainer responsible for the registry artifact, one design reviewer for token and visual changes, and one accessibility reviewer for interaction or semantic changes. A release is not complete until the changelog and package contents are verified from a packed tarball.

package/docs/design-system/roadmap.md

@@ -0,0 +1,14 @@
+# Roadmap
+
+The roadmap separates launch requirements from product-specific expansion. Items below are not stable APIs until they move into Components or Patterns with registry source, tokens, docs, and tests.
+
+| Candidate | Current direction | Gate before promotion |
+| --- | --- | --- |
+| Drawer naming/API | Evaluate whether Sheet and Slideout already cover the use cases | Distinct semantics and migration value |
+| Attachment/file item | Compose Item, File Upload, Progress, and actions first | Repeated product demand and a stable data model |
+| Hijri calendar | Keep calendar formatting in the product layer for launch | Calendar-system adapter, locale rules, keyboard QA, and date-library decision |
+| Compact density mode | Use supported component sizes | Named token mode, target-size guardrails, and full matrix QA |
+| Additional Arabic fonts | IBM Plex Sans Arabic is the installed default | Licensing, loading cost, fallback metrics, and typography review |
+| Framework adapters | Source installation remains framework-neutral | Maintained SSR/CSP tests and clear ownership |
+
+Feature requests should describe the user problem, why existing primitives do not compose cleanly, accessibility requirements, direction/localization impact, and the proposed token contract.

package/docs/design-system/support-matrix.md

@@ -0,0 +1,23 @@
+# Support Matrix
+
+| Area | Launch baseline |
+| --- | --- |
+| React | 18.2.x and 19.x; packed registry sources compile against both compatibility floors in CI |
+| React DOM | 18.2.x and 19.x; kept on the same major as React |
+| Tailwind CSS | 4.x |
+| Node | Published CLI and registry: 18.18 or newer, with packed-artifact CI on 18.18.0, 20, and 22; the private playground build toolchain runs on Node 22 |
+| TypeScript | Bundler-style module resolution; copied source is TypeScript/TSX |
+| Browsers | Current stable Chrome/Edge, Firefox, and Safari; previous major versions are best-effort until they are included in automated release testing |
+| Direction | Inherited LTR and RTL; explicit component overrides where documented |
+| Fonts | Inter for Latin and IBM Plex Sans Arabic for Arabic, installed by the CLI |
+| Package managers | npm, pnpm, Yarn, and Bun install hints |
+| Tooling | Vite configured automatically when detected; framework-neutral source installation otherwise |
+
+Internet Explorer and browsers without modern CSS custom properties, logical properties, or ES2022 support are not supported. Consumer applications remain responsible for their framework’s SSR, CSP, and browser-transpilation configuration.
+
+Release verification builds and extracts the real npm tarball, derives its
+required registry file and example closure from the packed index, executes the
+packed CLI from outside the repository, and installs every registry component
+into a clean fixture. React compatibility jobs then compile that packed source
+against exact React 18.2 and React 19 floors instead of relying only on the
+playground lockfile.

package/docs/design-system/tabs.md

@@ -0,0 +1,53 @@
+# Tabs
+
+Tabs switch between peer views while keeping the user in the same context.
+
+The implementation follows the Figma component at `Design system 3.0 Copy / Tabs` (`225:9832`). It supports every variant in the matrix: `underline`, `segment`, and `rounded`; `md`, `sm`, and `xs`; full-width and hug-content layouts; LTR and RTL.
+
+## API
+
+```tsx
+<Tabs
+  variant="underline"
+  size="md"
+  fullWidth={false}
+  dir="ltr"
+  items={["Tab item", "Tab item", "Tab item", "Tab item", "Tab item"]}
+/>
+```
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `variant` | `underline`, `segment`, `rounded` | `underline` |
+| `size` | `md`, `sm`, `xs` | `md` |
+| `fullWidth` | `boolean` | `false` |
+| `dir` | `ltr`, `rtl` | `ltr` |
+| `items` | `string[]` | five `Tab item` labels |
+| `activeIndex` | `number` | uncontrolled |
+| `defaultActiveIndex` | `number` | `0` |
+| `onActiveIndexChange` | `(index: number) => void` | none |
+
+## Token Contract
+
+The component consumes Banhaten semantic tokens and component aliases. Do not hard-code Figma fallback literals in component source; promote any Figma value into its owned `tokens/source/` fragment as a `--bh-*` token or alias first.
+
+- Backgrounds: `--bh-bg-neutral-subtle`, `--bh-bg-default`
+- Borders: `--bh-border-default`
+- Content: `--bh-content-brand-default`, `--bh-content-default`, `--bh-content-subtle`
+- Shape: `--bh-radius-md-6`, `--bh-radius-lg-8`, `--bh-radius-full`
+
+## Pixel Rules
+
+- Text is Inter `15px / 24px`.
+- Active labels use weight `500`; inactive labels use weight `400`.
+- Segment and rounded containers use `2px` padding and `2px` item gaps.
+- Underline containers use a `1px` default bottom border and `16px` item gaps.
+- Active underline tabs use a `2px` `#245ded` bottom border.
+- Segment selected tabs use a pill radius; rounded selected tabs use `6px`.
+- Selected segment and rounded tabs use white fill plus `0 1px 1px rgba(15, 17, 20, 0.06)`.
+- `md` segment and rounded tabs are `40px` tall inside a `44px` container.
+- `sm` segment and rounded tabs are `36px` tall inside a `40px` container.
+- `xs` segment and rounded tabs are `32px` tall inside a `36px` container.
+- `md` underline rows are `56px`; `sm` and `xs` underline rows are `48px`.
+- Full-width tabs stretch equally inside their parent width.
+- RTL uses `dir="rtl"` on the tablist so the active first item appears on the right edge.