@usetheo/ui 0.6.2-next.0 → 0.7.0-next.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usetheo/ui",
-  "version": "0.6.2-next.0",
+  "version": "0.7.0-next.0",
   "description": "Theo UI — framework-agnostic React component library with the Violet Forge design system. Focused on AI-agent interfaces, cloud dashboards, and developer-tooling surfaces.",
   "license": "Apache-2.0",
   "type": "module",
@@ -21,6 +21,10 @@
     "./fonts-cdn.css": "./dist/fonts-cdn.css",
     "./slide/themes/default.css": "./dist/slide/themes/default.css",
     "./slide/themes/violet-forge.css": "./dist/slide/themes/violet-forge.css",
+    "./account-menu": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
     "./agent-composer": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
@@ -253,6 +257,10 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./plan-badge": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
     "./preview-env-card": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
@@ -261,6 +269,10 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./progress": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
     "./progress-checklist": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
@@ -417,6 +429,10 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./usage-meter": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
     "./whiteboard": {
       "types": "./dist/whiteboard/index.d.ts",
       "import": "./dist/whiteboard/index.js"

package/registry/index.json

@@ -12,6 +12,12 @@
     }
   },
   "items": [
+    {
+      "name": "account-menu",
+      "type": "registry:ui",
+      "title": "AccountMenu",
+      "description": "Sidebar header for PaaS surfaces. Avatar + name + (optional) PlanBadge + (optional) secondary line, with dual mode: with onClick renders as a <button> with trailing chevron (account picker affordance); without, renders as a static <div>. PaaS-shape sibling of ProjectSwitcher."
+    },
     {
       "name": "agent-composer",
       "type": "registry:ui",
@@ -396,6 +402,12 @@
       "title": "Theo UI permission types",
       "description": "Shared TypeScript types for permission requests, scopes, and decisions."
     },
+    {
+      "name": "plan-badge",
+      "type": "registry:ui",
+      "title": "PlanBadge",
+      "description": "Semantic pricing-tier badge. Five canonical tiers (free, hobby, pro, team, enterprise) with distinct color tokens. Consumers self-document intent (plan=\"hobby\") instead of mapping generic Badge variants per app — future rebrand / dark-mode tweaks propagate automatically."
+    },
     {
       "name": "preview-env-card",
       "type": "registry:block",
@@ -414,6 +426,12 @@
       "title": "ProgressChecklist",
       "description": "Right-inspector checklist tracking subtask completion with success / running / pending tones."
     },
+    {
+      "name": "progress",
+      "type": "registry:ui",
+      "title": "Progress",
+      "description": "Accessible progress bar primitive with intent variants (default, success, warning, destructive), 4 heights (h-1 / h-1.5 / h-2 / h-3), and an indeterminate animated state. Built on role=\"progressbar\" + ARIA semantics."
+    },
     {
       "name": "project-card",
       "type": "registry:block",
@@ -732,6 +750,12 @@
       "title": "Theo UI shared types",
       "description": "Shared TypeScript helper types (IconComponent, etc.) used across Theo UI."
     },
+    {
+      "name": "usage-meter",
+      "type": "registry:ui",
+      "title": "UsageMeter",
+      "description": "Multi-metric stacked usage card for PaaS dashboards. Renders N metrics (data transfer, requests, build minutes, seats, …) each with label + value/max + Progress bar. Supports custom per-metric formatter, over-quota warning, and a compact bars-only mode. PaaS-shape sibling of CostMeter."
+    },
     {
       "name": "whiteboard",
       "type": "registry:ui",

package/registry/r/account-menu.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
+  "name": "account-menu",
+  "type": "registry:ui",
+  "title": "AccountMenu",
+  "description": "Sidebar header for PaaS surfaces. Avatar + name + (optional) PlanBadge + (optional) secondary line, with dual mode: with onClick renders as a <button> with trailing chevron (account picker affordance); without, renders as a static <div>. PaaS-shape sibling of ProjectSwitcher.",
+  "dependencies": [
+    "lucide-react"
+  ],
+  "registryDependencies": [
+    "https://usetheodev.github.io/theo-ui/r/cn.json",
+    "https://usetheodev.github.io/theo-ui/r/avatar.json",
+    "https://usetheodev.github.io/theo-ui/r/plan-badge.json",
+    "https://usetheodev.github.io/theo-ui/r/tailwind-preset.json"
+  ],
+  "files": [
+    {
+      "path": "components/composites/account-menu/account-menu.tsx",
+      "type": "registry:ui",
+      "target": "components/ui/account-menu.tsx",
+      "content": "import { ChevronsUpDown } from \"lucide-react\";\nimport { forwardRef } from \"react\";\nimport type { ButtonHTMLAttributes, HTMLAttributes, ReactNode } from \"react\";\nimport { cn } from \"@/lib/cn\";\nimport { Avatar } from \"@/components/ui/avatar\";\nimport { PlanBadge, type PlanTier } from \"@/components/ui/plan-badge\";\n\n/**\n * AccountMenu — sidebar header for PaaS surfaces.\n *\n * Renders avatar + name + (optional) plan badge + (optional) secondary line.\n * Dual mode: with `onClick`, renders as a `<button>` with a `ChevronsUpDown`\n * trailing icon (account picker affordance); without, renders as a static\n * `<div>` (read-only display, not focusable).\n *\n * Composition:\n *\n *   <Sidebar.Header className=\"p-0\">\n *     <AccountMenu\n *       name=\"paulohenriquevn\"\n *       avatar=\"https://avatars.githubusercontent.com/u/12345\"\n *       plan=\"hobby\"\n *       onClick={openAccountSwitcher}\n *     />\n *   </Sidebar.Header>\n *\n * Avatar handling:\n *   - URL (`http(s)://` or `/`) → `<Avatar.Image>` with `<Avatar.Fallback>` initials\n *   - Short string (≤2 chars) → treated as initials directly\n *   - Undefined → initials derived from the first character of `name`\n *\n * PaaS-shape sibling of `<ProjectSwitcher>` (workspace + branch + agent-status).\n * Same dual-mode (interactive vs static) pattern; different semantics.\n */\n\nexport interface AccountMenuProps\n  extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, \"type\" | \"children\" | \"name\"> {\n  /** Display name (username, email, org name). */\n  name: ReactNode;\n  /** Avatar URL or 1-2-char initials. If undefined, derives initials from `name`. */\n  avatar?: string;\n  /** Plan tier — renders inline `<PlanBadge size=\"sm\">`. Omit for none. */\n  plan?: PlanTier;\n  /** Optional secondary line below name (e.g. email). */\n  secondary?: ReactNode;\n  /** Make the row interactive (button) with a trailing chevron. */\n  onClick?: () => void;\n}\n\nconst URL_RE = /^(?:https?:\\/\\/|\\/)/;\n\nfunction deriveInitials(name: ReactNode, avatar: string | undefined): string {\n  if (avatar && !URL_RE.test(avatar) && avatar.length <= 2) {\n    return avatar.toUpperCase();\n  }\n  if (typeof name === \"string\" && name.length > 0) {\n    return name.charAt(0).toUpperCase();\n  }\n  return \"?\";\n}\n\nconst AccountMenu = forwardRef<HTMLElement, AccountMenuProps>(\n  ({ className, name, avatar, plan, secondary, onClick, ...props }, ref) => {\n    const interactive = typeof onClick === \"function\";\n    const initials = deriveInitials(name, avatar);\n    const isUrlAvatar = avatar !== undefined && URL_RE.test(avatar);\n    const altText = typeof name === \"string\" ? name : \"account\";\n\n    const content = (\n      <>\n        <Avatar size=\"sm\">\n          {isUrlAvatar ? <Avatar.Image src={avatar} alt={altText} /> : null}\n          <Avatar.Fallback delayMs={0}>{initials}</Avatar.Fallback>\n        </Avatar>\n\n        <div className=\"flex min-w-0 flex-1 flex-col\">\n          <div className=\"flex min-w-0 items-center gap-2\">\n            <span className=\"truncate font-medium text-body-sm text-foreground\">{name}</span>\n            {plan ? <PlanBadge plan={plan} size=\"sm\" /> : null}\n          </div>\n          {secondary ? (\n            <span className=\"truncate text-label text-muted-foreground\">{secondary}</span>\n          ) : null}\n        </div>\n\n        {interactive ? (\n          <ChevronsUpDown className=\"size-3 shrink-0 text-muted-foreground\" aria-hidden=\"true\" />\n        ) : null}\n      </>\n    );\n\n    const baseClass = cn(\n      \"flex w-full items-center gap-3 px-3 py-2\",\n      interactive &&\n        cn(\n          \"rounded-md text-left transition-colors\",\n          \"hover:bg-muted/40\",\n          \"focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-card\",\n        ),\n      className,\n    );\n\n    if (interactive) {\n      const { ...buttonProps } = props as ButtonHTMLAttributes<HTMLButtonElement>;\n      return (\n        <button\n          ref={ref as React.Ref<HTMLButtonElement>}\n          type=\"button\"\n          className={baseClass}\n          onClick={onClick}\n          {...buttonProps}\n        >\n          {content}\n        </button>\n      );\n    }\n\n    return (\n      <div\n        ref={ref as React.Ref<HTMLDivElement>}\n        className={baseClass}\n        {...(props as HTMLAttributes<HTMLDivElement>)}\n      >\n        {content}\n      </div>\n    );\n  },\n);\nAccountMenu.displayName = \"AccountMenu\";\n\nexport { AccountMenu };\n"
+    }
+  ]
+}

package/registry/r/button.json

@@ -17,7 +17,7 @@
       "path": "components/primitives/button/button.tsx",
       "type": "registry:ui",
       "target": "components/ui/button.tsx",
-      "content": "import { Slot } from \"@radix-ui/react-slot\";\nimport { type VariantProps, cva } from \"class-variance-authority\";\nimport { forwardRef } from \"react\";\nimport type { ButtonHTMLAttributes } from \"react\";\nimport { cn } from \"@/lib/cn\";\n\n/**\n * Button — primitive action element in the Violet Forge design system.\n *\n * Variants:\n *   - primary    Theo violet fill, glow on hover (signature)\n *   - secondary  surface with hairline border\n *   - accent     burnt-sienna fill, celebratory actions\n *   - ghost      transparent, hover lifts surface\n *   - link       text-only, primary color, underline on hover\n *   - destructive  for irreversible actions\n *\n * Sizes: sm (32px) · md (40px, default) · lg (48px) · icon (square 40px)\n *\n * `asChild` swaps the root for the consumer's element (Radix Slot pattern).\n */\nconst buttonVariants = cva(\n  [\n    \"inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-lg\",\n    // NIT-004: `font-medium` (500) aligns with the design-system.md UI weight.\n    // Previously `font-bold` (700) exceeded the normative 400/500/600 weight\n    // range declared for Geist Sans in the Violet Forge identity.\n    \"font-medium font-sans tracking-tight\",\n    \"transition-[box-shadow,background-color,color,transform] duration-base ease-out-soft\",\n    \"focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background\",\n    \"disabled:pointer-events-none disabled:opacity-50\",\n    \"[&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0\",\n  ],\n  {\n    variants: {\n      variant: {\n        primary: [\n          \"bg-primary text-primary-foreground\",\n          \"hover:bg-primary hover:shadow-glow\",\n          \"active:scale-[0.98] active:bg-primary-deep active:shadow-none\",\n        ],\n        secondary: [\n          \"border border-border bg-secondary text-secondary-foreground\",\n          \"hover:bg-muted\",\n          \"active:scale-[0.98]\",\n        ],\n        accent: [\"bg-accent text-accent-foreground\", \"hover:bg-accent-deep\", \"active:scale-[0.98]\"],\n        ghost: [\n          \"bg-transparent text-foreground\",\n          \"hover:bg-muted\",\n          \"active:scale-[0.98] active:bg-secondary\",\n        ],\n        link: [\n          \"bg-transparent text-primary underline-offset-4\",\n          \"hover:text-primary-deep hover:underline\",\n          \"h-auto p-0\",\n        ],\n        destructive: [\n          \"bg-destructive text-destructive-foreground\",\n          \"hover:bg-destructive/90\",\n          \"active:scale-[0.98]\",\n        ],\n      },\n      size: {\n        sm: \"h-8 px-3 text-body-sm\",\n        // md: tier ajustável via density (CSS var on :root). See D3 ADR of\n        // faang-density-tightening plan. Default `comfortable` density makes\n        // this 36px (--theo-control-h: 2.25rem). sm and lg stay hardcoded.\n        md: \"h-[var(--theo-control-h,2.25rem)] px-[var(--theo-control-px,0.875rem)] text-body-sm\",\n        lg: \"h-11 px-4 text-body-md\",\n        icon: \"h-[var(--theo-control-h,2.25rem)] w-[var(--theo-control-h,2.25rem)] p-0\",\n      },\n    },\n    defaultVariants: {\n      variant: \"primary\",\n      size: \"md\",\n    },\n  },\n);\n\nexport interface ButtonProps\n  extends ButtonHTMLAttributes<HTMLButtonElement>,\n    VariantProps<typeof buttonVariants> {\n  asChild?: boolean;\n}\n\nconst Button = forwardRef<HTMLButtonElement, ButtonProps>(\n  ({ className, variant, size, asChild = false, type, ...props }, ref) => {\n    const Comp = asChild ? Slot : \"button\";\n    return (\n      <Comp\n        ref={ref}\n        type={asChild ? undefined : (type ?? \"button\")}\n        className={cn(buttonVariants({ variant, size }), className)}\n        {...props}\n      />\n    );\n  },\n);\nButton.displayName = \"Button\";\n\nexport { Button, buttonVariants };\n"
+      "content": "import { Slot } from \"@radix-ui/react-slot\";\nimport { type VariantProps, cva } from \"class-variance-authority\";\nimport { forwardRef } from \"react\";\nimport type { ButtonHTMLAttributes } from \"react\";\nimport { cn } from \"@/lib/cn\";\n\n/**\n * Button — primitive action element in the Violet Forge design system.\n *\n * Variants:\n *   - primary    Theo violet fill, glow on hover (signature)\n *   - secondary  surface with hairline border\n *   - accent     burnt-sienna fill, celebratory actions\n *   - ghost      transparent, hover lifts surface\n *   - link       text-only, primary color, underline on hover\n *   - destructive  for irreversible actions\n *\n * Sizes: sm (32px) · md (40px, default) · lg (48px) · icon (square 40px)\n *\n * `asChild` swaps the root for the consumer's element (Radix Slot pattern).\n */\nconst buttonVariants = cva(\n  [\n    \"inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-lg\",\n    // NIT-004: `font-medium` (500) aligns with the design-system.md UI weight.\n    // Previously `font-bold` (700) exceeded the normative 400/500/600 weight\n    // range declared for Geist Sans in the Violet Forge identity.\n    \"font-medium font-sans tracking-tight\",\n    \"transition-[box-shadow,background-color,color,transform] duration-base ease-out-soft\",\n    \"focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background\",\n    // Tailwind v4 dropped the `button { cursor: pointer }` preflight rule\n    // (https://tailwindcss.com/docs/upgrade-guide#default-button-cursor) so\n    // every <button> now shows the default arrow cursor. Restore the\n    // \"clickable hand\" explicitly for the Button primitive; the\n    // `disabled:pointer-events-none` rule below short-circuits cursor\n    // application for disabled state (no events → cursor is moot).\n    // `aria-disabled:cursor-default` is a belt-and-suspenders override\n    // for paths where pointer-events still flow.\n    \"cursor-pointer disabled:cursor-default aria-disabled:cursor-default\",\n    \"disabled:pointer-events-none disabled:opacity-50\",\n    \"[&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0\",\n  ],\n  {\n    variants: {\n      variant: {\n        primary: [\n          \"bg-primary text-primary-foreground\",\n          \"hover:bg-primary hover:shadow-glow\",\n          \"active:scale-[0.98] active:bg-primary-deep active:shadow-none\",\n        ],\n        secondary: [\n          \"border border-border bg-secondary text-secondary-foreground\",\n          \"hover:bg-muted\",\n          \"active:scale-[0.98]\",\n        ],\n        accent: [\"bg-accent text-accent-foreground\", \"hover:bg-accent-deep\", \"active:scale-[0.98]\"],\n        ghost: [\n          \"bg-transparent text-foreground\",\n          \"hover:bg-muted\",\n          \"active:scale-[0.98] active:bg-secondary\",\n        ],\n        link: [\n          \"bg-transparent text-primary underline-offset-4\",\n          \"hover:text-primary-deep hover:underline\",\n          \"h-auto p-0\",\n        ],\n        destructive: [\n          \"bg-destructive text-destructive-foreground\",\n          \"hover:bg-destructive/90\",\n          \"active:scale-[0.98]\",\n        ],\n      },\n      size: {\n        sm: \"h-8 px-3 text-body-sm\",\n        // md: tier ajustável via density (CSS var on :root). See D3 ADR of\n        // faang-density-tightening plan. Default `comfortable` density makes\n        // this 36px (--theo-control-h: 2.25rem). sm and lg stay hardcoded.\n        md: \"h-[var(--theo-control-h,2.25rem)] px-[var(--theo-control-px,0.875rem)] text-body-sm\",\n        lg: \"h-11 px-4 text-body-md\",\n        icon: \"h-[var(--theo-control-h,2.25rem)] w-[var(--theo-control-h,2.25rem)] p-0\",\n      },\n    },\n    defaultVariants: {\n      variant: \"primary\",\n      size: \"md\",\n    },\n  },\n);\n\nexport interface ButtonProps\n  extends ButtonHTMLAttributes<HTMLButtonElement>,\n    VariantProps<typeof buttonVariants> {\n  asChild?: boolean;\n}\n\nconst Button = forwardRef<HTMLButtonElement, ButtonProps>(\n  ({ className, variant, size, asChild = false, type, ...props }, ref) => {\n    const Comp = asChild ? Slot : \"button\";\n    return (\n      <Comp\n        ref={ref}\n        type={asChild ? undefined : (type ?? \"button\")}\n        className={cn(buttonVariants({ variant, size }), className)}\n        {...props}\n      />\n    );\n  },\n);\nButton.displayName = \"Button\";\n\nexport { Button, buttonVariants };\n"
     }
   ]
 }

package/registry/r/plan-badge.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
+  "name": "plan-badge",
+  "type": "registry:ui",
+  "title": "PlanBadge",
+  "description": "Semantic pricing-tier badge. Five canonical tiers (free, hobby, pro, team, enterprise) with distinct color tokens. Consumers self-document intent (plan=\"hobby\") instead of mapping generic Badge variants per app — future rebrand / dark-mode tweaks propagate automatically.",
+  "dependencies": [],
+  "registryDependencies": [
+    "https://usetheodev.github.io/theo-ui/r/cn.json",
+    "https://usetheodev.github.io/theo-ui/r/tailwind-preset.json"
+  ],
+  "files": [
+    {
+      "path": "components/primitives/plan-badge/plan-badge.tsx",
+      "type": "registry:ui",
+      "target": "components/ui/plan-badge.tsx",
+      "content": "import { forwardRef } from \"react\";\nimport type { HTMLAttributes } from \"react\";\nimport { cn } from \"@/lib/cn\";\n\n/**\n * PlanBadge — semantic pricing-tier badge.\n *\n * Five canonical tiers (`free` / `hobby` / `pro` / `team` / `enterprise`) with\n * distinct color tokens. Consumers self-document intent with `plan=\"hobby\"`\n * instead of mapping a generic `<Badge variant=\"outline\">` to colors per app.\n * Future rebrand / dark-mode tweaks propagate automatically — no consumer\n * code change.\n *\n * Visual spec (per `theo/docs/handoff/2026-05-23-theo-ui-cloud-dashboard-gaps-brief.md`):\n *\n *   | tier         | bg                  | border                   | text                  |\n *   |--------------|---------------------|--------------------------|-----------------------|\n *   | free         | bg-muted/40         | border-muted-foreground/20 | text-muted-foreground |\n *   | hobby        | bg-warning/10       | border-warning/30        | text-warning          |\n *   | pro          | bg-primary/10       | border-primary/30        | text-primary          |\n *   | team         | bg-success/10       | border-success/30        | text-success          |\n *   | enterprise   | bg-foreground/5     | border-foreground/20     | text-foreground       |\n *\n * Default label capitalizes the tier (`hobby → \"Hobby\"`, `enterprise → \"Enterprise\"`).\n *\n * Used by `<AccountMenu>` inline with the user name; usable standalone.\n */\n\nexport type PlanTier = \"free\" | \"hobby\" | \"pro\" | \"team\" | \"enterprise\";\n\nexport interface PlanBadgeProps extends HTMLAttributes<HTMLSpanElement> {\n  /** Plan tier identifier. */\n  plan: PlanTier;\n  /** Override the display label. Defaults to the capitalized tier name. */\n  label?: string;\n  /** Size variant. */\n  size?: \"sm\" | \"md\";\n}\n\nconst TIER_CLASS: Record<PlanTier, string> = {\n  free: \"bg-muted/40 border-muted-foreground/20 text-muted-foreground\",\n  hobby: \"bg-warning/10 border-warning/30 text-warning\",\n  pro: \"bg-primary/10 border-primary/30 text-primary\",\n  team: \"bg-success/10 border-success/30 text-success\",\n  enterprise: \"bg-foreground/5 border-foreground/20 text-foreground\",\n};\n\nconst SIZE_CLASS = {\n  sm: \"px-1.5 py-0 text-label-caps\",\n  md: \"px-2 py-0.5 text-label\",\n} as const;\n\nfunction defaultLabel(plan: PlanTier): string {\n  return plan.charAt(0).toUpperCase() + plan.slice(1);\n}\n\nconst PlanBadge = forwardRef<HTMLSpanElement, PlanBadgeProps>(\n  ({ className, plan, label, size = \"md\", ...props }, ref) => {\n    // Runtime fallback for unknown tier (TypeScript prevents this at compile\n    // time; the guard handles consumers casting an arbitrary string).\n    const tierClass = TIER_CLASS[plan] ?? TIER_CLASS.free;\n    const displayLabel = label ?? defaultLabel(plan);\n    return (\n      <span\n        ref={ref}\n        className={cn(\n          \"inline-flex items-center rounded-md border\",\n          \"font-mono uppercase tabular-nums tracking-wider\",\n          tierClass,\n          SIZE_CLASS[size],\n          className,\n        )}\n        data-plan={plan}\n        {...props}\n      >\n        {displayLabel}\n      </span>\n    );\n  },\n);\nPlanBadge.displayName = \"PlanBadge\";\n\nexport { PlanBadge };\n"
+    }
+  ]
+}

package/registry/r/progress.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
+  "name": "progress",
+  "type": "registry:ui",
+  "title": "Progress",
+  "description": "Accessible progress bar primitive with intent variants (default, success, warning, destructive), 4 heights (h-1 / h-1.5 / h-2 / h-3), and an indeterminate animated state. Built on role=\"progressbar\" + ARIA semantics.",
+  "dependencies": [],
+  "registryDependencies": [
+    "https://usetheodev.github.io/theo-ui/r/cn.json",
+    "https://usetheodev.github.io/theo-ui/r/tailwind-preset.json"
+  ],
+  "files": [
+    {
+      "path": "components/primitives/progress/progress.tsx",
+      "type": "registry:ui",
+      "target": "components/ui/progress.tsx",
+      "content": "import { forwardRef } from \"react\";\nimport type { HTMLAttributes } from \"react\";\nimport { cn } from \"@/lib/cn\";\n\n/**\n * Progress — accessible progress bar primitive.\n *\n * Built on `<div role=\"progressbar\">` (NOT native `<progress>`) so Tailwind\n * classes can style the track + fill cross-browser (Chrome/Safari/Firefox\n * shadow-DOM hooks for `<progress>` diverge). Matches Radix / shadcn /\n * Mantine convention.\n *\n * Variants:\n *   - intent: `default` | `success` | `warning` | `destructive` — controls fill color\n *   - height: `h-1` (4px, default) | `h-1.5` | `h-2` | `h-3`\n *   - indeterminate: animated bar, no value (e.g. \"uploading…\", \"building…\")\n *\n * Composition:\n *   <Progress value={42} max={100} intent=\"success\" aria-label=\"Upload\" />\n *   <Progress indeterminate aria-label=\"Building\" />\n *\n * A11y:\n *   - role=\"progressbar\"\n *   - aria-valuenow / aria-valuemin / aria-valuemax (determinate)\n *   - aria-busy=\"true\" when indeterminate\n *   - Respects `prefers-reduced-motion` (no animation when set)\n *\n * Used by `<UsageMeter>` to render each metric's fill bar, but ships as a\n * standalone primitive for direct consumer use (deploy phase, file upload,\n * build progress, quota fill).\n */\n\nexport interface ProgressProps extends Omit<HTMLAttributes<HTMLDivElement>, \"role\"> {\n  /** Current value (0..max). Values outside the range are clamped. */\n  value?: number;\n  /** Maximum value. Defaults to 100. */\n  max?: number;\n  /** Visual intent — controls fill color. */\n  intent?: \"default\" | \"success\" | \"warning\" | \"destructive\";\n  /** Bar height in tailwind units. Defaults to `\"h-1\"` (4px). */\n  height?: \"h-1\" | \"h-1.5\" | \"h-2\" | \"h-3\";\n  /** When true, animated bar with no value. Omits `aria-valuenow`, adds `aria-busy`. */\n  indeterminate?: boolean;\n  /** Accessible label. Required if not preceded by an `aria-labelledby` element. */\n  \"aria-label\"?: string;\n}\n\nconst INTENT_FILL: Record<NonNullable<ProgressProps[\"intent\"]>, string> = {\n  default: \"bg-primary\",\n  success: \"bg-success\",\n  warning: \"bg-warning\",\n  destructive: \"bg-destructive\",\n};\n\nconst Progress = forwardRef<HTMLDivElement, ProgressProps>(\n  (\n    {\n      className,\n      value = 0,\n      max = 100,\n      intent = \"default\",\n      height = \"h-1\",\n      indeterminate = false,\n      ...props\n    },\n    ref,\n  ) => {\n    const clampedMax = Math.max(0, max);\n    const clampedValue = Math.min(clampedMax, Math.max(0, value));\n    const percent = clampedMax > 0 ? (clampedValue / clampedMax) * 100 : 0;\n    const fillClass = INTENT_FILL[intent];\n\n    return (\n      // biome-ignore lint/a11y/useFocusableInteractive: WAI-ARIA `progressbar` is a status role (https://www.w3.org/TR/wai-aria-1.2/#progressbar) — NOT supposed to be focusable; screen readers announce updates without keyboard navigation.\n      <div\n        ref={ref}\n        role=\"progressbar\"\n        aria-valuemin={0}\n        aria-valuemax={clampedMax}\n        aria-valuenow={indeterminate ? undefined : clampedValue}\n        aria-busy={indeterminate ? true : undefined}\n        className={cn(\"relative w-full overflow-hidden rounded-full bg-muted\", height, className)}\n        {...props}\n      >\n        {indeterminate ? (\n          <div\n            className={cn(\n              \"absolute inset-y-0 left-0 w-1/3 rounded-full\",\n              \"animate-[progress-indeterminate_1.4s_ease-in-out_infinite] motion-reduce:animate-none\",\n              \"motion-reduce:w-full motion-reduce:opacity-50\",\n              fillClass,\n            )}\n          />\n        ) : (\n          <div\n            className={cn(\n              \"h-full rounded-full transition-[width] duration-base ease-out-soft\",\n              \"motion-reduce:transition-none\",\n              fillClass,\n            )}\n            style={{ width: `${percent}%` }}\n          />\n        )}\n      </div>\n    );\n  },\n);\nProgress.displayName = \"Progress\";\n\nexport { Progress };\n"
+    }
+  ]
+}

package/registry/r/theme-provider.json

@@ -41,7 +41,7 @@
       "path": "themes/theme-provider.tsx",
       "type": "registry:lib",
       "target": "themes/theme-provider.tsx",
-      "content": "import { createContext, useCallback, useContext, useEffect, useMemo, useState } from \"react\";\nimport type { JSX, ReactNode } from \"react\";\nimport { safeHref } from \"@/lib/safe-href\";\nimport { type Density, DensityContext, injectDensityCss } from \"./density\";\nimport type { ColorScale, Theme, ThemeMode } from \"@/themes/types\";\n\ninterface ThemeContextValue {\n  /** Active theme (full descriptor). */\n  theme: Theme;\n  /** Active mode: light or dark. */\n  mode: ThemeMode;\n  /** All available themes. */\n  themes: Theme[];\n  /** Swap the active theme by name. */\n  setTheme: (name: string) => void;\n  /** Set light/dark explicitly. */\n  setMode: (mode: ThemeMode) => void;\n  /** Toggle light <> dark. */\n  toggleMode: () => void;\n  /** Register an additional theme at runtime. */\n  registerTheme: (theme: Theme) => void;\n}\n\nconst ThemeContext = createContext<ThemeContextValue | undefined>(undefined);\n\nconst STYLE_ELEMENT_ID = \"theo-ui-theme-vars\";\n\n// T3.2 (SEC-001): allowlist validators for theme values. injectThemeCss\n// interpolates theme name + color values + font families into a <style>\n// textContent. Without validation, a theme object from an untrusted source\n// (e.g., a feature-flag service, a CMS) could inject arbitrary CSS via\n// closing the declaration with `}` or smuggling `url(...)` for exfiltration.\n// We reject rather than escape: themes are code, not user input. Invalid\n// values cause a dev-time throw (caller sees the problem); production\n// silently substitutes a safe fallback so a misconfigured theme can't\n// crash the app.\n\n// Color values. Multiple accepted shapes:\n//   1. Hex: `#fff`, `#0a0a0a`, `#0a0a0aff`.\n//   2. Fully-parenthesized CSS color functions: `oklch(...)`, `rgb(...)`,\n//      `hsl(...)`, etc. Inner content restricted to digits/dots/spaces/\n//      percent/slash/comma/dash/plus — no semicolons, no braces, no `url(`.\n//   3. HSL-component split (shadcn-ui convention used by the built-in\n//      themes): `\"0 0% 100%\"`, `\"262 83% 58%\"` — space-separated numeric\n//      components consumed via `hsl(var(--token))` in stylesheets.\n//   4. `var(--token)` references, optionally with a fallback value that\n//      contains no parens/braces/semicolons.\n//   5. CSS keywords: `transparent`, `currentColor`, `inherit`, `initial`,\n//      `unset`.\nconst COLOR_VALUE_PATTERN =\n  /^(#[0-9a-fA-F]{3,8}|(?:oklch|oklab|rgb|rgba|hsl|hsla|lab|lch|color)\\(\\s*[\\d.\\s%,/+\\-]+\\s*\\)|-?\\d+(?:\\.\\d+)?%?(?:\\s+-?\\d+(?:\\.\\d+)?%?){1,3}|var\\(--[a-zA-Z0-9-]+(?:\\s*,\\s*[^();{}]+)?\\)|transparent|currentColor|inherit|initial|unset)$/;\n\n// Font family: word chars, spaces, commas, hyphens, dots, quotes. Excludes\n// parens (blocks `url(...)`) and semicolons (blocks declaration breakouts).\nconst FONT_FAMILY_PATTERN = /^[\\w\\s,\"'\\-.]+$/;\n\n// Theme name: kebab-case identifier. Excludes anything that could break out\n// of an attribute selector or inject additional rules.\nconst THEME_NAME_PATTERN = /^[a-z][a-z0-9-]*$/;\n\nconst IS_DEV = typeof process === \"undefined\" || process.env.NODE_ENV !== \"production\";\n\nfunction rejectOrFallback(scope: string, value: string, fallback: string): string {\n  if (IS_DEV) {\n    throw new Error(\n      `[@usetheo/ui] invalid ${scope} value: ${JSON.stringify(value)}. Theme values must match the allowlist (see src/themes/theme-provider.tsx). Refusing to inject potentially unsafe CSS.`,\n    );\n  }\n  return fallback;\n}\n\nfunction validatedColor(token: string, value: string): string {\n  if (COLOR_VALUE_PATTERN.test(value)) return value;\n  return rejectOrFallback(`color \"${token}\"`, value, \"transparent\");\n}\n\nfunction validatedFontFamily(slot: string, value: string): string {\n  if (FONT_FAMILY_PATTERN.test(value)) return value;\n  return rejectOrFallback(`fontFamily \"${slot}\"`, value, \"inherit\");\n}\n\nfunction validatedThemeName(value: string): string {\n  if (THEME_NAME_PATTERN.test(value)) return value;\n  return rejectOrFallback(\"theme.name\", value, \"invalid-theme\");\n}\n\nfunction colorScaleToCss(name: string, mode: ThemeMode, colors: ColorScale): string {\n  const safeName = validatedThemeName(name);\n  const selector =\n    mode === \"light\"\n      ? `[data-theme=\"${safeName}\"]`\n      : `[data-theme=\"${safeName}\"].dark, [data-theme=\"${safeName}\"][data-mode=\"dark\"]`;\n  const decls = Object.entries(colors)\n    .map(([token, value]) => `  --${token}: ${validatedColor(token, value)};`)\n    .join(\"\\n\");\n  return `${selector} {\\n${decls}\\n}`;\n}\n\nfunction fontsToCss(name: string, fonts: Theme[\"fonts\"]): string {\n  const safeName = validatedThemeName(name);\n  const display = validatedFontFamily(\"display\", fonts.display);\n  const body = validatedFontFamily(\"body\", fonts.body);\n  const mono = validatedFontFamily(\"mono\", fonts.mono);\n  return `[data-theme=\"${safeName}\"] {\\n  --font-display: ${display};\\n  --font-body: ${body};\\n  --font-mono: ${mono};\\n}`;\n}\n\nfunction injectThemeCss(themes: Theme[]): void {\n  if (typeof document === \"undefined\") return;\n  let style = document.getElementById(STYLE_ELEMENT_ID) as HTMLStyleElement | null;\n  if (!style) {\n    style = document.createElement(\"style\");\n    style.id = STYLE_ELEMENT_ID;\n    document.head.appendChild(style);\n  }\n  const blocks: string[] = [];\n  for (const theme of themes) {\n    blocks.push(fontsToCss(theme.name, theme.fonts));\n    blocks.push(colorScaleToCss(theme.name, \"light\", theme.light));\n    blocks.push(colorScaleToCss(theme.name, \"dark\", theme.dark));\n  }\n  style.textContent = blocks.join(\"\\n\\n\");\n}\n\n/**\n * loadThemeFonts — idempotently inject `<link rel=\"stylesheet\">` for each\n * font URL declared by the theme.\n *\n * T4.2: the previous implementation kept a module-level `Set` to track\n * already-injected URLs. That singleton broke test isolation (state\n * leaked across renders) and silently skipped injection in micro-frontend\n * setups with multiple `<ThemeProvider>` mounts. Replaced with a DOM\n * check: we query `document.head` for an existing link with the same\n * `href` before appending a new one. The DOM is the single source of\n * truth; no shared state across instances.\n */\nfunction loadThemeFonts(theme: Theme): void {\n  if (typeof document === \"undefined\") return;\n  if (!theme.fontUrls) return;\n  for (const url of theme.fontUrls) {\n    // Re-audit NEW-001 (SSRF, LOW): defang dangerous protocols on\n    // consumer-provided font URLs. Built-in themes use\n    // fonts.googleapis.com/gstatic.com — safe. registerTheme accepts\n    // arbitrary objects at runtime; a malicious theme could try to inject\n    // javascript:/data:text/html via fontUrls. safeHref returns undefined\n    // for dangerous protocols, which we skip silently.\n    const safe = safeHref(url);\n    if (!safe) continue;\n    if (document.head.querySelector(`link[rel=\"stylesheet\"][href=\"${CSS.escape(safe)}\"]`)) {\n      continue;\n    }\n    const link = document.createElement(\"link\");\n    link.rel = \"stylesheet\";\n    link.href = safe;\n    document.head.appendChild(link);\n  }\n}\n\ninterface ThemeProviderProps {\n  children: ReactNode;\n  /**\n   * Theme to start with. Must match the `name` of an entry in `themes`.\n   * Defaults to `\"violet-forge\"` for backward compat — if you don't pass\n   * `violet-forge` in `themes`, set this prop explicitly.\n   */\n  defaultTheme?: string;\n  /** Mode to start with. Defaults to `\"dark\"` (library is dark-first). */\n  defaultMode?: ThemeMode;\n  /**\n   * Available themes. **Required**: ThemeProvider does not auto-include any\n   * built-in theme since v0.1.0-next.0 — pass `builtinThemes` for all three\n   * Violet Forge defaults, or your own array for a slimmer bundle.\n   *\n   * Migration: consumers previously calling `<ThemeProvider>` without this\n   * prop now must pass `themes={builtinThemes}` (or use `<TheoUIProvider>`\n   * which defaults to `builtinThemes` for you).\n   */\n  themes: Theme[];\n  /**\n   * Persist selection in localStorage under this key. Pass `null` to disable.\n   * Default: \"theo-ui:theme\".\n   */\n  storageKey?: string | null;\n  /**\n   * Initial density. Drives `data-density` on `<html>` and the `--theo-control-h`\n   * / `--theo-control-px` CSS vars consumed by form-control `md` variants.\n   * Defaults to `\"comfortable\"` (36px controls — FAANG-tier modern density).\n   * Plan: faang-density-tightening (D3).\n   */\n  defaultDensity?: Density;\n}\n\n/**\n * Storage failure diagnostic — dev-only one-line warn so engineers see\n * something when localStorage throws (Safari private mode, blocked\n * third-party cookies, sandboxed iframes). In production we stay silent;\n * runtime behavior is fail-safe (state still lives in memory).\n *\n * Per HIGH-006: silent catches diverge from the \"fail loud\" principle\n * declared in the global CLAUDE.md. We accept silence in prod because the\n * fallback is correct, but we surface a single warn per call site in dev.\n */\nfunction warnStorageFailure(scope: string, err: unknown): void {\n  if (typeof process === \"undefined\" || process.env.NODE_ENV === \"production\") return;\n  // biome-ignore lint/suspicious/noConsole: dev-only diagnostic for storage failures (HIGH-006)\n  console.warn(`[@usetheo/ui] theme storage failure (${scope}):`, err);\n}\n\n/**\n * ThemeProvider — central registry + runtime switcher for Theo themes.\n *\n * Behavior:\n *   1. On mount, injects a `<style id=\"theo-ui-theme-vars\">` element with\n *      one CSS block per theme (`[data-theme=\"<name>\"] { --token: ... }`).\n *   2. Sets `data-theme` and `data-mode` on `<html>` so any element nested\n *      below inherits the right tokens (the Tailwind config consumes them).\n *   3. Lazy-loads theme font URLs by injecting `<link rel=\"stylesheet\">`.\n *   4. Optionally persists choice in localStorage.\n */\nfunction ThemeProvider({\n  children,\n  defaultTheme = \"violet-forge\",\n  defaultMode = \"dark\",\n  themes: themesProp,\n  storageKey = \"theo-ui:theme\",\n  defaultDensity = \"comfortable\",\n}: ThemeProviderProps): JSX.Element {\n  // Themes prop is required since v0.1.0-next.0 — see migration note in\n  // the JSDoc on ThemeProviderProps. Pass `builtinThemes` for the legacy\n  // default behavior (violet-forge + classic-paper + aurora-terminal), or\n  // an array of your own. Empty array is rejected: ThemeProvider has no\n  // valid state without at least one registered theme.\n  if (!themesProp || themesProp.length === 0) {\n    throw new Error(\n      \"<ThemeProvider> requires the `themes` prop with at least one Theme. \" +\n        \"Pass `themes={builtinThemes}` for the Violet Forge defaults (importable \" +\n        \"via the package barrel), or use <TheoUIProvider> which sets this for you.\",\n    );\n  }\n\n  // T3.2 (SEC-001): eager validation. Calling validatedColor/FontFamily/\n  // ThemeName here ensures CSS-injection attempts throw at construction\n  // time rather than inside the deferred useEffect that injects the\n  // <style>. Production-mode fallbacks keep the app rendering even if a\n  // theme has bad values.\n  //\n  // Re-audit NEW-3: wrapped in useMemo so the validation cost (O(themes *\n  // tokens), ~60 ops per built-in theme) only runs when themesProp's\n  // reference changes — not on every parent re-render. Consumers passing\n  // inline array literals (`themes={[violetForge, classicPaper]}`) would\n  // otherwise pay this on every parent update.\n  const mergedThemes = useMemo<Theme[]>(() => {\n    for (const t of themesProp) {\n      validatedThemeName(t.name);\n      validatedFontFamily(\"display\", t.fonts.display);\n      validatedFontFamily(\"body\", t.fonts.body);\n      validatedFontFamily(\"mono\", t.fonts.mono);\n      for (const [token, value] of Object.entries(t.light)) {\n        validatedColor(token, value);\n      }\n      for (const [token, value] of Object.entries(t.dark)) {\n        validatedColor(token, value);\n      }\n    }\n    // Dedup by theme name; last writer wins (allows registerTheme override).\n    const map = new Map<string, Theme>();\n    for (const t of themesProp) map.set(t.name, t);\n    return Array.from(map.values());\n  }, [themesProp]);\n\n  const [themes, setThemes] = useState<Theme[]>(mergedThemes);\n\n  // Re-sync state when the `themes` prop changes between renders. Avoids the\n  // common pitfall where the user passes a different array later and the\n  // initial-state-only seed silently ignores the change.\n  useEffect(() => {\n    setThemes(mergedThemes);\n  }, [mergedThemes]);\n\n  const [themeName, setThemeName] = useState<string>(() => {\n    if (typeof window === \"undefined\" || !storageKey) return defaultTheme;\n    try {\n      return window.localStorage.getItem(`${storageKey}:name`) ?? defaultTheme;\n    } catch (err) {\n      warnStorageFailure(\"read theme name\", err);\n      return defaultTheme;\n    }\n  });\n\n  const [mode, setModeState] = useState<ThemeMode>(() => {\n    if (typeof window === \"undefined\" || !storageKey) return defaultMode;\n    try {\n      const stored = window.localStorage.getItem(`${storageKey}:mode`);\n      return stored === \"dark\" || stored === \"light\" ? stored : defaultMode;\n    } catch (err) {\n      warnStorageFailure(\"read theme mode\", err);\n      return defaultMode;\n    }\n  });\n\n  const [density, setDensityState] = useState<Density>(() => {\n    if (typeof window === \"undefined\" || !storageKey) return defaultDensity;\n    try {\n      const stored = window.localStorage.getItem(`${storageKey}:density`);\n      return stored === \"compact\" || stored === \"comfortable\" || stored === \"spacious\"\n        ? stored\n        : defaultDensity;\n    } catch (err) {\n      warnStorageFailure(\"read density\", err);\n      return defaultDensity;\n    }\n  });\n\n  // Inject CSS vars whenever the themes list changes.\n  useEffect(() => {\n    injectThemeCss(themes);\n  }, [themes]);\n\n  // Apply data-theme + data-mode + data-density to <html>, load fonts,\n  // inject density CSS vars.\n  useEffect(() => {\n    if (typeof document === \"undefined\") return;\n    const active = themes.find((t) => t.name === themeName) ?? themes[0];\n    if (!active) return;\n    document.documentElement.setAttribute(\"data-theme\", active.name);\n    document.documentElement.setAttribute(\"data-mode\", mode);\n    document.documentElement.setAttribute(\"data-density\", density);\n    document.documentElement.classList.toggle(\"dark\", mode === \"dark\");\n    loadThemeFonts(active);\n    injectDensityCss();\n  }, [themeName, mode, density, themes]);\n\n  // Persist on change.\n  useEffect(() => {\n    if (typeof window === \"undefined\" || !storageKey) return;\n    try {\n      window.localStorage.setItem(`${storageKey}:name`, themeName);\n      window.localStorage.setItem(`${storageKey}:mode`, mode);\n      window.localStorage.setItem(`${storageKey}:density`, density);\n    } catch (err) {\n      // Storage may fail in private mode; behavior remains correct (state\n      // lives in memory). Per HIGH-006 we surface a one-time dev warning so\n      // the engineer sees something instead of complete silence.\n      warnStorageFailure(\"persist theme + mode + density\", err);\n    }\n  }, [themeName, mode, density, storageKey]);\n\n  const setTheme = useCallback((name: string) => setThemeName(name), []);\n  const setMode = useCallback((next: ThemeMode) => setModeState(next), []);\n  const toggleMode = useCallback(\n    () => setModeState((cur) => (cur === \"light\" ? \"dark\" : \"light\")),\n    [],\n  );\n  const setDensity = useCallback((next: Density) => setDensityState(next), []);\n  const registerTheme = useCallback((theme: Theme) => {\n    setThemes((cur) => {\n      const idx = cur.findIndex((t) => t.name === theme.name);\n      if (idx >= 0) {\n        const next = cur.slice();\n        next[idx] = theme;\n        return next;\n      }\n      return [...cur, theme];\n    });\n  }, []);\n\n  // themes[0] is guaranteed non-undefined by the constructor-time check\n  // above (themesProp is non-empty); the non-null assert encodes that\n  // invariant for TypeScript, which can't trace it through useState.\n  // biome-ignore lint/style/noNonNullAssertion: T2.5 runtime invariant — themesProp non-empty validated at top of function\n  const active = themes.find((t) => t.name === themeName) ?? themes[0]!;\n\n  const value = useMemo<ThemeContextValue>(\n    () => ({\n      theme: active,\n      mode,\n      themes,\n      setTheme,\n      setMode,\n      toggleMode,\n      registerTheme,\n    }),\n    [active, mode, themes, setTheme, setMode, toggleMode, registerTheme],\n  );\n\n  const densityValue = useMemo(() => ({ density, setDensity }), [density, setDensity]);\n\n  return (\n    <ThemeContext.Provider value={value}>\n      <DensityContext.Provider value={densityValue}>{children}</DensityContext.Provider>\n    </ThemeContext.Provider>\n  );\n}\n\n/**\n * useTheme — access theme state from any component inside <ThemeProvider>.\n * Throws if used outside the provider — fail-fast.\n */\nfunction useTheme(): ThemeContextValue {\n  const ctx = useContext(ThemeContext);\n  if (!ctx) {\n    throw new Error(\"useTheme must be used inside <ThemeProvider>.\");\n  }\n  return ctx;\n}\n\nexport { ThemeProvider, useTheme };\n"
+      "content": "import {\n  createContext,\n  useCallback,\n  useContext,\n  useEffect,\n  useMemo,\n  useRef,\n  useState,\n} from \"react\";\nimport type { JSX, ReactNode } from \"react\";\nimport { safeHref } from \"@/lib/safe-href\";\nimport { type Density, DensityContext, injectDensityCss } from \"./density\";\nimport type { ColorScale, Theme, ThemeMode } from \"@/themes/types\";\n\ninterface ThemeContextValue {\n  /** Active theme (full descriptor). */\n  theme: Theme;\n  /** Active mode: light or dark. */\n  mode: ThemeMode;\n  /** All available themes. */\n  themes: Theme[];\n  /** Swap the active theme by name. */\n  setTheme: (name: string) => void;\n  /** Set light/dark explicitly. */\n  setMode: (mode: ThemeMode) => void;\n  /** Toggle light <> dark. */\n  toggleMode: () => void;\n  /** Register an additional theme at runtime. */\n  registerTheme: (theme: Theme) => void;\n}\n\nconst ThemeContext = createContext<ThemeContextValue | undefined>(undefined);\n\nconst STYLE_ELEMENT_ID = \"theo-ui-theme-vars\";\n\n// T3.2 (SEC-001): allowlist validators for theme values. injectThemeCss\n// interpolates theme name + color values + font families into a <style>\n// textContent. Without validation, a theme object from an untrusted source\n// (e.g., a feature-flag service, a CMS) could inject arbitrary CSS via\n// closing the declaration with `}` or smuggling `url(...)` for exfiltration.\n// We reject rather than escape: themes are code, not user input. Invalid\n// values cause a dev-time throw (caller sees the problem); production\n// silently substitutes a safe fallback so a misconfigured theme can't\n// crash the app.\n\n// Color values. Multiple accepted shapes:\n//   1. Hex: `#fff`, `#0a0a0a`, `#0a0a0aff`.\n//   2. Fully-parenthesized CSS color functions: `oklch(...)`, `rgb(...)`,\n//      `hsl(...)`, etc. Inner content restricted to digits/dots/spaces/\n//      percent/slash/comma/dash/plus — no semicolons, no braces, no `url(`.\n//   3. HSL-component split (shadcn-ui convention used by the built-in\n//      themes): `\"0 0% 100%\"`, `\"262 83% 58%\"` — space-separated numeric\n//      components consumed via `hsl(var(--token))` in stylesheets.\n//   4. `var(--token)` references, optionally with a fallback value that\n//      contains no parens/braces/semicolons.\n//   5. CSS keywords: `transparent`, `currentColor`, `inherit`, `initial`,\n//      `unset`.\nconst COLOR_VALUE_PATTERN =\n  /^(#[0-9a-fA-F]{3,8}|(?:oklch|oklab|rgb|rgba|hsl|hsla|lab|lch|color)\\(\\s*[\\d.\\s%,/+\\-]+\\s*\\)|-?\\d+(?:\\.\\d+)?%?(?:\\s+-?\\d+(?:\\.\\d+)?%?){1,3}|var\\(--[a-zA-Z0-9-]+(?:\\s*,\\s*[^();{}]+)?\\)|transparent|currentColor|inherit|initial|unset)$/;\n\n// Font family: word chars, spaces, commas, hyphens, dots, quotes. Excludes\n// parens (blocks `url(...)`) and semicolons (blocks declaration breakouts).\nconst FONT_FAMILY_PATTERN = /^[\\w\\s,\"'\\-.]+$/;\n\n// Theme name: kebab-case identifier. Excludes anything that could break out\n// of an attribute selector or inject additional rules.\nconst THEME_NAME_PATTERN = /^[a-z][a-z0-9-]*$/;\n\nconst IS_DEV = typeof process === \"undefined\" || process.env.NODE_ENV !== \"production\";\n\nfunction rejectOrFallback(scope: string, value: string, fallback: string): string {\n  if (IS_DEV) {\n    throw new Error(\n      `[@usetheo/ui] invalid ${scope} value: ${JSON.stringify(value)}. Theme values must match the allowlist (see src/themes/theme-provider.tsx). Refusing to inject potentially unsafe CSS.`,\n    );\n  }\n  return fallback;\n}\n\nfunction validatedColor(token: string, value: string): string {\n  if (COLOR_VALUE_PATTERN.test(value)) return value;\n  return rejectOrFallback(`color \"${token}\"`, value, \"transparent\");\n}\n\nfunction validatedFontFamily(slot: string, value: string): string {\n  if (FONT_FAMILY_PATTERN.test(value)) return value;\n  return rejectOrFallback(`fontFamily \"${slot}\"`, value, \"inherit\");\n}\n\nfunction validatedThemeName(value: string): string {\n  if (THEME_NAME_PATTERN.test(value)) return value;\n  return rejectOrFallback(\"theme.name\", value, \"invalid-theme\");\n}\n\nfunction colorScaleToCss(name: string, mode: ThemeMode, colors: ColorScale): string {\n  const safeName = validatedThemeName(name);\n  const selector =\n    mode === \"light\"\n      ? `[data-theme=\"${safeName}\"]`\n      : `[data-theme=\"${safeName}\"].dark, [data-theme=\"${safeName}\"][data-mode=\"dark\"]`;\n  const decls = Object.entries(colors)\n    .map(([token, value]) => `  --${token}: ${validatedColor(token, value)};`)\n    .join(\"\\n\");\n  return `${selector} {\\n${decls}\\n}`;\n}\n\nfunction fontsToCss(name: string, fonts: Theme[\"fonts\"]): string {\n  const safeName = validatedThemeName(name);\n  const display = validatedFontFamily(\"display\", fonts.display);\n  const body = validatedFontFamily(\"body\", fonts.body);\n  const mono = validatedFontFamily(\"mono\", fonts.mono);\n  return `[data-theme=\"${safeName}\"] {\\n  --font-display: ${display};\\n  --font-body: ${body};\\n  --font-mono: ${mono};\\n}`;\n}\n\nfunction injectThemeCss(themes: Theme[]): void {\n  if (typeof document === \"undefined\") return;\n  let style = document.getElementById(STYLE_ELEMENT_ID) as HTMLStyleElement | null;\n  if (!style) {\n    style = document.createElement(\"style\");\n    style.id = STYLE_ELEMENT_ID;\n    document.head.appendChild(style);\n  }\n  const blocks: string[] = [];\n  for (const theme of themes) {\n    blocks.push(fontsToCss(theme.name, theme.fonts));\n    blocks.push(colorScaleToCss(theme.name, \"light\", theme.light));\n    blocks.push(colorScaleToCss(theme.name, \"dark\", theme.dark));\n  }\n  style.textContent = blocks.join(\"\\n\\n\");\n}\n\n/**\n * loadThemeFonts — idempotently inject `<link rel=\"stylesheet\">` for each\n * font URL declared by the theme.\n *\n * T4.2: the previous implementation kept a module-level `Set` to track\n * already-injected URLs. That singleton broke test isolation (state\n * leaked across renders) and silently skipped injection in micro-frontend\n * setups with multiple `<ThemeProvider>` mounts. Replaced with a DOM\n * check: we query `document.head` for an existing link with the same\n * `href` before appending a new one. The DOM is the single source of\n * truth; no shared state across instances.\n */\nfunction loadThemeFonts(theme: Theme): void {\n  if (typeof document === \"undefined\") return;\n  if (!theme.fontUrls) return;\n  for (const url of theme.fontUrls) {\n    // Re-audit NEW-001 (SSRF, LOW): defang dangerous protocols on\n    // consumer-provided font URLs. Built-in themes use\n    // fonts.googleapis.com/gstatic.com — safe. registerTheme accepts\n    // arbitrary objects at runtime; a malicious theme could try to inject\n    // javascript:/data:text/html via fontUrls. safeHref returns undefined\n    // for dangerous protocols, which we skip silently.\n    const safe = safeHref(url);\n    if (!safe) continue;\n    if (document.head.querySelector(`link[rel=\"stylesheet\"][href=\"${CSS.escape(safe)}\"]`)) {\n      continue;\n    }\n    const link = document.createElement(\"link\");\n    link.rel = \"stylesheet\";\n    link.href = safe;\n    document.head.appendChild(link);\n  }\n}\n\ninterface ThemeProviderProps {\n  children: ReactNode;\n  /**\n   * Theme to start with. Must match the `name` of an entry in `themes`.\n   * Defaults to `\"violet-forge\"` for backward compat — if you don't pass\n   * `violet-forge` in `themes`, set this prop explicitly.\n   */\n  defaultTheme?: string;\n  /** Mode to start with. Defaults to `\"dark\"` (library is dark-first). */\n  defaultMode?: ThemeMode;\n  /**\n   * Available themes. **Required**: ThemeProvider does not auto-include any\n   * built-in theme since v0.1.0-next.0 — pass `builtinThemes` for all three\n   * Violet Forge defaults, or your own array for a slimmer bundle.\n   *\n   * Migration: consumers previously calling `<ThemeProvider>` without this\n   * prop now must pass `themes={builtinThemes}` (or use `<TheoUIProvider>`\n   * which defaults to `builtinThemes` for you).\n   */\n  themes: Theme[];\n  /**\n   * Persist selection in localStorage under this key. Pass `null` to disable.\n   * Default: \"theo-ui:theme\".\n   */\n  storageKey?: string | null;\n  /**\n   * Initial density. Drives `data-density` on `<html>` and the `--theo-control-h`\n   * / `--theo-control-px` CSS vars consumed by form-control `md` variants.\n   * Defaults to `\"comfortable\"` (36px controls — FAANG-tier modern density).\n   * Plan: faang-density-tightening (D3).\n   */\n  defaultDensity?: Density;\n}\n\n/**\n * Storage failure diagnostic — dev-only one-line warn so engineers see\n * something when localStorage throws (Safari private mode, blocked\n * third-party cookies, sandboxed iframes). In production we stay silent;\n * runtime behavior is fail-safe (state still lives in memory).\n *\n * Per HIGH-006: silent catches diverge from the \"fail loud\" principle\n * declared in the global CLAUDE.md. We accept silence in prod because the\n * fallback is correct, but we surface a single warn per call site in dev.\n */\nfunction warnStorageFailure(scope: string, err: unknown): void {\n  if (typeof process === \"undefined\" || process.env.NODE_ENV === \"production\") return;\n  // biome-ignore lint/suspicious/noConsole: dev-only diagnostic for storage failures (HIGH-006)\n  console.warn(`[@usetheo/ui] theme storage failure (${scope}):`, err);\n}\n\n/**\n * ThemeProvider — central registry + runtime switcher for Theo themes.\n *\n * Behavior:\n *   1. On mount, injects a `<style id=\"theo-ui-theme-vars\">` element with\n *      one CSS block per theme (`[data-theme=\"<name>\"] { --token: ... }`).\n *   2. Sets `data-theme` and `data-mode` on `<html>` so any element nested\n *      below inherits the right tokens (the Tailwind config consumes them).\n *   3. Lazy-loads theme font URLs by injecting `<link rel=\"stylesheet\">`.\n *   4. Optionally persists choice in localStorage.\n */\nfunction ThemeProvider({\n  children,\n  defaultTheme = \"violet-forge\",\n  defaultMode = \"dark\",\n  themes: themesProp,\n  storageKey = \"theo-ui:theme\",\n  defaultDensity = \"comfortable\",\n}: ThemeProviderProps): JSX.Element {\n  // Themes prop is required since v0.1.0-next.0 — see migration note in\n  // the JSDoc on ThemeProviderProps. Pass `builtinThemes` for the legacy\n  // default behavior (violet-forge + classic-paper + aurora-terminal), or\n  // an array of your own. Empty array is rejected: ThemeProvider has no\n  // valid state without at least one registered theme.\n  if (!themesProp || themesProp.length === 0) {\n    throw new Error(\n      \"<ThemeProvider> requires the `themes` prop with at least one Theme. \" +\n        \"Pass `themes={builtinThemes}` for the Violet Forge defaults (importable \" +\n        \"via the package barrel), or use <TheoUIProvider> which sets this for you.\",\n    );\n  }\n\n  // T3.2 (SEC-001): eager validation. Calling validatedColor/FontFamily/\n  // ThemeName here ensures CSS-injection attempts throw at construction\n  // time rather than inside the deferred useEffect that injects the\n  // <style>. Production-mode fallbacks keep the app rendering even if a\n  // theme has bad values.\n  //\n  // Re-audit NEW-3: wrapped in useMemo so the validation cost (O(themes *\n  // tokens), ~60 ops per built-in theme) only runs when themesProp's\n  // reference changes — not on every parent re-render. Consumers passing\n  // inline array literals (`themes={[violetForge, classicPaper]}`) would\n  // otherwise pay this on every parent update.\n  const mergedThemes = useMemo<Theme[]>(() => {\n    for (const t of themesProp) {\n      validatedThemeName(t.name);\n      validatedFontFamily(\"display\", t.fonts.display);\n      validatedFontFamily(\"body\", t.fonts.body);\n      validatedFontFamily(\"mono\", t.fonts.mono);\n      for (const [token, value] of Object.entries(t.light)) {\n        validatedColor(token, value);\n      }\n      for (const [token, value] of Object.entries(t.dark)) {\n        validatedColor(token, value);\n      }\n    }\n    // Dedup by theme name; last writer wins (allows registerTheme override).\n    const map = new Map<string, Theme>();\n    for (const t of themesProp) map.set(t.name, t);\n    return Array.from(map.values());\n  }, [themesProp]);\n\n  const [themes, setThemes] = useState<Theme[]>(mergedThemes);\n\n  // Re-sync state when the `themes` prop changes between renders. Avoids the\n  // common pitfall where the user passes a different array later and the\n  // initial-state-only seed silently ignores the change.\n  useEffect(() => {\n    setThemes(mergedThemes);\n  }, [mergedThemes]);\n\n  // SSR-safe initialization (0.6.3-next.0 hydration-mismatch fix).\n  //\n  // Previously: `useState(() => localStorage.getItem(…))`. The initializer\n  // ran on BOTH server (no `window`, returned default) AND client at\n  // hydration time (with `window`, returned the stored value). The two\n  // results disagreed → React threw a hydration error on every page load\n  // for any user who had previously changed themes, and re-rendered the\n  // entire tree from scratch — defeating SSR.\n  //\n  // Fix: initialize with the SSR default ALWAYS. Promote to the stored\n  // value in a post-mount `useEffect` below. The 1-frame visual flicker\n  // is mitigated by the optional `<ThemeScript>` component, which sets\n  // `data-theme` / `data-mode` / `data-density` on `<html>` before React\n  // hydrates — see `theme-script.tsx`.\n  //\n  // The `hydratedRef` flag below guards the persist effect so that\n  // first-mount writes (with the SSR default values) don't clobber the\n  // user's stored preference in the brief window between mount and the\n  // post-mount hydration effect.\n  const [themeName, setThemeName] = useState<string>(defaultTheme);\n  const [mode, setModeState] = useState<ThemeMode>(defaultMode);\n  const [density, setDensityState] = useState<Density>(defaultDensity);\n\n  // First-run guard for the persist effect below. On initial mount the\n  // state is the SSR-safe default; we MUST NOT clobber the user's stored\n  // preference with that default before the post-mount hydration effect\n  // can promote it. After the first persist-effect call returns early,\n  // every subsequent change (post-hydration setState OR user-driven)\n  // persists normally.\n  const skipFirstPersistRef = useRef(true);\n\n  // Post-mount hydration: read localStorage and promote stored values to\n  // state. Runs ONCE on mount. If `storageKey` is null or no value is\n  // stored, this is a no-op — state stays at the SSR defaults.\n  useEffect(() => {\n    if (typeof window === \"undefined\" || !storageKey) return;\n    try {\n      const storedName = window.localStorage.getItem(`${storageKey}:name`);\n      const storedMode = window.localStorage.getItem(`${storageKey}:mode`);\n      const storedDensity = window.localStorage.getItem(`${storageKey}:density`);\n      if (storedName) setThemeName(storedName);\n      if (storedMode === \"dark\" || storedMode === \"light\") setModeState(storedMode);\n      if (\n        storedDensity === \"compact\" ||\n        storedDensity === \"comfortable\" ||\n        storedDensity === \"spacious\"\n      ) {\n        setDensityState(storedDensity);\n      }\n    } catch (err) {\n      warnStorageFailure(\"read theme + mode + density\", err);\n    }\n  }, [storageKey]);\n\n  // Inject CSS vars whenever the themes list changes.\n  useEffect(() => {\n    injectThemeCss(themes);\n  }, [themes]);\n\n  // Apply data-theme + data-mode + data-density to <html>, load fonts,\n  // inject density CSS vars.\n  useEffect(() => {\n    if (typeof document === \"undefined\") return;\n    const active = themes.find((t) => t.name === themeName) ?? themes[0];\n    if (!active) return;\n    document.documentElement.setAttribute(\"data-theme\", active.name);\n    document.documentElement.setAttribute(\"data-mode\", mode);\n    document.documentElement.setAttribute(\"data-density\", density);\n    document.documentElement.classList.toggle(\"dark\", mode === \"dark\");\n    loadThemeFonts(active);\n    injectDensityCss();\n  }, [themeName, mode, density, themes]);\n\n  // Persist on change.\n  //\n  // The first run is SKIPPED via `skipFirstPersistRef`: state at mount\n  // is the SSR-safe default. If we wrote it to storage immediately,\n  // we'd clobber the user's stored preference between mount and the\n  // post-mount hydration effect that promotes the stored value. After\n  // the first call, every subsequent run persists — whether the change\n  // came from the hydration effect (no-op write back of the stored\n  // value) or a user-driven `setTheme` / `toggleMode` / `setDensity`.\n  useEffect(() => {\n    if (skipFirstPersistRef.current) {\n      skipFirstPersistRef.current = false;\n      return;\n    }\n    if (typeof window === \"undefined\" || !storageKey) return;\n    try {\n      window.localStorage.setItem(`${storageKey}:name`, themeName);\n      window.localStorage.setItem(`${storageKey}:mode`, mode);\n      window.localStorage.setItem(`${storageKey}:density`, density);\n    } catch (err) {\n      // Storage may fail in private mode; behavior remains correct (state\n      // lives in memory). Per HIGH-006 we surface a one-time dev warning so\n      // the engineer sees something instead of complete silence.\n      warnStorageFailure(\"persist theme + mode + density\", err);\n    }\n  }, [themeName, mode, density, storageKey]);\n\n  const setTheme = useCallback((name: string) => setThemeName(name), []);\n  const setMode = useCallback((next: ThemeMode) => setModeState(next), []);\n  const toggleMode = useCallback(\n    () => setModeState((cur) => (cur === \"light\" ? \"dark\" : \"light\")),\n    [],\n  );\n  const setDensity = useCallback((next: Density) => setDensityState(next), []);\n  const registerTheme = useCallback((theme: Theme) => {\n    setThemes((cur) => {\n      const idx = cur.findIndex((t) => t.name === theme.name);\n      if (idx >= 0) {\n        const next = cur.slice();\n        next[idx] = theme;\n        return next;\n      }\n      return [...cur, theme];\n    });\n  }, []);\n\n  // themes[0] is guaranteed non-undefined by the constructor-time check\n  // above (themesProp is non-empty); the non-null assert encodes that\n  // invariant for TypeScript, which can't trace it through useState.\n  // biome-ignore lint/style/noNonNullAssertion: T2.5 runtime invariant — themesProp non-empty validated at top of function\n  const active = themes.find((t) => t.name === themeName) ?? themes[0]!;\n\n  const value = useMemo<ThemeContextValue>(\n    () => ({\n      theme: active,\n      mode,\n      themes,\n      setTheme,\n      setMode,\n      toggleMode,\n      registerTheme,\n    }),\n    [active, mode, themes, setTheme, setMode, toggleMode, registerTheme],\n  );\n\n  const densityValue = useMemo(() => ({ density, setDensity }), [density, setDensity]);\n\n  return (\n    <ThemeContext.Provider value={value}>\n      <DensityContext.Provider value={densityValue}>{children}</DensityContext.Provider>\n    </ThemeContext.Provider>\n  );\n}\n\n/**\n * useTheme — access theme state from any component inside <ThemeProvider>.\n * Throws if used outside the provider — fail-fast.\n */\nfunction useTheme(): ThemeContextValue {\n  const ctx = useContext(ThemeContext);\n  if (!ctx) {\n    throw new Error(\"useTheme must be used inside <ThemeProvider>.\");\n  }\n  return ctx;\n}\n\nexport { ThemeProvider, useTheme };\n"
     },
     {
       "path": "themes/theme-switcher.tsx",

package/registry/r/theme-script.json

@@ -12,7 +12,7 @@
       "path": "themes/theme-script.tsx",
       "type": "registry:lib",
       "target": "themes/theme-script.tsx",
-      "content": "/**\n * ThemeScript — inline `<script>` for SSR-safe theme initialization.\n *\n * Renders a synchronous script that runs BEFORE React hydration. It reads the\n * persisted theme + mode from localStorage (or falls back to the defaults) and\n * sets `data-theme` / `data-mode` on `<html>`, plus the `.dark` class when\n * mode is dark. This eliminates FOUC and avoids hydration mismatch warnings\n * when the user's persisted choice differs from the SSR defaults.\n *\n * Place this in `<head>` ABOVE `<body>`. The component does not need to live\n * inside `<ThemeProvider>`.\n *\n * Security: every interpolated value is passed through `safe()`, which both\n * `JSON.stringify`s the value AND escapes `<` to `<`. The `<` escape is\n * REQUIRED because `JSON.stringify` alone does NOT escape `/`, so a payload\n * like `\"</script><script>alert(1)</script>\"` would otherwise break out of\n * the inline `<script>` tag even though it stays inside a JS string literal.\n * (The browser tokenizes `</script>` at the HTML layer before JS parses.)\n *\n * Example (Next.js App Router): see docs/design-system.md → SSR section.\n * Pass `defaultTheme` and `defaultMode` to align with the consumer's\n * preferred initial state. Always wrap the root in `<html\n * suppressHydrationWarning>` to silence the expected one-render diff.\n */\nimport type { JSX } from \"react\";\nimport type { ThemeMode } from \"@/themes/types\";\n\ninterface ThemeScriptProps {\n  /** Theme name to apply when no persisted value exists. Default `\"violet-forge\"`. */\n  defaultTheme?: string;\n  /** Mode to apply when no persisted value exists. Default `\"dark\"`. */\n  defaultMode?: ThemeMode;\n  /**\n   * localStorage namespace. Must match the `storageKey` passed to\n   * `<ThemeProvider>`. Default `\"theo-ui:theme\"`. Pass `null` to disable\n   * persistence reads (the script will always apply defaults).\n   */\n  storageKey?: string | null;\n}\n\n/**\n * Encode a value for safe embedding inside an inline `<script>` block.\n *\n * `JSON.stringify` does NOT escape `/` by default, so `\"</script>\"` survives\n * as the literal three-character sequence inside the resulting string. When\n * that string is then rendered inside `<script>...</script>`, the browser's\n * HTML tokenizer sees `</script>` and ends the script tag — regardless of\n * whether the JS parser would have kept it inside a string. Escaping `<` to\n * its Unicode escape `<` preserves JS semantics (the JS parser still\n * resolves the escape to `<`) while making the HTML tokenizer happy.\n *\n * Reference: OWASP \"JSON-in-script\" guidance; React's own server-renderer\n * applies the same escape for inline JSON.\n */\nfunction safe(value: unknown): string {\n  return JSON.stringify(value).replace(/</g, \"\\\\u003c\");\n}\n\nfunction buildScript(\n  defaultTheme: string,\n  defaultMode: ThemeMode,\n  storageKey: string | null,\n): string {\n  const k = safe(storageKey);\n  const t = safe(defaultTheme);\n  const m = safe(defaultMode);\n  return `(function(){try{var k=${k};var d=document.documentElement;var t=null;var m=null;if(k){t=localStorage.getItem(k+\":name\");m=localStorage.getItem(k+\":mode\");}d.setAttribute(\"data-theme\",t||${t});d.setAttribute(\"data-mode\",m||${m});if((m||${m})===\"dark\"){d.classList.add(\"dark\");}}catch(e){}})();`;\n}\n\nfunction ThemeScript({\n  defaultTheme = \"violet-forge\",\n  defaultMode = \"dark\",\n  storageKey = \"theo-ui:theme\",\n}: ThemeScriptProps): JSX.Element {\n  const code = buildScript(defaultTheme, defaultMode, storageKey);\n  // biome-ignore lint/security/noDangerouslySetInnerHtml: payload is JSON.stringify-encoded literals (no user input); intentional for SSR theme bootstrap before React hydrates\n  return <script suppressHydrationWarning dangerouslySetInnerHTML={{ __html: code }} />;\n}\n\nexport { ThemeScript };\n"
+      "content": "/**\n * ThemeScript — inline `<script>` for SSR-safe theme initialization.\n *\n * Renders a synchronous script that runs BEFORE React hydration. It reads the\n * persisted theme + mode from localStorage (or falls back to the defaults) and\n * sets `data-theme` / `data-mode` on `<html>`, plus the `.dark` class when\n * mode is dark. This eliminates FOUC and avoids hydration mismatch warnings\n * when the user's persisted choice differs from the SSR defaults.\n *\n * Place this in `<head>` ABOVE `<body>`. The component does not need to live\n * inside `<ThemeProvider>`.\n *\n * Security: every interpolated value is passed through `safe()`, which both\n * `JSON.stringify`s the value AND escapes `<` to `<`. The `<` escape is\n * REQUIRED because `JSON.stringify` alone does NOT escape `/`, so a payload\n * like `\"</script><script>alert(1)</script>\"` would otherwise break out of\n * the inline `<script>` tag even though it stays inside a JS string literal.\n * (The browser tokenizes `</script>` at the HTML layer before JS parses.)\n *\n * Example (Next.js App Router): see docs/design-system.md → SSR section.\n * Pass `defaultTheme` and `defaultMode` to align with the consumer's\n * preferred initial state. Always wrap the root in `<html\n * suppressHydrationWarning>` to silence the expected one-render diff.\n */\nimport type { JSX } from \"react\";\nimport type { ThemeMode } from \"@/themes/types\";\n\ninterface ThemeScriptProps {\n  /** Theme name to apply when no persisted value exists. Default `\"violet-forge\"`. */\n  defaultTheme?: string;\n  /** Mode to apply when no persisted value exists. Default `\"dark\"`. */\n  defaultMode?: ThemeMode;\n  /**\n   * Density to apply when no persisted value exists. Default `\"comfortable\"`.\n   * Mirrors `ThemeProvider`'s `defaultDensity` so the inline-script and\n   * the React provider agree on the SSR-default density (and the\n   * `data-density` attribute set by this script matches what\n   * `ThemeProvider` promotes via its post-mount hydration effect).\n   */\n  defaultDensity?: \"compact\" | \"comfortable\" | \"spacious\";\n  /**\n   * localStorage namespace. Must match the `storageKey` passed to\n   * `<ThemeProvider>`. Default `\"theo-ui:theme\"`. Pass `null` to disable\n   * persistence reads (the script will always apply defaults).\n   */\n  storageKey?: string | null;\n}\n\n/**\n * Encode a value for safe embedding inside an inline `<script>` block.\n *\n * `JSON.stringify` does NOT escape `/` by default, so `\"</script>\"` survives\n * as the literal three-character sequence inside the resulting string. When\n * that string is then rendered inside `<script>...</script>`, the browser's\n * HTML tokenizer sees `</script>` and ends the script tag — regardless of\n * whether the JS parser would have kept it inside a string. Escaping `<` to\n * its Unicode escape `<` preserves JS semantics (the JS parser still\n * resolves the escape to `<`) while making the HTML tokenizer happy.\n *\n * Reference: OWASP \"JSON-in-script\" guidance; React's own server-renderer\n * applies the same escape for inline JSON.\n */\nfunction safe(value: unknown): string {\n  return JSON.stringify(value).replace(/</g, \"\\\\u003c\");\n}\n\nfunction buildScript(\n  defaultTheme: string,\n  defaultMode: ThemeMode,\n  defaultDensity: \"compact\" | \"comfortable\" | \"spacious\",\n  storageKey: string | null,\n): string {\n  const k = safe(storageKey);\n  const t = safe(defaultTheme);\n  const m = safe(defaultMode);\n  const dn = safe(defaultDensity);\n  return `(function(){try{var k=${k};var d=document.documentElement;var t=null;var m=null;var dn=null;if(k){t=localStorage.getItem(k+\":name\");m=localStorage.getItem(k+\":mode\");dn=localStorage.getItem(k+\":density\");}d.setAttribute(\"data-theme\",t||${t});d.setAttribute(\"data-mode\",m||${m});d.setAttribute(\"data-density\",dn||${dn});if((m||${m})===\"dark\"){d.classList.add(\"dark\");}}catch(e){}})();`;\n}\n\nfunction ThemeScript({\n  defaultTheme = \"violet-forge\",\n  defaultMode = \"dark\",\n  defaultDensity = \"comfortable\",\n  storageKey = \"theo-ui:theme\",\n}: ThemeScriptProps): JSX.Element {\n  const code = buildScript(defaultTheme, defaultMode, defaultDensity, storageKey);\n  // biome-ignore lint/security/noDangerouslySetInnerHtml: payload is JSON.stringify-encoded literals (no user input); intentional for SSR theme bootstrap before React hydrates\n  return <script suppressHydrationWarning dangerouslySetInnerHTML={{ __html: code }} />;\n}\n\nexport { ThemeScript };\n"
     }
   ]
 }

package/registry/r/usage-meter.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
+  "name": "usage-meter",
+  "type": "registry:ui",
+  "title": "UsageMeter",
+  "description": "Multi-metric stacked usage card for PaaS dashboards. Renders N metrics (data transfer, requests, build minutes, seats, …) each with label + value/max + Progress bar. Supports custom per-metric formatter, over-quota warning, and a compact bars-only mode. PaaS-shape sibling of CostMeter.",
+  "dependencies": [],
+  "registryDependencies": [
+    "https://usetheodev.github.io/theo-ui/r/cn.json",
+    "https://usetheodev.github.io/theo-ui/r/progress.json",
+    "https://usetheodev.github.io/theo-ui/r/tailwind-preset.json"
+  ],
+  "files": [
+    {
+      "path": "components/composites/usage-meter/usage-meter.tsx",
+      "type": "registry:ui",
+      "target": "components/ui/usage-meter.tsx",
+      "content": "import { forwardRef } from \"react\";\nimport type { HTMLAttributes, ReactNode } from \"react\";\nimport { cn } from \"@/lib/cn\";\nimport { Progress } from \"@/components/ui/progress\";\n\n/**\n * UsageMeter — multi-metric stacked usage card.\n *\n * PaaS-shape sibling of `<CostMeter>` (which is mono-USD). Displays N\n * metrics with arbitrary units (GB, requests, build-minutes, seats) per\n * the reference TheoCloud dashboard mockup. Each row = label + value/max\n * + `<Progress>` fill bar.\n *\n * Composition:\n *\n *   <UsageMeter\n *     title=\"Last 30 days\"\n *     action={<Badge variant=\"outline\">Upgrade</Badge>}\n *     metrics={[\n *       { label: \"Fast Data Transfer\", value: 0, max: 100, unit: \"GB\" },\n *       { label: \"Edge Requests\", value: 0, max: 1_000_000, unit: \"req\",\n *         formatter: (v, m) => `${v} / ${m >= 1e6 ? `${m / 1e6}M` : m}` },\n *     ]}\n *   />\n *\n * Over-quota detection: when `value > max`, the value text gets the\n * `text-warning` class and the underlying `<Progress>` uses\n * `intent=\"warning\"` (bar fills 100% via Progress's own clamping).\n *\n * `compact` mode renders only the bars (no label/value text) — useful in\n * narrow nav-bar slots.\n *\n * Imports the sibling `<Progress>` primitive via relative path (per RFC\n * dashboard-paas-primitives D3) — primitives must not depend on the\n * `@usetheo/ui` barrel.\n */\n\nexport interface UsageMetric {\n  /** Display label (e.g. \"Fast Data Transfer\"). */\n  label: ReactNode;\n  /** Current consumption. */\n  value: number;\n  /** Maximum allowed in the current period. */\n  max: number;\n  /** Unit string (e.g. \"GB\", \"req\", \"min\"). Rendered after value/max. */\n  unit?: string;\n  /** Optional custom formatter — overrides default `${value} / ${max} ${unit}`. */\n  formatter?: (value: number, max: number, unit?: string) => string;\n}\n\nexport interface UsageMeterProps extends Omit<HTMLAttributes<HTMLDivElement>, \"title\"> {\n  /** Card title (e.g. \"Last 30 days\", \"This billing period\"). */\n  title?: ReactNode;\n  /** Optional right-aligned action slot (e.g. an Upgrade Badge or Button). */\n  action?: ReactNode;\n  /** Array of metrics to display. Order preserved. */\n  metrics: UsageMetric[];\n  /** When true, show only the bars without label/value text (sparkline mode). */\n  compact?: boolean;\n}\n\nfunction defaultFormat(value: number, max: number, unit?: string): string {\n  return `${value} / ${max}${unit ? ` ${unit}` : \"\"}`;\n}\n\nfunction metricAriaLabel(metric: UsageMetric, formatted: string): string {\n  // Label may be a ReactNode; coerce to string for aria-label.\n  const label = typeof metric.label === \"string\" ? metric.label : \"metric\";\n  return `${label}: ${formatted}`;\n}\n\nconst UsageMeter = forwardRef<HTMLDivElement, UsageMeterProps>(\n  ({ className, title, action, metrics, compact = false, ...props }, ref) => {\n    const hasHeader = Boolean(title) || Boolean(action);\n    return (\n      <div\n        ref={ref}\n        className={cn(\n          \"grid gap-3 rounded-xl border border-border bg-card p-4\",\n          compact && \"gap-2\",\n          className,\n        )}\n        data-theo-usage-meter=\"\"\n        {...props}\n      >\n        {hasHeader ? (\n          <header className=\"flex items-baseline justify-between gap-3\">\n            {title ? (\n              <span\n                className={cn(\n                  \"font-mono text-label-caps text-muted-foreground uppercase tracking-wider\",\n                )}\n              >\n                {title}\n              </span>\n            ) : (\n              <span />\n            )}\n            {action ? <div className=\"shrink-0\">{action}</div> : null}\n          </header>\n        ) : null}\n\n        {metrics.map((metric, idx) => {\n          const overQuota = metric.value > metric.max;\n          const fmt = metric.formatter ?? defaultFormat;\n          const formatted = fmt(metric.value, metric.max, metric.unit);\n          const intent = overQuota ? \"warning\" : \"default\";\n          // Each metric needs a stable key. Without a unique id field we\n          // synthesize one from label + idx — duplicates resolve via the\n          // index suffix.\n          const key = `${typeof metric.label === \"string\" ? metric.label : \"metric\"}-${idx}`;\n\n          if (compact) {\n            return (\n              <Progress\n                key={key}\n                value={metric.value}\n                max={metric.max}\n                intent={intent}\n                aria-label={metricAriaLabel(metric, formatted)}\n              />\n            );\n          }\n\n          return (\n            <div key={key} className=\"grid gap-1.5\">\n              <div className=\"flex items-baseline justify-between gap-3 text-body-sm\">\n                <span className=\"truncate text-muted-foreground\">{metric.label}</span>\n                <span\n                  className={cn(\n                    \"shrink-0 font-mono tabular-nums\",\n                    overQuota ? \"text-warning\" : \"text-foreground\",\n                  )}\n                >\n                  {formatted}\n                </span>\n              </div>\n              <Progress\n                value={metric.value}\n                max={metric.max}\n                intent={intent}\n                aria-label={metricAriaLabel(metric, formatted)}\n              />\n            </div>\n          );\n        })}\n      </div>\n    );\n  },\n);\nUsageMeter.displayName = \"UsageMeter\";\n\nexport { UsageMeter };\n"
+    }
+  ]
+}