From e8147be0ec88bfacac0474f3b72edd38ee992b4c Mon Sep 17 00:00:00 2001
From: Jonas Pfalzgraf <jolun.swtor@gmail.com>
Date: Fri, 31 Jul 2026 12:02:49 +0000
Subject: [PATCH 1/5] update

---
 AGENT.md                                      |  67 +++
 README.md                                     |  20 +-
 bun.lock                                      | 511 ++++++++++++++----
 docs/.vitepress/config.ts                     |  10 +
 docs/components/avatar-group.md               |  87 +++
 docs/components/banner.md                     |  93 ++++
 docs/components/button-group.md               |  75 +++
 docs/components/file-upload.md                | 116 ++++
 docs/components/index.md                      |  22 +-
 docs/components/kbd.md                        |  81 +++
 docs/components/number-input.md               | 126 +++++
 docs/components/popover.md                    |  97 ++++
 docs/components/rating.md                     | 103 ++++
 docs/components/stepper.md                    | 103 ++++
 docs/components/timeline.md                   |  96 ++++
 docs/guide/installation.md                    |   4 +-
 docs/guide/migration-from-1-1-0.md            |   2 +-
 package.json                                  |  38 +-
 src/components/accordion/BqAccordion.ts       |   8 +-
 src/components/alert/BqAlert.ts               |  11 +-
 src/components/avatar-group/BqAvatarGroup.ts  | 154 ++++++
 src/components/avatar-group/index.ts          |   1 +
 src/components/avatar/BqAvatar.ts             |   8 +-
 src/components/badge/BqBadge.ts               |   8 +-
 src/components/banner/BqBanner.ts             | 123 +++++
 src/components/banner/index.ts                |   1 +
 src/components/breadcrumbs/BqBreadcrumbs.ts   |  11 +-
 src/components/button-group/BqButtonGroup.ts  | 115 ++++
 src/components/button-group/index.ts          |   1 +
 src/components/button/BqButton.ts             |  11 +-
 src/components/card/BqCard.ts                 |   8 +-
 src/components/checkbox/BqCheckbox.ts         |  11 +-
 src/components/chip/BqChip.ts                 |  11 +-
 src/components/dialog/BqDialog.ts             | 101 +---
 src/components/divider/BqDivider.ts           |   8 +-
 src/components/drawer/BqDrawer.ts             | 100 +---
 .../dropdown-menu/BqDropdownMenu.ts           | 159 ++----
 src/components/empty-state/BqEmptyState.ts    |   8 +-
 src/components/file-upload/BqFileUpload.ts    | 371 +++++++++++++
 src/components/file-upload/index.ts           |   1 +
 src/components/icon-button/BqIconButton.ts    |   8 +-
 src/components/index.ts                       |  10 +
 src/components/input/BqInput.ts               |   8 +-
 src/components/kbd/BqKbd.ts                   | 104 ++++
 src/components/kbd/index.ts                   |   1 +
 src/components/number-input/BqNumberInput.ts  | 346 ++++++++++++
 src/components/number-input/index.ts          |   1 +
 src/components/pagination/BqPagination.ts     |  11 +-
 src/components/popover/BqPopover.ts           | 242 +++++++++
 src/components/popover/index.ts               |   1 +
 src/components/progress/BqProgress.ts         |   8 +-
 src/components/radio/BqRadio.ts               |  11 +-
 src/components/rating/BqRating.ts             | 214 ++++++++
 src/components/rating/index.ts                |   1 +
 .../segmented-control/BqSegmentedControl.ts   |   8 +-
 src/components/select/BqSelect.ts             |   8 +-
 src/components/skeleton/BqSkeleton.ts         |   8 +-
 src/components/slider/BqSlider.ts             |  11 +-
 src/components/spinner/BqSpinner.ts           |   8 +-
 src/components/stat-card/BqStatCard.ts        |  10 +-
 src/components/stepper/BqStepper.ts           | 247 +++++++++
 src/components/stepper/index.ts               |   1 +
 src/components/switch/BqSwitch.ts             |  11 +-
 src/components/table/BqTable.ts               |  11 +-
 src/components/tabs/BqTabs.ts                 |   8 +-
 src/components/textarea/BqTextarea.ts         |   8 +-
 src/components/timeline/BqTimeline.ts         | 144 +++++
 src/components/timeline/index.ts              |   1 +
 src/components/toast/BqToast.ts               |  11 +-
 src/components/tooltip/BqTooltip.ts           | 112 ++--
 src/i18n/en.ts                                |  38 ++
 src/index.ts                                  |  20 +
 src/utils/component.ts                        | 167 ++++++
 src/utils/dom.ts                              |  74 +++
 src/utils/index.ts                            |  13 +-
 src/utils/styles.ts                           |  79 ++-
 stories/avatar-group.stories.ts               |  32 ++
 stories/banner.stories.ts                     |  55 ++
 stories/button-group.stories.ts               |  36 ++
 stories/file-upload.stories.ts                |  44 ++
 stories/kbd.stories.ts                        |  33 ++
 stories/number-input.stories.ts               |  60 ++
 stories/popover.stories.ts                    |  49 ++
 stories/rating.stories.ts                     |  46 ++
 stories/stepper.stories.ts                    |  40 ++
 stories/timeline.stories.ts                   |  58 ++
 tests/component-utils.test.ts                 | 191 +++++++
 tests/new-components.test.ts                  | 461 ++++++++++++++++
 tests/styles.test.ts                          |  74 +++
 89 files changed, 5440 insertions(+), 584 deletions(-)
 create mode 100644 docs/components/avatar-group.md
 create mode 100644 docs/components/banner.md
 create mode 100644 docs/components/button-group.md
 create mode 100644 docs/components/file-upload.md
 create mode 100644 docs/components/kbd.md
 create mode 100644 docs/components/number-input.md
 create mode 100644 docs/components/popover.md
 create mode 100644 docs/components/rating.md
 create mode 100644 docs/components/stepper.md
 create mode 100644 docs/components/timeline.md
 create mode 100644 src/components/avatar-group/BqAvatarGroup.ts
 create mode 100644 src/components/avatar-group/index.ts
 create mode 100644 src/components/banner/BqBanner.ts
 create mode 100644 src/components/banner/index.ts
 create mode 100644 src/components/button-group/BqButtonGroup.ts
 create mode 100644 src/components/button-group/index.ts
 create mode 100644 src/components/file-upload/BqFileUpload.ts
 create mode 100644 src/components/file-upload/index.ts
 create mode 100644 src/components/kbd/BqKbd.ts
 create mode 100644 src/components/kbd/index.ts
 create mode 100644 src/components/number-input/BqNumberInput.ts
 create mode 100644 src/components/number-input/index.ts
 create mode 100644 src/components/popover/BqPopover.ts
 create mode 100644 src/components/popover/index.ts
 create mode 100644 src/components/rating/BqRating.ts
 create mode 100644 src/components/rating/index.ts
 create mode 100644 src/components/stepper/BqStepper.ts
 create mode 100644 src/components/stepper/index.ts
 create mode 100644 src/components/timeline/BqTimeline.ts
 create mode 100644 src/components/timeline/index.ts
 create mode 100644 src/utils/component.ts
 create mode 100644 stories/avatar-group.stories.ts
 create mode 100644 stories/banner.stories.ts
 create mode 100644 stories/button-group.stories.ts
 create mode 100644 stories/file-upload.stories.ts
 create mode 100644 stories/kbd.stories.ts
 create mode 100644 stories/number-input.stories.ts
 create mode 100644 stories/popover.stories.ts
 create mode 100644 stories/rating.stories.ts
 create mode 100644 stories/stepper.stories.ts
 create mode 100644 stories/timeline.stories.ts
 create mode 100644 tests/component-utils.test.ts
 create mode 100644 tests/new-components.test.ts
 create mode 100644 tests/styles.test.ts

diff --git a/AGENT.md b/AGENT.md
index 132fd19..4128e35 100644
--- a/AGENT.md
+++ b/AGENT.md
@@ -22,6 +22,73 @@ This repository is `@bquery/ui`, a framework-agnostic Web Components library bui
 5. Treat import side effects (`import '@bquery/ui'`) and per-component entrypoints (`@bquery/ui/components/<name>`) as the canonical registration model; `registerAll()` is deprecated compatibility-only.
 6. When touching versioned install snippets or release-facing docs, keep pinned CDN examples aligned with the current package version in `package.json`.
 
+## Component conventions
+
+### Styles
+
+Declare styles with the `css` tagged template from `@bquery/bquery/component` and
+interpolate the shared fragments from `src/utils/styles.ts`:
+
+```ts
+import { component, css, html } from '@bquery/bquery/component';
+import { baseStyles, reset, srOnly } from '../../utils/styles.js';
+
+styles: css`
+  ${baseStyles}
+  ${reset}
+  :host { display: block; }
+`
+```
+
+This matters for more than tidiness. A `css` payload is handed to
+`adoptedStyleSheets`, so the stylesheet is constructed **once per component and
+shared by every instance**, and re-renders no longer rewrite it. A plain string
+falls back to a per-instance `<style>` element whose ~5.6 KB of token/theme CSS
+is duplicated per element and rewritten on every render.
+
+Only `ComponentStyles` values survive interpolation intact — `css` escapes
+interpolated *strings*, which would corrupt raw CSS. Use `rawCss()` from
+`src/utils/styles.ts` to wrap CSS text generated at runtime.
+
+### Lifecycle and teardown
+
+Use the helpers in `src/utils/component.ts` rather than stashing handlers on the
+host element:
+
+```ts
+connected() {
+  const el = host<MyState>(this);      // typed setState/getState/setProp
+  const scope = bind(el);
+  scope.on(document, 'keydown', onKeyDown);   // removal registered for you
+  scope.timeout(fn, 200);                      // cleared on disconnect
+},
+disconnected() {
+  release(this);                               // unwinds everything
+},
+```
+
+Anything reaching outside the component — `document`/`window` listeners, timers,
+`MutationObserver`s, form proxies, `aria-*` written onto slotted light-DOM
+elements — must be registered on the scope. `tests/component-utils.test.ts`
+asserts that the overlay components leave no document listeners behind.
+
+Use `store(owner, init)` when a value created in `connected()` has to stay
+reachable from `updated()`.
+
+### Sanitizer allowlist
+
+Rendered markup is sanitized. The framework's base allowlist covers `part`,
+`aria-*`, `data-*` and the usual form attributes, but not everything — `accept`,
+`datetime` and `inputmode` each needed an explicit `sanitize.allowAttributes`
+entry. If an attribute silently disappears from rendered output, this is why.
+
+### Shadow-DOM state and re-renders
+
+Every render replaces the shadow root's contents. Anything written into the
+shadow root imperatively (for example the file-upload file list, or the
+avatar-group overflow counter, which depend on light-DOM children that `render`
+cannot see) must be repainted from `updated()`.
+
 ## Setup and validation
 
 Install dependencies with Bun:
diff --git a/README.md b/README.md
index 9fb38ea..6acb8d0 100644
--- a/README.md
+++ b/README.md
@@ -28,14 +28,14 @@ It is designed to give teams the kind of component coverage, polish, accessibili
 
 The current library covers the core component categories developers expect from modern UI libraries:
 
-| Category         | Components                                                     |
-| ---------------- | -------------------------------------------------------------- |
-| **Actions**      | Button, Icon Button                                            |
-| **Forms**        | Input, Textarea, Select, Checkbox, Radio, Switch, Slider, Chip |
-| **Navigation**   | Tabs, Accordion, Breadcrumbs, Pagination                       |
-| **Data Display** | Card, Badge, Avatar, Table, Divider, Empty State, Stat Card    |
-| **Feedback**     | Alert, Progress, Spinner, Skeleton, Tooltip, Toast             |
-| **Overlays**     | Dialog, Drawer, Dropdown Menu                                  |
+| Category         | Components                                                                                                            |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------- |
+| **Actions**      | Button, Icon Button, Button Group                                                                                     |
+| **Forms**        | Input, Number Input, Textarea, Select, Segmented Control, Checkbox, Radio, Switch, Slider, Chip, Rating, File Upload   |
+| **Navigation**   | Tabs, Accordion, Breadcrumbs, Pagination, Stepper                                                                     |
+| **Data Display** | Card, Badge, Avatar, Avatar Group, Table, Divider, Empty State, Stat Card, Timeline, Kbd                               |
+| **Feedback**     | Alert, Banner, Progress, Spinner, Skeleton, Tooltip, Toast                                                            |
+| **Overlays**     | Dialog, Drawer, Dropdown Menu, Popover                                                                                |
 
 For the full catalog and feature coverage, see [`docs/components/index.md`](./docs/components/index.md).
 
@@ -69,10 +69,10 @@ import '@bquery/ui';
 
 ```html
 <!-- UMD -->
-<script src="https://cdn.jsdelivr.net/npm/@bquery/ui@1.10.0/dist/index.umd.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@bquery/ui@1.15.0/dist/index.umd.js"></script>
 
 <!-- IIFE -->
-<script src="https://cdn.jsdelivr.net/npm/@bquery/ui@1.10.0/dist/index.iife.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@bquery/ui@1.15.0/dist/index.iife.js"></script>
 ```
 
 The UMD and IIFE bundles register all components on load and expose the library on `window.BQueryUI`.
diff --git a/bun.lock b/bun.lock
index 74012cd..6279449 100644
--- a/bun.lock
+++ b/bun.lock
@@ -5,24 +5,29 @@
     "": {
       "name": "@bquery/ui",
       "devDependencies": {
-        "@bquery/bquery": "^1.11.0",
-        "@storybook/addon-docs": "^10.3.6",
-        "@storybook/web-components-vite": "^10.3.6",
-        "@tailwindcss/postcss": "^4.2.4",
-        "@types/node": "^25.6.0",
-        "autoprefixer": "^10.5.0",
-        "bun-types": "^1.3.13",
-        "happy-dom": "^20.9.0",
-        "postcss": "^8.5.12",
-        "storybook": "^10.3.6",
-        "tailwindcss": "^4.2.4",
+        "@bquery/bquery": "^1.15.1",
+        "@storybook/addon-docs": "^10.5.5",
+        "@storybook/web-components-vite": "^10.5.5",
+        "@tailwindcss/postcss": "^4.3.3",
+        "@types/node": "^26.1.2",
+        "@typescript-eslint/eslint-plugin": "^8.65.0",
+        "@typescript-eslint/parser": "^8.65.0",
+        "autoprefixer": "^10.5.4",
+        "bun-types": "^1.3.14",
+        "eslint": "^10.8.0",
+        "eslint-config-prettier": "^10.1.8",
+        "globals": "^17.8.0",
+        "happy-dom": "^20.11.1",
+        "postcss": "^8.5.25",
+        "storybook": "^10.5.5",
+        "tailwindcss": "^4.3.3",
         "typescript": "^6.0.3",
-        "vite": "^8.0.10",
-        "vite-plugin-dts": "^5.0.0",
+        "vite": "^8.2.0",
+        "vite-plugin-dts": "^5.0.3",
         "vitepress": "^1.6.4",
       },
       "peerDependencies": {
-        "@bquery/bquery": "^1.11.0",
+        "@bquery/bquery": "^1.15.1",
       },
     },
   },
@@ -79,7 +84,7 @@
 
     "@babel/types": ["@babel/types@7.29.0", "", { "dependencies": { "@babel/helper-string-parser": "^7.27.1", "@babel/helper-validator-identifier": "^7.28.5" } }, "sha512-LwdZHpScM4Qz8Xw2iKSzS+cfglZzJGvofQICy7W7v4caru4EaAmyUuO6BGrbyQ2mYV11W0U8j5mBhd14dd3B0A=="],
 
-    "@bquery/bquery": ["@bquery/bquery@1.11.0", "", {}, "sha512-EkbeMX7YK4IwiER/CU72GvmYAQhHagOczoT0hQB/v7C668K7xA55QzGvYAfFpqhLa1NfppZ4kEoYtOue5g34SQ=="],
+    "@bquery/bquery": ["@bquery/bquery@1.15.1", "", { "bin": { "bquery-view-compile": "bin/bquery-view-compile.mjs", "bquery-i18n": "bin/bquery-i18n.mjs" } }, "sha512-DRuVZCbzppo1pPtxbTC3zYkFVkpPvqut4x5hd1FqlrTQUcYmQplruMvDUtuqtJU7mNNGXyez5z/87urW7ioOQQ=="],
 
     "@docsearch/css": ["@docsearch/css@3.8.2", "", {}, "sha512-y05ayQFyUmCXze79+56v/4HpycYF3uFqB78pLPrSV5ZKAlDuIAAJNhaRi8tTdRNXh05yxX/TyNnzD6LwSM89vQ=="],
 
@@ -87,9 +92,9 @@
 
     "@docsearch/react": ["@docsearch/react@3.8.2", "", { "dependencies": { "@algolia/autocomplete-core": "1.17.7", "@algolia/autocomplete-preset-algolia": "1.17.7", "@docsearch/css": "3.8.2", "algoliasearch": "^5.14.2" }, "peerDependencies": { "@types/react": ">= 16.8.0 < 19.0.0", "react": ">= 16.8.0 < 19.0.0", "react-dom": ">= 16.8.0 < 19.0.0", "search-insights": ">= 1 < 3" }, "optionalPeers": ["@types/react", "react", "react-dom", "search-insights"] }, "sha512-xCRrJQlTt8N9GU0DG4ptwHRkfnSnD/YpdeaXe02iKfqs97TkZJv60yE+1eq/tjPcVnTW8dP5qLP7itifFVV5eg=="],
 
-    "@emnapi/core": ["@emnapi/core@1.10.0", "", { "dependencies": { "@emnapi/wasi-threads": "1.2.1", "tslib": "^2.4.0" } }, "sha512-yq6OkJ4p82CAfPl0u9mQebQHKPJkY7WrIuk205cTYnYe+k2Z8YBh11FrbRG/H6ihirqcacOgl2BIO8oyMQLeXw=="],
+    "@emnapi/core": ["@emnapi/core@1.9.2", "", { "dependencies": { "@emnapi/wasi-threads": "1.2.1", "tslib": "^2.4.0" } }, "sha512-UC+ZhH3XtczQYfOlu3lNEkdW/p4dsJ1r/bP7H8+rhao3TTTMO1ATq/4DdIi23XuGoFY+Cz0JmCbdVl0hz9jZcA=="],
 
-    "@emnapi/runtime": ["@emnapi/runtime@1.10.0", "", { "dependencies": { "tslib": "^2.4.0" } }, "sha512-ewvYlk86xUoGI0zQRNq/mC+16R1QeDlKQy21Ki3oSYXNgLb45GV1P6A0M+/s6nyCuNDqe5VpaY84BzXGwVbwFA=="],
+    "@emnapi/runtime": ["@emnapi/runtime@1.9.2", "", { "dependencies": { "tslib": "^2.4.0" } }, "sha512-3U4+MIWHImeyu1wnmVygh5WlgfYDtyf0k8AbLhMFxOipihf6nrWC4syIm/SwEeec0mNSafiiNnMJwbza/Is6Lw=="],
 
     "@emnapi/wasi-threads": ["@emnapi/wasi-threads@1.2.1", "", { "dependencies": { "tslib": "^2.4.0" } }, "sha512-uTII7OYF+/Mes/MrcIOYp5yOtSMLBWSIoLPpcgwipoiKbli6k322tcoFsxoIIxPDqW01SQGAgko4EzZi2BNv2w=="],
 
@@ -139,6 +144,30 @@
 
     "@esbuild/win32-x64": ["@esbuild/win32-x64@0.21.5", "", { "os": "win32", "cpu": "x64" }, "sha512-tQd/1efJuzPC6rCFwEvLtci/xNFcTZknmXs98FYDfGE4wP9ClFV98nyKrzJKVPMhdDnjzLhdUyMX4PsQAPjwIw=="],
 
+    "@eslint-community/eslint-utils": ["@eslint-community/eslint-utils@4.10.1", "", { "dependencies": { "eslint-visitor-keys": "^3.4.3" }, "peerDependencies": { "eslint": "^6.0.0 || ^7.0.0 || >=8.0.0" } }, "sha512-cuadcxVFE8sDK6iWJbs8Sn0av2Nrh2QSGQhVlBW9AaAHqHwjWsZHT8LJ4hFGPh7ASBV2deFdM7H/DPjulmh8rg=="],
+
+    "@eslint-community/regexpp": ["@eslint-community/regexpp@4.12.2", "", {}, "sha512-EriSTlt5OC9/7SXkRSCAhfSxxoSUgBm33OH+IkwbdpgoqsSsUg7y3uh+IICI/Qg4BBWr3U2i39RpmycbxMq4ew=="],
+
+    "@eslint/config-array": ["@eslint/config-array@0.23.5", "", { "dependencies": { "@eslint/object-schema": "^3.0.5", "debug": "^4.3.1", "minimatch": "^10.2.4" } }, "sha512-Y3kKLvC1dvTOT+oGlqNQ1XLqK6D1HU2YXPc52NmAlJZbMMWDzGYXMiPRJ8TYD39muD/OTjlZmNJ4ib7dvSrMBA=="],
+
+    "@eslint/config-helpers": ["@eslint/config-helpers@0.7.0", "", { "dependencies": { "@eslint/core": "^1.2.1" } }, "sha512-DObd/KKUsU+FaFv4PLxSRenpXfQWmPXXP3pPZ6/K1PCrMu2vQpMDMuQe/BqYeoLcz8ro0bVDF1RxOJgfVEdhUw=="],
+
+    "@eslint/core": ["@eslint/core@1.2.1", "", { "dependencies": { "@types/json-schema": "^7.0.15" } }, "sha512-MwcE1P+AZ4C6DWlpin/OmOA54mmIZ/+xZuJiQd4SyB29oAJjN30UW9wkKNptW2ctp4cEsvhlLY/CsQ1uoHDloQ=="],
+
+    "@eslint/object-schema": ["@eslint/object-schema@3.0.5", "", {}, "sha512-vqTaUEgxzm+YDSdElad6PiRoX4t8VGDjCtt05zn4nU810UIx/uNEV7/lZJ6KwFThKZOzOxzXy48da+No7HZaMw=="],
+
+    "@eslint/plugin-kit": ["@eslint/plugin-kit@0.7.2", "", { "dependencies": { "@eslint/core": "^1.2.1", "levn": "^0.4.1" } }, "sha512-+CNAzxglkrpNf/kKywqQfk74QjtceuOE7Qm+AF8miRvPF/wmmK5+OJOgVh3AVTT3RP2mH3+FOaxlE5v72owk0A=="],
+
+    "@humanfs/core": ["@humanfs/core@0.19.2", "", { "dependencies": { "@humanfs/types": "^0.15.0" } }, "sha512-UhXNm+CFMWcbChXywFwkmhqjs3PRCmcSa/hfBgLIb7oQ5HNb1wS0icWsGtSAUNgefHeI+eBrA8I1fxmbHsGdvA=="],
+
+    "@humanfs/node": ["@humanfs/node@0.16.8", "", { "dependencies": { "@humanfs/core": "^0.19.2", "@humanfs/types": "^0.15.0", "@humanwhocodes/retry": "^0.4.0" } }, "sha512-gE1eQNZ3R++kTzFUpdGlpmy8kDZD/MLyHqDwqjkVQI0JMdI1D51sy1H958PNXYkM2rAac7e5/CnIKZrHtPh3BQ=="],
+
+    "@humanfs/types": ["@humanfs/types@0.15.0", "", {}, "sha512-ZZ1w0aoQkwuUuC7Yf+7sdeaNfqQiiLcSRbfI08oAxqLtpXQr9AIVX7Ay7HLDuiLYAaFPu8oBYNq/QIi9URHJ3Q=="],
+
+    "@humanwhocodes/module-importer": ["@humanwhocodes/module-importer@1.0.1", "", {}, "sha512-bxveV4V8v5Yb4ncFTT3rPSgZBOpCkjfK0y4oVVVJwIuDVBRMDXrPyXRL988i5ap9m9bnyEEjWfm5WkBmtffLfA=="],
+
+    "@humanwhocodes/retry": ["@humanwhocodes/retry@0.4.3", "", {}, "sha512-bV0Tgo9K4hfPCek+aMAn81RppFKv2ySDQeMoSZuvTASywNTnVJCArCZE2FWqpvIatKu7VMRLWlR1EazvVhDyhQ=="],
+
     "@iconify-json/simple-icons": ["@iconify-json/simple-icons@1.2.74", "", { "dependencies": { "@iconify/types": "*" } }, "sha512-yqaohfY6jnYjTVpuTkaBQHrWbdUrQyWXhau0r/0EZiNWYXPX/P8WWwl1DoLH5CbvDjjcWQw5J0zADhgCUklOqA=="],
 
     "@iconify/types": ["@iconify/types@2.0.0", "", {}, "sha512-+wluvCrRhXrhyOmRDJ3q8mux9JkKy5SJ/v8ol2tu4FVjyYvtEzkc/3pK15ET6RKg4b4w4BmTk1+gsCUhf21Ykg=="],
@@ -159,41 +188,119 @@
 
     "@mdx-js/react": ["@mdx-js/react@3.1.1", "", { "dependencies": { "@types/mdx": "^2.0.0" }, "peerDependencies": { "@types/react": ">=16", "react": ">=16" } }, "sha512-f++rKLQgUVYDAtECQ6fn/is15GkEH9+nZPM3MS0RcxVqoTfawHvDlSCH7JbMhAM6uJ32v3eXLvLmLvjGu7PTQw=="],
 
-    "@napi-rs/wasm-runtime": ["@napi-rs/wasm-runtime@1.1.4", "", { "dependencies": { "@tybys/wasm-util": "^0.10.1" }, "peerDependencies": { "@emnapi/core": "^1.7.1", "@emnapi/runtime": "^1.7.1" } }, "sha512-3NQNNgA1YSlJb/kMH1ildASP9HW7/7kYnRI2szWJaofaS1hWmbGI4H+d3+22aGzXXN9IJ+n+GiFVcGipJP18ow=="],
+    "@napi-rs/wasm-runtime": ["@napi-rs/wasm-runtime@1.2.2", "", { "dependencies": { "@tybys/wasm-util": "^0.10.3" }, "peerDependencies": { "@emnapi/core": "^1.7.1 || ^2.0.0-alpha.3", "@emnapi/runtime": "^1.7.1 || ^2.0.0-alpha.3" } }, "sha512-JfB4kuJQjaoHuCTseIINHtHWeJnvgEcxjwA5t/Y00ZgaOO1Crz3fjT/p8kT28zA/Caz7oiUMn3d6H2yOVCVwuw=="],
+
+    "@oxc-parser/binding-android-arm-eabi": ["@oxc-parser/binding-android-arm-eabi@0.127.0", "", { "os": "android", "cpu": "arm" }, "sha512-0LC7ye4hvqbIKxAzThzvswgHLFu2AURKzYLeSVvLdu2TBOYWQDmHnTqPLeA597BcUCxiLqLsS4CJ5uoI5WYWCQ=="],
+
+    "@oxc-parser/binding-android-arm64": ["@oxc-parser/binding-android-arm64@0.127.0", "", { "os": "android", "cpu": "arm64" }, "sha512-b5jtVTH6AU5CJXHNdj7Jj9IEiR9yVjjnwHzPJhGyHGPdcsZSzBCkS9GBbV33niRMvKthDwQRFRJfI4a+k4PvYg=="],
+
+    "@oxc-parser/binding-darwin-arm64": ["@oxc-parser/binding-darwin-arm64@0.127.0", "", { "os": "darwin", "cpu": "arm64" }, "sha512-obCE8B7ISKkJidjlhv9xRGJPOSDG2Yu6PRga9Ruaz35uintHxbp1Ki/Yc71wx4rj3Edrm0a1kzG1TAwit0wFpg=="],
+
+    "@oxc-parser/binding-darwin-x64": ["@oxc-parser/binding-darwin-x64@0.127.0", "", { "os": "darwin", "cpu": "x64" }, "sha512-JL6Xb5IwPQT8rUzlpsX7E+AgfcdNklXNPFp8pjCQQ5MQOQo5rtEB2ui+3Hgg9Sn7Y9Egj6YOLLiHhLpdAe12Aw=="],
+
+    "@oxc-parser/binding-freebsd-x64": ["@oxc-parser/binding-freebsd-x64@0.127.0", "", { "os": "freebsd", "cpu": "x64" }, "sha512-SDQ/3MQFw58fqQz3Z1PhSKFF3JoCF4gmlNjziDm8X02tTahCw0qJbd7FGPDKw1i4VTBZene9JPyC3mHtSvi+wA=="],
+
+    "@oxc-parser/binding-linux-arm-gnueabihf": ["@oxc-parser/binding-linux-arm-gnueabihf@0.127.0", "", { "os": "linux", "cpu": "arm" }, "sha512-Av+D1MIqzV0YMGPT9we2SIZaMKD7Cxs4CvXSx/yxaWHewZjYEjScpOf5igc8IILASViw4WTnjlwUdI1KzVtDHQ=="],
+
+    "@oxc-parser/binding-linux-arm-musleabihf": ["@oxc-parser/binding-linux-arm-musleabihf@0.127.0", "", { "os": "linux", "cpu": "arm" }, "sha512-Cs2fdJ8cPpFdeebj6p4dag8A4+56hPvZ0AhQQzlaLswGz1tz7bXt1nETLeorrM9+AMcWFFkqxcXwDGfTVidY8g=="],
+
+    "@oxc-parser/binding-linux-arm64-gnu": ["@oxc-parser/binding-linux-arm64-gnu@0.127.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-qdOfTcT6SY8gsJrrV92uyEUyjqMGPpIB5JZUG6QN5dukYd+7/j0kX6MwK1DgQj39jtUYixxPiaRUiEN1+0CXgQ=="],
+
+    "@oxc-parser/binding-linux-arm64-musl": ["@oxc-parser/binding-linux-arm64-musl@0.127.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-EoTCZneNFU/P2qrpEM+RHmQwt+CvDkyGESG6qhr7KaegXLZwePfbrkCDfAk8/rhxbDUVGsZILX+2tqPzFtoFWA=="],
+
+    "@oxc-parser/binding-linux-ppc64-gnu": ["@oxc-parser/binding-linux-ppc64-gnu@0.127.0", "", { "os": "linux", "cpu": "ppc64" }, "sha512-zALjmZYgxFLHjXeudcDF0xFGNydTAtkAeXAr2EuC17ywCyFxcmQra4w0BMde0Yi/re4Bi4iwEoEXtYN7l6eBLQ=="],
+
+    "@oxc-parser/binding-linux-riscv64-gnu": ["@oxc-parser/binding-linux-riscv64-gnu@0.127.0", "", { "os": "linux", "cpu": "none" }, "sha512-fPP8M6zQLS7Jz7o9d5ArUSuAuSK3e+WCYVrCpdzeCOejidtZExJ9tjhDrAd3HEPqARBCPmdpqxESPFqy44vkBQ=="],
+
+    "@oxc-parser/binding-linux-riscv64-musl": ["@oxc-parser/binding-linux-riscv64-musl@0.127.0", "", { "os": "linux", "cpu": "none" }, "sha512-7IcC4Ao02oGpfnjt+X/oF4U2mllo2qoSkw5xxiXNKL9MCTsTiAC6616beOuehdxGcnz1bRoPC1RQ2f1GQDdN+g=="],
+
+    "@oxc-parser/binding-linux-s390x-gnu": ["@oxc-parser/binding-linux-s390x-gnu@0.127.0", "", { "os": "linux", "cpu": "s390x" }, "sha512-pbXIhiNFHoqWeqDNLiJ9JkpHz1IM9k4DXa66x+1GTWMG7iLxtkXgE53iiuKSXwmk3zIYmaPVfBvgcAhS583K4Q=="],
+
+    "@oxc-parser/binding-linux-x64-gnu": ["@oxc-parser/binding-linux-x64-gnu@0.127.0", "", { "os": "linux", "cpu": "x64" }, "sha512-MYCguB9RvBvlSd6gbuNI7QwiLoCCAlGnlRJFPrzLI6U1/9wkC/WK6LtBAUln55H1Ctqw45PWmqrobKoMhsYQzQ=="],
+
+    "@oxc-parser/binding-linux-x64-musl": ["@oxc-parser/binding-linux-x64-musl@0.127.0", "", { "os": "linux", "cpu": "x64" }, "sha512-5eY0B/bxf1xIUxb4NOTvOI3KWtBQfPWYyKAzgcrCt0mDibSZygVpO1Pz8bkeiSZ5Jj9+M09dkggG3H8I5d0Uyg=="],
+
+    "@oxc-parser/binding-openharmony-arm64": ["@oxc-parser/binding-openharmony-arm64@0.127.0", "", { "os": "none", "cpu": "arm64" }, "sha512-Gld0ajrFTUXNtdw20fVBuTQx66FA75nIVg+//pPfR3sXkuABB4mTBhl3r9JNzrJpgW//qiwxf0nWXUWGJSL3UQ=="],
+
+    "@oxc-parser/binding-wasm32-wasi": ["@oxc-parser/binding-wasm32-wasi@0.127.0", "", { "dependencies": { "@emnapi/core": "1.9.2", "@emnapi/runtime": "1.9.2", "@napi-rs/wasm-runtime": "^1.1.4" }, "cpu": "none" }, "sha512-T6KVD7rhLzFlwGRXMnxUFfkCZD8FHnb968wVXW1mXzgRFc5RNXOBY2mPPDZ77x5Ln76ltLMgtPg0cOkU1NSrEQ=="],
+
+    "@oxc-parser/binding-win32-arm64-msvc": ["@oxc-parser/binding-win32-arm64-msvc@0.127.0", "", { "os": "win32", "cpu": "arm64" }, "sha512-Ujvw4X+LD1CCGULcsQcvb4YNVoBGqt+JHgNNzGGaCImELiZLk477ifUH53gIbE7EKd933NdTi25JWEr9K2HwXw=="],
+
+    "@oxc-parser/binding-win32-ia32-msvc": ["@oxc-parser/binding-win32-ia32-msvc@0.127.0", "", { "os": "win32", "cpu": "ia32" }, "sha512-0cwxKO7KHQQQfo4Uf4B2SQrhgm+cJaP9OvFFhx52Tkg4bezsacu83GB2/In5bC415Ueeym+kXdnge/57rbSfTw=="],
+
+    "@oxc-parser/binding-win32-x64-msvc": ["@oxc-parser/binding-win32-x64-msvc@0.127.0", "", { "os": "win32", "cpu": "x64" }, "sha512-rOrnSQSCbhI2kowr9XxE7m9a8oQXnBHjnS6j95LxxAnEZ0+Fz20WlRXG4ondQb+ejjt2KOsa65sE6++L6kUd+w=="],
 
     "@oxc-project/types": ["@oxc-project/types@0.127.0", "", {}, "sha512-aIYXQBo4lCbO4z0R3FHeucQHpF46l2LbMdxRvqvuRuW2OxdnSkcng5B8+K12spgLDj93rtN3+J2Vac/TIO+ciQ=="],
 
-    "@rolldown/binding-android-arm64": ["@rolldown/binding-android-arm64@1.0.0-rc.17", "", { "os": "android", "cpu": "arm64" }, "sha512-s70pVGhw4zqGeFnXWvAzJDlvxhlRollagdCCKRgOsgUOH3N1l0LIxf83AtGzmb5SiVM4Hjl5HyarMRfdfj3DaQ=="],
+    "@oxc-resolver/binding-android-arm-eabi": ["@oxc-resolver/binding-android-arm-eabi@11.24.2", "", { "os": "android", "cpu": "arm" }, "sha512-y09e0L0SRI2OA2tUIrjBgoV3eH5hvUKXNkJqXmNo5V2WxIjyC7I7aJfRLMEVpA8yi95f90gFDvO0VMgrDw+vwA=="],
+
+    "@oxc-resolver/binding-android-arm64": ["@oxc-resolver/binding-android-arm64@11.24.2", "", { "os": "android", "cpu": "arm64" }, "sha512-cl4icWaZFnLdg8m6qtnh5rBMuGbxc/ptStFHLeCNwr+2cZjkjNwQu/jYRS0CHlnPecOJMpuS5M6/BH+0J/YkEg=="],
+
+    "@oxc-resolver/binding-darwin-arm64": ["@oxc-resolver/binding-darwin-arm64@11.24.2", "", { "os": "darwin", "cpu": "arm64" }, "sha512-At29QEMF6HajbQvgY8K6OXnHD1x9rad74xBEfmCB6ZqCGsdq75aK7tOYcTbOanMy8qdIBrfL3SMr3p/lfSlb9w=="],
+
+    "@oxc-resolver/binding-darwin-x64": ["@oxc-resolver/binding-darwin-x64@11.24.2", "", { "os": "darwin", "cpu": "x64" }, "sha512-A5Kqr1EUj4oIL5CF4WRssq/o5P0Y11cwoFouMRmQ7YnC/A8V93nv1nb7aSU8HwcgmXropjLNkVTl4MN87cu28Q=="],
+
+    "@oxc-resolver/binding-freebsd-x64": ["@oxc-resolver/binding-freebsd-x64@11.24.2", "", { "os": "freebsd", "cpu": "x64" }, "sha512-R5xkRBRRz7ceH/P5Jrc6G7FmdUdgpLYyESFAUDVTNQ9K0sGPxcp4ljiwEwEqsvNcQ4sYbMRrWcHHBCu7ksAJVw=="],
+
+    "@oxc-resolver/binding-linux-arm-gnueabihf": ["@oxc-resolver/binding-linux-arm-gnueabihf@11.24.2", "", { "os": "linux", "cpu": "arm" }, "sha512-k/RuYL4L/R58IBn3wT5ma3Wh4k62bp1eYCFRWCmMsasUOqL+H6sW0VGFadEzKWXFFlz+2uIMoeMk9ySSZJHgbg=="],
+
+    "@oxc-resolver/binding-linux-arm-musleabihf": ["@oxc-resolver/binding-linux-arm-musleabihf@11.24.2", "", { "os": "linux", "cpu": "arm" }, "sha512-bnHAak3ujYfH5pKk4NieFNbvYvernfoQDgwLddbZ3OtMYrem87/qjlA+u+aKG0oZcqSLGCful/6/CEA+aeAgaA=="],
 
-    "@rolldown/binding-darwin-arm64": ["@rolldown/binding-darwin-arm64@1.0.0-rc.17", "", { "os": "darwin", "cpu": "arm64" }, "sha512-4ksWc9n0mhlZpZ9PMZgTGjeOPRu8MB1Z3Tz0Mo02eWfWCHMW1zN82Qz/pL/rC+yQa+8ZnutMF0JjJe7PjwasYw=="],
+    "@oxc-resolver/binding-linux-arm64-gnu": ["@oxc-resolver/binding-linux-arm64-gnu@11.24.2", "", { "os": "linux", "cpu": "arm64" }, "sha512-vDT3KHgzYp47gmtNOqL2VNhCyl5Zv643eyxm//A68J8DeUGXrvD1pZFiaT4jSfe+RInfnn1R2yVHye4enx6RnA=="],
 
-    "@rolldown/binding-darwin-x64": ["@rolldown/binding-darwin-x64@1.0.0-rc.17", "", { "os": "darwin", "cpu": "x64" }, "sha512-SUSDOI6WwUVNcWxd02QEBjLdY1VPHvlEkw6T/8nYG322iYWCTxRb1vzk4E+mWWYehTp7ERibq54LSJGjmouOsw=="],
+    "@oxc-resolver/binding-linux-arm64-musl": ["@oxc-resolver/binding-linux-arm64-musl@11.24.2", "", { "os": "linux", "cpu": "arm64" }, "sha512-+kMlQvbzfyEYtu5FcjE4p+ttBLpKW4d/AsAsuE69BxV6V4twZJeIQZFfD8gh/wqglY0MkPSezWXQH0jBV13MUw=="],
 
-    "@rolldown/binding-freebsd-x64": ["@rolldown/binding-freebsd-x64@1.0.0-rc.17", "", { "os": "freebsd", "cpu": "x64" }, "sha512-hwnz3nw9dbJ05EDO/PvcjaaewqqDy7Y1rn1UO81l8iIK1GjenME75dl16ajbvSSMfv66WXSRCYKIqfgq2KCfxw=="],
+    "@oxc-resolver/binding-linux-ppc64-gnu": ["@oxc-resolver/binding-linux-ppc64-gnu@11.24.2", "", { "os": "linux", "cpu": "ppc64" }, "sha512-shjfMhmZ3gq9fv/w7bi3PnZlgOPG+2QAOFf0BJF0EgBSIGZ6PMLN2zbGEblTUYB/NKVDRyYhE2ff3dJ1QqNPkA=="],
 
-    "@rolldown/binding-linux-arm-gnueabihf": ["@rolldown/binding-linux-arm-gnueabihf@1.0.0-rc.17", "", { "os": "linux", "cpu": "arm" }, "sha512-IS+W7epTcwANmFSQFrS1SivEXHtl1JtuQA9wlxrZTcNi6mx+FDOYrakGevvvTwgj2JvWiK8B29/qD9BELZPyXQ=="],
+    "@oxc-resolver/binding-linux-riscv64-gnu": ["@oxc-resolver/binding-linux-riscv64-gnu@11.24.2", "", { "os": "linux", "cpu": "none" }, "sha512-zGelwFR5oRo+b69k8Lrzun86DyUHzfKN6cnjbR9l7Z7NIRznOE/2ZvPa1IUKqAL2PzAXOdwkfVqNvO1H2RlpAw=="],
 
-    "@rolldown/binding-linux-arm64-gnu": ["@rolldown/binding-linux-arm64-gnu@1.0.0-rc.17", "", { "os": "linux", "cpu": "arm64" }, "sha512-e6usGaHKW5BMNZOymS1UcEYGowQMWcgZ71Z17Sl/h2+ZziNJ1a9n3Zvcz6LdRyIW5572wBCTH/Z+bKuZouGk9Q=="],
+    "@oxc-resolver/binding-linux-riscv64-musl": ["@oxc-resolver/binding-linux-riscv64-musl@11.24.2", "", { "os": "linux", "cpu": "none" }, "sha512-qxZ1SWCXJY0eyhAlP6Lmo9F2Nrtx7EkYj9oCgL8apDPCwXwCEDA2U697bbT81JIc2IrVjxO4KX6WU2N+oN9Z4w=="],
 
-    "@rolldown/binding-linux-arm64-musl": ["@rolldown/binding-linux-arm64-musl@1.0.0-rc.17", "", { "os": "linux", "cpu": "arm64" }, "sha512-b/CgbwAJpmrRLp02RPfhbudf5tZnN9nsPWK82znefso832etkem8H7FSZwxrOI9djcdTP7U6YfNhbRnh7djErg=="],
+    "@oxc-resolver/binding-linux-s390x-gnu": ["@oxc-resolver/binding-linux-s390x-gnu@11.24.2", "", { "os": "linux", "cpu": "s390x" }, "sha512-sGCecF3cx2DFlH4t/z7ApnOnXqN48p5p5mlHDEnHTAukQa2P+qMVE4CwyWE9W+q/m3QJ7kKfGrIjax31f44oFQ=="],
 
-    "@rolldown/binding-linux-ppc64-gnu": ["@rolldown/binding-linux-ppc64-gnu@1.0.0-rc.17", "", { "os": "linux", "cpu": "ppc64" }, "sha512-4EII1iNGRUN5WwGbF/kOh/EIkoDN9HsupgLQoXfY+D1oyJm7/F4t5PYU5n8SWZgG0FEwakyM8pGgwcBYruGTlA=="],
+    "@oxc-resolver/binding-linux-x64-gnu": ["@oxc-resolver/binding-linux-x64-gnu@11.24.2", "", { "os": "linux", "cpu": "x64" }, "sha512-k/VlMMcSzMlahb3/fENM4rTlsJ0s3fFROA0KXPBmKggqmTSaE383sl8F3KCOXPLmVsYfW6hCitMhXCEtNeZxxg=="],
 
-    "@rolldown/binding-linux-s390x-gnu": ["@rolldown/binding-linux-s390x-gnu@1.0.0-rc.17", "", { "os": "linux", "cpu": "s390x" }, "sha512-AH8oq3XqQo4IibpVXvPeLDI5pzkpYn0WiZAfT05kFzoJ6tQNzwRdDYQ45M8I/gslbodRZwW8uxLhbSBbkv96rA=="],
+    "@oxc-resolver/binding-linux-x64-musl": ["@oxc-resolver/binding-linux-x64-musl@11.24.2", "", { "os": "linux", "cpu": "x64" }, "sha512-8hbnZyNi97b/8wapYaIF9+t9GmZKBW2vunaOc3h9HGJptH7b7XpvZqOTBSm/MpTjr7H497BlgOaSfLUdhmy2bw=="],
 
-    "@rolldown/binding-linux-x64-gnu": ["@rolldown/binding-linux-x64-gnu@1.0.0-rc.17", "", { "os": "linux", "cpu": "x64" }, "sha512-cLnjV3xfo7KslbU41Z7z8BH/E1y5mzUYzAqih1d1MDaIGZRCMqTijqLv76/P7fyHuvUcfGsIpqCdddbxLLK9rA=="],
+    "@oxc-resolver/binding-openharmony-arm64": ["@oxc-resolver/binding-openharmony-arm64@11.24.2", "", { "os": "none", "cpu": "arm64" }, "sha512-MvyGik3a6pVgZ0t/kWlbmFxFLmXQJwgLsY2eYFHLpy0wGwRbfzeIGgDwQ3kXqE30z+kSXennRkCrT7TUvkptNg=="],
 
-    "@rolldown/binding-linux-x64-musl": ["@rolldown/binding-linux-x64-musl@1.0.0-rc.17", "", { "os": "linux", "cpu": "x64" }, "sha512-0phclDw1spsL7dUB37sIARuis2tAgomCJXAHZlpt8PXZ4Ba0dRP1e+66lsRqrfhISeN9bEGNjQs+T/Fbd7oYGw=="],
+    "@oxc-resolver/binding-wasm32-wasi": ["@oxc-resolver/binding-wasm32-wasi@11.24.2", "", { "dependencies": { "@emnapi/core": "1.11.2", "@emnapi/runtime": "1.11.2", "@napi-rs/wasm-runtime": "^1.1.6" }, "cpu": "none" }, "sha512-vHcssMPwO08RTvj/c0iOBz90attxyG3wQJ0dTcyEQK43LRpcdLWZlV5feBhv6Isn6ahbQIzHbCgfa81+RiML0Q=="],
 
-    "@rolldown/binding-openharmony-arm64": ["@rolldown/binding-openharmony-arm64@1.0.0-rc.17", "", { "os": "none", "cpu": "arm64" }, "sha512-0ag/hEgXOwgw4t8QyQvUCxvEg+V0KBcA6YuOx9g0r02MprutRF5dyljgm3EmR02O292UX7UeS6HzWHAl6KgyhA=="],
+    "@oxc-resolver/binding-win32-arm64-msvc": ["@oxc-resolver/binding-win32-arm64-msvc@11.24.2", "", { "os": "win32", "cpu": "arm64" }, "sha512-uokJqro2iBqkFvJdKQLP7d8/BUmFwESQFVmIJUQKj1Xn1a/LysJoe1vmeECLF5b3jsV8CAL5sEMJXX6SdK9Nhg=="],
 
-    "@rolldown/binding-wasm32-wasi": ["@rolldown/binding-wasm32-wasi@1.0.0-rc.17", "", { "dependencies": { "@emnapi/core": "1.10.0", "@emnapi/runtime": "1.10.0", "@napi-rs/wasm-runtime": "^1.1.4" }, "cpu": "none" }, "sha512-LEXei6vo0E5wTGwpkJ4KoT3OZJRnglwldt5ziLzOlc6qqb55z4tWNq2A+PFqCJuvWWdP53CVhG1Z9NtToDPJrA=="],
+    "@oxc-resolver/binding-win32-x64-msvc": ["@oxc-resolver/binding-win32-x64-msvc@11.24.2", "", { "os": "win32", "cpu": "x64" }, "sha512-UqGPmo56KDfLlfXFAFIrNflHT8tFxWGEivWg3Zeyp4Uy2NlKN1FGPr6/BxcLGG3+kZ6Wp14g5Uj+n71boqZfiw=="],
 
-    "@rolldown/binding-win32-arm64-msvc": ["@rolldown/binding-win32-arm64-msvc@1.0.0-rc.17", "", { "os": "win32", "cpu": "arm64" }, "sha512-gUmyzBl3SPMa6hrqFUth9sVfcLBlYsbMzBx5PlexMroZStgzGqlZ26pYG89rBb45Mnia+oil6YAIFeEWGWhoZA=="],
+    "@rolldown/binding-android-arm64": ["@rolldown/binding-android-arm64@1.2.1", "", { "os": "android", "cpu": "arm64" }, "sha512-02hOeOSryYxVrOIphmLAsqnCJWxwlzFk+pEt/N/i6OgT3lShHO7xGCU5cpgchRDHboAEbSjzgGh+O/u1GswQmA=="],
 
-    "@rolldown/binding-win32-x64-msvc": ["@rolldown/binding-win32-x64-msvc@1.0.0-rc.17", "", { "os": "win32", "cpu": "x64" }, "sha512-3hkiolcUAvPB9FLb3UZdfjVVNWherN1f/skkGWJP/fgSQhYUZpSIRr0/I8ZK9TkF3F7kxvJAk0+IcKvPHk9qQg=="],
+    "@rolldown/binding-darwin-arm64": ["@rolldown/binding-darwin-arm64@1.2.1", "", { "os": "darwin", "cpu": "arm64" }, "sha512-fMsTOnN0OjFm3CyppWPitKnc8UlliVARUULW6cfU6AIqjdtgmSFWSk9vecHzZduv/yMWIHDlRhM1e8Iff9uAfA=="],
 
-    "@rolldown/pluginutils": ["@rolldown/pluginutils@1.0.0-rc.17", "", {}, "sha512-n8iosDOt6Ig1UhJ2AYqoIhHWh/isz0xpicHTzpKBeotdVsTEcxsSA/i3EVM7gQAj0rU27OLAxCjzlj15IWY7bg=="],
+    "@rolldown/binding-darwin-x64": ["@rolldown/binding-darwin-x64@1.2.1", "", { "os": "darwin", "cpu": "x64" }, "sha512-1wjKdz/XLGKHaTNHjQveQ/B23TKx4ItAqm1JbyVuvNPc4Ze0Fb48s49TAd/2zcplPl8okE/UbTgmlVfwT7eFeQ=="],
+
+    "@rolldown/binding-freebsd-x64": ["@rolldown/binding-freebsd-x64@1.2.1", "", { "os": "freebsd", "cpu": "x64" }, "sha512-Fa0jHR07E7YBN4vOEsbVf2briYNsuOowfLJaXULZM0ldMlaCaj2LJgLMbMe4iacRyZmvR8efFhgR9wKuGclQUg=="],
+
+    "@rolldown/binding-linux-arm-gnueabihf": ["@rolldown/binding-linux-arm-gnueabihf@1.2.1", "", { "os": "linux", "cpu": "arm" }, "sha512-pzkgu1SSHGgRRyRZ4fbmSgmajbVt+epaLP99NDjFft69v/ypfTi6swBMiVdh2EkQ0OSnHE1lZDM7DRGkyAzUpA=="],
+
+    "@rolldown/binding-linux-arm64-gnu": ["@rolldown/binding-linux-arm64-gnu@1.2.1", "", { "os": "linux", "cpu": "arm64" }, "sha512-QI5SEDY8cbiYWHx0VO4vIc3UlS6a32vXHjU8Qy/17adEmZIPuByJg13UEvo9c/UCiUkdcVWY83C+b+JrwnNyUg=="],
+
+    "@rolldown/binding-linux-arm64-musl": ["@rolldown/binding-linux-arm64-musl@1.2.1", "", { "os": "linux", "cpu": "arm64" }, "sha512-Sm41FyCeXqmYcERoYOCbGIL5hNfd8w9LQ7Y61Bev48HkcjaJqV/iiVOaiDxjVTRMS+QKrZmD8cfPt4uMVnvM+A=="],
+
+    "@rolldown/binding-linux-ppc64-gnu": ["@rolldown/binding-linux-ppc64-gnu@1.2.1", "", { "os": "linux", "cpu": "ppc64" }, "sha512-2x+WhXTGl9yJYPbltW/BSEPTVz9OIWQyER4N+gJEDWkkn904eRcBzELqh/Hf7K0w/ubGbKNMv0ZC+94QK/IFEg=="],
+
+    "@rolldown/binding-linux-s390x-gnu": ["@rolldown/binding-linux-s390x-gnu@1.2.1", "", { "os": "linux", "cpu": "s390x" }, "sha512-eEjmQpuRQayHPWWnywaWHkFT3ToPbP3RYy42VVd/B9aBGDA+Ol25EIWHxKQST3IiWJjikCWUF7KtbfqwZrzVwQ=="],
+
+    "@rolldown/binding-linux-x64-gnu": ["@rolldown/binding-linux-x64-gnu@1.2.1", "", { "os": "linux", "cpu": "x64" }, "sha512-/Orga1fZYkLc/56jBICcHrKchl8Z2UKdDSr3LG9ToWO1lQ6a4Livk9Xz+9WN91zsz5QR3XQz2NNoSDEvP6qadw=="],
+
+    "@rolldown/binding-linux-x64-musl": ["@rolldown/binding-linux-x64-musl@1.2.1", "", { "os": "linux", "cpu": "x64" }, "sha512-xxBJRL+0q0Kce7orznGWLuylHDY65vuARXZRpX+hPdv+DqK2c3NlCsVA98tlWzWNEE7yPqA/1NQ5nnCrj49Y5A=="],
+
+    "@rolldown/binding-openharmony-arm64": ["@rolldown/binding-openharmony-arm64@1.2.1", "", { "os": "none", "cpu": "arm64" }, "sha512-M6AdXIXw3s+/8XpKMzdGDEXGS1S7kwUsy+rcTIUIOx5Ge4nXKCtAFHFV9YKkXvGcC5WMoTjAteLzlsQROVI0Yw=="],
+
+    "@rolldown/binding-wasm32-wasi": ["@rolldown/binding-wasm32-wasi@1.2.1", "", { "dependencies": { "@emnapi/core": "2.0.0-alpha.3", "@emnapi/runtime": "2.0.0-alpha.3", "@napi-rs/wasm-runtime": "^1.2.0" } }, "sha512-/TX0SoRGojHzSAHpfVBbavRVSazg5U3h3Y3VXfcc0cdugq6kxdqw8LPGFiPr+/7gE/60zRcsOY2Vi9b9eT0jww=="],
+
+    "@rolldown/binding-win32-arm64-msvc": ["@rolldown/binding-win32-arm64-msvc@1.2.1", "", { "os": "win32", "cpu": "arm64" }, "sha512-EvRrivJieyHG+AO9lleZWgq+g0+S7oV2C51yuqlcyU/R9net+sI4Pj0F+lUoP2bEr6TWX3SqFaaS0SzfLxSzkw=="],
+
+    "@rolldown/binding-win32-x64-msvc": ["@rolldown/binding-win32-x64-msvc@1.2.1", "", { "os": "win32", "cpu": "x64" }, "sha512-Z4eCmn5QJ/5+azF9knpLWKfVd9aidn0mAe9TpJgvBLId9Ax3t0+JVxBmT25Bv7NBbVW1TZyKjQjQReouMeH5UQ=="],
+
+    "@rolldown/pluginutils": ["@rolldown/pluginutils@1.0.1", "", {}, "sha512-2j9bGt5Jh8hj+vPtgzPtl72j0yRxHAyumoo6TNfAjsLB04UtpSvPbPcDcBMxz7n+9CYB0c1GxQFxYRg2jimqGw=="],
 
     "@rollup/pluginutils": ["@rollup/pluginutils@5.3.0", "", { "dependencies": { "@types/estree": "^1.0.0", "estree-walker": "^2.0.2", "picomatch": "^4.0.2" }, "peerDependencies": { "rollup": "^1.20.0||^2.0.0||^3.0.0||^4.0.0" }, "optionalPeers": ["rollup"] }, "sha512-5EdhGZtnu3V88ces7s53hhfK5KSASnJZv8Lulpc04cWO3REESroJXg73DFsOmgbU2BhwV0E20bu2IDZb3VKW4Q=="],
 
@@ -263,51 +370,51 @@
 
     "@shikijs/vscode-textmate": ["@shikijs/vscode-textmate@10.0.2", "", {}, "sha512-83yeghZ2xxin3Nj8z1NMd/NCuca+gsYXswywDy5bHvwlWL8tpTQmzGeUuHd9FC3E/SBEMvzJRwWEOz5gGes9Qg=="],
 
-    "@storybook/addon-docs": ["@storybook/addon-docs@10.3.6", "", { "dependencies": { "@mdx-js/react": "^3.0.0", "@storybook/csf-plugin": "10.3.6", "@storybook/icons": "^2.0.1", "@storybook/react-dom-shim": "10.3.6", "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0", "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0", "ts-dedent": "^2.0.0" }, "peerDependencies": { "storybook": "^10.3.6" } }, "sha512-TvIdADVPtauxW0LzXIpIv7X6GxwetorhyNh+6+7MHC27XSBCWVxxRUwL63YeLlHTuXsIk0quG3b1xgwVRzWOJA=="],
+    "@storybook/addon-docs": ["@storybook/addon-docs@10.5.5", "", { "dependencies": { "@mdx-js/react": "^3.0.0", "@storybook/csf-plugin": "10.5.5", "@storybook/icons": "^2.0.2", "@storybook/react-dom-shim": "10.5.5", "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0", "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0", "ts-dedent": "^2.0.0" }, "peerDependencies": { "@types/react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0", "storybook": "^10.5.5" }, "optionalPeers": ["@types/react"] }, "sha512-0YpKlimS4XE0kQ8Maa5coeefQxdyDrBHg1wOP3WTPuBe4FolFSCDveR0ge2+vuUBk+fZfn2+l+3Q2jmAWaRGDg=="],
 
-    "@storybook/builder-vite": ["@storybook/builder-vite@10.3.6", "", { "dependencies": { "@storybook/csf-plugin": "10.3.6", "ts-dedent": "^2.0.0" }, "peerDependencies": { "storybook": "^10.3.6", "vite": "^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0" } }, "sha512-gpvR/sE4BcrFtmQZ+Ker7zD23oQzoVeqD9nF6cK6yzY+Q0svJXyX2EPmFG4y+EwygD5/vNzDpP84gGMut8VRwg=="],
+    "@storybook/builder-vite": ["@storybook/builder-vite@10.5.5", "", { "dependencies": { "@storybook/csf-plugin": "10.5.5", "ts-dedent": "^2.0.0" }, "peerDependencies": { "storybook": "^10.5.5", "vite": "^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0" } }, "sha512-dQoJ7gUl8y0z5rV9cE0mz6qTBNmN9R4GOLIZk98rJ8CwduNJOb9eGZXusDzzvnYcp8TnNkqDtyx4tXQSUDInPQ=="],
 
-    "@storybook/csf-plugin": ["@storybook/csf-plugin@10.3.6", "", { "dependencies": { "unplugin": "^2.3.5" }, "peerDependencies": { "esbuild": "*", "rollup": "*", "storybook": "^10.3.6", "vite": "*", "webpack": "*" }, "optionalPeers": ["esbuild", "rollup", "vite", "webpack"] }, "sha512-9kBf7VRdRqTSIYo+rPtVn5yjYYyK8kP2QhEYx3oiXvfwy4RexmbJnhk/tXa/lNiTqukA1TqaWQ2+5MqF4fu6YQ=="],
+    "@storybook/csf-plugin": ["@storybook/csf-plugin@10.5.5", "", { "dependencies": { "unplugin": "^2.3.5" }, "peerDependencies": { "esbuild": "*", "rollup": "*", "storybook": "^10.5.5", "vite": "*", "webpack": "*" }, "optionalPeers": ["esbuild", "rollup", "vite", "webpack"] }, "sha512-/euibhRFqklYCZqUseokojmfYcQpXshVY2QmA1qCuxMz9SzVFD3iSTw+aFLTxpsJGGdcZJk8fnm/rEthLzZ9jA=="],
 
     "@storybook/global": ["@storybook/global@5.0.0", "", {}, "sha512-FcOqPAXACP0I3oJ/ws6/rrPT9WGhu915Cg8D02a9YxLo0DE9zI+a9A5gRGvmQ09fiWPukqI8ZAEoQEdWUKMQdQ=="],
 
-    "@storybook/icons": ["@storybook/icons@2.0.1", "", { "peerDependencies": { "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0", "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0" } }, "sha512-/smVjw88yK3CKsiuR71vNgWQ9+NuY2L+e8X7IMrFjexjm6ZR8ULrV2DRkTA61aV6ryefslzHEGDInGpnNeIocg=="],
+    "@storybook/icons": ["@storybook/icons@2.1.0", "", { "peerDependencies": { "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0" } }, "sha512-Fxh9vYpX9bQqFeHRiY8h2ApeRGDzRSMLwJwNZ/AIRqnyOKHxRKL+yFe+ctEkVJmuptRE9u1Hrn8ZZNHyfDKKNg=="],
 
-    "@storybook/react-dom-shim": ["@storybook/react-dom-shim@10.3.6", "", { "peerDependencies": { "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0", "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0", "storybook": "^10.3.6" } }, "sha512-/Tu1gPu+Fw+zOnAGmxRmOD30FX3a04LxcTAKflEtdpmtIMVR5bA3qpjy+f5YhoyDCecbXyKmL1OeIU2FIIZHqQ=="],
+    "@storybook/react-dom-shim": ["@storybook/react-dom-shim@10.5.5", "", { "peerDependencies": { "@types/react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0", "@types/react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0", "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0", "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0", "storybook": "^10.5.5" }, "optionalPeers": ["@types/react", "@types/react-dom"] }, "sha512-PIk7N3LLrZIxfNxmkvmQN1d5UQ70XEedT8n0GhBiXnM6XL09xPGB8n8TZXeJBRYluKhDQcAyQeT0/OZmcDVQJg=="],
 
-    "@storybook/web-components": ["@storybook/web-components@10.3.6", "", { "dependencies": { "@storybook/global": "^5.0.0", "tiny-invariant": "^1.3.1", "ts-dedent": "^2.0.0" }, "peerDependencies": { "lit": "^2.0.0 || ^3.0.0", "storybook": "^10.3.6" } }, "sha512-femDZGYBGQDckL7F6ZCl2S+dNNBjvd9lp6rQrwBdbNprjctLd6d3EB4HyNM502QxtdEo7laq8y1goDu8KwIV3A=="],
+    "@storybook/web-components": ["@storybook/web-components@10.5.5", "", { "dependencies": { "@storybook/global": "^5.0.0", "tiny-invariant": "^1.3.1", "ts-dedent": "^2.0.0" }, "peerDependencies": { "lit": "^2.0.0 || ^3.0.0", "storybook": "^10.5.5" } }, "sha512-ZUk1TmJ6JsRrf7Wh4NnuTxenKrbav7NlHAwzEQtnA3eE0Kzv204k8IskTFr8tKDEYxXzjBppONdRgJZf5i128g=="],
 
-    "@storybook/web-components-vite": ["@storybook/web-components-vite@10.3.6", "", { "dependencies": { "@storybook/builder-vite": "10.3.6", "@storybook/web-components": "10.3.6" }, "peerDependencies": { "storybook": "^10.3.6" } }, "sha512-VeDEAJuOOQV6VAqEF0pilXucS6kp+1ILJVkI+ets6Ku2D+RKeu167YrQAzh1NwzRTv0e5H0anDDNke+sWvg2dg=="],
+    "@storybook/web-components-vite": ["@storybook/web-components-vite@10.5.5", "", { "dependencies": { "@storybook/builder-vite": "10.5.5", "@storybook/web-components": "10.5.5" }, "peerDependencies": { "storybook": "^10.5.5", "vite": "^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0" } }, "sha512-5Gw5bdqgLJTASGtUQoeQVmc4mRiHUCjuGPWiwrcAjkcAhiuYZ4sZnHNJaCCO9IXoB0SN/ZHDojtEadK7mrnLBA=="],
 
-    "@tailwindcss/node": ["@tailwindcss/node@4.2.4", "", { "dependencies": { "@jridgewell/remapping": "^2.3.5", "enhanced-resolve": "^5.19.0", "jiti": "^2.6.1", "lightningcss": "1.32.0", "magic-string": "^0.30.21", "source-map-js": "^1.2.1", "tailwindcss": "4.2.4" } }, "sha512-Ai7+yQPxz3ddrDQzFfBKdHEVBg0w3Zl83jnjuwxnZOsnH9pGn93QHQtpU0p/8rYWxvbFZHneni6p1BSLK4DkGA=="],
+    "@tailwindcss/node": ["@tailwindcss/node@4.3.3", "", { "dependencies": { "@jridgewell/remapping": "^2.3.5", "enhanced-resolve": "^5.24.1", "jiti": "^2.7.0", "lightningcss": "1.32.0", "magic-string": "^0.30.21", "source-map-js": "^1.2.1", "tailwindcss": "4.3.3" } }, "sha512-/T8IKEsf9VTU6tLjgC7+sv2mOPtQxzE2jMw7u4Tt40Tx+QSZxpzh95/H6cMKoja9XuW7iMdLJYBB0o9G1CaAgg=="],
 
-    "@tailwindcss/oxide": ["@tailwindcss/oxide@4.2.4", "", { "optionalDependencies": { "@tailwindcss/oxide-android-arm64": "4.2.4", "@tailwindcss/oxide-darwin-arm64": "4.2.4", "@tailwindcss/oxide-darwin-x64": "4.2.4", "@tailwindcss/oxide-freebsd-x64": "4.2.4", "@tailwindcss/oxide-linux-arm-gnueabihf": "4.2.4", "@tailwindcss/oxide-linux-arm64-gnu": "4.2.4", "@tailwindcss/oxide-linux-arm64-musl": "4.2.4", "@tailwindcss/oxide-linux-x64-gnu": "4.2.4", "@tailwindcss/oxide-linux-x64-musl": "4.2.4", "@tailwindcss/oxide-wasm32-wasi": "4.2.4", "@tailwindcss/oxide-win32-arm64-msvc": "4.2.4", "@tailwindcss/oxide-win32-x64-msvc": "4.2.4" } }, "sha512-9El/iI069DKDSXwTvB9J4BwdO5JhRrOweGaK25taBAvBXyXqJAX+Jqdvs8r8gKpsI/1m0LeJLyQYTf/WLrBT1Q=="],
+    "@tailwindcss/oxide": ["@tailwindcss/oxide@4.3.3", "", { "optionalDependencies": { "@tailwindcss/oxide-android-arm64": "4.3.3", "@tailwindcss/oxide-darwin-arm64": "4.3.3", "@tailwindcss/oxide-darwin-x64": "4.3.3", "@tailwindcss/oxide-freebsd-x64": "4.3.3", "@tailwindcss/oxide-linux-arm-gnueabihf": "4.3.3", "@tailwindcss/oxide-linux-arm64-gnu": "4.3.3", "@tailwindcss/oxide-linux-arm64-musl": "4.3.3", "@tailwindcss/oxide-linux-x64-gnu": "4.3.3", "@tailwindcss/oxide-linux-x64-musl": "4.3.3", "@tailwindcss/oxide-wasm32-wasi": "4.3.3", "@tailwindcss/oxide-win32-arm64-msvc": "4.3.3", "@tailwindcss/oxide-win32-x64-msvc": "4.3.3" } }, "sha512-krXjAikiaFSPaK/FkAQT5UTx3VormQaiZ5hBFlJZ9UFQGB/rwg1MZIhHAG9smMQRTdyJxP6Qt5MwMtdyU5FWrA=="],
 
-    "@tailwindcss/oxide-android-arm64": ["@tailwindcss/oxide-android-arm64@4.2.4", "", { "os": "android", "cpu": "arm64" }, "sha512-e7MOr1SAn9U8KlZzPi1ZXGZHeC5anY36qjNwmZv9pOJ8E4Q6jmD1vyEHkQFmNOIN7twGPEMXRHmitN4zCMN03g=="],
+    "@tailwindcss/oxide-android-arm64": ["@tailwindcss/oxide-android-arm64@4.3.3", "", { "os": "android", "cpu": "arm64" }, "sha512-Y85A2gmPSkl5Ve5qR86GL4HT509cFqQh1aes9p3sSkyTPwt0Pppf3GkwGe4JPACcRYjgJIEhQgM6dBClnr0NYw=="],
 
-    "@tailwindcss/oxide-darwin-arm64": ["@tailwindcss/oxide-darwin-arm64@4.2.4", "", { "os": "darwin", "cpu": "arm64" }, "sha512-tSC/Kbqpz/5/o/C2sG7QvOxAKqyd10bq+ypZNf+9Fi2TvbVbv1zNpcEptcsU7DPROaSbVgUXmrzKhurFvo5eDg=="],
+    "@tailwindcss/oxide-darwin-arm64": ["@tailwindcss/oxide-darwin-arm64@4.3.3", "", { "os": "darwin", "cpu": "arm64" }, "sha512-BiaWatpBcERQFDlOjRDpIVXuFK5PJez5SA4JMg6VYZdBYU+qKfV/vqjcIs+IYmtitf1xYQZTwXvU/8y4lfZUGw=="],
 
-    "@tailwindcss/oxide-darwin-x64": ["@tailwindcss/oxide-darwin-x64@4.2.4", "", { "os": "darwin", "cpu": "x64" }, "sha512-yPyUXn3yO/ufR6+Kzv0t4fCg2qNr90jxXc5QqBpjlPNd0NqyDXcmQb/6weunH/MEDXW5dhyEi+agTDiqa3WsGg=="],
+    "@tailwindcss/oxide-darwin-x64": ["@tailwindcss/oxide-darwin-x64@4.3.3", "", { "os": "darwin", "cpu": "x64" }, "sha512-fAeUqfV5ndhxRwai8cXGzdLvul9utWOmeTkv69unv4ZXixjn61Z+p9lCWdwOwA3TYboG3BwdVuN/RDjhBRl0mw=="],
 
-    "@tailwindcss/oxide-freebsd-x64": ["@tailwindcss/oxide-freebsd-x64@4.2.4", "", { "os": "freebsd", "cpu": "x64" }, "sha512-BoMIB4vMQtZsXdGLVc2z+P9DbETkiopogfWZKbWwM8b/1Vinbs4YcUwo+kM/KeLkX3Ygrf4/PsRndKaYhS8Eiw=="],
+    "@tailwindcss/oxide-freebsd-x64": ["@tailwindcss/oxide-freebsd-x64@4.3.3", "", { "os": "freebsd", "cpu": "x64" }, "sha512-iyf5bV6+wnAlflVeEy7R25dupxTNECZN5QMI0qNT6eT+EgaGdZcKhGkr5SdoaWiLJ3spLqIY9VCeSGrwmtg4kw=="],
 
-    "@tailwindcss/oxide-linux-arm-gnueabihf": ["@tailwindcss/oxide-linux-arm-gnueabihf@4.2.4", "", { "os": "linux", "cpu": "arm" }, "sha512-7pIHBLTHYRAlS7V22JNuTh33yLH4VElwKtB3bwchK/UaKUPpQ0lPQiOWcbm4V3WP2I6fNIJ23vABIvoy2izdwA=="],
+    "@tailwindcss/oxide-linux-arm-gnueabihf": ["@tailwindcss/oxide-linux-arm-gnueabihf@4.3.3", "", { "os": "linux", "cpu": "arm" }, "sha512-aAYUprJAJQWWbRrPvtjdroZ56Md+JM8pMiopS6xGEwDfLhqj+2ver2p4nU4Mb3CRqcMmNBjo8KkUgcxhkzVQGQ=="],
 
-    "@tailwindcss/oxide-linux-arm64-gnu": ["@tailwindcss/oxide-linux-arm64-gnu@4.2.4", "", { "os": "linux", "cpu": "arm64" }, "sha512-+E4wxJ0ZGOzSH325reXTWB48l42i93kQqMvDyz5gqfRzRZ7faNhnmvlV4EPGJU3QJM/3Ab5jhJ5pCRUsKn6OQw=="],
+    "@tailwindcss/oxide-linux-arm64-gnu": ["@tailwindcss/oxide-linux-arm64-gnu@4.3.3", "", { "os": "linux", "cpu": "arm64" }, "sha512-nDxldcEENOxZRzC2uu9jrutZdAAQtb+8WWDCSnWL1zvBk1+FN+x6MtDViPB5AJMfttVCUhehGWus3XBPgatM/w=="],
 
-    "@tailwindcss/oxide-linux-arm64-musl": ["@tailwindcss/oxide-linux-arm64-musl@4.2.4", "", { "os": "linux", "cpu": "arm64" }, "sha512-bBADEGAbo4ASnppIziaQJelekCxdMaxisrk+fB7Thit72IBnALp9K6ffA2G4ruj90G9XRS2VQ6q2bCKbfFV82g=="],
+    "@tailwindcss/oxide-linux-arm64-musl": ["@tailwindcss/oxide-linux-arm64-musl@4.3.3", "", { "os": "linux", "cpu": "arm64" }, "sha512-Md44bD6veX/PC5iyF8cDVnw4HBIANZepRZZ7a8DQOvkfo5WUBwcp6iAuCUz23u+4SUkhJlD3eL7hNdW8ezd/kA=="],
 
-    "@tailwindcss/oxide-linux-x64-gnu": ["@tailwindcss/oxide-linux-x64-gnu@4.2.4", "", { "os": "linux", "cpu": "x64" }, "sha512-7Mx25E4WTfnht0TVRTyC00j3i0M+EeFe7wguMDTlX4mRxafznw0CA8WJkFjWYH5BlgELd1kSjuU2JiPnNZbJDA=="],
+    "@tailwindcss/oxide-linux-x64-gnu": ["@tailwindcss/oxide-linux-x64-gnu@4.3.3", "", { "os": "linux", "cpu": "x64" }, "sha512-tx7us1muwOKAKWao2v/GaafFeQboE6aj88vC6ziN2NCGcRm8gWUhwjzg+YdVB1e4boAtdtma4L43onunI6NS4w=="],
 
-    "@tailwindcss/oxide-linux-x64-musl": ["@tailwindcss/oxide-linux-x64-musl@4.2.4", "", { "os": "linux", "cpu": "x64" }, "sha512-2wwJRF7nyhOR0hhHoChc04xngV3iS+akccHTGtz965FwF0up4b2lOdo6kI1EbDaEXKgvcrFBYcYQQ/rrnWFVfA=="],
+    "@tailwindcss/oxide-linux-x64-musl": ["@tailwindcss/oxide-linux-x64-musl@4.3.3", "", { "os": "linux", "cpu": "x64" }, "sha512-SJxX60smvHgasZoBy11dX6YRjXJFovwWBoedhbQPOBzgFWBHGB+TVPWB9BxzR7TTxU8FQZAI2AyiNCMzFm8Img=="],
 
-    "@tailwindcss/oxide-wasm32-wasi": ["@tailwindcss/oxide-wasm32-wasi@4.2.4", "", { "dependencies": { "@emnapi/core": "^1.8.1", "@emnapi/runtime": "^1.8.1", "@emnapi/wasi-threads": "^1.1.0", "@napi-rs/wasm-runtime": "^1.1.1", "@tybys/wasm-util": "^0.10.1", "tslib": "^2.8.1" }, "cpu": "none" }, "sha512-FQsqApeor8Fo6gUEklzmaa9994orJZZDBAlQpK2Mq+DslRKFJeD6AjHpBQ0kZFQohVr8o85PPh8eOy86VlSCmw=="],
+    "@tailwindcss/oxide-wasm32-wasi": ["@tailwindcss/oxide-wasm32-wasi@4.3.3", "", { "dependencies": { "@emnapi/core": "^1.11.1", "@emnapi/runtime": "^1.11.1", "@emnapi/wasi-threads": "^1.2.2", "@napi-rs/wasm-runtime": "^1.1.4", "@tybys/wasm-util": "^0.10.2", "tslib": "^2.8.1" }, "cpu": "none" }, "sha512-jx1+rPhY/5Ympkktd656HBWEBLxP7dH06losBLjjf5vgCODXvi9KhtftWcMIwTFIDqBr7cRnQkdLnAG+IOlGvQ=="],
 
-    "@tailwindcss/oxide-win32-arm64-msvc": ["@tailwindcss/oxide-win32-arm64-msvc@4.2.4", "", { "os": "win32", "cpu": "arm64" }, "sha512-L9BXqxC4ToVgwMFqj3pmZRqyHEztulpUJzCxUtLjobMCzTPsGt1Fa9enKbOpY2iIyVtaHNeNvAK8ERP/64sqGQ=="],
+    "@tailwindcss/oxide-win32-arm64-msvc": ["@tailwindcss/oxide-win32-arm64-msvc@4.3.3", "", { "os": "win32", "cpu": "arm64" }, "sha512-3rc292Ca2ceK6Ulcc/bAVnTs/3nDtoPhyEKlgPv+yQJQi/JS/AMJlqzxvlDacL1nekbrcf6bTqp/jV4qgnPxNQ=="],
 
-    "@tailwindcss/oxide-win32-x64-msvc": ["@tailwindcss/oxide-win32-x64-msvc@4.2.4", "", { "os": "win32", "cpu": "x64" }, "sha512-ESlKG0EpVJQwRjXDDa9rLvhEAh0mhP1sF7sap9dNZT0yyl9SAG6T7gdP09EH0vIv0UNTlo6jPWyujD6559fZvw=="],
+    "@tailwindcss/oxide-win32-x64-msvc": ["@tailwindcss/oxide-win32-x64-msvc@4.3.3", "", { "os": "win32", "cpu": "x64" }, "sha512-yJ0pwIVc/nYeGoV02WtsN8KYyLQv7kyI2wDnkezyJlGGjkd4QLwDGAwl47YpPJeuI0M0ObaXGSPjvWDPeTPggw=="],
 
-    "@tailwindcss/postcss": ["@tailwindcss/postcss@4.2.4", "", { "dependencies": { "@alloc/quick-lru": "^5.2.0", "@tailwindcss/node": "4.2.4", "@tailwindcss/oxide": "4.2.4", "postcss": "^8.5.6", "tailwindcss": "4.2.4" } }, "sha512-wgAVj6nUWAolAu8YFvzT2cTBIElWHkjZwFYovF+xsqKsW2ADxM/X2opxj5NsF/qVccAOjRNe8X2IdPzMsWyHTg=="],
+    "@tailwindcss/postcss": ["@tailwindcss/postcss@4.3.3", "", { "dependencies": { "@alloc/quick-lru": "^5.2.0", "@tailwindcss/node": "4.3.3", "@tailwindcss/oxide": "4.3.3", "postcss": "^8.5.16", "tailwindcss": "4.3.3" } }, "sha512-JTSZZGQi1AyKirbLN3azmjVzef92tcX7h+iSqPdaeStyFpGpDlKvvpxeOE8njhbUanbRwr3z8DyzhICWnMtQeg=="],
 
     "@testing-library/dom": ["@testing-library/dom@10.4.1", "", { "dependencies": { "@babel/code-frame": "^7.10.4", "@babel/runtime": "^7.12.5", "@types/aria-query": "^5.0.1", "aria-query": "5.3.0", "dom-accessibility-api": "^0.5.9", "lz-string": "^1.5.0", "picocolors": "1.1.1", "pretty-format": "^27.0.2" } }, "sha512-o4PXJQidqJl82ckFaXUeoAW+XysPLauYI43Abki5hABd853iMhitooc6znOnczgbTYmEP6U6/y1ZyKAIsvMKGg=="],
 
@@ -315,7 +422,7 @@
 
     "@testing-library/user-event": ["@testing-library/user-event@14.6.1", "", { "peerDependencies": { "@testing-library/dom": ">=7.21.4" } }, "sha512-vq7fv0rnt+QTXgPxr5Hjc210p6YKq2kmdziLgnsZGgLJ9e6VAShx1pACLuRjd/AS/sr7phAR58OIIpf0LlmQNw=="],
 
-    "@tybys/wasm-util": ["@tybys/wasm-util@0.10.1", "", { "dependencies": { "tslib": "^2.4.0" } }, "sha512-9tTaPJLSiejZKx+Bmog4uSubteqTvFrVrURwkmHixBo0G4seD0zUxp98E1DzUBJxLQ3NPwXrGKDiVjwx/DpPsg=="],
+    "@tybys/wasm-util": ["@tybys/wasm-util@0.10.3", "", { "dependencies": { "tslib": "^2.4.0" } }, "sha512-F3fo1MYrRJYL3zER0OUOmkutjr1Vp23m7OsSgp7nq4SP6OqX6C/56XFIPAl5bt3zaBRjmW7SGz3u/6LwFpYcOg=="],
 
     "@types/aria-query": ["@types/aria-query@5.0.4", "", {}, "sha512-rfT93uj5s0PRL7EzccGMs3brplhcrghnDoV26NqKhCAS1hVo+WdNsPvE/yb6ilfr5hi2MEk6d5EWJTKdxg8jVw=="],
 
@@ -323,10 +430,14 @@
 
     "@types/deep-eql": ["@types/deep-eql@4.0.2", "", {}, "sha512-c9h9dVVMigMPc4bwTvC5dxqtqJZwQPePsWjPlpSOnojbor6pGqdk541lfA7AqFQr5pB1BRdq0juY9db81BwyFw=="],
 
+    "@types/esrecurse": ["@types/esrecurse@4.3.1", "", {}, "sha512-xJBAbDifo5hpffDBuHl0Y8ywswbiAp/Wi7Y/GtAgSlZyIABppyurxVueOPE8LUQOxdlgi6Zqce7uoEpqNTeiUw=="],
+
     "@types/estree": ["@types/estree@1.0.8", "", {}, "sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w=="],
 
     "@types/hast": ["@types/hast@3.0.4", "", { "dependencies": { "@types/unist": "*" } }, "sha512-WPs+bbQw5aCj+x6laNGWLH3wviHtoCv/P3+otBhbOhJgG8qtpdAMlTCxLtsTWA7LH1Oh/bFCHsBn0TPS5m30EQ=="],
 
+    "@types/json-schema": ["@types/json-schema@7.0.15", "", {}, "sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA=="],
+
     "@types/linkify-it": ["@types/linkify-it@5.0.0", "", {}, "sha512-sVDA58zAw4eWAffKOaQH5/5j3XeayukzDk+ewSsnv3p4yJEZHCCzMDiZM8e0OUrRvmpGZ85jf4yDHkHsgBNr9Q=="],
 
     "@types/markdown-it": ["@types/markdown-it@14.1.2", "", { "dependencies": { "@types/linkify-it": "^5", "@types/mdurl": "^2" } }, "sha512-promo4eFwuiW+TfGxhi+0x3czqTYJkG8qB17ZUJiVF10Xm7NLVRSLUsfRTU/6h1e24VvRnXCx+hG7li58lkzog=="],
@@ -337,7 +448,7 @@
 
     "@types/mdx": ["@types/mdx@2.0.13", "", {}, "sha512-+OWZQfAYyio6YkJb3HLxDrvnx6SWWDbC0zVPfBRzUk0/nqoDyf6dNxQi3eArPe8rJ473nobTMQ/8Zk+LxJ+Yuw=="],
 
-    "@types/node": ["@types/node@25.6.0", "", { "dependencies": { "undici-types": "~7.19.0" } }, "sha512-+qIYRKdNYJwY3vRCZMdJbPLJAtGjQBudzZzdzwQYkEPQd+PJGixUL5QfvCLDaULoLv+RhT3LDkwEfKaAkgSmNQ=="],
+    "@types/node": ["@types/node@26.1.2", "", { "dependencies": { "undici-types": "~8.3.0" } }, "sha512-Vu4a5UFA9rIIFJ7rB/Vaafh9lrCQszopTCx6KjFboXTGQbPNasehVR5TEiithSDGyd1DEiUByggTZsg8jukeIg=="],
 
     "@types/react": ["@types/react@19.2.14", "", { "dependencies": { "csstype": "^3.2.2" } }, "sha512-ilcTH/UniCkMdtexkoCN0bI7pMcJDvmQFPvuPvmEaYA/NSfFTAgdUSLAoVjaRJm7+6PvcM+q1zYOwS4wTYMF9w=="],
 
@@ -351,6 +462,26 @@
 
     "@types/ws": ["@types/ws@8.18.1", "", { "dependencies": { "@types/node": "*" } }, "sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg=="],
 
+    "@typescript-eslint/eslint-plugin": ["@typescript-eslint/eslint-plugin@8.65.0", "", { "dependencies": { "@eslint-community/regexpp": "^4.12.2", "@typescript-eslint/scope-manager": "8.65.0", "@typescript-eslint/type-utils": "8.65.0", "@typescript-eslint/utils": "8.65.0", "@typescript-eslint/visitor-keys": "8.65.0", "ignore": "^7.0.5", "natural-compare": "^1.4.0", "ts-api-utils": "^2.5.0" }, "peerDependencies": { "@typescript-eslint/parser": "^8.65.0", "eslint": "^8.57.0 || ^9.0.0 || ^10.0.0", "typescript": ">=4.8.4 <6.1.0" } }, "sha512-IEgob78X12rHpUmtcwFsXhZdVGJtwTVP8FiCLZkR6GlYVrl2PcuB+KhCE5BlVC/eQpQnu8WXRtkHZuPar+gCRA=="],
+
+    "@typescript-eslint/parser": ["@typescript-eslint/parser@8.65.0", "", { "dependencies": { "@typescript-eslint/scope-manager": "8.65.0", "@typescript-eslint/types": "8.65.0", "@typescript-eslint/typescript-estree": "8.65.0", "@typescript-eslint/visitor-keys": "8.65.0", "debug": "^4.4.3" }, "peerDependencies": { "eslint": "^8.57.0 || ^9.0.0 || ^10.0.0", "typescript": ">=4.8.4 <6.1.0" } }, "sha512-CZ4nMxWwgu1HEEFNkeaCptra9QCtkmKdgf3sWh1rl1trIhmxLilgTV4cwcbQ4wemnT4sWQN8CaKOmdYx+g2gMA=="],
+
+    "@typescript-eslint/project-service": ["@typescript-eslint/project-service@8.65.0", "", { "dependencies": { "@typescript-eslint/tsconfig-utils": "^8.65.0", "@typescript-eslint/types": "^8.65.0", "debug": "^4.4.3" }, "peerDependencies": { "typescript": ">=4.8.4 <6.1.0" } }, "sha512-SxnPhbTsGahizDgbu7oqFH/xVtzIqMd/s+WtnSxNxJZJpLbdT5IPdzg8EZxO3+PoKahXmwJLeNQOpKJb3/bi7Q=="],
+
+    "@typescript-eslint/scope-manager": ["@typescript-eslint/scope-manager@8.65.0", "", { "dependencies": { "@typescript-eslint/types": "8.65.0", "@typescript-eslint/visitor-keys": "8.65.0" } }, "sha512-Esbl8OSYiVxBokYgWPf7VVWg/BE798wXhimnn9ML9Pt5qoDf8bfQlgjlKXR/k98+AcNzlLKYrpCcrcuZ9DZLgg=="],
+
+    "@typescript-eslint/tsconfig-utils": ["@typescript-eslint/tsconfig-utils@8.65.0", "", { "peerDependencies": { "typescript": ">=4.8.4 <6.1.0" } }, "sha512-j6GzGqCiRdA7Qhur2VVmKZAkBLfnHFQfx4TaJGL9RMveZqCo48jSHHO0DTgizEnGhtWnqmbtCUSrqSkdiY/0Hg=="],
+
+    "@typescript-eslint/type-utils": ["@typescript-eslint/type-utils@8.65.0", "", { "dependencies": { "@typescript-eslint/types": "8.65.0", "@typescript-eslint/typescript-estree": "8.65.0", "@typescript-eslint/utils": "8.65.0", "debug": "^4.4.3", "ts-api-utils": "^2.5.0" }, "peerDependencies": { "eslint": "^8.57.0 || ^9.0.0 || ^10.0.0", "typescript": ">=4.8.4 <6.1.0" } }, "sha512-YjaZ7PRI5qY7ax2L3PbvX0rRyGtipAReCWs0mhhDBHjH/vl0g0BonaGXrKdKpMbIIsMIwDgbk/xzkBTyAltS5g=="],
+
+    "@typescript-eslint/types": ["@typescript-eslint/types@8.65.0", "", {}, "sha512-JSSwWNy+H0E/01jJEM+hrX6N0OFDzFzeIhHFSAS01tlVaevpG8cFyYRPhS5yjGOvBUx3sqQHVMjCL1CAZZMxBg=="],
+
+    "@typescript-eslint/typescript-estree": ["@typescript-eslint/typescript-estree@8.65.0", "", { "dependencies": { "@typescript-eslint/project-service": "8.65.0", "@typescript-eslint/tsconfig-utils": "8.65.0", "@typescript-eslint/types": "8.65.0", "@typescript-eslint/visitor-keys": "8.65.0", "debug": "^4.4.3", "minimatch": "^10.2.2", "semver": "^7.7.3", "tinyglobby": "^0.2.15", "ts-api-utils": "^2.5.0" }, "peerDependencies": { "typescript": ">=4.8.4 <6.1.0" } }, "sha512-JboAE2swaYt4tb1fHhHTABE2K+OLy09XfcTbhnk4Pw96f9dd2e9iYsJ28gBggHlo5z5x1rkyWvcPoTuNTd4oGg=="],
+
+    "@typescript-eslint/utils": ["@typescript-eslint/utils@8.65.0", "", { "dependencies": { "@eslint-community/eslint-utils": "^4.9.1", "@typescript-eslint/scope-manager": "8.65.0", "@typescript-eslint/types": "8.65.0", "@typescript-eslint/typescript-estree": "8.65.0" }, "peerDependencies": { "eslint": "^8.57.0 || ^9.0.0 || ^10.0.0", "typescript": ">=4.8.4 <6.1.0" } }, "sha512-gXiwIHsYreboxeJucHKPvgwl7dXt50mF8s1/c00cP/WoVTyWKFdtfhRWwZiXYFU5H2O8vVoSLNrexFZjYS/SGA=="],
+
+    "@typescript-eslint/visitor-keys": ["@typescript-eslint/visitor-keys@8.65.0", "", { "dependencies": { "@typescript-eslint/types": "8.65.0", "eslint-visitor-keys": "^5.0.0" } }, "sha512-8C71BQkGjiMmXtop7pHVJu1l2NNShFdkCyD6a2ezzs5vU/L3LRtb69EtcteFwz0mYMPzIgOw0n6OV4VBUWZd7A=="],
+
     "@ungap/structured-clone": ["@ungap/structured-clone@1.3.0", "", {}, "sha512-WmoN8qaIAo7WTYWbAZuG8PYEhn5fkz7dZrqTBZ7dtt//lL2Gwms1IcnQ5yHqjDfX8Ft5j4YzDM23f87zBfDe9g=="],
 
     "@vitejs/plugin-vue": ["@vitejs/plugin-vue@5.2.4", "", { "peerDependencies": { "vite": "^5.0.0 || ^6.0.0", "vue": "^3.2.25" } }, "sha512-7Yx/SXSOcQq5HiiV3orevHUFn+pmMB4cgbEkDYgnkUWb0WfeQ/wa2yFv6D5ICiCQOVpjA7vYDXrC7AGO8yjDHA=="],
@@ -405,31 +536,41 @@
 
     "acorn": ["acorn@8.16.0", "", { "bin": { "acorn": "bin/acorn" } }, "sha512-UVJyE9MttOsBQIDKw1skb9nAwQuR5wuGD3+82K6JgJlm/Y+KI92oNsMNGZCYdDsVtRHSak0pcV5Dno5+4jh9sw=="],
 
+    "acorn-jsx": ["acorn-jsx@5.3.2", "", { "peerDependencies": { "acorn": "^6.0.0 || ^7.0.0 || ^8.0.0" } }, "sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ=="],
+
+    "ajv": ["ajv@6.15.0", "", { "dependencies": { "fast-deep-equal": "^3.1.1", "fast-json-stable-stringify": "^2.0.0", "json-schema-traverse": "^0.4.1", "uri-js": "^4.2.2" } }, "sha512-fgFx7Hfoq60ytK2c7DhnF8jIvzYgOMxfugjLOSMHjLIPgenqa7S7oaagATUq99mV6IYvN2tRmC0wnTYX6iPbMw=="],
+
     "algoliasearch": ["algoliasearch@5.49.2", "", { "dependencies": { "@algolia/abtesting": "1.15.2", "@algolia/client-abtesting": "5.49.2", "@algolia/client-analytics": "5.49.2", "@algolia/client-common": "5.49.2", "@algolia/client-insights": "5.49.2", "@algolia/client-personalization": "5.49.2", "@algolia/client-query-suggestions": "5.49.2", "@algolia/client-search": "5.49.2", "@algolia/ingestion": "1.49.2", "@algolia/monitoring": "1.49.2", "@algolia/recommend": "5.49.2", "@algolia/requester-browser-xhr": "5.49.2", "@algolia/requester-fetch": "5.49.2", "@algolia/requester-node-http": "5.49.2" } }, "sha512-1K0wtDaRONwfhL4h8bbJ9qTjmY6rhGgRvvagXkMBsAOMNr+3Q2SffHECh9DIuNVrMA1JwA0zCwhyepgBZVakng=="],
 
     "ansi-regex": ["ansi-regex@5.0.1", "", {}, "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ=="],
 
     "ansi-styles": ["ansi-styles@5.2.0", "", {}, "sha512-Cxwpt2SfTzTtXcfOlzGEee8O+c+MmUgGrNiBcXnuWxuFJHe6a5Hz7qwhwe5OgaSYI0IJvkLqWX1ASG+cJOkEiA=="],
 
-    "aria-query": ["aria-query@5.3.2", "", {}, "sha512-COROpnaoap1E2F000S62r6A60uHZnmlvomhfyT2DlTcrY1OrBKn2UhH7qn5wTC9zMvD0AY7csdPSNwKP+7WiQw=="],
+    "aria-query": ["aria-query@5.3.0", "", { "dependencies": { "dequal": "^2.0.3" } }, "sha512-b0P0sZPKtyu8HkeRAfCq0IfURZK+SuwMjY1UXGBU27wpAiTwQAIlq56IbIO+ytk/JjS1fMR14ee5WBBfKi5J6A=="],
 
     "assertion-error": ["assertion-error@2.0.1", "", {}, "sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA=="],
 
     "ast-types": ["ast-types@0.16.1", "", { "dependencies": { "tslib": "^2.0.1" } }, "sha512-6t10qk83GOG8p0vKmaCr8eiilZwO171AvbROMtvvNiwrTly62t+7XkA8RdIIVbpMhCASAsxgAzdRSwh6nw/5Dg=="],
 
-    "autoprefixer": ["autoprefixer@10.5.0", "", { "dependencies": { "browserslist": "^4.28.2", "caniuse-lite": "^1.0.30001787", "fraction.js": "^5.3.4", "picocolors": "^1.1.1", "postcss-value-parser": "^4.2.0" }, "peerDependencies": { "postcss": "^8.1.0" }, "bin": { "autoprefixer": "bin/autoprefixer" } }, "sha512-FMhOoZV4+qR6aTUALKX2rEqGG+oyATvwBt9IIzVR5rMa2HRWPkxf+P+PAJLD1I/H5/II+HuZcBJYEFBpq39ong=="],
+    "autoprefixer": ["autoprefixer@10.5.4", "", { "dependencies": { "browserslist": "^4.28.6", "caniuse-lite": "^1.0.30001806", "fraction.js": "^5.3.4", "picocolors": "^1.1.1", "postcss-value-parser": "^4.2.0" }, "peerDependencies": { "postcss": "^8.1.0" }, "bin": { "autoprefixer": "bin/autoprefixer" } }, "sha512-MaU0U/za7N3r6brxD4YB/l4NSrFzLPlANv6wEuQVaIPlD3L4W9rFcQPbL/EilY9BHhHvhfcz3gInDLrEtWT4EA=="],
 
-    "baseline-browser-mapping": ["baseline-browser-mapping@2.10.24", "", { "bin": { "baseline-browser-mapping": "dist/cli.cjs" } }, "sha512-I2NkZOOrj2XuguvWCK6OVh9GavsNjZjK908Rq3mIBK25+GD8vPX5w2WdxVqnQ7xx3SrZJiCiZFu+/Oz50oSYSA=="],
+    "balanced-match": ["balanced-match@4.0.4", "", {}, "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA=="],
+
+    "baseline-browser-mapping": ["baseline-browser-mapping@2.11.8", "", { "bin": { "baseline-browser-mapping": "dist/cli.cjs" } }, "sha512-zAgkquC2WYF0PIc6XbNYkA2uuxxFavzgmX61R+dHDUa558V8Ejf8ozTZFR6QzM24RWu4kBcRkhJ5kpz77j9fnQ=="],
 
     "birpc": ["birpc@2.9.0", "", {}, "sha512-KrayHS5pBi69Xi9JmvoqrIgYGDkD6mcSe/i6YKi3w5kekCLzrX4+nawcXqrj2tIp50Kw/mT/s3p+GVK0A0sKxw=="],
 
-    "browserslist": ["browserslist@4.28.2", "", { "dependencies": { "baseline-browser-mapping": "^2.10.12", "caniuse-lite": "^1.0.30001782", "electron-to-chromium": "^1.5.328", "node-releases": "^2.0.36", "update-browserslist-db": "^1.2.3" }, "bin": { "browserslist": "cli.js" } }, "sha512-48xSriZYYg+8qXna9kwqjIVzuQxi+KYWp2+5nCYnYKPTr0LvD89Jqk2Or5ogxz0NUMfIjhh2lIUX/LyX9B4oIg=="],
+    "brace-expansion": ["brace-expansion@5.0.9", "", { "dependencies": { "balanced-match": "^4.0.2" } }, "sha512-ScQ4IuvIEF1TMlP7Zt+vjJ//9zlPb2SDcxWxM3bk8s6t6GGdJ7KO1dCcTidOPJKePW30LE/2cT7wCyPho9/Wxg=="],
+
+    "browserslist": ["browserslist@4.28.7", "", { "dependencies": { "baseline-browser-mapping": "^2.10.44", "caniuse-lite": "^1.0.30001806", "electron-to-chromium": "^1.5.393", "node-releases": "^2.0.51", "update-browserslist-db": "^1.2.3" }, "bin": { "browserslist": "cli.js" } }, "sha512-JxV13hNrFxqjOc8alRbq9dK1MM79NEXYpma2B2J4wAtpWS5zIEIKqWPGCl7N4o7Uc7B7itylh7SuDujATRyyTw=="],
 
-    "bun-types": ["bun-types@1.3.13", "", { "dependencies": { "@types/node": "*" } }, "sha512-QXKeHLlOLqQX9LgYaHJfzdBaV21T63HhFJnvuRCcjZiaUDpbs5ED1MgxbMra71CsryN/1dAoXuJJJwIv/2drVA=="],
+    "buffer-image-size": ["buffer-image-size@0.6.4", "", { "dependencies": { "@types/node": "*" } }, "sha512-nEh+kZOPY1w+gcCMobZ6ETUp9WfibndnosbpwB1iJk/8Gt5ZF2bhS6+B6bPYz424KtwsR6Rflc3tCz1/ghX2dQ=="],
+
+    "bun-types": ["bun-types@1.3.14", "", { "dependencies": { "@types/node": "*" } }, "sha512-4N0ig0fEomHt5R0KCFWjovxow98rIoRwKolrYdCcknNwMekCXRnWEUvgu5soYV8QXtVsrUD8B95MBOZGPvr6KQ=="],
 
     "bundle-name": ["bundle-name@4.1.0", "", { "dependencies": { "run-applescript": "^7.0.0" } }, "sha512-tjwM5exMg6BGRI+kNmTntNsvdZS1X8BFYS6tnJ2hdH0kVxM6/eVZ2xy+FqStSWvYmtfFMDLIxurorHwDKfDz5Q=="],
 
-    "caniuse-lite": ["caniuse-lite@1.0.30001791", "", {}, "sha512-yk0l/YSrOnFZk3UROpDLQD9+kC1l4meK/wed583AXrzoarMGJcbRi2Q4RaUYbKxYAsZ8sWmaSa/DsLmdBeI1vQ=="],
+    "caniuse-lite": ["caniuse-lite@1.0.30001806", "", {}, "sha512-72Cuvd95zbSYPKq6Fhg8eDJRlzgWDf7/mtoZv6Qe/DYNCEBdNxoA3+rZAU2ZhGCpZlns3EssFavaZomckT5Uuw=="],
 
     "ccount": ["ccount@2.0.1", "", {}, "sha512-eyrF0jiFpY+3drT6383f1qhkbGsLSifNAjA61IUjZjmLCWjItY6LB9ft9YhoDgwfmclB2zhu51Lc7+95b8NRAg=="],
 
@@ -449,6 +590,8 @@
 
     "copy-anything": ["copy-anything@4.0.5", "", { "dependencies": { "is-what": "^5.2.0" } }, "sha512-7Vv6asjS4gMOuILabD3l739tsaxFQmC+a7pLZm02zyvs8p977bL3zEgq3yDk5rn9B0PbYgIv++jmHcuUab4RhA=="],
 
+    "cross-spawn": ["cross-spawn@7.0.6", "", { "dependencies": { "path-key": "^3.1.0", "shebang-command": "^2.0.0", "which": "^2.0.1" } }, "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA=="],
+
     "css.escape": ["css.escape@1.5.1", "", {}, "sha512-YUifsXXuknHlUsmlgyY0PKzgPOr7/FjCePfHNt0jxm83wHZi44VDMQ7/fGNkjY3/jV1MC+1CmZbaHzugyeRtpg=="],
 
     "csstype": ["csstype@3.2.3", "", {}, "sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ=="],
@@ -457,6 +600,8 @@
 
     "deep-eql": ["deep-eql@5.0.2", "", {}, "sha512-h5k/5U50IJJFpzfL6nO9jaaumfjO/f2NjK/oYB2Djzm4p9L+3T9qWpZqZ2hAbLPuuYq9wrU08WQyBTL5GbPk5Q=="],
 
+    "deep-is": ["deep-is@0.1.4", "", {}, "sha512-oIPzksmTg4/MriiaYGO+okXDT7ztn/w3Eptv/+gSIdMdKsJo0u4CfYNFJPy+4SKMuCqGw2wxnA+URMg3t8a/bQ=="],
+
     "default-browser": ["default-browser@5.5.0", "", { "dependencies": { "bundle-name": "^4.1.0", "default-browser-id": "^5.0.0" } }, "sha512-H9LMLr5zwIbSxrmvikGuI/5KGhZ8E2zH3stkMgM5LpOWDutGM2JZaj460Udnf1a+946zc7YBgrqEWwbk7zHvGw=="],
 
     "default-browser-id": ["default-browser-id@5.0.1", "", {}, "sha512-x1VCxdX4t+8wVfd1so/9w+vQ4vx7lKd2Qp5tDRutErwmR85OgmfX7RlLRMWafRMY7hbEiXIbudNrjOAPa/hL8Q=="],
@@ -469,13 +614,13 @@
 
     "devlop": ["devlop@1.1.0", "", { "dependencies": { "dequal": "^2.0.0" } }, "sha512-RWmIqhcFf1lRYBvNmr7qTNuyCt/7/ns2jbpp1+PalgE/rDQcBT0fioSMUpJ93irlUhC5hrg4cYqe6U+0ImW0rA=="],
 
-    "dom-accessibility-api": ["dom-accessibility-api@0.6.3", "", {}, "sha512-7ZgogeTnjuHbo+ct10G9Ffp0mif17idi0IyWNVA/wcwcm7NPOD/WEHVP3n7n3MhXqxoIYm8d6MuZohYWIZ4T3w=="],
+    "dom-accessibility-api": ["dom-accessibility-api@0.5.16", "", {}, "sha512-X7BJ2yElsnOJ30pZF4uIIDfBEVgF4XEBxL9Bxhy6dnrm5hkzqmsWHGTiHqRiITNhMyFLyAiWndIJP7Z1NTteDg=="],
 
-    "electron-to-chromium": ["electron-to-chromium@1.5.345", "", {}, "sha512-F9JXQGiMrz6yVNPI2qOVPvB9HzjH5cGzhs8oJ6A28V5L/YnzN/0KsuiibqF+F1Fd9qxFzD1BUnYSd8JfULxTwg=="],
+    "electron-to-chromium": ["electron-to-chromium@1.5.399", "", {}, "sha512-lEcqhErbHjXRvd41rnWLpzbyU/IXfIYo7QwaFWmxGeLiLyY2TBCdHnWY88vB+p3ubnihRypDm66panXl7TylLA=="],
 
     "emoji-regex-xs": ["emoji-regex-xs@1.0.0", "", {}, "sha512-LRlerrMYoIDrT6jgpeZ2YYl/L8EulRTt5hQcYjy5AInh7HWXKimpqx68aknBFpGL2+/IcogTcaydJEgaTmOpDg=="],
 
-    "enhanced-resolve": ["enhanced-resolve@5.20.1", "", { "dependencies": { "graceful-fs": "^4.2.4", "tapable": "^2.3.0" } }, "sha512-Qohcme7V1inbAfvjItgw0EaxVX5q2rdVEZHRBrEQdRZTssLDGsL8Lwrznl8oQ/6kuTJONLaDcGjkNP247XEhcA=="],
+    "enhanced-resolve": ["enhanced-resolve@5.24.5", "", { "dependencies": { "graceful-fs": "^4.2.4", "tapable": "^2.3.3" } }, "sha512-L1l8TNvomm6UVW5B253AGxQagSQr+vGwhMlrrfRS2qmhx46AMpMVJKQYLvWYbysTMY8VoicOvzHzoHMbyzB+4A=="],
 
     "entities": ["entities@7.0.1", "", {}, "sha512-TWrgLOFUQTH994YUyl1yT4uyavY5nNB5muff+RtWaqNVCAK408b5ZnnbNAUEWLTCpum9w6arT70i1XdQ4UeOPA=="],
 
@@ -483,23 +628,61 @@
 
     "escalade": ["escalade@3.2.0", "", {}, "sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA=="],
 
+    "escape-string-regexp": ["escape-string-regexp@4.0.0", "", {}, "sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA=="],
+
+    "eslint": ["eslint@10.8.0", "", { "dependencies": { "@eslint-community/eslint-utils": "^4.8.0", "@eslint-community/regexpp": "^4.12.2", "@eslint/config-array": "^0.23.5", "@eslint/config-helpers": "^0.7.0", "@eslint/core": "^1.2.1", "@eslint/plugin-kit": "^0.7.2", "@humanfs/node": "^0.16.6", "@humanwhocodes/module-importer": "^1.0.1", "@humanwhocodes/retry": "^0.4.2", "@types/estree": "^1.0.6", "ajv": "^6.14.0", "cross-spawn": "^7.0.6", "debug": "^4.3.2", "escape-string-regexp": "^4.0.0", "eslint-scope": "^9.1.2", "eslint-visitor-keys": "^5.0.1", "espree": "^11.2.0", "esquery": "^1.7.0", "esutils": "^2.0.2", "fast-deep-equal": "^3.1.3", "file-entry-cache": "^8.0.0", "find-up": "^5.0.0", "glob-parent": "^6.0.2", "ignore": "^5.2.0", "imurmurhash": "^0.1.4", "is-glob": "^4.0.0", "json-stable-stringify-without-jsonify": "^1.0.1", "minimatch": "^10.2.5", "natural-compare": "^1.4.0", "optionator": "^0.9.3" }, "peerDependencies": { "jiti": "*" }, "optionalPeers": ["jiti"], "bin": { "eslint": "bin/eslint.js" } }, "sha512-nuKKvN+oIBO0koN7Tm7dlkmnkc21mtt0QJLwAKzjLq14y6lRTdVG36MZHJ8eQHwdJMwZbQNMlPOYedMq/oVJvQ=="],
+
+    "eslint-config-prettier": ["eslint-config-prettier@10.1.8", "", { "peerDependencies": { "eslint": ">=7.0.0" }, "bin": { "eslint-config-prettier": "bin/cli.js" } }, "sha512-82GZUjRS0p/jganf6q1rEO25VSoHH0hKPCTrgillPjdI/3bgBhAE1QzHrHTizjpRvy6pGAvKjDJtk2pF9NDq8w=="],
+
+    "eslint-scope": ["eslint-scope@9.1.2", "", { "dependencies": { "@types/esrecurse": "^4.3.1", "@types/estree": "^1.0.8", "esrecurse": "^4.3.0", "estraverse": "^5.2.0" } }, "sha512-xS90H51cKw0jltxmvmHy2Iai1LIqrfbw57b79w/J7MfvDfkIkFZ+kj6zC3BjtUwh150HsSSdxXZcsuv72miDFQ=="],
+
+    "eslint-visitor-keys": ["eslint-visitor-keys@5.0.1", "", {}, "sha512-tD40eHxA35h0PEIZNeIjkHoDR4YjjJp34biM0mDvplBe//mB+IHCqHDGV7pxF+7MklTvighcCPPZC7ynWyjdTA=="],
+
+    "espree": ["espree@11.2.0", "", { "dependencies": { "acorn": "^8.16.0", "acorn-jsx": "^5.3.2", "eslint-visitor-keys": "^5.0.1" } }, "sha512-7p3DrVEIopW1B1avAGLuCSh1jubc01H2JHc8B4qqGblmg5gI9yumBgACjWo4JlIc04ufug4xJ3SQI8HkS/Rgzw=="],
+
     "esprima": ["esprima@4.0.1", "", { "bin": { "esparse": "./bin/esparse.js", "esvalidate": "./bin/esvalidate.js" } }, "sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A=="],
 
+    "esquery": ["esquery@1.7.0", "", { "dependencies": { "estraverse": "^5.1.0" } }, "sha512-Ap6G0WQwcU/LHsvLwON1fAQX9Zp0A2Y6Y/cJBl9r/JbW90Zyg4/zbG6zzKa2OTALELarYHmKu0GhpM5EO+7T0g=="],
+
+    "esrecurse": ["esrecurse@4.3.0", "", { "dependencies": { "estraverse": "^5.2.0" } }, "sha512-KmfKL3b6G+RXvP8N1vr3Tq1kL/oCFgn2NYXEtqP8/L3pKapUA4G8cFVaoF3SU323CD4XypR/ffioHmkti6/Tag=="],
+
+    "estraverse": ["estraverse@5.3.0", "", {}, "sha512-MMdARuVEQziNTeJD8DgMqmhwR11BRQ/cBP+pLtYdSTnf3MIO8fFeiINEbX36ZdNlfU/7A9f3gUw49B3oQsvwBA=="],
+
     "estree-walker": ["estree-walker@2.0.2", "", {}, "sha512-Rfkk/Mp/DL7JVje3u18FxFujQlTNR2q6QfMSMB7AvCBx91NGj/ba3kCfza0f6dVDbw7YlRf/nDrn7pQrCCyQ/w=="],
 
+    "esutils": ["esutils@2.0.3", "", {}, "sha512-kVscqXk4OCp68SZ0dkgEKVi6/8ij300KBWTJq32P/dYeWTSwK41WyTxalN1eRmA5Z9UU/LX9D7FWSmV9SAYx6g=="],
+
     "exsolve": ["exsolve@1.0.8", "", {}, "sha512-LmDxfWXwcTArk8fUEnOfSZpHOJ6zOMUJKOtFLFqJLoKJetuQG874Uc7/Kki7zFLzYybmZhp1M7+98pfMqeX8yA=="],
 
+    "fast-deep-equal": ["fast-deep-equal@3.1.3", "", {}, "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q=="],
+
+    "fast-json-stable-stringify": ["fast-json-stable-stringify@2.1.0", "", {}, "sha512-lhd/wF+Lk98HZoTCtlVraHtfh5XYijIjalXck7saUtuanSDyLMxnHhSXEDJqHxD7msR8D0uCmqlkwjCV8xvwHw=="],
+
+    "fast-levenshtein": ["fast-levenshtein@2.0.6", "", {}, "sha512-DCXu6Ifhqcks7TZKY3Hxp3y6qphY5SJZmrWMDrKcERSOXWQdMhU9Ig/PYrzyw/ul9jOIyh0N4M0tbC5hodg8dw=="],
+
     "fdir": ["fdir@6.5.0", "", { "peerDependencies": { "picomatch": "^3 || ^4" }, "optionalPeers": ["picomatch"] }, "sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg=="],
 
+    "file-entry-cache": ["file-entry-cache@8.0.0", "", { "dependencies": { "flat-cache": "^4.0.0" } }, "sha512-XXTUwCvisa5oacNGRP9SfNtYBNAMi+RPwBFmblZEF7N7swHYQS6/Zfk7SRwx4D5j3CH211YNRco1DEMNVfZCnQ=="],
+
+    "find-up": ["find-up@5.0.0", "", { "dependencies": { "locate-path": "^6.0.0", "path-exists": "^4.0.0" } }, "sha512-78/PXT1wlLLDgTzDs7sjq9hzz0vXD+zn+7wypEe4fXQxCmdmqfGsEPQxmiCSQI3ajFV91bVSsvNtrJRiW6nGng=="],
+
+    "flat-cache": ["flat-cache@4.0.1", "", { "dependencies": { "flatted": "^3.2.9", "keyv": "^4.5.4" } }, "sha512-f7ccFPK3SXFHpx15UIGyRJ/FJQctuKZ0zVuN3frBo4HnK3cay9VEW0R6yPYFHC0AgqhukPzKjq22t5DmAyqGyw=="],
+
+    "flatted": ["flatted@3.4.4", "", {}, "sha512-5+ybhBZANEJxaH3X5evAFatUxLfEHSr7n6kYJ+1Qd0mUqr4eu9gIf6GDbWHf8RJijHrjjO8G+la14SlL2SeS1Q=="],
+
     "focus-trap": ["focus-trap@7.8.0", "", { "dependencies": { "tabbable": "^6.4.0" } }, "sha512-/yNdlIkpWbM0ptxno3ONTuf+2g318kh2ez3KSeZN5dZ8YC6AAmgeWz+GasYYiBJPFaYcSAPeu4GfhUaChzIJXA=="],
 
     "fraction.js": ["fraction.js@5.3.4", "", {}, "sha512-1X1NTtiJphryn/uLQz3whtY6jK3fTqoE3ohKs0tT+Ujr1W59oopxmoEh7Lu5p6vBaPbgoM0bzveAW4Qi5RyWDQ=="],
 
     "fsevents": ["fsevents@2.3.3", "", { "os": "darwin" }, "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw=="],
 
+    "glob-parent": ["glob-parent@6.0.2", "", { "dependencies": { "is-glob": "^4.0.3" } }, "sha512-XxwI8EOhVQgWp6iDL+3b0r86f4d6AX6zSU55HfB4ydCEuXLXc5FcYeOu+nnGftS4TEju/11rt4KJPTMgbfmv4A=="],
+
+    "globals": ["globals@17.8.0", "", {}, "sha512-Zz/LMDZScFmkakeL2cTHzf+PbWKdpU3uclqkZT7TjDG58j5WPt0PpA+n9uPI24fZtlw07q0OtEi84K+umsRzqQ=="],
+
     "graceful-fs": ["graceful-fs@4.2.11", "", {}, "sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ=="],
 
-    "happy-dom": ["happy-dom@20.9.0", "", { "dependencies": { "@types/node": ">=20.0.0", "@types/whatwg-mimetype": "^3.0.2", "@types/ws": "^8.18.1", "entities": "^7.0.1", "whatwg-mimetype": "^3.0.0", "ws": "^8.18.3" } }, "sha512-GZZ9mKe8r646NUAf/zemnGbjYh4Bt8/MqASJY+pSm5ZDtc3YQox+4gsLI7yi1hba6o+eCsGxpHn5+iEVn31/FQ=="],
+    "happy-dom": ["happy-dom@20.11.1", "", { "dependencies": { "@types/node": ">=20.0.0", "@types/whatwg-mimetype": "^3.0.2", "@types/ws": "^8.18.1", "buffer-image-size": "^0.6.4", "entities": "^7.0.1", "whatwg-mimetype": "^3.0.0", "ws": "^8.21.0" } }, "sha512-XSt8tMzbW9ymE7687xztkO1ckR7qJNQ3LywY9vlYGhGi3zXrGBHuUo2Cl1ztZaICW+1eAGdkLbj6iwVqDT33kg=="],
 
     "hast-util-to-html": ["hast-util-to-html@9.0.5", "", { "dependencies": { "@types/hast": "^3.0.0", "@types/unist": "^3.0.0", "ccount": "^2.0.0", "comma-separated-tokens": "^2.0.0", "hast-util-whitespace": "^3.0.0", "html-void-elements": "^3.0.0", "mdast-util-to-hast": "^13.0.0", "property-information": "^7.0.0", "space-separated-tokens": "^2.0.0", "stringify-entities": "^4.0.0", "zwitch": "^2.0.4" } }, "sha512-OguPdidb+fbHQSU4Q4ZiLKnzWo8Wwsf5bZfbvu7//a9oTYoqD/fWpe96NuHkoS9h0ccGOTe0C4NGXdtS0iObOw=="],
 
@@ -509,45 +692,67 @@
 
     "html-void-elements": ["html-void-elements@3.0.0", "", {}, "sha512-bEqo66MRXsUGxWHV5IP0PUiAWwoEjba4VCzg0LjFJBpchPaTfyfCKTG6bc5F8ucKec3q5y6qOdGyYTSBEvhCrg=="],
 
+    "ignore": ["ignore@7.0.6", "", {}, "sha512-BAg6QkE8W+TuQLrrw0Ugr7HegXduRuuj8/ti2kSOc+jz1dmx8/WNcjr6XGnq5YpDWxFwwaavqD0+jIUOKelTsw=="],
+
+    "imurmurhash": ["imurmurhash@0.1.4", "", {}, "sha512-JmXMZ6wuvDmLiHEml9ykzqO6lwFbof0GG4IkcGaENdCRDDmMVnny7s5HsIgHCbaq0w2MyPhDqkhTUgS2LU2PHA=="],
+
     "indent-string": ["indent-string@4.0.0", "", {}, "sha512-EdDDZu4A2OyIK7Lr/2zG+w5jmbuk1DVBnEwREQvBzspBJkCEbRa8GxU1lghYcaGJCnRWibjDXlq779X1/y5xwg=="],
 
     "is-docker": ["is-docker@3.0.0", "", { "bin": { "is-docker": "cli.js" } }, "sha512-eljcgEDlEns/7AXFosB5K/2nCM4P7FQPkGc/DWLy5rmFEWvZayGrik1d9/QIY5nJ4f9YsVvBkA6kJpHn9rISdQ=="],
 
+    "is-extglob": ["is-extglob@2.1.1", "", {}, "sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ=="],
+
+    "is-glob": ["is-glob@4.0.3", "", { "dependencies": { "is-extglob": "^2.1.1" } }, "sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg=="],
+
     "is-inside-container": ["is-inside-container@1.0.0", "", { "dependencies": { "is-docker": "^3.0.0" }, "bin": { "is-inside-container": "cli.js" } }, "sha512-KIYLCCJghfHZxqjYBE7rEy0OBuTd5xCHS7tHVgvCLkx7StIoaxwNW3hCALgEUjFfeRk+MG/Qxmp/vtETEF3tRA=="],
 
     "is-what": ["is-what@5.5.0", "", {}, "sha512-oG7cgbmg5kLYae2N5IVd3jm2s+vldjxJzK1pcu9LfpGuQ93MQSzo0okvRna+7y5ifrD+20FE8FvjusyGaz14fw=="],
 
     "is-wsl": ["is-wsl@3.1.1", "", { "dependencies": { "is-inside-container": "^1.0.0" } }, "sha512-e6rvdUCiQCAuumZslxRJWR/Doq4VpPR82kqclvcS0efgt430SlGIk05vdCN58+VrzgtIcfNODjozVielycD4Sw=="],
 
+    "isexe": ["isexe@2.0.0", "", {}, "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw=="],
+
     "jiti": ["jiti@2.6.1", "", { "bin": { "jiti": "lib/jiti-cli.mjs" } }, "sha512-ekilCSN1jwRvIbgeg/57YFh8qQDNbwDb9xT/qu2DAHbFFZUicIl4ygVaAvzveMhMVr3LnpSKTNnwt8PoOfmKhQ=="],
 
     "js-tokens": ["js-tokens@4.0.0", "", {}, "sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ=="],
 
+    "json-buffer": ["json-buffer@3.0.1", "", {}, "sha512-4bV5BfR2mqfQTJm+V5tPPdf+ZpuhiIvTuAB5g8kcrXOZpTT/QwwVRWBywX1ozr6lEuPdbHxwaJlm9G6mI2sfSQ=="],
+
+    "json-schema-traverse": ["json-schema-traverse@0.4.1", "", {}, "sha512-xbbCH5dCYU5T8LcEhhuh7HJ88HXuW3qsI3Y0zOZFKfZEHcpWiHU/Jxzk629Brsab/mMiHQti9wMP+845RPe3Vg=="],
+
+    "json-stable-stringify-without-jsonify": ["json-stable-stringify-without-jsonify@1.0.1", "", {}, "sha512-Bdboy+l7tA3OGW6FjyFHWkP5LuByj1Tk33Ljyq0axyzdk9//JSi2u3fP1QSmd1KNwq6VOKYGlAu87CisVir6Pw=="],
+
+    "jsonc-parser": ["jsonc-parser@3.3.1", "", {}, "sha512-HUgH65KyejrUFPvHFPbqOY0rsFip3Bo5wb4ngvdi1EpCYWUQDC5V+Y7mZws+DLkr4M//zQJoanu1SP+87Dv1oQ=="],
+
+    "keyv": ["keyv@4.5.4", "", { "dependencies": { "json-buffer": "3.0.1" } }, "sha512-oxVHkHR/EJf2CNXnWxRLW6mg7JyCCUcG0DtEGmL2ctUo1PNTin1PUil+r/+4r5MpVgC/fn1kjsx7mjSujKqIpw=="],
+
     "kolorist": ["kolorist@1.8.0", "", {}, "sha512-Y+60/zizpJ3HRH8DCss+q95yr6145JXZo46OTpFvDZWLfRCE4qChOyk1b26nMaNpfHHgxagk9dXT5OP0Tfe+dQ=="],
 
-    "lightningcss": ["lightningcss@1.32.0", "", { "dependencies": { "detect-libc": "^2.0.3" }, "optionalDependencies": { "lightningcss-android-arm64": "1.32.0", "lightningcss-darwin-arm64": "1.32.0", "lightningcss-darwin-x64": "1.32.0", "lightningcss-freebsd-x64": "1.32.0", "lightningcss-linux-arm-gnueabihf": "1.32.0", "lightningcss-linux-arm64-gnu": "1.32.0", "lightningcss-linux-arm64-musl": "1.32.0", "lightningcss-linux-x64-gnu": "1.32.0", "lightningcss-linux-x64-musl": "1.32.0", "lightningcss-win32-arm64-msvc": "1.32.0", "lightningcss-win32-x64-msvc": "1.32.0" } }, "sha512-NXYBzinNrblfraPGyrbPoD19C1h9lfI/1mzgWYvXUTe414Gz/X1FD2XBZSZM7rRTrMA8JL3OtAaGifrIKhQ5yQ=="],
+    "levn": ["levn@0.4.1", "", { "dependencies": { "prelude-ls": "^1.2.1", "type-check": "~0.4.0" } }, "sha512-+bT2uH4E5LGE7h/n3evcS/sQlJXCpIp6ym8OWJ5eV6+67Dsql/LaaT7qJBAt2rzfoa/5QBGBhxDix1dMt2kQKQ=="],
+
+    "lightningcss": ["lightningcss@1.33.0", "", { "dependencies": { "detect-libc": "^2.0.3" }, "optionalDependencies": { "lightningcss-android-arm64": "1.33.0", "lightningcss-darwin-arm64": "1.33.0", "lightningcss-darwin-x64": "1.33.0", "lightningcss-freebsd-x64": "1.33.0", "lightningcss-linux-arm-gnueabihf": "1.33.0", "lightningcss-linux-arm64-gnu": "1.33.0", "lightningcss-linux-arm64-musl": "1.33.0", "lightningcss-linux-x64-gnu": "1.33.0", "lightningcss-linux-x64-musl": "1.33.0", "lightningcss-win32-arm64-msvc": "1.33.0", "lightningcss-win32-x64-msvc": "1.33.0" } }, "sha512-WkUDrojuJs0xkgGf2udWxa3yGBRxPtxUkB79i6aCZLRgc7PM8fZe9TosfPDcvEpQZbuFASnHYmRLBLUbmLOIIA=="],
 
-    "lightningcss-android-arm64": ["lightningcss-android-arm64@1.32.0", "", { "os": "android", "cpu": "arm64" }, "sha512-YK7/ClTt4kAK0vo6w3X+Pnm0D2cf2vPHbhOXdoNti1Ga0al1P4TBZhwjATvjNwLEBCnKvjJc2jQgHXH0NEwlAg=="],
+    "lightningcss-android-arm64": ["lightningcss-android-arm64@1.33.0", "", { "os": "android", "cpu": "arm64" }, "sha512-gEpRTalKdosp4Bb8qWtc2iOgE5SeIHlpS1up9bFq2wAyYhl1UdTObYiHe98zEM9SQvSoqQZ1IQD0JNpg3Ml5pg=="],
 
-    "lightningcss-darwin-arm64": ["lightningcss-darwin-arm64@1.32.0", "", { "os": "darwin", "cpu": "arm64" }, "sha512-RzeG9Ju5bag2Bv1/lwlVJvBE3q6TtXskdZLLCyfg5pt+HLz9BqlICO7LZM7VHNTTn/5PRhHFBSjk5lc4cmscPQ=="],
+    "lightningcss-darwin-arm64": ["lightningcss-darwin-arm64@1.33.0", "", { "os": "darwin", "cpu": "arm64" }, "sha512-Sciaz8eenNTKn9b3t7+xr0ipTp9YxKQY4npwQ3mrRuL0BAVHBLyZxofhaKBAVtzmtRZ/zTyo0/to4B1uWG/Djg=="],
 
-    "lightningcss-darwin-x64": ["lightningcss-darwin-x64@1.32.0", "", { "os": "darwin", "cpu": "x64" }, "sha512-U+QsBp2m/s2wqpUYT/6wnlagdZbtZdndSmut/NJqlCcMLTWp5muCrID+K5UJ6jqD2BFshejCYXniPDbNh73V8w=="],
+    "lightningcss-darwin-x64": ["lightningcss-darwin-x64@1.33.0", "", { "os": "darwin", "cpu": "x64" }, "sha512-Z5UPAxzrjlWNNyGy6i65cJzzvgJ5D3T6wMvs+gWpY9d7qRhANrxqAp6LhxIgZhWEw18RfJTGcRxjuLIBr+m8XQ=="],
 
-    "lightningcss-freebsd-x64": ["lightningcss-freebsd-x64@1.32.0", "", { "os": "freebsd", "cpu": "x64" }, "sha512-JCTigedEksZk3tHTTthnMdVfGf61Fky8Ji2E4YjUTEQX14xiy/lTzXnu1vwiZe3bYe0q+SpsSH/CTeDXK6WHig=="],
+    "lightningcss-freebsd-x64": ["lightningcss-freebsd-x64@1.33.0", "", { "os": "freebsd", "cpu": "x64" }, "sha512-QQM/Ti/hQajJwCY+RiWuCZ9sdtI/XQk7nDK5vC8kkdwixezOlDgvDx7+RT+QjK6FcFT4MpsuoBnHIo/O3StRRg=="],
 
-    "lightningcss-linux-arm-gnueabihf": ["lightningcss-linux-arm-gnueabihf@1.32.0", "", { "os": "linux", "cpu": "arm" }, "sha512-x6rnnpRa2GL0zQOkt6rts3YDPzduLpWvwAF6EMhXFVZXD4tPrBkEFqzGowzCsIWsPjqSK+tyNEODUBXeeVHSkw=="],
+    "lightningcss-linux-arm-gnueabihf": ["lightningcss-linux-arm-gnueabihf@1.33.0", "", { "os": "linux", "cpu": "arm" }, "sha512-N7FVBe6iS24MlM6R/4RBTxGhQheZGs7tiQ9U32UtF75NzP5Q7xWPRqLBCKxlRQRk3rY1jCIPLzx7WzOhuUIRLQ=="],
 
-    "lightningcss-linux-arm64-gnu": ["lightningcss-linux-arm64-gnu@1.32.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-0nnMyoyOLRJXfbMOilaSRcLH3Jw5z9HDNGfT/gwCPgaDjnx0i8w7vBzFLFR1f6CMLKF8gVbebmkUN3fa/kQJpQ=="],
+    "lightningcss-linux-arm64-gnu": ["lightningcss-linux-arm64-gnu@1.33.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-j2v/itmy4HlNxlc6voKXYgBqNi0Ng2LShg4z7GufpEgs05P+2suBVyi9I6YHq5uoVFx9ETin3eCEhLVyXGQnKg=="],
 
-    "lightningcss-linux-arm64-musl": ["lightningcss-linux-arm64-musl@1.32.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-UpQkoenr4UJEzgVIYpI80lDFvRmPVg6oqboNHfoH4CQIfNA+HOrZ7Mo7KZP02dC6LjghPQJeBsvXhJod/wnIBg=="],
+    "lightningcss-linux-arm64-musl": ["lightningcss-linux-arm64-musl@1.33.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-yiO5ROMuYQgXbC60yjZU5CYSFZGKXL0HFATXt9mHJn1+zW55oCtMI9NfcVhYLMFDL7gV7oBPon/EmMMGg2OvtQ=="],
 
-    "lightningcss-linux-x64-gnu": ["lightningcss-linux-x64-gnu@1.32.0", "", { "os": "linux", "cpu": "x64" }, "sha512-V7Qr52IhZmdKPVr+Vtw8o+WLsQJYCTd8loIfpDaMRWGUZfBOYEJeyJIkqGIDMZPwPx24pUMfwSxxI8phr/MbOA=="],
+    "lightningcss-linux-x64-gnu": ["lightningcss-linux-x64-gnu@1.33.0", "", { "os": "linux", "cpu": "x64" }, "sha512-ar+Ju7LmcN0Jo4FpL4hpFybwNG9/3A/Br5KW2n2jyODg3MEZXaDYADdemoNS+BDNfMgKvylJLj4S5tyRActuAg=="],
 
-    "lightningcss-linux-x64-musl": ["lightningcss-linux-x64-musl@1.32.0", "", { "os": "linux", "cpu": "x64" }, "sha512-bYcLp+Vb0awsiXg/80uCRezCYHNg1/l3mt0gzHnWV9XP1W5sKa5/TCdGWaR/zBM2PeF/HbsQv/j2URNOiVuxWg=="],
+    "lightningcss-linux-x64-musl": ["lightningcss-linux-x64-musl@1.33.0", "", { "os": "linux", "cpu": "x64" }, "sha512-RYiYbkokw0trfKqqzfF55lginwEPrD3OJDfTuJzFs1MK6iFnDenaz1fqLLtX4ITG3OktJQXOeTaw1awrBAlZPw=="],
 
-    "lightningcss-win32-arm64-msvc": ["lightningcss-win32-arm64-msvc@1.32.0", "", { "os": "win32", "cpu": "arm64" }, "sha512-8SbC8BR40pS6baCM8sbtYDSwEVQd4JlFTOlaD3gWGHfThTcABnNDBda6eTZeqbofalIJhFx0qKzgHJmcPTnGdw=="],
+    "lightningcss-win32-arm64-msvc": ["lightningcss-win32-arm64-msvc@1.33.0", "", { "os": "win32", "cpu": "arm64" }, "sha512-1K+MPfLSFVpphzpdbfkhlWk6wBrTObBzS2T6db10PNOZgR9GoVsAWzwNyuhUYYbTp23j+4RrncfujZ4uAzXvwA=="],
 
-    "lightningcss-win32-x64-msvc": ["lightningcss-win32-x64-msvc@1.32.0", "", { "os": "win32", "cpu": "x64" }, "sha512-Amq9B/SoZYdDi1kFrojnoqPLxYhQ4Wo5XiL8EVJrVsB8ARoC1PWW6VGtT0WKCemjy8aC+louJnjS7U18x3b06Q=="],
+    "lightningcss-win32-x64-msvc": ["lightningcss-win32-x64-msvc@1.33.0", "", { "os": "win32", "cpu": "x64" }, "sha512-OlEICDx/Xl0FqSp4bry8zFnCvGpig3Gl4gCquvYwHuqJKEC1+n9NgDniFvqHGmMv1ZkqDJrDqKKSykTDX+ehuA=="],
 
     "lit": ["lit@3.3.2", "", { "dependencies": { "@lit/reactive-element": "^2.1.0", "lit-element": "^4.2.0", "lit-html": "^3.3.0" } }, "sha512-NF9zbsP79l4ao2SNrH3NkfmFgN/hBYSQo90saIVI1o5GpjAdCPVstVzO1MrLOakHoEhYkrtRjPK6Ob521aoYWQ=="],
 
@@ -557,6 +762,8 @@
 
     "local-pkg": ["local-pkg@1.1.2", "", { "dependencies": { "mlly": "^1.7.4", "pkg-types": "^2.3.0", "quansync": "^0.2.11" } }, "sha512-arhlxbFRmoQHl33a0Zkle/YWlmNwoyt6QNZEIJcqNbdrsix5Lvc4HyyI3EnwxTYlZYc32EbYrQ8SzEZ7dqgg9A=="],
 
+    "locate-path": ["locate-path@6.0.0", "", { "dependencies": { "p-locate": "^5.0.0" } }, "sha512-iPZK6eYjbxRu3uB4/WZ3EsEIMJFMqAoopl3R+zuq0UjcAm/MO6KCweDgPfP3elTztoKP3KtnVHxTn2NHBSDVUw=="],
+
     "loupe": ["loupe@3.2.1", "", {}, "sha512-CdzqowRJCeLU72bHvWqwRBBlLcMEtIvGrlvef74kMnV2AolS9Y8xUv1I0U/MNAWMhBlKIoyuEgoJ0t/bbwHbLQ=="],
 
     "lz-string": ["lz-string@1.5.0", "", { "bin": { "lz-string": "bin/bin.js" } }, "sha512-h5bgJWpxJNswbU7qCrV0tIKQCaS3blPDrqKWx+QxzuzL1zGUzij9XCWLrSLsJPu5t+eWA/ycetzYAO5IOMcWAQ=="],
@@ -579,6 +786,8 @@
 
     "min-indent": ["min-indent@1.0.1", "", {}, "sha512-I9jwMn07Sy/IwOj3zVkVik2JTvgpaykDZEigL6Rx6N9LbMywwUSMtxET+7lVoDLLd3O3IXwJwvuuns8UB/HeAg=="],
 
+    "minimatch": ["minimatch@10.2.6", "", { "dependencies": { "brace-expansion": "^5.0.8" } }, "sha512-vpLQEs+VLCr1nU0BXS07maYoFwlDAH0gngQuuttxIwutDFEMHq2blX+8vpgxDdK3J1PwjCJiep77OitTZ4Ll1A=="],
+
     "minisearch": ["minisearch@7.2.0", "", {}, "sha512-dqT2XBYUOZOiC5t2HRnwADjhNS2cecp9u+TJRiJ1Qp/f5qjkeT5APcGPjHw+bz89Ms8Jp+cG4AlE+QZ/QnDglg=="],
 
     "mitt": ["mitt@3.0.1", "", {}, "sha512-vKivATfr97l2/QBCYAkXYDbrIWPM2IIKEl7YPhjCvKlG3kE2gm+uBo6nEXK3M5/Ffh/FLpKExzOQ3JJoJGFKBw=="],
@@ -587,16 +796,32 @@
 
     "ms": ["ms@2.1.3", "", {}, "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA=="],
 
-    "nanoid": ["nanoid@3.3.11", "", { "bin": { "nanoid": "bin/nanoid.cjs" } }, "sha512-N8SpfPUnUp1bK+PMYW8qSWdl9U+wwNWI4QKxOYDy9JAro3WMX7p2OeVRF9v+347pnakNevPmiHhNmZ2HbFA76w=="],
+    "nanoid": ["nanoid@3.3.16", "", { "bin": { "nanoid": "bin/nanoid.cjs" } }, "sha512-bzlKTyNJ7+LdGIIwy8ijFpIqEQIvafahV7eYykJ8Cvh42EdJeODoJ6gUJXpQJvej1BddH8OqTXZNE/KfbWAu8Q=="],
+
+    "natural-compare": ["natural-compare@1.4.0", "", {}, "sha512-OWND8ei3VtNC9h7V60qff3SVobHr996CTwgxubgyQYEpg290h9J0buyECNNJexkFm5sOajh5G116RYA1c8ZMSw=="],
 
-    "node-releases": ["node-releases@2.0.36", "", {}, "sha512-TdC8FSgHz8Mwtw9g5L4gR/Sh9XhSP/0DEkQxfEFXOpiul5IiHgHan2VhYYb6agDSfp4KuvltmGApc8HMgUrIkA=="],
+    "node-releases": ["node-releases@2.0.51", "", {}, "sha512-wRNIrw4DmVLKQlbgOMdkMx27Wrpzes2hh5Jtbi2bjPd+4wJstWIqP5A+lscnqbm0xxmT5Bpg8Lec5ItEBwx6BQ=="],
 
     "oniguruma-to-es": ["oniguruma-to-es@3.1.1", "", { "dependencies": { "emoji-regex-xs": "^1.0.0", "regex": "^6.0.1", "regex-recursion": "^6.0.2" } }, "sha512-bUH8SDvPkH3ho3dvwJwfonjlQ4R80vjyvrU8YpxuROddv55vAEJrTuCuCVUhhsHbtlD9tGGbaNApGQckXhS8iQ=="],
 
     "open": ["open@10.2.0", "", { "dependencies": { "default-browser": "^5.2.1", "define-lazy-prop": "^3.0.0", "is-inside-container": "^1.0.0", "wsl-utils": "^0.1.0" } }, "sha512-YgBpdJHPyQ2UE5x+hlSXcnejzAvD0b22U2OuAP+8OnlJT+PjWPxtgmGqKKc+RgTM63U9gN0YzrYc71R2WT/hTA=="],
 
+    "optionator": ["optionator@0.9.4", "", { "dependencies": { "deep-is": "^0.1.3", "fast-levenshtein": "^2.0.6", "levn": "^0.4.1", "prelude-ls": "^1.2.1", "type-check": "^0.4.0", "word-wrap": "^1.2.5" } }, "sha512-6IpQ7mKUxRcZNLIObR0hz7lxsapSSIYNZJwXPGeF0mTVqGKFIXj1DQcMoT22S3ROcLyY/rz0PWaWZ9ayWmad9g=="],
+
+    "oxc-parser": ["oxc-parser@0.127.0", "", { "dependencies": { "@oxc-project/types": "^0.127.0" }, "optionalDependencies": { "@oxc-parser/binding-android-arm-eabi": "0.127.0", "@oxc-parser/binding-android-arm64": "0.127.0", "@oxc-parser/binding-darwin-arm64": "0.127.0", "@oxc-parser/binding-darwin-x64": "0.127.0", "@oxc-parser/binding-freebsd-x64": "0.127.0", "@oxc-parser/binding-linux-arm-gnueabihf": "0.127.0", "@oxc-parser/binding-linux-arm-musleabihf": "0.127.0", "@oxc-parser/binding-linux-arm64-gnu": "0.127.0", "@oxc-parser/binding-linux-arm64-musl": "0.127.0", "@oxc-parser/binding-linux-ppc64-gnu": "0.127.0", "@oxc-parser/binding-linux-riscv64-gnu": "0.127.0", "@oxc-parser/binding-linux-riscv64-musl": "0.127.0", "@oxc-parser/binding-linux-s390x-gnu": "0.127.0", "@oxc-parser/binding-linux-x64-gnu": "0.127.0", "@oxc-parser/binding-linux-x64-musl": "0.127.0", "@oxc-parser/binding-openharmony-arm64": "0.127.0", "@oxc-parser/binding-wasm32-wasi": "0.127.0", "@oxc-parser/binding-win32-arm64-msvc": "0.127.0", "@oxc-parser/binding-win32-ia32-msvc": "0.127.0", "@oxc-parser/binding-win32-x64-msvc": "0.127.0" } }, "sha512-bkgD4qHlN7WxLdX8bLXdaU54TtQtAIg/ZBAfm0aje/mo3MRDo3P0hZSgr4U7O3xfX+fQmR5AP04JS/TGcZLcFA=="],
+
+    "oxc-resolver": ["oxc-resolver@11.24.2", "", { "optionalDependencies": { "@oxc-resolver/binding-android-arm-eabi": "11.24.2", "@oxc-resolver/binding-android-arm64": "11.24.2", "@oxc-resolver/binding-darwin-arm64": "11.24.2", "@oxc-resolver/binding-darwin-x64": "11.24.2", "@oxc-resolver/binding-freebsd-x64": "11.24.2", "@oxc-resolver/binding-linux-arm-gnueabihf": "11.24.2", "@oxc-resolver/binding-linux-arm-musleabihf": "11.24.2", "@oxc-resolver/binding-linux-arm64-gnu": "11.24.2", "@oxc-resolver/binding-linux-arm64-musl": "11.24.2", "@oxc-resolver/binding-linux-ppc64-gnu": "11.24.2", "@oxc-resolver/binding-linux-riscv64-gnu": "11.24.2", "@oxc-resolver/binding-linux-riscv64-musl": "11.24.2", "@oxc-resolver/binding-linux-s390x-gnu": "11.24.2", "@oxc-resolver/binding-linux-x64-gnu": "11.24.2", "@oxc-resolver/binding-linux-x64-musl": "11.24.2", "@oxc-resolver/binding-openharmony-arm64": "11.24.2", "@oxc-resolver/binding-wasm32-wasi": "11.24.2", "@oxc-resolver/binding-win32-arm64-msvc": "11.24.2", "@oxc-resolver/binding-win32-x64-msvc": "11.24.2" } }, "sha512-FY91FiDBj7ls5MsFS9jN3tjz2o0/zsdSsymlakySaBwVJZorHhkWyICLZMKxlu1R9vYo+sd3z1jwb4J8x7bNDw=="],
+
+    "p-limit": ["p-limit@3.1.0", "", { "dependencies": { "yocto-queue": "^0.1.0" } }, "sha512-TYOanM3wGwNGsZN2cVTYPArw454xnXj5qmWF1bEoAc4+cU/ol7GVh7odevjp1FNHduHc3KZMcFduxU5Xc6uJRQ=="],
+
+    "p-locate": ["p-locate@5.0.0", "", { "dependencies": { "p-limit": "^3.0.2" } }, "sha512-LaNjtRWUBY++zB5nE/NwcaoMylSPk+S+ZHNB1TzdbMJMny6dynpAGt7X/tl/QYq3TIeE6nxHppbo2LGymrG5Pw=="],
+
     "path-browserify": ["path-browserify@1.0.1", "", {}, "sha512-b7uo2UCUOYZcnF/3ID0lulOJi/bafxa1xPe7ZPsammBSpjSWQkjNxlt635YGS2MiR9GjvuXCtz2emr3jbsz98g=="],
 
+    "path-exists": ["path-exists@4.0.0", "", {}, "sha512-ak9Qy5Q7jYb2Wwcey5Fpvg2KoAc/ZIhLSLOSBmRmygPsGwkVVt0fZa0qrtMz+m6tJTAHfZQ8FnmB4MG4LWy7/w=="],
+
+    "path-key": ["path-key@3.1.1", "", {}, "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q=="],
+
     "pathe": ["pathe@2.0.3", "", {}, "sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w=="],
 
     "pathval": ["pathval@2.0.1", "", {}, "sha512-//nshmD55c46FuFw26xV/xFAaB5HF9Xdap7HJBBnrKdAd6/GxDBaNA1870O79+9ueg61cZLSVc+OaFlfmObYVQ=="],
@@ -605,20 +830,24 @@
 
     "picocolors": ["picocolors@1.1.1", "", {}, "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA=="],
 
-    "picomatch": ["picomatch@4.0.4", "", {}, "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A=="],
+    "picomatch": ["picomatch@4.0.5", "", {}, "sha512-RvwwcruNjI1ncT5xRakeyS9Lf8lcItv34KD+aif+VH9kduAyfYBipGh12274xtenIPZ119/R9BdTBa8gAwSh0A=="],
 
     "pkg-types": ["pkg-types@2.3.0", "", { "dependencies": { "confbox": "^0.2.2", "exsolve": "^1.0.7", "pathe": "^2.0.3" } }, "sha512-SIqCzDRg0s9npO5XQ3tNZioRY1uK06lA41ynBC1YmFTmnY6FjUjVt6s4LoADmwoig1qqD0oK8h1p/8mlMx8Oig=="],
 
-    "postcss": ["postcss@8.5.12", "", { "dependencies": { "nanoid": "^3.3.11", "picocolors": "^1.1.1", "source-map-js": "^1.2.1" } }, "sha512-W62t/Se6rA0Az3DfCL0AqJwXuKwBeYg6nOaIgzP+xZ7N5BFCI7DYi1qs6ygUYT6rvfi6t9k65UMLJC+PHZpDAA=="],
+    "postcss": ["postcss@8.5.25", "", { "dependencies": { "nanoid": "^3.3.16", "picocolors": "^1.1.1", "source-map-js": "^1.2.1" } }, "sha512-DTPx3RWSSnWyzLxQnlH0rJP+EW5ekl16ZU4/psbIhA0e53kJfdgaN5vKM+xP7yJtXVu+nfdVFmlgFDEKAe4Pyw=="],
 
     "postcss-value-parser": ["postcss-value-parser@4.2.0", "", {}, "sha512-1NNCs6uurfkVbeXG4S8JFT9t19m45ICnif8zWLd5oPSZ50QnwMfK+H3jv408d4jw/7Bttv5axS5IiHoLaVNHeQ=="],
 
     "preact": ["preact@10.29.0", "", {}, "sha512-wSAGyk2bYR1c7t3SZ3jHcM6xy0lcBcDel6lODcs9ME6Th++Dx2KU+6D3HD8wMMKGA8Wpw7OMd3/4RGzYRpzwRg=="],
 
+    "prelude-ls": ["prelude-ls@1.2.1", "", {}, "sha512-vkcDPrRZo1QZLbn5RLGPpg/WmIQ65qoWWhcGKf/b5eplkkarX0m9z8ppCat4mlOqUsWpyNuYgO3VRyrYHSzX5g=="],
+
     "pretty-format": ["pretty-format@27.5.1", "", { "dependencies": { "ansi-regex": "^5.0.1", "ansi-styles": "^5.0.0", "react-is": "^17.0.1" } }, "sha512-Qb1gy5OrP5+zDf2Bvnzdl3jsTf1qXVMazbvCoKhtKqVs4/YK4ozX4gKQJJVyNe+cajNPn0KoC0MC3FUmaHWEmQ=="],
 
     "property-information": ["property-information@7.1.0", "", {}, "sha512-TwEZ+X+yCJmYfL7TPUOcvBZ4QfoT5YenQiJuX//0th53DE6w0xxLEtfK3iyryQFddXuvkIk51EEgrJQ0WJkOmQ=="],
 
+    "punycode": ["punycode@2.3.1", "", {}, "sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg=="],
+
     "quansync": ["quansync@0.2.11", "", {}, "sha512-AifT7QEbW9Nri4tAwR5M/uzpBuqfZf+zwaEM/QkzEjj7NBuFD2rBuy0K3dE+8wltbezDV7JMA0WfnCPYRSYbXA=="],
 
     "react": ["react@19.2.4", "", {}, "sha512-9nfp2hYpCwOjAN+8TZFGhtWEwgvWHXqESH8qT89AT/lWklpLON22Lc8pEtnpsZz7VmawabSU0gCjnj8aC0euHQ=="],
@@ -639,7 +868,7 @@
 
     "rfdc": ["rfdc@1.4.1", "", {}, "sha512-q1b3N5QkRUWUl7iyylaaj3kOpIT0N2i9MqIEQXP73GVsN9cw3fdx8X63cEmWhJGi2PPCF23Ijp7ktmd39rawIA=="],
 
-    "rolldown": ["rolldown@1.0.0-rc.17", "", { "dependencies": { "@oxc-project/types": "=0.127.0", "@rolldown/pluginutils": "1.0.0-rc.17" }, "optionalDependencies": { "@rolldown/binding-android-arm64": "1.0.0-rc.17", "@rolldown/binding-darwin-arm64": "1.0.0-rc.17", "@rolldown/binding-darwin-x64": "1.0.0-rc.17", "@rolldown/binding-freebsd-x64": "1.0.0-rc.17", "@rolldown/binding-linux-arm-gnueabihf": "1.0.0-rc.17", "@rolldown/binding-linux-arm64-gnu": "1.0.0-rc.17", "@rolldown/binding-linux-arm64-musl": "1.0.0-rc.17", "@rolldown/binding-linux-ppc64-gnu": "1.0.0-rc.17", "@rolldown/binding-linux-s390x-gnu": "1.0.0-rc.17", "@rolldown/binding-linux-x64-gnu": "1.0.0-rc.17", "@rolldown/binding-linux-x64-musl": "1.0.0-rc.17", "@rolldown/binding-openharmony-arm64": "1.0.0-rc.17", "@rolldown/binding-wasm32-wasi": "1.0.0-rc.17", "@rolldown/binding-win32-arm64-msvc": "1.0.0-rc.17", "@rolldown/binding-win32-x64-msvc": "1.0.0-rc.17" }, "bin": { "rolldown": "bin/cli.mjs" } }, "sha512-ZrT53oAKrtA4+YtBWPQbtPOxIbVDbxT0orcYERKd63VJTF13zPcgXTvD4843L8pcsI7M6MErt8QtON6lrB9tyA=="],
+    "rolldown": ["rolldown@1.2.1", "", { "dependencies": { "@oxc-project/types": "=0.142.0", "@rolldown/pluginutils": "^1.0.0" }, "optionalDependencies": { "@rolldown/binding-android-arm64": "1.2.1", "@rolldown/binding-darwin-arm64": "1.2.1", "@rolldown/binding-darwin-x64": "1.2.1", "@rolldown/binding-freebsd-x64": "1.2.1", "@rolldown/binding-linux-arm-gnueabihf": "1.2.1", "@rolldown/binding-linux-arm64-gnu": "1.2.1", "@rolldown/binding-linux-arm64-musl": "1.2.1", "@rolldown/binding-linux-ppc64-gnu": "1.2.1", "@rolldown/binding-linux-s390x-gnu": "1.2.1", "@rolldown/binding-linux-x64-gnu": "1.2.1", "@rolldown/binding-linux-x64-musl": "1.2.1", "@rolldown/binding-openharmony-arm64": "1.2.1", "@rolldown/binding-wasm32-wasi": "1.2.1", "@rolldown/binding-win32-arm64-msvc": "1.2.1", "@rolldown/binding-win32-x64-msvc": "1.2.1" }, "bin": { "rolldown": "./bin/cli.mjs" } }, "sha512-4FKJhg8d3OiyQOA6Q1Q0hoFFpW9/OoX+VsHzpECsdsIZoOArrAK90gl59YK/Z+gnDel45bgJZK03ozH/9bCqEw=="],
 
     "rollup": ["rollup@4.59.0", "", { "dependencies": { "@types/estree": "1.0.8" }, "optionalDependencies": { "@rollup/rollup-android-arm-eabi": "4.59.0", "@rollup/rollup-android-arm64": "4.59.0", "@rollup/rollup-darwin-arm64": "4.59.0", "@rollup/rollup-darwin-x64": "4.59.0", "@rollup/rollup-freebsd-arm64": "4.59.0", "@rollup/rollup-freebsd-x64": "4.59.0", "@rollup/rollup-linux-arm-gnueabihf": "4.59.0", "@rollup/rollup-linux-arm-musleabihf": "4.59.0", "@rollup/rollup-linux-arm64-gnu": "4.59.0", "@rollup/rollup-linux-arm64-musl": "4.59.0", "@rollup/rollup-linux-loong64-gnu": "4.59.0", "@rollup/rollup-linux-loong64-musl": "4.59.0", "@rollup/rollup-linux-ppc64-gnu": "4.59.0", "@rollup/rollup-linux-ppc64-musl": "4.59.0", "@rollup/rollup-linux-riscv64-gnu": "4.59.0", "@rollup/rollup-linux-riscv64-musl": "4.59.0", "@rollup/rollup-linux-s390x-gnu": "4.59.0", "@rollup/rollup-linux-x64-gnu": "4.59.0", "@rollup/rollup-linux-x64-musl": "4.59.0", "@rollup/rollup-openbsd-x64": "4.59.0", "@rollup/rollup-openharmony-arm64": "4.59.0", "@rollup/rollup-win32-arm64-msvc": "4.59.0", "@rollup/rollup-win32-ia32-msvc": "4.59.0", "@rollup/rollup-win32-x64-gnu": "4.59.0", "@rollup/rollup-win32-x64-msvc": "4.59.0", "fsevents": "~2.3.2" }, "bin": { "rollup": "dist/bin/rollup" } }, "sha512-2oMpl67a3zCH9H79LeMcbDhXW/UmWG/y2zuqnF2jQq5uq9TbM9TVyXvA4+t+ne2IIkBdrLpAaRQAvo7YI/Yyeg=="],
 
@@ -651,6 +880,10 @@
 
     "semver": ["semver@7.7.4", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-vFKC2IEtQnVhpT78h1Yp8wzwrf8CM+MzKMHGJZfBtzhZNycRFnXsHk6E5TxIkkMsgNS7mdX3AGB7x2QM2di4lA=="],
 
+    "shebang-command": ["shebang-command@2.0.0", "", { "dependencies": { "shebang-regex": "^3.0.0" } }, "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA=="],
+
+    "shebang-regex": ["shebang-regex@3.0.0", "", {}, "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A=="],
+
     "shiki": ["shiki@2.5.0", "", { "dependencies": { "@shikijs/core": "2.5.0", "@shikijs/engine-javascript": "2.5.0", "@shikijs/engine-oniguruma": "2.5.0", "@shikijs/langs": "2.5.0", "@shikijs/themes": "2.5.0", "@shikijs/types": "2.5.0", "@shikijs/vscode-textmate": "^10.0.2", "@types/hast": "^3.0.4" } }, "sha512-mI//trrsaiCIPsja5CNfsyNOqgAZUb6VpJA+340toL42UpzQlXpwRV9nch69X6gaUxrr9kaOOa6e3y3uAkGFxQ=="],
 
     "source-map": ["source-map@0.6.1", "", {}, "sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g=="],
@@ -661,7 +894,7 @@
 
     "speakingurl": ["speakingurl@14.0.1", "", {}, "sha512-1POYv7uv2gXoyGFpBCmpDVSNV74IfsWlDW216UPjbWufNf+bSU6GdbDsxdcxtfwb4xlI3yxzOTKClUosxARYrQ=="],
 
-    "storybook": ["storybook@10.3.6", "", { "dependencies": { "@storybook/global": "^5.0.0", "@storybook/icons": "^2.0.1", "@testing-library/jest-dom": "^6.9.1", "@testing-library/user-event": "^14.6.1", "@vitest/expect": "3.2.4", "@vitest/spy": "3.2.4", "@webcontainer/env": "^1.1.1", "esbuild": "^0.18.0 || ^0.19.0 || ^0.20.0 || ^0.21.0 || ^0.22.0 || ^0.23.0 || ^0.24.0 || ^0.25.0 || ^0.26.0 || ^0.27.0", "open": "^10.2.0", "recast": "^0.23.5", "semver": "^7.7.3", "use-sync-external-store": "^1.5.0", "ws": "^8.18.0" }, "peerDependencies": { "prettier": "^2 || ^3", "vite-plus": "^0.1.15" }, "optionalPeers": ["prettier", "vite-plus"], "bin": "./dist/bin/dispatcher.js" }, "sha512-vbSz7g/1rGMC1uAULqMZjALkIuLu2QABqfhRYhyr/11kzyesi+vAmwyJLukZP1FfecxGOgMwOh6GS0YsGpHAvQ=="],
+    "storybook": ["storybook@10.5.5", "", { "dependencies": { "@storybook/global": "^5.0.0", "@storybook/icons": "^2.0.2", "@testing-library/dom": "^10.4.1", "@testing-library/jest-dom": "^6.9.1", "@testing-library/user-event": "^14.6.1", "@vitest/expect": "3.2.4", "@vitest/spy": "3.2.4", "@webcontainer/env": "^1.1.1", "esbuild": "^0.18.0 || ^0.19.0 || ^0.20.0 || ^0.21.0 || ^0.22.0 || ^0.23.0 || ^0.24.0 || ^0.25.0 || ^0.26.0 || ^0.27.0 || ^0.28.0", "jsonc-parser": "^3.3.1", "open": "^10.2.0", "oxc-parser": "^0.127.0", "oxc-resolver": "^11.19.1", "recast": "^0.23.5", "semver": "^7.7.3", "use-sync-external-store": "^1.5.0", "ws": "^8.21.1" }, "peerDependencies": { "@types/react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0", "prettier": "^2 || ^3", "vite-plus": "^0.1.15 || ^0.2.0" }, "optionalPeers": ["@types/react", "prettier", "vite-plus"], "bin": "./dist/bin/dispatcher.js" }, "sha512-UscBIBJDloUeqntukHOhP1a5W/vouePDJbzPSxj466WK801FZtzQiMffMtkjzJiWSuj20wfaYlB2QQKh9aOYAg=="],
 
     "stringify-entities": ["stringify-entities@4.0.4", "", { "dependencies": { "character-entities-html4": "^2.0.0", "character-entities-legacy": "^3.0.0" } }, "sha512-IwfBptatlO+QCJUo19AqvrPNqlVMpW9YEL2LIVY+Rpv2qsjCGxaDLNRgeGsQWJhfItebuJhsGSLjaBbNSQ+ieg=="],
 
@@ -671,13 +904,13 @@
 
     "tabbable": ["tabbable@6.4.0", "", {}, "sha512-05PUHKSNE8ou2dwIxTngl4EzcnsCDZGJ/iCLtDflR/SHB/ny14rXc+qU5P4mG9JkusiV7EivzY9Mhm55AzAvCg=="],
 
-    "tailwindcss": ["tailwindcss@4.2.4", "", {}, "sha512-HhKppgO81FQof5m6TEnuBWCZGgfRAWbaeOaGT00KOy/Pf/j6oUihdvBpA7ltCeAvZpFhW3j0PTclkxsd4IXYDA=="],
+    "tailwindcss": ["tailwindcss@4.3.3", "", {}, "sha512-gOhV3P7ufE62QDGg1zVaTgCR+EtPv92k2nIhVcVKcLmxT1sUBsQGhnZj175j+MqRt4zLF7ic+sCYjfhxMxj7YQ=="],
 
-    "tapable": ["tapable@2.3.0", "", {}, "sha512-g9ljZiwki/LfxmQADO3dEY1CbpmXT5Hm2fJ+QaGKwSXUylMybePR7/67YW7jOrrvjEgL1Fmz5kzyAjWVWLlucg=="],
+    "tapable": ["tapable@2.3.3", "", {}, "sha512-uxc/zpqFg6x7C8vOE7lh6Lbda8eEL9zmVm/PLeTPBRhh1xCgdWaQ+J1CUieGpIfm2HdtsUpRv+HshiasBMcc6A=="],
 
     "tiny-invariant": ["tiny-invariant@1.3.3", "", {}, "sha512-+FbBPE1o9QAYvviau/qC5SE3caw21q3xkvWKBtja5vgqOWIHHJ3ioaq1VPfn/Szqctz2bU/oYeKd9/z5BL+PVg=="],
 
-    "tinyglobby": ["tinyglobby@0.2.16", "", { "dependencies": { "fdir": "^6.5.0", "picomatch": "^4.0.4" } }, "sha512-pn99VhoACYR8nFHhxqix+uvsbXineAasWm5ojXoN8xEwK5Kd3/TrhNn1wByuD52UxWRLy8pu+kRMniEi6Eq9Zg=="],
+    "tinyglobby": ["tinyglobby@0.2.17", "", { "dependencies": { "fdir": "^6.5.0", "picomatch": "^4.0.4" } }, "sha512-wXR/dYpcqKmfWpEdZjiKJOwCNFndD0DMnrW/cYjVGttEkBfVgcLFHoNrlj47mjOVic9yyNu65alsgF4NQyTa2g=="],
 
     "tinyrainbow": ["tinyrainbow@2.0.0", "", {}, "sha512-op4nsTR47R6p0vMUUoYl/a+ljLFVtlfaXkLQmqfLR1qHma1h/ysYk4hEXZ880bf2CYgTskvTa/e196Vd5dDQXw=="],
 
@@ -685,15 +918,19 @@
 
     "trim-lines": ["trim-lines@3.0.1", "", {}, "sha512-kRj8B+YHZCc9kQYdWfJB2/oUl9rA99qbowYYBtr4ui4mZyAQ2JpvVBd/6U2YloATfqBhBTSMhTpgBHtU0Mf3Rg=="],
 
+    "ts-api-utils": ["ts-api-utils@2.5.0", "", { "peerDependencies": { "typescript": ">=4.8.4" } }, "sha512-OJ/ibxhPlqrMM0UiNHJ/0CKQkoKF243/AEmplt3qpRgkW8VG7IfOS41h7V8TjITqdByHzrjcS/2si+y4lIh8NA=="],
+
     "ts-dedent": ["ts-dedent@2.2.0", "", {}, "sha512-q5W7tVM71e2xjHZTlgfTDoPF/SmqKG5hddq9SzR49CH2hayqRKJtQ4mtRlSxKaJlR/+9rEM+mnBHf7I2/BQcpQ=="],
 
     "tslib": ["tslib@2.8.1", "", {}, "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w=="],
 
+    "type-check": ["type-check@0.4.0", "", { "dependencies": { "prelude-ls": "^1.2.1" } }, "sha512-XleUoc9uwGXqjWwXaUTZAmzMcFZ5858QA2vvx1Ur5xIcixXIP+8LnFDgRplU30us6teqdlskFfu+ae4K79Ooew=="],
+
     "typescript": ["typescript@6.0.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-y2TvuxSZPDyQakkFRPZHKFm+KKVqIisdg9/CZwm9ftvKXLP8NRWj38/ODjNbr43SsoXqNuAisEf1GdCxqWcdBw=="],
 
     "ufo": ["ufo@1.6.3", "", {}, "sha512-yDJTmhydvl5lJzBmy/hyOAA0d+aqCBuwl818haVdYCRrWV84o7YyeVm4QlVHStqNrrJSTb6jKuFAVqAFsr+K3Q=="],
 
-    "undici-types": ["undici-types@7.19.2", "", {}, "sha512-qYVnV5OEm2AW8cJMCpdV20CDyaN3g0AjDlOGf1OW4iaDEx8MwdtChUp4zu4H0VP3nDRF/8RKWH+IPp9uW0YGZg=="],
+    "undici-types": ["undici-types@8.3.0", "", {}, "sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ=="],
 
     "unist-util-is": ["unist-util-is@6.0.1", "", { "dependencies": { "@types/unist": "^3.0.0" } }, "sha512-LsiILbtBETkDz8I9p1dQ0uyRUWuaQzd/cuEeS1hoRSyW5E5XGmTzlwY1OrNzzakGowI9Dr/I8HVaw4hTtnxy8g=="],
 
@@ -707,19 +944,21 @@
 
     "unplugin": ["unplugin@2.3.11", "", { "dependencies": { "@jridgewell/remapping": "^2.3.5", "acorn": "^8.15.0", "picomatch": "^4.0.3", "webpack-virtual-modules": "^0.6.2" } }, "sha512-5uKD0nqiYVzlmCRs01Fhs2BdkEgBS3SAVP6ndrBsuK42iC2+JHyxM05Rm9G8+5mkmRtzMZGY8Ct5+mliZxU/Ww=="],
 
-    "unplugin-dts": ["unplugin-dts@1.0.0", "", { "dependencies": { "@rollup/pluginutils": "^5.1.4", "@volar/typescript": "^2.4.26", "compare-versions": "^6.1.1", "debug": "^4.4.0", "kolorist": "^1.8.0", "local-pkg": "^1.1.1", "magic-string": "^0.30.17", "unplugin": "^2.3.2" }, "peerDependencies": { "@microsoft/api-extractor": ">=7", "@rspack/core": "^1", "@vue/language-core": "~3.1.5", "esbuild": "*", "rolldown": "*", "rollup": ">=3", "typescript": ">=4", "vite": ">=3", "webpack": "^4 || ^5" }, "optionalPeers": ["@microsoft/api-extractor", "@rspack/core", "@vue/language-core", "esbuild", "rolldown", "rollup", "vite", "webpack"] }, "sha512-qz+U1lCscwq+t8Mkaxy5Esa7IQ5wWV18b4mnioOXSdnPaNiJ0+qgE3I+KL6UkXYZWxxGo2qdGone8LEQ52Sfkw=="],
+    "unplugin-dts": ["unplugin-dts@1.0.3", "", { "dependencies": { "@rollup/pluginutils": "^5.1.4", "@volar/typescript": "^2.4.26", "compare-versions": "^6.1.1", "debug": "^4.4.0", "kolorist": "^1.8.0", "local-pkg": "^1.1.1", "magic-string": "^0.30.17", "unplugin": "^2.3.2" }, "peerDependencies": { "@microsoft/api-extractor": ">=7", "@rspack/core": "^1", "@vue/language-core": "^3.1.5", "esbuild": "*", "rolldown": "*", "rollup": ">=3", "typescript": ">=4", "vite": ">=3", "webpack": "^4 || ^5" }, "optionalPeers": ["@microsoft/api-extractor", "@rspack/core", "@vue/language-core", "esbuild", "rolldown", "rollup", "vite", "webpack"] }, "sha512-/GR887wfG4r1cWyt1UZsLRuMIjsmEbGkS9yJrz+0dsToHAYUD5CTyP3JMGVLv25j9K0mJcwAVvZno/aTuSUvNg=="],
 
     "update-browserslist-db": ["update-browserslist-db@1.2.3", "", { "dependencies": { "escalade": "^3.2.0", "picocolors": "^1.1.1" }, "peerDependencies": { "browserslist": ">= 4.21.0" }, "bin": { "update-browserslist-db": "cli.js" } }, "sha512-Js0m9cx+qOgDxo0eMiFGEueWztz+d4+M3rGlmKPT+T4IS/jP4ylw3Nwpu6cpTTP8R1MAC1kF4VbdLt3ARf209w=="],
 
+    "uri-js": ["uri-js@4.4.1", "", { "dependencies": { "punycode": "^2.1.0" } }, "sha512-7rKUyy33Q1yc98pQ1DAmLtwX109F7TIfWlW1Ydo8Wl1ii1SeHieeh0HHfPeL2fMXK6z0s8ecKs9frCuLJvndBg=="],
+
     "use-sync-external-store": ["use-sync-external-store@1.6.0", "", { "peerDependencies": { "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0" } }, "sha512-Pp6GSwGP/NrPIrxVFAIkOQeyw8lFenOHijQWkUTrDvrF4ALqylP2C/KCkeS9dpUM3KvYRQhna5vt7IL95+ZQ9w=="],
 
     "vfile": ["vfile@6.0.3", "", { "dependencies": { "@types/unist": "^3.0.0", "vfile-message": "^4.0.0" } }, "sha512-KzIbH/9tXat2u30jf+smMwFCsno4wHVdNmzFyL+T/L3UGqqk6JKfVqOFOZEpZSHADH1k40ab6NUIXZq422ov3Q=="],
 
     "vfile-message": ["vfile-message@4.0.3", "", { "dependencies": { "@types/unist": "^3.0.0", "unist-util-stringify-position": "^4.0.0" } }, "sha512-QTHzsGd1EhbZs4AsQ20JX1rC3cOlt/IWJruk893DfLRr57lcnOeMaWG4K0JrRta4mIJZKth2Au3mM3u03/JWKw=="],
 
-    "vite": ["vite@8.0.10", "", { "dependencies": { "lightningcss": "^1.32.0", "picomatch": "^4.0.4", "postcss": "^8.5.10", "rolldown": "1.0.0-rc.17", "tinyglobby": "^0.2.16" }, "optionalDependencies": { "fsevents": "~2.3.3" }, "peerDependencies": { "@types/node": "^20.19.0 || >=22.12.0", "@vitejs/devtools": "^0.1.0", "esbuild": "^0.27.0 || ^0.28.0", "jiti": ">=1.21.0", "less": "^4.0.0", "sass": "^1.70.0", "sass-embedded": "^1.70.0", "stylus": ">=0.54.8", "sugarss": "^5.0.0", "terser": "^5.16.0", "tsx": "^4.8.1", "yaml": "^2.4.2" }, "optionalPeers": ["@types/node", "@vitejs/devtools", "esbuild", "jiti", "less", "sass", "sass-embedded", "stylus", "sugarss", "terser", "tsx", "yaml"], "bin": { "vite": "bin/vite.js" } }, "sha512-rZuUu9j6J5uotLDs+cAA4O5H4K1SfPliUlQwqa6YEwSrWDZzP4rhm00oJR5snMewjxF5V/K3D4kctsUTsIU9Mw=="],
+    "vite": ["vite@8.2.0", "", { "dependencies": { "lightningcss": "^1.33.0", "picomatch": "^4.0.5", "postcss": "^8.5.23", "rolldown": "~1.2.0", "tinyglobby": "^0.2.17" }, "optionalDependencies": { "fsevents": "~2.3.3" }, "peerDependencies": { "@types/node": "^20.19.0 || >=22.12.0", "@vitejs/devtools": "^0.4.0", "esbuild": "^0.27.0 || ^0.28.0", "jiti": ">=1.21.0", "less": "^4.0.0", "sass": "^1.70.0", "sass-embedded": "^1.70.0", "stylus": ">=0.54.8", "sugarss": "^5.0.0", "terser": "^5.16.0", "tsx": "^4.8.1", "yaml": "^2.4.2" }, "optionalPeers": ["@types/node", "@vitejs/devtools", "esbuild", "jiti", "less", "sass", "sass-embedded", "stylus", "sugarss", "terser", "tsx", "yaml"], "bin": { "vite": "bin/vite.js" } }, "sha512-pn+CFpM0lwDeKwmOq1ZaBK/9sjorZcgqxki6MbY/jPEVd9vichIlmlD4HmQ5wdP5EgqQCFRaACBxMC7uEGc6lQ=="],
 
-    "vite-plugin-dts": ["vite-plugin-dts@5.0.0", "", { "dependencies": { "unplugin-dts": "1.0.0" }, "peerDependencies": { "@microsoft/api-extractor": ">=7", "rollup": ">=3", "vite": ">=3" }, "optionalPeers": ["@microsoft/api-extractor", "rollup", "vite"] }, "sha512-VLNAUttBq7pLxxL/m/ztjd5zj5yiviiC7ijfPFVLK5c45FLcibvieBsdjSka3a4ag1qdrAF9K3OysH4/lW+rPQ=="],
+    "vite-plugin-dts": ["vite-plugin-dts@5.0.3", "", { "dependencies": { "unplugin-dts": "1.0.3" }, "peerDependencies": { "@microsoft/api-extractor": ">=7", "rollup": ">=3", "vite": ">=3" }, "optionalPeers": ["@microsoft/api-extractor", "rollup", "vite"] }, "sha512-gIth6NdCEHWPiiRMCK3N6C8WjvdsrtEQrmsiG8h6Ov+lFP+b07Y+wcs9H0H7n146l0PDTYK4cQN1vgeG1pMdRQ=="],
 
     "vitepress": ["vitepress@1.6.4", "", { "dependencies": { "@docsearch/css": "3.8.2", "@docsearch/js": "3.8.2", "@iconify-json/simple-icons": "^1.2.21", "@shikijs/core": "^2.1.0", "@shikijs/transformers": "^2.1.0", "@shikijs/types": "^2.1.0", "@types/markdown-it": "^14.1.2", "@vitejs/plugin-vue": "^5.2.1", "@vue/devtools-api": "^7.7.0", "@vue/shared": "^3.5.13", "@vueuse/core": "^12.4.0", "@vueuse/integrations": "^12.4.0", "focus-trap": "^7.6.4", "mark.js": "8.11.1", "minisearch": "^7.1.1", "shiki": "^2.1.0", "vite": "^5.4.14", "vue": "^3.5.13" }, "peerDependencies": { "markdown-it-mathjax3": "^4", "postcss": "^8" }, "optionalPeers": ["markdown-it-mathjax3", "postcss"], "bin": { "vitepress": "bin/vitepress.js" } }, "sha512-+2ym1/+0VVrbhNyRoFFesVvBvHAVMZMK0rw60E3X/5349M1GuVdKeazuksqopEdvkKwKGs21Q729jX81/bkBJg=="],
 
@@ -731,44 +970,114 @@
 
     "whatwg-mimetype": ["whatwg-mimetype@3.0.0", "", {}, "sha512-nt+N2dzIutVRxARx1nghPKGv1xHikU7HKdfafKkLNLindmPU/ch3U31NOCGGA/dmPcmb1VlofO0vnKAcsm0o/Q=="],
 
-    "ws": ["ws@8.19.0", "", { "peerDependencies": { "bufferutil": "^4.0.1", "utf-8-validate": ">=5.0.2" }, "optionalPeers": ["bufferutil", "utf-8-validate"] }, "sha512-blAT2mjOEIi0ZzruJfIhb3nps74PRWTCz1IjglWEEpQl5XS/UNama6u2/rjFkDDouqr4L67ry+1aGIALViWjDg=="],
+    "which": ["which@2.0.2", "", { "dependencies": { "isexe": "^2.0.0" }, "bin": { "node-which": "./bin/node-which" } }, "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA=="],
+
+    "word-wrap": ["word-wrap@1.2.5", "", {}, "sha512-BN22B5eaMMI9UMtjrGd5g5eCYPpCPDUy0FJXbYsaT5zYxjFOckS53SQDE3pWkVoWpHXVb3BrYcEN4Twa55B5cA=="],
+
+    "ws": ["ws@8.21.1", "", { "peerDependencies": { "bufferutil": "^4.0.1", "utf-8-validate": ">=5.0.2" }, "optionalPeers": ["bufferutil", "utf-8-validate"] }, "sha512-+0NTnW77fFN/DjQi6k/Sq/Yvk4Sgajw7urW8V+asjXnRgDs9gyGkdb7EzgfhA4goXsRIZKE28fzIXBHEzhuiWw=="],
 
     "wsl-utils": ["wsl-utils@0.1.0", "", { "dependencies": { "is-wsl": "^3.1.0" } }, "sha512-h3Fbisa2nKGPxCpm89Hk33lBLsnaGBvctQopaBSOW/uIs6FTe1ATyAnKFJrzVs9vpGdsTe73WF3V4lIsk4Gacw=="],
 
+    "yocto-queue": ["yocto-queue@0.1.0", "", {}, "sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q=="],
+
     "zwitch": ["zwitch@2.0.4", "", {}, "sha512-bXE4cR/kVZhKZX/RjPEflHaKVhUVl85noU3v6b8apfQEc1x4A+zBxjZ4lN8LqGd6WZ3dl98pY4o717VFmoPp+A=="],
 
+    "@eslint-community/eslint-utils/eslint-visitor-keys": ["eslint-visitor-keys@3.4.3", "", {}, "sha512-wpc+LXeiyiisxPlEkUzU6svyS1frIO3Mgxj1fdy7Pm8Ygzguax2N3Fa/D/ag1WqbOprdI+uY6wMUl8/a2G+iag=="],
+
+    "@oxc-resolver/binding-wasm32-wasi/@emnapi/core": ["@emnapi/core@1.11.2", "", { "dependencies": { "@emnapi/wasi-threads": "1.2.2", "tslib": "^2.4.0" } }, "sha512-TC8MkTuZUtcTSiFeuC0ksCh9QIJ5+F21MvZ4Wn4ORfYaFJ/0dsiudv5tVkejgwZlwQ39jL9WWDe2lz8x0WglOA=="],
+
+    "@oxc-resolver/binding-wasm32-wasi/@emnapi/runtime": ["@emnapi/runtime@1.11.2", "", { "dependencies": { "tslib": "^2.4.0" } }, "sha512-kyOl3X0DuTiT1h2ft8r2fYO8JYtU9a9Xis/zBSiGArNaagCOWx90N1k2wxp18czFDH+OgcWGb5ZP/XMt3dcyPA=="],
+
+    "@rolldown/binding-wasm32-wasi/@emnapi/core": ["@emnapi/core@2.0.0-alpha.3", "", { "dependencies": { "@emnapi/wasi-threads": "2.0.1", "tslib": "^2.4.0" } }, "sha512-AZypUeJ/yByuxyS7BlSNRDOMLMlROYtjYdIAuBmJssVz1UJDSeYxLrdizhXCFYhedC5bqd/ASy8EuNXbVVXp9g=="],
+
+    "@rolldown/binding-wasm32-wasi/@emnapi/runtime": ["@emnapi/runtime@2.0.0-alpha.3", "", { "dependencies": { "tslib": "^2.4.0" } }, "sha512-hFPAhMUjJD9BSyCANEISPOogeXC9Zo9ZQl7L6vKnaVsMkCtzznaW/naYypeyl0Gv5rYfWYsZbpixTMpjDJzQeA=="],
+
     "@rollup/pluginutils/picomatch": ["picomatch@4.0.3", "", {}, "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q=="],
 
-    "@tailwindcss/oxide-wasm32-wasi/@emnapi/core": ["@emnapi/core@1.9.0", "", { "dependencies": { "@emnapi/wasi-threads": "1.2.0", "tslib": "^2.4.0" }, "bundled": true }, "sha512-0DQ98G9ZQZOxfUcQn1waV2yS8aWdZ6kJMbYCJB3oUBecjWYO1fqJ+a1DRfPF3O5JEkwqwP1A9QEN/9mYm2Yd0w=="],
+    "@tailwindcss/node/jiti": ["jiti@2.7.0", "", { "bin": { "jiti": "lib/jiti-cli.mjs" } }, "sha512-AC/7JofJvZGrrneWNaEnJeOLUx+JlGt7tNa0wZiRPT4MY1wmfKjt2+6O2p2uz2+skll8OZZmJMNqeke7kKbNgQ=="],
+
+    "@tailwindcss/node/lightningcss": ["lightningcss@1.32.0", "", { "dependencies": { "detect-libc": "^2.0.3" }, "optionalDependencies": { "lightningcss-android-arm64": "1.32.0", "lightningcss-darwin-arm64": "1.32.0", "lightningcss-darwin-x64": "1.32.0", "lightningcss-freebsd-x64": "1.32.0", "lightningcss-linux-arm-gnueabihf": "1.32.0", "lightningcss-linux-arm64-gnu": "1.32.0", "lightningcss-linux-arm64-musl": "1.32.0", "lightningcss-linux-x64-gnu": "1.32.0", "lightningcss-linux-x64-musl": "1.32.0", "lightningcss-win32-arm64-msvc": "1.32.0", "lightningcss-win32-x64-msvc": "1.32.0" } }, "sha512-NXYBzinNrblfraPGyrbPoD19C1h9lfI/1mzgWYvXUTe414Gz/X1FD2XBZSZM7rRTrMA8JL3OtAaGifrIKhQ5yQ=="],
+
+    "@tailwindcss/oxide-wasm32-wasi/@emnapi/core": ["@emnapi/core@1.11.2", "", { "dependencies": { "@emnapi/wasi-threads": "1.2.2", "tslib": "^2.4.0" }, "bundled": true }, "sha512-TC8MkTuZUtcTSiFeuC0ksCh9QIJ5+F21MvZ4Wn4ORfYaFJ/0dsiudv5tVkejgwZlwQ39jL9WWDe2lz8x0WglOA=="],
 
-    "@tailwindcss/oxide-wasm32-wasi/@emnapi/runtime": ["@emnapi/runtime@1.9.0", "", { "dependencies": { "tslib": "^2.4.0" }, "bundled": true }, "sha512-QN75eB0IH2ywSpRpNddCRfQIhmJYBCJ1x5Lb3IscKAL8bMnVAKnRg8dCoXbHzVLLH7P38N2Z3mtulB7W0J0FKw=="],
+    "@tailwindcss/oxide-wasm32-wasi/@emnapi/runtime": ["@emnapi/runtime@1.11.2", "", { "dependencies": { "tslib": "^2.4.0" }, "bundled": true }, "sha512-kyOl3X0DuTiT1h2ft8r2fYO8JYtU9a9Xis/zBSiGArNaagCOWx90N1k2wxp18czFDH+OgcWGb5ZP/XMt3dcyPA=="],
 
-    "@tailwindcss/oxide-wasm32-wasi/@emnapi/wasi-threads": ["@emnapi/wasi-threads@1.2.0", "", { "dependencies": { "tslib": "^2.4.0" }, "bundled": true }, "sha512-N10dEJNSsUx41Z6pZsXU8FjPjpBEplgH24sfkmITrBED1/U2Esum9F3lfLrMjKHHjmi557zQn7kR9R+XWXu5Rg=="],
+    "@tailwindcss/oxide-wasm32-wasi/@emnapi/wasi-threads": ["@emnapi/wasi-threads@1.2.2", "", { "dependencies": { "tslib": "^2.4.0" }, "bundled": true }, "sha512-c95qOXkHdydNKhscBTebqEC1CVAZpyqOfVfBzQ1qgzyl3gfeldUjIggDbIZgDKsHLgnsM+igH7TJ/eAasaVuMA=="],
 
-    "@tailwindcss/oxide-wasm32-wasi/@napi-rs/wasm-runtime": ["@napi-rs/wasm-runtime@1.1.1", "", { "dependencies": { "@emnapi/core": "^1.7.1", "@emnapi/runtime": "^1.7.1", "@tybys/wasm-util": "^0.10.1" }, "bundled": true }, "sha512-p64ah1M1ld8xjWv3qbvFwHiFVWrq1yFvV4f7w+mzaqiR4IlSgkqhcRdHwsGgomwzBH51sRY4NEowLxnaBjcW/A=="],
+    "@tailwindcss/oxide-wasm32-wasi/@napi-rs/wasm-runtime": ["@napi-rs/wasm-runtime@1.2.2", "", { "dependencies": { "@tybys/wasm-util": "^0.10.3" }, "peerDependencies": { "@emnapi/core": "^1.7.1 || ^2.0.0-alpha.3", "@emnapi/runtime": "^1.7.1 || ^2.0.0-alpha.3" }, "bundled": true }, "sha512-JfB4kuJQjaoHuCTseIINHtHWeJnvgEcxjwA5t/Y00ZgaOO1Crz3fjT/p8kT28zA/Caz7oiUMn3d6H2yOVCVwuw=="],
 
-    "@tailwindcss/oxide-wasm32-wasi/@tybys/wasm-util": ["@tybys/wasm-util@0.10.1", "", { "dependencies": { "tslib": "^2.4.0" }, "bundled": true }, "sha512-9tTaPJLSiejZKx+Bmog4uSubteqTvFrVrURwkmHixBo0G4seD0zUxp98E1DzUBJxLQ3NPwXrGKDiVjwx/DpPsg=="],
+    "@tailwindcss/oxide-wasm32-wasi/@tybys/wasm-util": ["@tybys/wasm-util@0.10.3", "", { "dependencies": { "tslib": "^2.4.0" }, "bundled": true }, "sha512-F3fo1MYrRJYL3zER0OUOmkutjr1Vp23m7OsSgp7nq4SP6OqX6C/56XFIPAl5bt3zaBRjmW7SGz3u/6LwFpYcOg=="],
 
     "@tailwindcss/oxide-wasm32-wasi/tslib": ["tslib@2.8.1", "", { "bundled": true }, "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w=="],
 
-    "@testing-library/dom/aria-query": ["aria-query@5.3.0", "", { "dependencies": { "dequal": "^2.0.3" } }, "sha512-b0P0sZPKtyu8HkeRAfCq0IfURZK+SuwMjY1UXGBU27wpAiTwQAIlq56IbIO+ytk/JjS1fMR14ee5WBBfKi5J6A=="],
+    "@testing-library/jest-dom/aria-query": ["aria-query@5.3.2", "", {}, "sha512-COROpnaoap1E2F000S62r6A60uHZnmlvomhfyT2DlTcrY1OrBKn2UhH7qn5wTC9zMvD0AY7csdPSNwKP+7WiQw=="],
 
-    "@testing-library/dom/dom-accessibility-api": ["dom-accessibility-api@0.5.16", "", {}, "sha512-X7BJ2yElsnOJ30pZF4uIIDfBEVgF4XEBxL9Bxhy6dnrm5hkzqmsWHGTiHqRiITNhMyFLyAiWndIJP7Z1NTteDg=="],
+    "@testing-library/jest-dom/dom-accessibility-api": ["dom-accessibility-api@0.6.3", "", {}, "sha512-7ZgogeTnjuHbo+ct10G9Ffp0mif17idi0IyWNVA/wcwcm7NPOD/WEHVP3n7n3MhXqxoIYm8d6MuZohYWIZ4T3w=="],
 
     "@types/ws/@types/node": ["@types/node@20.19.37", "", { "dependencies": { "undici-types": "~6.21.0" } }, "sha512-8kzdPJ3FsNsVIurqBs7oodNnCEVbni9yUEkaHbgptDACOPW04jimGagZ51E6+lXUwJjgnBw+hyko/lkFWCldqw=="],
 
+    "@typescript-eslint/typescript-estree/tinyglobby": ["tinyglobby@0.2.16", "", { "dependencies": { "fdir": "^6.5.0", "picomatch": "^4.0.4" } }, "sha512-pn99VhoACYR8nFHhxqix+uvsbXineAasWm5ojXoN8xEwK5Kd3/TrhNn1wByuD52UxWRLy8pu+kRMniEi6Eq9Zg=="],
+
     "@vue/compiler-sfc/postcss": ["postcss@8.5.8", "", { "dependencies": { "nanoid": "^3.3.11", "picocolors": "^1.1.1", "source-map-js": "^1.2.1" } }, "sha512-OW/rX8O/jXnm82Ey1k44pObPtdblfiuWnrd8X7GJ7emImCOstunGbXUpp7HdBrFQX6rJzn3sPT397Wp5aCwCHg=="],
 
+    "buffer-image-size/@types/node": ["@types/node@25.9.5", "", { "dependencies": { "undici-types": ">=7.24.0 <7.24.7" } }, "sha512-OScDchr2fwuUmWdf4kZ9h7PcJiYDVInhJizG/biAq3cAvqwYktuy/TYGGdZNMtNTFUP7rnb0NU4TUdm82kt4Rg=="],
+
+    "bun-types/@types/node": ["@types/node@25.9.5", "", { "dependencies": { "undici-types": ">=7.24.0 <7.24.7" } }, "sha512-OScDchr2fwuUmWdf4kZ9h7PcJiYDVInhJizG/biAq3cAvqwYktuy/TYGGdZNMtNTFUP7rnb0NU4TUdm82kt4Rg=="],
+
+    "eslint/ignore": ["ignore@5.3.2", "", {}, "sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g=="],
+
+    "happy-dom/@types/node": ["@types/node@25.9.5", "", { "dependencies": { "undici-types": ">=7.24.0 <7.24.7" } }, "sha512-OScDchr2fwuUmWdf4kZ9h7PcJiYDVInhJizG/biAq3cAvqwYktuy/TYGGdZNMtNTFUP7rnb0NU4TUdm82kt4Rg=="],
+
     "mlly/pkg-types": ["pkg-types@1.3.1", "", { "dependencies": { "confbox": "^0.1.8", "mlly": "^1.7.4", "pathe": "^2.0.1" } }, "sha512-/Jm5M4RvtBFVkKWRu2BLUTNP8/M2a+UwuAX+ae4770q1qVGtfjG+WTCupoZixokjmHiry8uI+dlY8KXYV5HVVQ=="],
 
+    "rolldown/@oxc-project/types": ["@oxc-project/types@0.142.0", "", {}, "sha512-7W+2q5AKQVU36fkaryontrHn3YDt1RyUYXatw9i5H8ocYe2sPKSFB6eS8WNPeRKiN1qAWWZUPm7gwFzJGrccqQ=="],
+
     "unplugin/picomatch": ["picomatch@4.0.3", "", {}, "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q=="],
 
     "vitepress/vite": ["vite@5.4.21", "", { "dependencies": { "esbuild": "^0.21.3", "postcss": "^8.4.43", "rollup": "^4.20.0" }, "optionalDependencies": { "fsevents": "~2.3.3" }, "peerDependencies": { "@types/node": "^18.0.0 || >=20.0.0", "less": "*", "lightningcss": "^1.21.0", "sass": "*", "sass-embedded": "*", "stylus": "*", "sugarss": "*", "terser": "^5.4.0" }, "optionalPeers": ["@types/node", "less", "lightningcss", "sass", "sass-embedded", "stylus", "sugarss", "terser"], "bin": { "vite": "bin/vite.js" } }, "sha512-o5a9xKjbtuhY6Bi5S3+HvbRERmouabWbyUcpXXUA1u+GNUKoROi9byOJ8M0nHbHYHkYICiMlqxkg1KkYmm25Sw=="],
 
+    "@oxc-resolver/binding-wasm32-wasi/@emnapi/core/@emnapi/wasi-threads": ["@emnapi/wasi-threads@1.2.2", "", { "dependencies": { "tslib": "^2.4.0" } }, "sha512-c95qOXkHdydNKhscBTebqEC1CVAZpyqOfVfBzQ1qgzyl3gfeldUjIggDbIZgDKsHLgnsM+igH7TJ/eAasaVuMA=="],
+
+    "@rolldown/binding-wasm32-wasi/@emnapi/core/@emnapi/wasi-threads": ["@emnapi/wasi-threads@2.0.1", "", { "dependencies": { "tslib": "^2.4.0" } }, "sha512-9DsSk+o5NBX0CCJT8s0EROGSGxjR/tKu6aBTaVyq+SjAEQH4XcdcRxPBRzsBLizTTJ49MJjF+jgu3qnO9GLQcQ=="],
+
+    "@tailwindcss/node/lightningcss/lightningcss-android-arm64": ["lightningcss-android-arm64@1.32.0", "", { "os": "android", "cpu": "arm64" }, "sha512-YK7/ClTt4kAK0vo6w3X+Pnm0D2cf2vPHbhOXdoNti1Ga0al1P4TBZhwjATvjNwLEBCnKvjJc2jQgHXH0NEwlAg=="],
+
+    "@tailwindcss/node/lightningcss/lightningcss-darwin-arm64": ["lightningcss-darwin-arm64@1.32.0", "", { "os": "darwin", "cpu": "arm64" }, "sha512-RzeG9Ju5bag2Bv1/lwlVJvBE3q6TtXskdZLLCyfg5pt+HLz9BqlICO7LZM7VHNTTn/5PRhHFBSjk5lc4cmscPQ=="],
+
+    "@tailwindcss/node/lightningcss/lightningcss-darwin-x64": ["lightningcss-darwin-x64@1.32.0", "", { "os": "darwin", "cpu": "x64" }, "sha512-U+QsBp2m/s2wqpUYT/6wnlagdZbtZdndSmut/NJqlCcMLTWp5muCrID+K5UJ6jqD2BFshejCYXniPDbNh73V8w=="],
+
+    "@tailwindcss/node/lightningcss/lightningcss-freebsd-x64": ["lightningcss-freebsd-x64@1.32.0", "", { "os": "freebsd", "cpu": "x64" }, "sha512-JCTigedEksZk3tHTTthnMdVfGf61Fky8Ji2E4YjUTEQX14xiy/lTzXnu1vwiZe3bYe0q+SpsSH/CTeDXK6WHig=="],
+
+    "@tailwindcss/node/lightningcss/lightningcss-linux-arm-gnueabihf": ["lightningcss-linux-arm-gnueabihf@1.32.0", "", { "os": "linux", "cpu": "arm" }, "sha512-x6rnnpRa2GL0zQOkt6rts3YDPzduLpWvwAF6EMhXFVZXD4tPrBkEFqzGowzCsIWsPjqSK+tyNEODUBXeeVHSkw=="],
+
+    "@tailwindcss/node/lightningcss/lightningcss-linux-arm64-gnu": ["lightningcss-linux-arm64-gnu@1.32.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-0nnMyoyOLRJXfbMOilaSRcLH3Jw5z9HDNGfT/gwCPgaDjnx0i8w7vBzFLFR1f6CMLKF8gVbebmkUN3fa/kQJpQ=="],
+
+    "@tailwindcss/node/lightningcss/lightningcss-linux-arm64-musl": ["lightningcss-linux-arm64-musl@1.32.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-UpQkoenr4UJEzgVIYpI80lDFvRmPVg6oqboNHfoH4CQIfNA+HOrZ7Mo7KZP02dC6LjghPQJeBsvXhJod/wnIBg=="],
+
+    "@tailwindcss/node/lightningcss/lightningcss-linux-x64-gnu": ["lightningcss-linux-x64-gnu@1.32.0", "", { "os": "linux", "cpu": "x64" }, "sha512-V7Qr52IhZmdKPVr+Vtw8o+WLsQJYCTd8loIfpDaMRWGUZfBOYEJeyJIkqGIDMZPwPx24pUMfwSxxI8phr/MbOA=="],
+
+    "@tailwindcss/node/lightningcss/lightningcss-linux-x64-musl": ["lightningcss-linux-x64-musl@1.32.0", "", { "os": "linux", "cpu": "x64" }, "sha512-bYcLp+Vb0awsiXg/80uCRezCYHNg1/l3mt0gzHnWV9XP1W5sKa5/TCdGWaR/zBM2PeF/HbsQv/j2URNOiVuxWg=="],
+
+    "@tailwindcss/node/lightningcss/lightningcss-win32-arm64-msvc": ["lightningcss-win32-arm64-msvc@1.32.0", "", { "os": "win32", "cpu": "arm64" }, "sha512-8SbC8BR40pS6baCM8sbtYDSwEVQd4JlFTOlaD3gWGHfThTcABnNDBda6eTZeqbofalIJhFx0qKzgHJmcPTnGdw=="],
+
+    "@tailwindcss/node/lightningcss/lightningcss-win32-x64-msvc": ["lightningcss-win32-x64-msvc@1.32.0", "", { "os": "win32", "cpu": "x64" }, "sha512-Amq9B/SoZYdDi1kFrojnoqPLxYhQ4Wo5XiL8EVJrVsB8ARoC1PWW6VGtT0WKCemjy8aC+louJnjS7U18x3b06Q=="],
+
     "@types/ws/@types/node/undici-types": ["undici-types@6.21.0", "", {}, "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ=="],
 
+    "@typescript-eslint/typescript-estree/tinyglobby/picomatch": ["picomatch@4.0.4", "", {}, "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A=="],
+
+    "@vue/compiler-sfc/postcss/nanoid": ["nanoid@3.3.11", "", { "bin": { "nanoid": "bin/nanoid.cjs" } }, "sha512-N8SpfPUnUp1bK+PMYW8qSWdl9U+wwNWI4QKxOYDy9JAro3WMX7p2OeVRF9v+347pnakNevPmiHhNmZ2HbFA76w=="],
+
+    "buffer-image-size/@types/node/undici-types": ["undici-types@7.24.6", "", {}, "sha512-WRNW+sJgj5OBN4/0JpHFqtqzhpbnV0GuB+OozA9gCL7a993SmU+1JBZCzLNxYsbMfIeDL+lTsphD5jN5N+n0zg=="],
+
+    "bun-types/@types/node/undici-types": ["undici-types@7.24.6", "", {}, "sha512-WRNW+sJgj5OBN4/0JpHFqtqzhpbnV0GuB+OozA9gCL7a993SmU+1JBZCzLNxYsbMfIeDL+lTsphD5jN5N+n0zg=="],
+
+    "happy-dom/@types/node/undici-types": ["undici-types@7.24.6", "", {}, "sha512-WRNW+sJgj5OBN4/0JpHFqtqzhpbnV0GuB+OozA9gCL7a993SmU+1JBZCzLNxYsbMfIeDL+lTsphD5jN5N+n0zg=="],
+
     "mlly/pkg-types/confbox": ["confbox@0.1.8", "", {}, "sha512-RMtmw0iFkeR4YV+fUOSucriAQNb9g8zFR52MWCtl+cCZOFRNL6zeB395vPzFhEjjn4fMxXudmELnl/KF/WrK6w=="],
 
     "vitepress/vite/postcss": ["postcss@8.5.8", "", { "dependencies": { "nanoid": "^3.3.11", "picocolors": "^1.1.1", "source-map-js": "^1.2.1" } }, "sha512-OW/rX8O/jXnm82Ey1k44pObPtdblfiuWnrd8X7GJ7emImCOstunGbXUpp7HdBrFQX6rJzn3sPT397Wp5aCwCHg=="],
+
+    "vitepress/vite/postcss/nanoid": ["nanoid@3.3.11", "", { "bin": { "nanoid": "bin/nanoid.cjs" } }, "sha512-N8SpfPUnUp1bK+PMYW8qSWdl9U+wwNWI4QKxOYDy9JAro3WMX7p2OeVRF9v+347pnakNevPmiHhNmZ2HbFA76w=="],
   }
 }
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index 8a674fa..f70ad01 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -55,9 +55,12 @@ export default defineConfig({
           { text: 'Accordion', link: '/components/accordion' },
           { text: 'Alert', link: '/components/alert' },
           { text: 'Avatar', link: '/components/avatar' },
+          { text: 'Avatar Group', link: '/components/avatar-group' },
           { text: 'Badge', link: '/components/badge' },
+          { text: 'Banner', link: '/components/banner' },
           { text: 'Breadcrumbs', link: '/components/breadcrumbs' },
           { text: 'Button', link: '/components/button' },
+          { text: 'Button Group', link: '/components/button-group' },
           { text: 'Card', link: '/components/card' },
           { text: 'Checkbox', link: '/components/checkbox' },
           { text: 'Chip', link: '/components/chip' },
@@ -66,21 +69,28 @@ export default defineConfig({
           { text: 'Drawer', link: '/components/drawer' },
           { text: 'Dropdown Menu', link: '/components/dropdown-menu' },
           { text: 'Empty State', link: '/components/empty-state' },
+          { text: 'File Upload', link: '/components/file-upload' },
           { text: 'Icon Button', link: '/components/icon-button' },
           { text: 'Input', link: '/components/input' },
+          { text: 'Kbd', link: '/components/kbd' },
+          { text: 'Number Input', link: '/components/number-input' },
           { text: 'Pagination', link: '/components/pagination' },
+          { text: 'Popover', link: '/components/popover' },
           { text: 'Progress', link: '/components/progress' },
           { text: 'Radio', link: '/components/radio' },
+          { text: 'Rating', link: '/components/rating' },
           { text: 'Select', link: '/components/select' },
           { text: 'Segmented Control', link: '/components/segmented-control' },
           { text: 'Skeleton', link: '/components/skeleton' },
           { text: 'Slider', link: '/components/slider' },
           { text: 'Spinner', link: '/components/spinner' },
           { text: 'Stat Card', link: '/components/stat-card' },
+          { text: 'Stepper', link: '/components/stepper' },
           { text: 'Switch', link: '/components/switch' },
           { text: 'Table', link: '/components/table' },
           { text: 'Tabs', link: '/components/tabs' },
           { text: 'Textarea', link: '/components/textarea' },
+          { text: 'Timeline', link: '/components/timeline' },
           { text: 'Toast', link: '/components/toast' },
           { text: 'Tooltip', link: '/components/tooltip' },
         ],
diff --git a/docs/components/avatar-group.md b/docs/components/avatar-group.md
new file mode 100644
index 0000000..6cad55c
--- /dev/null
+++ b/docs/components/avatar-group.md
@@ -0,0 +1,87 @@
+# Avatar Group
+
+The `bq-avatar-group` component stacks `bq-avatar` elements and collapses the remainder into a `+N` counter.
+
+## Basic Usage
+
+```html
+<bq-avatar-group>
+  <bq-avatar initials="AB"></bq-avatar>
+  <bq-avatar initials="CD"></bq-avatar>
+  <bq-avatar initials="EF"></bq-avatar>
+</bq-avatar-group>
+```
+
+## Overflow
+
+Set `max` to cap how many avatars are shown. The rest are hidden in place and summarized by the counter:
+
+```html
+<bq-avatar-group max="3">
+  <bq-avatar initials="AB"></bq-avatar>
+  <bq-avatar initials="CD"></bq-avatar>
+  <bq-avatar initials="EF"></bq-avatar>
+  <bq-avatar initials="GH"></bq-avatar>
+  <bq-avatar initials="IJ"></bq-avatar>
+</bq-avatar-group>
+```
+
+Renders three avatars followed by `+2`.
+
+Clicking the counter emits `bq-overflow-click`, which is a good hook for opening a full member list:
+
+```js
+group.addEventListener('bq-overflow-click', (event) => {
+  console.log(`${event.detail.hidden} more people`);
+});
+```
+
+## Size
+
+`size` is forwarded to every slotted avatar, so the group stays visually consistent:
+
+```html
+<bq-avatar-group size="sm" max="3">…</bq-avatar-group>
+```
+
+## Spacing
+
+```html
+<bq-avatar-group spacing="tight">…</bq-avatar-group>
+<bq-avatar-group spacing="normal">…</bq-avatar-group>
+<bq-avatar-group spacing="loose">…</bq-avatar-group>
+```
+
+## Properties
+
+| Property  | Type     | Default    | Description                                                     |
+| --------- | -------- | ---------- | --------------------------------------------------------------- |
+| `max`     | `number` | `0`        | Maximum avatars to show before collapsing (`0` shows all)        |
+| `size`    | `string` | `''`       | `xs` \| `sm` \| `md` \| `lg` \| `xl` — forwarded to the avatars  |
+| `spacing` | `string` | `'normal'` | `tight` \| `normal` \| `loose`                                   |
+| `label`   | `string` | `''`       | Accessible label for the group                                   |
+
+## Slots
+
+| Slot        | Description        |
+| ----------- | ------------------ |
+| *(default)* | `bq-avatar` elements |
+
+## Events
+
+| Event                 | Detail               | Description                       |
+| --------------------- | -------------------- | --------------------------------- |
+| `bq-overflow-click`   | `{ hidden: number }` | The overflow counter was clicked  |
+
+## CSS Parts
+
+| Part       | Description            |
+| ---------- | ---------------------- |
+| `group`    | The group container    |
+| `overflow` | The `+N` counter       |
+
+## Accessibility
+
+- The group exposes `role="group"` with an accessible name (`label`, or a localized default).
+- Overflow avatars are hidden with `display: none` rather than removed, so the host page keeps ownership of its own elements.
+- The counter carries an `aria-label` describing how many people are hidden.
diff --git a/docs/components/banner.md b/docs/components/banner.md
new file mode 100644
index 0000000..3f68e31
--- /dev/null
+++ b/docs/components/banner.md
@@ -0,0 +1,93 @@
+# Banner
+
+The `bq-banner` component is a full-width, page-level announcement — maintenance notices, trial expiry, cookie policies.
+
+Use `bq-alert` for messages scoped to a section of the page, and `bq-toast` for transient notifications.
+
+## Basic Usage
+
+```html
+<bq-banner variant="info">Scheduled maintenance on Sunday, 02:00–04:00 UTC.</bq-banner>
+```
+
+## Variants
+
+```html
+<bq-banner variant="info">New workspace settings are available.</bq-banner>
+<bq-banner variant="success">Your plan was upgraded.</bq-banner>
+<bq-banner variant="warning">Your trial ends in 3 days.</bq-banner>
+<bq-banner variant="danger">We could not process your last payment.</bq-banner>
+<bq-banner variant="neutral">This workspace is read-only.</bq-banner>
+```
+
+## Dismissible
+
+```html
+<bq-banner variant="warning" dismissible>
+  Your trial ends in 3 days.
+</bq-banner>
+```
+
+`bq-dismiss` is cancelable. Call `preventDefault()` to keep the banner mounted — for example to persist the dismissal first, or to run your own exit animation:
+
+```js
+banner.addEventListener('bq-dismiss', (event) => {
+  event.preventDefault();
+  savePreference('trial-banner-dismissed').then(() => banner.remove());
+});
+```
+
+## Icon and Actions
+
+```html
+<bq-banner variant="warning" dismissible>
+  <span slot="icon">⚠️</span>
+  Your trial ends in 3 days.
+  <bq-button slot="actions" size="sm">Upgrade</bq-button>
+</bq-banner>
+```
+
+## Sticky
+
+```html
+<bq-banner variant="info" sticky>This banner stays at the top while scrolling.</bq-banner>
+```
+
+## Properties
+
+| Property      | Type      | Default  | Description                                                    |
+| ------------- | --------- | -------- | -------------------------------------------------------------- |
+| `variant`     | `string`  | `'info'` | `info` \| `success` \| `warning` \| `danger` \| `neutral`      |
+| `dismissible` | `boolean` | `false`  | Show a dismiss button                                          |
+| `sticky`      | `boolean` | `false`  | Stick to the top of the viewport                               |
+| `label`       | `string`  | `''`     | Accessible label for the banner region                         |
+
+## Slots
+
+| Slot        | Description       |
+| ----------- | ----------------- |
+| *(default)* | Banner message    |
+| `icon`      | Leading icon      |
+| `actions`   | Trailing actions  |
+
+## Events
+
+| Event         | Detail | Cancelable | Description                        |
+| ------------- | ------ | ---------- | ---------------------------------- |
+| `bq-dismiss`  | —      | Yes        | The dismiss button was activated   |
+
+## CSS Parts
+
+| Part      | Description             |
+| --------- | ----------------------- |
+| `banner`  | The banner container    |
+| `icon`    | Icon wrapper            |
+| `content` | Message wrapper         |
+| `actions` | Actions wrapper         |
+| `dismiss` | The dismiss button      |
+
+## Accessibility
+
+- The `danger` variant renders `role="alert"` with `aria-live="assertive"` so failures interrupt; every other variant uses `role="status"` with `aria-live="polite"`.
+- Set `label` when the banner needs a name distinct from its text content.
+- Keep the dismiss button reachable: it is a real `<button>` with an `aria-label` and a visible focus ring.
diff --git a/docs/components/button-group.md b/docs/components/button-group.md
new file mode 100644
index 0000000..ace2a6b
--- /dev/null
+++ b/docs/components/button-group.md
@@ -0,0 +1,75 @@
+# Button Group
+
+The `bq-button-group` component joins related buttons into a single visual control.
+
+## Basic Usage
+
+```html
+<bq-button-group label="Text alignment">
+  <bq-button variant="outline">Left</bq-button>
+  <bq-button variant="outline">Center</bq-button>
+  <bq-button variant="outline">Right</bq-button>
+</bq-button-group>
+```
+
+## Attached
+
+`attached` removes the gap so the buttons share borders and only the outer corners stay rounded:
+
+```html
+<bq-button-group attached label="Text alignment">
+  <bq-button variant="outline">Left</bq-button>
+  <bq-button variant="outline">Center</bq-button>
+  <bq-button variant="outline">Right</bq-button>
+</bq-button-group>
+```
+
+## Orientation
+
+```html
+<bq-button-group orientation="vertical" attached label="Actions">
+  <bq-button variant="outline">Edit</bq-button>
+  <bq-button variant="outline">Duplicate</bq-button>
+  <bq-button variant="outline">Delete</bq-button>
+</bq-button-group>
+```
+
+## Shared Size
+
+Set `size` once on the group instead of on every button. A size set explicitly on a child always wins:
+
+```html
+<bq-button-group size="sm">
+  <bq-button>Save</bq-button>
+  <bq-button>Cancel</bq-button>
+  <bq-button size="lg">Publish</bq-button>
+</bq-button-group>
+```
+
+## Properties
+
+| Property      | Type      | Default        | Description                                              |
+| ------------- | --------- | -------------- | -------------------------------------------------------- |
+| `orientation` | `string`  | `'horizontal'` | `horizontal` \| `vertical`                               |
+| `size`        | `string`  | `''`           | `sm` \| `md` \| `lg` — forwarded to slotted buttons      |
+| `attached`    | `boolean` | `false`        | Collapse the gap so buttons share borders                |
+| `label`       | `string`  | `''`           | Accessible label for the group                           |
+
+## Slots
+
+| Slot        | Description                                                |
+| ----------- | ---------------------------------------------------------- |
+| *(default)* | Buttons (`bq-button`, `bq-icon-button` or native `button`)  |
+
+## CSS Parts
+
+| Part    | Description         |
+| ------- | ------------------- |
+| `group` | The group container |
+
+## Accessibility
+
+- The group exposes `role="group"` with an accessible name, so screen readers announce the buttons as one set.
+- Buttons keep their own semantics and tab order; the group adds no keyboard behavior of its own.
+- The focused button is lifted above its neighbours so its focus ring is never clipped by an adjacent border.
+- For a single-choice control such as a view switcher, prefer [`bq-segmented-control`](./segmented-control), which has radio-group semantics.
diff --git a/docs/components/file-upload.md b/docs/components/file-upload.md
new file mode 100644
index 0000000..834936c
--- /dev/null
+++ b/docs/components/file-upload.md
@@ -0,0 +1,116 @@
+# File Upload
+
+The `bq-file-upload` component is a drop zone backed by a native file input, with client-side type and size filtering.
+
+## Basic Usage
+
+```html
+<bq-file-upload label="Attachments"></bq-file-upload>
+```
+
+## Multiple Files
+
+```html
+<bq-file-upload label="Attachments" multiple></bq-file-upload>
+```
+
+Without `multiple`, a new selection replaces the previous one.
+
+## Restricting Types
+
+`accept` takes extensions, wildcard MIME types, or exact MIME types:
+
+```html
+<bq-file-upload accept=".png,.jpg,image/webp" multiple></bq-file-upload>
+<bq-file-upload accept="image/*"></bq-file-upload>
+```
+
+## Size Limit
+
+`max-size` is per file, in bytes:
+
+```html
+<bq-file-upload max-size="5242880" hint="Up to 5 MB per file"></bq-file-upload>
+```
+
+## Handling Selections
+
+```js
+upload.addEventListener('bq-change', (event) => {
+  console.log(event.detail.files); // File[]
+});
+
+upload.addEventListener('bq-rejected', (event) => {
+  for (const { file, reason } of event.detail.files) {
+    console.warn(`${file.name} rejected: ${reason}`); // 'accept' | 'max-size'
+  }
+});
+```
+
+`bq-change` carries the full current selection, not just the newly added files, so it can be used directly as the source of truth.
+
+## Uploading
+
+The component does not perform the upload itself — it hands you `File` objects:
+
+```js
+upload.addEventListener('bq-change', async (event) => {
+  const body = new FormData();
+  for (const file of event.detail.files) body.append('files', file);
+  await fetch('/api/upload', { method: 'POST', body });
+});
+```
+
+## Hint and Error
+
+```html
+<bq-file-upload hint="PNG or JPG, up to 5 MB"></bq-file-upload>
+<bq-file-upload error="Upload failed, please try again"></bq-file-upload>
+```
+
+## Properties
+
+| Property   | Type      | Default | Description                                          |
+| ---------- | --------- | ------- | ---------------------------------------------------- |
+| `accept`   | `string`  | `''`    | Comma-separated list of extensions or MIME types     |
+| `multiple` | `boolean` | `false` | Allow selecting more than one file                   |
+| `disabled` | `boolean` | `false` | Disable the drop zone                                |
+| `max-size` | `number`  | `0`     | Maximum size per file in bytes (`0` = unlimited)     |
+| `name`     | `string`  | `''`    | Form field name                                      |
+| `label`    | `string`  | `''`    | Field label                                          |
+| `hint`     | `string`  | `''`    | Helper text                                          |
+| `error`    | `string`  | `''`    | Error message; marks the field invalid               |
+
+## Slots
+
+| Slot   | Description        |
+| ------ | ------------------ |
+| `icon` | Drop zone icon     |
+
+## Events
+
+| Event         | Detail                                          | Description                              |
+| ------------- | ----------------------------------------------- | ---------------------------------------- |
+| `bq-change`   | `{ files: File[] }`                             | The selection changed                    |
+| `bq-rejected` | `{ files: { file: File, reason: string }[] }`    | Files failed `accept` or `max-size`      |
+
+## CSS Parts
+
+| Part    | Description               |
+| ------- | ------------------------- |
+| `field` | The outer wrapper         |
+| `label` | The label element         |
+| `zone`  | The drop zone button      |
+| `icon`  | Icon wrapper              |
+| `files` | The selected-files list   |
+| `file`  | A selected-file row       |
+| `hint`  | Helper text               |
+| `error` | Error message             |
+
+## Accessibility
+
+- The drop zone is a real `<button>`, so it is reachable by keyboard and activates the file picker with <kbd>Enter</kbd> or <kbd>Space</kbd> — drag and drop is an enhancement, never the only route.
+- Hint and error text are linked with `aria-describedby`; an error also sets `aria-invalid` and `role="alert"`.
+- A polite live region announces how many files are selected.
+- Each file row has a remove button labelled with that file's name.
+- File names are written with `textContent`, never interpolated into HTML, since they come from user-supplied files.
diff --git a/docs/components/index.md b/docs/components/index.md
index 416b976..3d14130 100644
--- a/docs/components/index.md
+++ b/docs/components/index.md
@@ -8,12 +8,12 @@ This catalog gives you a complete overview of the currently available building b
 
 | Category | Components |
 | --- | --- |
-| **Actions** | `bq-button`, `bq-icon-button` |
-| **Forms** | `bq-input`, `bq-textarea`, `bq-select`, `bq-segmented-control`, `bq-checkbox`, `bq-radio`, `bq-switch`, `bq-slider`, `bq-chip` |
-| **Navigation & Disclosure** | `bq-tabs`, `bq-accordion`, `bq-breadcrumbs`, `bq-pagination` |
-| **Data Display** | `bq-card`, `bq-badge`, `bq-avatar`, `bq-table`, `bq-divider`, `bq-empty-state`, `bq-stat-card` |
-| **Feedback & Loading** | `bq-alert`, `bq-progress`, `bq-spinner`, `bq-skeleton`, `bq-tooltip`, `bq-toast` |
-| **Overlays** | `bq-dialog`, `bq-drawer`, `bq-dropdown-menu` |
+| **Actions** | `bq-button`, `bq-icon-button`, `bq-button-group` |
+| **Forms** | `bq-input`, `bq-number-input`, `bq-textarea`, `bq-select`, `bq-segmented-control`, `bq-checkbox`, `bq-radio`, `bq-switch`, `bq-slider`, `bq-chip`, `bq-rating`, `bq-file-upload` |
+| **Navigation & Disclosure** | `bq-tabs`, `bq-accordion`, `bq-breadcrumbs`, `bq-pagination`, `bq-stepper` |
+| **Data Display** | `bq-card`, `bq-badge`, `bq-avatar`, `bq-avatar-group`, `bq-table`, `bq-divider`, `bq-empty-state`, `bq-stat-card`, `bq-timeline`, `bq-kbd` |
+| **Feedback & Loading** | `bq-alert`, `bq-banner`, `bq-progress`, `bq-spinner`, `bq-skeleton`, `bq-tooltip`, `bq-toast` |
+| **Overlays** | `bq-dialog`, `bq-drawer`, `bq-dropdown-menu`, `bq-popover` |
 
 ## Cross-Cutting Features
 
@@ -32,12 +32,14 @@ Across the component library you will find the same professional capabilities th
 | --- | --- | --- |
 | `bq-button` | Primary and secondary actions | Variants, sizes, loading state, link rendering, icon slots, accessible label override |
 | `bq-icon-button` | Compact icon-only actions | Accessible label or title fallback, multiple variants, loading state, link rendering |
+| `bq-button-group` | Joining related actions into one control | Attached mode with shared borders, orientation, shared size forwarding, group semantics |
 
 ## Forms
 
 | Component | Use it for | Highlights |
 | --- | --- | --- |
 | `bq-input` | Single-line text input | Labels, hints, validation, prefix/suffix slots, size variants |
+| `bq-number-input` | Numeric entry with bounds | Stepper buttons, range clamping, step snapping, precision control, prefix/suffix slots |
 | `bq-textarea` | Multi-line text input | Rows, max length, validation, hints |
 | `bq-select` | Native dropdown selection | Placeholder, form-friendly behavior, error state |
 | `bq-segmented-control` | Compact single-choice view and filter toggles | Radio-group semantics, form participation, keyboard navigation, mobile-friendly full-width mode |
@@ -46,6 +48,8 @@ Across the component library you will find the same professional capabilities th
 | `bq-switch` | Toggle settings and preferences | Size variants, switch semantics, animated thumb |
 | `bq-slider` | Numeric range selection | Min/max/step, inline value display, input/change events |
 | `bq-chip` | Compact selectable tags | Selection state, removable chips, contextual variants |
+| `bq-rating` | Star ratings and scores | Radio-group semantics, keyboard support, read-only and clearable modes, form participation |
+| `bq-file-upload` | File selection and drag-and-drop | Type and size filtering, selected-file list, rejection events, keyboard-reachable drop zone |
 
 ## Navigation & Disclosure
 
@@ -55,6 +59,7 @@ Across the component library you will find the same professional capabilities th
 | `bq-accordion` | Expand/collapse detail sections | Smooth toggle animation, bordered/flush variants, keyboard support |
 | `bq-breadcrumbs` | Hierarchical navigation | Automatic separators, semantic navigation markup |
 | `bq-pagination` | Paging through result sets | Previous/next controls, ellipsis logic, sibling page calculation |
+| `bq-stepper` | Multi-step flows and wizards | Horizontal/vertical layouts, clickable steps, per-step status announcements |
 
 ## Data Display
 
@@ -63,16 +68,20 @@ Across the component library you will find the same professional capabilities th
 | `bq-card` | Structured surfaces and grouped content | Header/footer slots, padding control, elevation toggle |
 | `bq-badge` | Inline statuses and labels | Variants, sizes, pill mode |
 | `bq-avatar` | User and entity identity | Image/initial fallback, shapes, sizes, status indicators |
+| `bq-avatar-group` | Stacked collections of people | Overflow counter, shared sizing, configurable spacing |
 | `bq-table` | Tabular datasets | Sortable columns, bordered/striped/hoverable variants, empty/loading states |
 | `bq-divider` | Visual separation of content | Horizontal/vertical orientation, label support, multiple line styles |
 | `bq-empty-state` | No-data or no-results messaging | Title, description, icon slot, action slot |
 | `bq-stat-card` | Dashboard metrics and KPI summaries | Compact metric layout, trend pill, loading skeleton, icon slot |
+| `bq-timeline` | Activity feeds and audit trails | Ordered-list semantics, event variants, machine-readable timestamps, custom markers |
+| `bq-kbd` | Keyboard shortcuts | Combination parsing, symbol substitution, sizes and variants |
 
 ## Feedback & Loading
 
 | Component | Use it for | Highlights |
 | --- | --- | --- |
 | `bq-alert` | In-page status messaging | Semantic variants, dismissible mode, optional title |
+| `bq-banner` | Page-level announcements | Sticky mode, cancelable dismissal, severity-aware live regions, action slot |
 | `bq-progress` | Determinate or indeterminate progress | Value/max support, size variants, status variants |
 | `bq-spinner` | Compact loading indicator | Multiple sizes and color variants |
 | `bq-skeleton` | Loading placeholders | Text, circle, rect, and card variants with shimmer animation |
@@ -86,6 +95,7 @@ Across the component library you will find the same professional capabilities th
 | `bq-dialog` | Blocking confirmation and form flows | Focus trap, escape handling, click-outside close, multiple sizes |
 | `bq-drawer` | Supplemental side panels and mobile flows | Multiple placements, responsive sizes, overlay/backdrop handling |
 | `bq-dropdown-menu` | Contextual actions and navigation menus | Full keyboard navigation, placement options, click-outside close, focus management |
+| `bq-popover` | Rich anchored overlays | Dialog semantics, placement options, focus management, escape and click-outside close |
 
 ## Feature Coverage Compared to Typical UI Libraries
 
diff --git a/docs/components/kbd.md b/docs/components/kbd.md
new file mode 100644
index 0000000..1f02a24
--- /dev/null
+++ b/docs/components/kbd.md
@@ -0,0 +1,81 @@
+# Kbd
+
+The `bq-kbd` component renders a keystroke or key combination.
+
+## Basic Usage
+
+```html
+<bq-kbd keys="Ctrl+K"></bq-kbd>
+```
+
+Without `keys`, the slotted content is rendered inside a single key cap:
+
+```html
+<bq-kbd>Esc</bq-kbd>
+```
+
+## Key Combinations
+
+Keys are separated with `+`. Common key names are replaced with their symbol:
+
+```html
+<bq-kbd keys="Cmd+Shift+P"></bq-kbd>
+<bq-kbd keys="Alt+Enter"></bq-kbd>
+<bq-kbd keys="Ctrl+F5"></bq-kbd>
+```
+
+| Written | Rendered |
+| ------- | -------- |
+| `cmd`, `command`, `meta` | ⌘ |
+| `option` | ⌥ |
+| `shift` | ⇧ |
+| `enter`, `return` | ↵ |
+| `backspace` | ⌫ |
+| `delete` | ⌦ |
+| `tab` | ⇥ |
+| `up`, `down`, `left`, `right` | ↑ ↓ ← → |
+| `escape`, `esc` | Esc |
+
+Unrecognized names such as `F5` or `K` are shown as written.
+
+## Sizes
+
+```html
+<bq-kbd size="sm" keys="Ctrl+C"></bq-kbd>
+<bq-kbd size="md" keys="Ctrl+C"></bq-kbd>
+<bq-kbd size="lg" keys="Ctrl+C"></bq-kbd>
+```
+
+## Variants
+
+```html
+<bq-kbd variant="solid" keys="Ctrl+S"></bq-kbd>
+<bq-kbd variant="outline" keys="Ctrl+S"></bq-kbd>
+```
+
+## Properties
+
+| Property  | Type     | Default   | Description                                          |
+| --------- | -------- | --------- | ---------------------------------------------------- |
+| `keys`    | `string` | `''`      | Combination such as `Ctrl+Shift+K`; overrides the slot |
+| `size`    | `string` | `'md'`    | `sm` \| `md` \| `lg`                                 |
+| `variant` | `string` | `'solid'` | `solid` \| `outline`                                 |
+
+## Slots
+
+| Slot        | Description                              |
+| ----------- | ---------------------------------------- |
+| *(default)* | Key content, used when `keys` is not set |
+
+## CSS Parts
+
+| Part  | Description             |
+| ----- | ----------------------- |
+| `kbd` | The wrapping element    |
+| `key` | An individual key cap   |
+
+## Accessibility
+
+- Each key renders as a native `<kbd>` element, so assistive technology announces it as keyboard input.
+- The `+` separators are marked `aria-hidden` so the combination is not read as punctuation.
+- When a shortcut is the only way to reach a feature, describe it in text as well — a symbol such as ⌘ is not always announced usefully.
diff --git a/docs/components/number-input.md b/docs/components/number-input.md
new file mode 100644
index 0000000..1c659e4
--- /dev/null
+++ b/docs/components/number-input.md
@@ -0,0 +1,126 @@
+# Number Input
+
+The `bq-number-input` component is a numeric field with stepper buttons, range clamping and step snapping.
+
+## Basic Usage
+
+```html
+<bq-number-input label="Quantity" value="1" min="1" max="99"></bq-number-input>
+```
+
+## Step and Precision
+
+Values are snapped to the `step` grid and clamped to `[min, max]`:
+
+```html
+<bq-number-input label="Weight" value="2.5" min="0" max="10" step="0.5"></bq-number-input>
+```
+
+Display precision is derived from `step` — `step="0.5"` shows one decimal — which also avoids floating-point drift such as `0.30000000000000004`. Override it with `precision`:
+
+```html
+<bq-number-input value="1" step="0.1" precision="3"></bq-number-input>
+```
+
+## Prefix and Suffix
+
+```html
+<bq-number-input label="Price" value="20" min="0" step="0.01">
+  <span slot="prefix">€</span>
+</bq-number-input>
+
+<bq-number-input label="Duration" value="30" min="0" step="5">
+  <span slot="suffix">min</span>
+</bq-number-input>
+```
+
+## Hint and Error
+
+```html
+<bq-number-input label="Seats" value="4" hint="Between 1 and 20"></bq-number-input>
+<bq-number-input label="Seats" value="99" error="Maximum is 20"></bq-number-input>
+```
+
+## States
+
+```html
+<bq-number-input label="Locked" value="5" readonly></bq-number-input>
+<bq-number-input label="Unavailable" value="5" disabled></bq-number-input>
+```
+
+## Handling Changes
+
+```js
+input.addEventListener('bq-input', (event) => {
+  console.log('typing', event.detail.value);
+});
+
+input.addEventListener('bq-change', (event) => {
+  console.log('committed', event.detail.value);
+});
+```
+
+`bq-input` fires on each keystroke with the raw value. `bq-change` fires on commit (blur or a stepper button) with the normalized value — typing is never interrupted by mid-edit clamping.
+
+## Forms
+
+```html
+<form>
+  <bq-number-input name="quantity" value="2" min="1"></bq-number-input>
+  <button type="submit">Send</button>
+</form>
+```
+
+## Properties
+
+| Property      | Type      | Default | Description                                            |
+| ------------- | --------- | ------- | ------------------------------------------------------ |
+| `value`       | `number`  | `0`     | Current value                                          |
+| `min`         | `number`  | `-∞`    | Lower bound                                            |
+| `max`         | `number`  | `+∞`    | Upper bound                                            |
+| `step`        | `number`  | `1`     | Increment and snapping grid                            |
+| `precision`   | `number`  | `-1`    | Decimal places (`-1` derives them from `step`)         |
+| `label`       | `string`  | `''`    | Field label                                            |
+| `placeholder` | `string`  | `''`    | Placeholder text                                       |
+| `name`        | `string`  | `''`    | Form field name                                        |
+| `size`        | `string`  | `'md'`  | `sm` \| `md` \| `lg`                                   |
+| `disabled`    | `boolean` | `false` | Disable the field                                      |
+| `readonly`    | `boolean` | `false` | Prevent editing                                        |
+| `required`    | `boolean` | `false` | Mark the field required                                |
+| `error`       | `string`  | `''`    | Error message; marks the field invalid                 |
+| `hint`        | `string`  | `''`    | Helper text                                            |
+
+## Slots
+
+| Slot     | Description                                |
+| -------- | ------------------------------------------ |
+| `prefix` | Content before the field, e.g. a currency  |
+| `suffix` | Content after the field, e.g. a unit       |
+
+## Events
+
+| Event       | Detail              | Description                          |
+| ----------- | ------------------- | ------------------------------------ |
+| `bq-input`  | `{ value: number }` | The field value changed while typing |
+| `bq-change` | `{ value: number }` | A normalized value was committed     |
+
+## CSS Parts
+
+| Part        | Description             |
+| ----------- | ----------------------- |
+| `field`     | The outer wrapper       |
+| `label`     | The label element       |
+| `control`   | The input row           |
+| `input`     | The native input        |
+| `decrement` | The decrement button    |
+| `increment` | The increment button    |
+| `hint`      | Helper text             |
+| `error`     | Error message           |
+
+## Accessibility
+
+- The label is a real `<label>` bound to the input via `for`/`id`.
+- Hint and error text are linked with `aria-describedby`; an error also sets `aria-invalid` and `role="alert"`.
+- Stepper buttons carry localized `aria-label`s and are removed from the tab order — the field itself is the tab stop, and native <kbd>↑</kbd>/<kbd>↓</kbd> already step the value.
+- A stepper button is disabled once its bound is reached, so the limit is conveyed non-visually.
+- The native spin buttons are hidden in favour of the styled ones, which stay full-size and easy to hit on touch.
diff --git a/docs/components/popover.md b/docs/components/popover.md
new file mode 100644
index 0000000..48be8fb
--- /dev/null
+++ b/docs/components/popover.md
@@ -0,0 +1,97 @@
+# Popover
+
+The `bq-popover` component is a rich overlay anchored to a trigger. Unlike [`bq-tooltip`](./tooltip) — hover-activated and text-only — a popover holds interactive content, opens on click, and manages focus.
+
+## Basic Usage
+
+```html
+<bq-popover heading="Filters">
+  <bq-button slot="trigger">Open filters</bq-button>
+  Choose how results are sorted.
+</bq-popover>
+```
+
+## Placement
+
+```html
+<bq-popover placement="top">…</bq-popover>
+<bq-popover placement="bottom-start">…</bq-popover>
+<bq-popover placement="right">…</bq-popover>
+```
+
+Supported values are `top`, `bottom`, `left` and `right`, each optionally suffixed with `-start` or `-end` to align to an edge instead of the centre.
+
+## Footer Actions
+
+```html
+<bq-popover heading="Delete project">
+  <bq-button slot="trigger" variant="danger">Delete</bq-button>
+  This cannot be undone.
+  <bq-button slot="footer" variant="ghost">Cancel</bq-button>
+  <bq-button slot="footer" variant="danger">Delete</bq-button>
+</bq-popover>
+```
+
+## Without Chrome
+
+```html
+<bq-popover dismissible="false" arrow="false">
+  <bq-button slot="trigger">Details</bq-button>
+  Just the content.
+</bq-popover>
+```
+
+## Controlling It
+
+```js
+popover.setAttribute('open', '');   // open
+popover.removeAttribute('open');    // close
+
+popover.addEventListener('bq-open', () => console.log('opened'));
+popover.addEventListener('bq-close', () => console.log('closed'));
+```
+
+## Properties
+
+| Property      | Type      | Default    | Description                                              |
+| ------------- | --------- | ---------- | -------------------------------------------------------- |
+| `open`        | `boolean` | `false`    | Whether the popover is open                              |
+| `placement`   | `string`  | `'bottom'` | `top` \| `bottom` \| `left` \| `right` (+ `-start`/`-end`) |
+| `heading`     | `string`  | `''`       | Optional title                                           |
+| `dismissible` | `boolean` | `true`     | Show a close button                                      |
+| `arrow`       | `boolean` | `true`     | Render a pointer arrow                                   |
+
+## Slots
+
+| Slot        | Description                     |
+| ----------- | ------------------------------- |
+| `trigger`   | Element that toggles the popover |
+| *(default)* | Popover content                 |
+| `footer`    | Footer actions                  |
+
+## Events
+
+| Event      | Detail | Description             |
+| ---------- | ------ | ----------------------- |
+| `bq-open`  | —      | The popover opened      |
+| `bq-close` | —      | The popover closed      |
+
+## CSS Parts
+
+| Part      | Description          |
+| --------- | -------------------- |
+| `panel`   | The popover panel    |
+| `arrow`   | The pointer arrow    |
+| `header`  | Header row           |
+| `heading` | Title element        |
+| `close`   | Close button         |
+| `content` | Content wrapper      |
+| `footer`  | Footer wrapper       |
+
+## Accessibility
+
+- The panel exposes `role="dialog"`, labelled by the heading when one is set.
+- The trigger receives `aria-expanded`, `aria-haspopup="dialog"` and `aria-controls`, kept in sync as the popover opens and closes.
+- Opening moves focus to the first focusable element in the panel; <kbd>Escape</kbd> and the close button return focus to the trigger.
+- Clicking outside closes the popover. That document listener only exists while the popover is open and is removed on disconnect.
+- Use a genuinely focusable element (a button) in the `trigger` slot so keyboard users can reach it.
diff --git a/docs/components/rating.md b/docs/components/rating.md
new file mode 100644
index 0000000..63f34c8
--- /dev/null
+++ b/docs/components/rating.md
@@ -0,0 +1,103 @@
+# Rating
+
+The `bq-rating` component is a star rating input.
+
+## Basic Usage
+
+```html
+<bq-rating value="4"></bq-rating>
+```
+
+## Read-only and Disabled
+
+```html
+<bq-rating value="3" readonly></bq-rating>
+<bq-rating value="3" disabled></bq-rating>
+```
+
+`readonly` displays the value without allowing changes. `disabled` additionally dims the control.
+
+## Custom Scale
+
+```html
+<bq-rating value="7" max="10"></bq-rating>
+```
+
+## Clearable
+
+With `clearable`, selecting the current value resets the rating to `0`:
+
+```html
+<bq-rating value="3" clearable></bq-rating>
+```
+
+## Sizes
+
+```html
+<bq-rating value="3" size="sm"></bq-rating>
+<bq-rating value="3" size="md"></bq-rating>
+<bq-rating value="3" size="lg"></bq-rating>
+```
+
+## Handling Changes
+
+```js
+rating.addEventListener('bq-change', (event) => {
+  console.log(event.detail.value); // 4
+});
+```
+
+## Forms
+
+Set `name` to take part in native form submission:
+
+```html
+<form>
+  <bq-rating name="score" value="4"></bq-rating>
+  <button type="submit">Send</button>
+</form>
+```
+
+The component keeps a hidden input in sync, so `new FormData(form).get('score')` returns the current rating.
+
+## Properties
+
+| Property    | Type      | Default | Description                                   |
+| ----------- | --------- | ------- | --------------------------------------------- |
+| `value`     | `number`  | `0`     | Current rating                                |
+| `max`       | `number`  | `5`     | Number of stars                               |
+| `readonly`  | `boolean` | `false` | Display only                                  |
+| `disabled`  | `boolean` | `false` | Disable interaction                           |
+| `clearable` | `boolean` | `false` | Re-selecting the current value clears it      |
+| `size`      | `string`  | `'md'`  | `sm` \| `md` \| `lg`                          |
+| `label`     | `string`  | `''`    | Accessible label                              |
+| `name`      | `string`  | `''`    | Form field name                               |
+
+## Events
+
+| Event       | Detail              | Description             |
+| ----------- | ------------------- | ----------------------- |
+| `bq-change` | `{ value: number }` | The rating changed      |
+
+## CSS Parts
+
+| Part     | Description        |
+| -------- | ------------------ |
+| `rating` | The group wrapper  |
+| `star`   | An individual star |
+
+## Keyboard
+
+| Key                      | Action                  |
+| ------------------------ | ----------------------- |
+| <kbd>→</kbd> / <kbd>↑</kbd> | Increase by one      |
+| <kbd>←</kbd> / <kbd>↓</kbd> | Decrease by one      |
+| <kbd>Home</kbd>          | Clear to `0`            |
+| <kbd>End</kbd>           | Set to `max`            |
+
+## Accessibility
+
+- The control exposes `role="radiogroup"` and each star `role="radio"`, with `aria-readonly` and `aria-disabled` reflecting the current mode.
+- Only the active star is in the tab order; arrow keys move within the group, matching the WAI-ARIA radio-group pattern.
+- Every star has an `aria-label` describing the value it would set, and a polite live region announces the current rating.
+- Values are clamped to `0…max`, so an out-of-range `value` attribute cannot produce an inconsistent state.
diff --git a/docs/components/stepper.md b/docs/components/stepper.md
new file mode 100644
index 0000000..863cd5e
--- /dev/null
+++ b/docs/components/stepper.md
@@ -0,0 +1,103 @@
+# Stepper
+
+The `bq-stepper` component shows progress through a multi-step flow such as a checkout or onboarding wizard.
+
+## Basic Usage
+
+Steps are declared as light-DOM children carrying `data-step`:
+
+```html
+<bq-stepper current="1">
+  <div data-step label="Account"></div>
+  <div data-step label="Shipping"></div>
+  <div data-step label="Payment"></div>
+</bq-stepper>
+```
+
+`current` is a zero-based index: everything before it is complete, the step at that index is current, the rest are upcoming.
+
+## Descriptions
+
+```html
+<bq-stepper current="0">
+  <div data-step label="Account" description="Your details"></div>
+  <div data-step label="Shipping" description="Where it goes"></div>
+  <div data-step label="Payment" description="How you pay"></div>
+</bq-stepper>
+```
+
+## Orientation
+
+```html
+<bq-stepper current="1" orientation="vertical">
+  <div data-step label="Account"></div>
+  <div data-step label="Shipping"></div>
+  <div data-step label="Payment"></div>
+</bq-stepper>
+```
+
+## Clickable Steps
+
+With `clickable`, each step renders as a button and emits `bq-step-change` when activated:
+
+```html
+<bq-stepper current="2" clickable>
+  <div data-step label="Account"></div>
+  <div data-step label="Shipping"></div>
+  <div data-step label="Payment"></div>
+</bq-stepper>
+```
+
+```js
+stepper.addEventListener('bq-step-change', (event) => {
+  console.log(event.detail); // { index: 0, label: 'Account' }
+});
+```
+
+Add `disabled` to a step to keep it unreachable:
+
+```html
+<div data-step label="Payment" disabled></div>
+```
+
+## Properties
+
+| Property      | Type      | Default        | Description                              |
+| ------------- | --------- | -------------- | ---------------------------------------- |
+| `current`     | `number`  | `0`            | Zero-based index of the active step      |
+| `orientation` | `string`  | `'horizontal'` | `horizontal` \| `vertical`               |
+| `clickable`   | `boolean` | `false`        | Render steps as buttons                  |
+| `label`       | `string`  | `''`           | Accessible label for the step list       |
+
+## Step Attributes
+
+| Attribute     | Description                                    |
+| ------------- | ---------------------------------------------- |
+| `data-step`   | Marks the element as a step (required)         |
+| `label`       | Step title                                     |
+| `description` | Secondary text under the title                 |
+| `disabled`    | Prevents activation when `clickable` is set    |
+
+## Events
+
+| Event             | Detail                             | Description                    |
+| ----------------- | ---------------------------------- | ------------------------------ |
+| `bq-step-change`  | `{ index: number, label: string }` | A clickable step was activated |
+
+## CSS Parts
+
+| Part          | Description                |
+| ------------- | -------------------------- |
+| `stepper`     | The stepper container      |
+| `step`        | An individual step         |
+| `marker`      | The numbered/checked circle |
+| `label`       | Step title                 |
+| `description` | Step description           |
+
+## Accessibility
+
+- The active step carries `aria-current="step"`.
+- Each step includes visually hidden status text (`Completed`, `Current step`, `Upcoming step`) so its state is not conveyed by colour alone.
+- A polite live region announces `Step N of M` as `current` changes.
+- Step markers are `aria-hidden`; the label carries the accessible name.
+- Steps are read from the light DOM and kept in sync with a `MutationObserver`, so steps can be added or relabelled at runtime.
diff --git a/docs/components/timeline.md b/docs/components/timeline.md
new file mode 100644
index 0000000..727ce55
--- /dev/null
+++ b/docs/components/timeline.md
@@ -0,0 +1,96 @@
+# Timeline
+
+The `bq-timeline` component lists events in order along a connecting line — activity feeds, audit logs, release histories.
+
+## Basic Usage
+
+```html
+<bq-timeline>
+  <bq-timeline-item headline="Order placed" timestamp="Mar 1" datetime="2026-03-01">
+    Payment authorized.
+  </bq-timeline-item>
+  <bq-timeline-item headline="Shipped" timestamp="Mar 3" datetime="2026-03-03" variant="info">
+    Left the warehouse.
+  </bq-timeline-item>
+  <bq-timeline-item headline="Delivered" timestamp="Mar 5" datetime="2026-03-05" variant="success" last>
+    Signed for by A. Berger.
+  </bq-timeline-item>
+</bq-timeline>
+```
+
+Mark the final entry with `last` to drop its trailing connector.
+
+## Variants
+
+The marker colour communicates the kind of event:
+
+```html
+<bq-timeline-item variant="primary" headline="Created"></bq-timeline-item>
+<bq-timeline-item variant="success" headline="Approved"></bq-timeline-item>
+<bq-timeline-item variant="warning" headline="Needs review"></bq-timeline-item>
+<bq-timeline-item variant="danger"  headline="Rejected"></bq-timeline-item>
+<bq-timeline-item variant="info"    headline="Commented"></bq-timeline-item>
+<bq-timeline-item variant="neutral" headline="Archived"></bq-timeline-item>
+```
+
+## Compact Spacing
+
+```html
+<bq-timeline variant="compact">…</bq-timeline>
+```
+
+## Custom Markers
+
+```html
+<bq-timeline-item headline="Deployed">
+  <span slot="marker">🚀</span>
+  Release 1.15.0 is live.
+</bq-timeline-item>
+```
+
+## Properties
+
+### `bq-timeline`
+
+| Property  | Type     | Default     | Description                    |
+| --------- | -------- | ----------- | ------------------------------ |
+| `variant` | `string` | `'default'` | `default` \| `compact`         |
+| `align`   | `string` | `'start'`   | `start` \| `alternate`         |
+| `label`   | `string` | `''`        | Accessible label for the list  |
+
+### `bq-timeline-item`
+
+| Property    | Type      | Default     | Description                                                             |
+| ----------- | --------- | ----------- | ----------------------------------------------------------------------- |
+| `variant`   | `string`  | `'primary'` | `primary` \| `success` \| `danger` \| `warning` \| `info` \| `neutral`  |
+| `headline`  | `string`  | `''`        | Item title                                                              |
+| `timestamp` | `string`  | `''`        | Human-readable timestamp                                                |
+| `datetime`  | `string`  | `''`        | Machine-readable value for the `<time>` element                         |
+| `last`      | `boolean` | `false`     | Hide the trailing connector                                             |
+
+## Slots
+
+| Slot        | Element            | Description             |
+| ----------- | ------------------ | ----------------------- |
+| *(default)* | `bq-timeline`      | `bq-timeline-item` elements |
+| *(default)* | `bq-timeline-item` | Item body               |
+| `marker`    | `bq-timeline-item` | Custom marker content   |
+
+## CSS Parts
+
+| Part        | Description                |
+| ----------- | -------------------------- |
+| `timeline`  | The `<ol>` container       |
+| `item`      | An individual `<li>`       |
+| `marker`    | The event marker           |
+| `connector` | The line below the marker  |
+| `content`   | Item content wrapper       |
+| `headline`  | Item title                 |
+| `timestamp` | The `<time>` element       |
+| `body`      | Item body wrapper          |
+
+## Accessibility
+
+- The timeline renders a real `<ol>` and each item an `<li>`, so order and item count are announced.
+- Set `datetime` alongside `timestamp` to expose a machine-readable date on the `<time>` element.
+- Marker colour is decorative: keep the meaning of an event in its headline or body text.
diff --git a/docs/guide/installation.md b/docs/guide/installation.md
index d818cb0..3462e63 100644
--- a/docs/guide/installation.md
+++ b/docs/guide/installation.md
@@ -29,11 +29,11 @@ bun add @bquery/ui
 ::: code-group
 
 ```html [UMD]
-<script src="https://cdn.jsdelivr.net/npm/@bquery/ui@1.10.0/dist/index.umd.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@bquery/ui@1.15.0/dist/index.umd.js"></script>
 ```
 
 ```html [IIFE]
-<script src="https://cdn.jsdelivr.net/npm/@bquery/ui@1.10.0/dist/index.iife.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@bquery/ui@1.15.0/dist/index.iife.js"></script>
 ```
 
 :::
diff --git a/docs/guide/migration-from-1-1-0.md b/docs/guide/migration-from-1-1-0.md
index e3b1e67..d1141c4 100644
--- a/docs/guide/migration-from-1-1-0.md
+++ b/docs/guide/migration-from-1-1-0.md
@@ -89,7 +89,7 @@ These changes are backward compatible for most consumers, but they may affect sn
 For direct browser delivery, pin the bundled browser files to the current version:
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/@bquery/ui@1.10.0/dist/index.umd.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@bquery/ui@1.15.0/dist/index.umd.js"></script>
 ```
 
 The library ESM entry is still the right choice for bundlers, but the published `dist/index.js` keeps `@bquery/bquery` as a peer dependency, so browser-direct CDN usage should prefer `index.umd.js` or `index.iife.js`.
diff --git a/package.json b/package.json
index ed8d2b5..991b48d 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@bquery/ui",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "description": "Production-grade web component library for the bQuery project",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -86,28 +86,28 @@
     "build:storybook": "storybook build --output-dir storybook-static"
   },
   "peerDependencies": {
-    "@bquery/bquery": "^1.14.0"
+    "@bquery/bquery": "^1.15.1"
   },
   "devDependencies": {
-    "@bquery/bquery": "^1.14.0",
-    "@storybook/addon-docs": "^10.3.6",
-    "@storybook/web-components-vite": "^10.3.6",
-    "@tailwindcss/postcss": "^4.2.4",
-    "@types/node": "^25.6.0",
-    "@typescript-eslint/eslint-plugin": "^8.60.0",
-    "@typescript-eslint/parser": "^8.60.0",
-    "autoprefixer": "^10.5.0",
-    "bun-types": "^1.3.13",
-    "eslint": "^10.4.0",
+    "@bquery/bquery": "^1.15.1",
+    "@storybook/addon-docs": "^10.5.5",
+    "@storybook/web-components-vite": "^10.5.5",
+    "@tailwindcss/postcss": "^4.3.3",
+    "@types/node": "^26.1.2",
+    "@typescript-eslint/eslint-plugin": "^8.65.0",
+    "@typescript-eslint/parser": "^8.65.0",
+    "autoprefixer": "^10.5.4",
+    "bun-types": "^1.3.14",
+    "eslint": "^10.8.0",
     "eslint-config-prettier": "^10.1.8",
-    "globals": "^17.6.0",
-    "happy-dom": "^20.9.0",
-    "postcss": "^8.5.12",
-    "storybook": "^10.3.6",
-    "tailwindcss": "^4.2.4",
+    "globals": "^17.8.0",
+    "happy-dom": "^20.11.1",
+    "postcss": "^8.5.25",
+    "storybook": "^10.5.5",
+    "tailwindcss": "^4.3.3",
     "typescript": "^6.0.3",
-    "vite": "^8.0.10",
-    "vite-plugin-dts": "^5.0.0",
+    "vite": "^8.2.0",
+    "vite-plugin-dts": "^5.0.3",
     "vitepress": "^1.6.4"
   }
 }
diff --git a/src/components/accordion/BqAccordion.ts b/src/components/accordion/BqAccordion.ts
index db2bb4e..a25e1c0 100644
--- a/src/components/accordion/BqAccordion.ts
+++ b/src/components/accordion/BqAccordion.ts
@@ -9,10 +9,10 @@
  * @fires bq-toggle - { open: boolean }
  */
 import type { ComponentDefinition } from '@bquery/bquery/component';
-import { bool, component, html } from '@bquery/bquery/component';
+import { bool, component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { getAnimationTimeoutMs, uniqueId } from '../../utils/dom.js';
-import { getBaseStyles } from '../../utils/styles.js';
+import { baseStyles } from '../../utils/styles.js';
 
 type BqAccordionProps = {
   label: string;
@@ -34,8 +34,8 @@ const definition: ComponentDefinition<BqAccordionProps, BqAccordionState> = {
   state: {
     uid: '',
   },
-  styles: `
-    ${getBaseStyles()}
+  styles: css`
+    ${baseStyles}
     *, *::before, *::after { box-sizing: border-box; }
     :host { display: block; }
     :host([variant="bordered"]) .accordion { border: 1.5px solid var(--bq-border-base,#e2e8f0); border-radius: var(--bq-radius-lg); }
diff --git a/src/components/alert/BqAlert.ts b/src/components/alert/BqAlert.ts
index f43a65c..62369fe 100644
--- a/src/components/alert/BqAlert.ts
+++ b/src/components/alert/BqAlert.ts
@@ -7,10 +7,11 @@
  * @slot - Alert body content
  * @fires bq-close
  */
-import { component, html } from '@bquery/bquery/component';
+import { component, css, html } from '@bquery/bquery/component';
 import type { ComponentDefinition } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
-import { getBaseStyles } from '../../utils/styles.js';
+import { host } from '../../utils/component.js';
+import { baseStyles } from '../../utils/styles.js';
 import { t } from '../../i18n/index.js';
 
 type BqAlertProps = { variant: string; title: string; dismissible: boolean };
@@ -21,8 +22,8 @@ const definition: ComponentDefinition<BqAlertProps> = {
     title:      { type: String, default: '' },
     dismissible:{ type: Boolean, default: false },
   },
-  styles: `
-    ${getBaseStyles()}
+  styles: css`
+    ${baseStyles}
     *, *::before, *::after { box-sizing: border-box; }
     :host { display: block; }
     :host([hidden]) { display: none; }
@@ -44,7 +45,7 @@ const definition: ComponentDefinition<BqAlertProps> = {
     .close:focus-visible { outline: 2px solid transparent; box-shadow: var(--bq-focus-ring); }
   `,
   connected() {
-    const self = this;
+    const self = host(this);
     const handler = (e: Event) => {
       if ((e.target as Element).closest('.close')) {
         self.setAttribute('hidden', '');
diff --git a/src/components/avatar-group/BqAvatarGroup.ts b/src/components/avatar-group/BqAvatarGroup.ts
new file mode 100644
index 0000000..2663534
--- /dev/null
+++ b/src/components/avatar-group/BqAvatarGroup.ts
@@ -0,0 +1,154 @@
+/**
+ * Avatar group component — overlapping avatars with an overflow counter.
+ * @element bq-avatar-group
+ * @prop {number} max     - Maximum avatars to show before collapsing into "+N" (0 = show all)
+ * @prop {string} size    - xs | sm | md | lg | xl — forwarded to slotted avatars
+ * @prop {string} spacing - tight | normal | loose
+ * @prop {string} label   - Accessible label for the group
+ * @slot - `bq-avatar` elements
+ * @fires bq-overflow-click - { hidden: number }
+ */
+import { component, css, html } from '@bquery/bquery/component';
+import type { ComponentDefinition } from '@bquery/bquery/component';
+import { escapeHtml } from '@bquery/bquery/security';
+import { t } from '../../i18n/index.js';
+import { bind, host, release } from '../../utils/component.js';
+import { baseStyles, reset } from '../../utils/styles.js';
+
+type BqAvatarGroupProps = {
+  max: number;
+  size: string;
+  spacing: string;
+  label: string;
+};
+
+/**
+ * Reconciles the slotted avatars with the `max`/`size` props.
+ *
+ * The avatars live in the light DOM and belong to the host page, so overflow
+ * is applied by hiding them in place rather than by moving nodes. The counter
+ * lives in the shadow root but depends on that light-DOM count, which `render`
+ * cannot see — so it is written here.
+ */
+function syncGroup(el: HTMLElement): void {
+  const max = Number(el.getAttribute('max') ?? '0');
+  const size = el.getAttribute('size')?.trim();
+  const children = Array.from(el.children);
+
+  children.forEach((child, index) => {
+    if (size) child.setAttribute('size', size);
+    const hidden = max > 0 && index >= max;
+    if (hidden) child.setAttribute('data-bq-overflow-hidden', '');
+    else child.removeAttribute('data-bq-overflow-hidden');
+    (child as HTMLElement).style.display = hidden ? 'none' : '';
+  });
+
+  const hiddenCount = max > 0 ? Math.max(0, children.length - max) : 0;
+  const overflow = el.shadowRoot?.querySelector('.overflow');
+  if (!overflow) return;
+  if (hiddenCount > 0) {
+    overflow.removeAttribute('hidden');
+    overflow.textContent = `+${hiddenCount}`;
+    overflow.setAttribute(
+      'aria-label',
+      t('avatarGroup.overflow', { count: hiddenCount })
+    );
+  } else {
+    overflow.setAttribute('hidden', '');
+    overflow.textContent = '';
+    overflow.removeAttribute('aria-label');
+  }
+}
+
+const definition: ComponentDefinition<BqAvatarGroupProps> = {
+  props: {
+    max: { type: Number, default: 0 },
+    size: { type: String, default: '' },
+    spacing: { type: String, default: 'normal' },
+    label: { type: String, default: '' },
+  },
+  styles: css`
+    ${baseStyles}
+    ${reset}
+    :host { display: inline-flex; }
+    .group { display: inline-flex; align-items: center; }
+    .group[data-spacing="tight"]  ::slotted(*:not(:first-child)) { margin-left: -0.75rem; }
+    .group[data-spacing="normal"] ::slotted(*:not(:first-child)) { margin-left: -0.5rem; }
+    .group[data-spacing="loose"]  ::slotted(*:not(:first-child)) { margin-left: -0.25rem; }
+    ::slotted(*) {
+      border-radius: var(--bq-radius-full,9999px);
+      box-shadow: 0 0 0 2px var(--bq-bg-base,#fff);
+    }
+    /* Lift the hovered avatar above the ones stacked on top of it. */
+    ::slotted(*:hover) { z-index: 1; }
+    .overflow {
+      display: inline-flex; align-items: center; justify-content: center;
+      border-radius: var(--bq-radius-full,9999px);
+      background: var(--bq-bg-emphasis,#e2e8f0);
+      color: var(--bq-text-muted,#475569);
+      font-family: var(--bq-font-family-sans);
+      font-weight: var(--bq-font-weight-semibold,600);
+      box-shadow: 0 0 0 2px var(--bq-bg-base,#fff);
+    }
+    .overflow[hidden] { display: none; }
+    .group[data-spacing="tight"]  .overflow { margin-left: -0.75rem; }
+    .group[data-spacing="normal"] .overflow { margin-left: -0.5rem; }
+    .group[data-spacing="loose"]  .overflow { margin-left: -0.25rem; }
+    .overflow[data-size="xs"] { width: 1.5rem;  height: 1.5rem;  font-size: 0.625rem; }
+    .overflow[data-size="sm"] { width: 2rem;    height: 2rem;    font-size: 0.6875rem; }
+    .overflow[data-size="md"] { width: 2.5rem;  height: 2.5rem;  font-size: 0.75rem; }
+    .overflow[data-size="lg"] { width: 3rem;    height: 3rem;    font-size: 0.875rem; }
+    .overflow[data-size="xl"] { width: 4rem;    height: 4rem;    font-size: 1rem; }
+  `,
+  connected() {
+    const self = host(this);
+    const scope = bind(self);
+
+    const observer = new MutationObserver(() => syncGroup(self));
+    observer.observe(self, { childList: true });
+    scope.add(() => observer.disconnect());
+    scope.frame(() => syncGroup(self));
+
+    scope.on(self.shadowRoot, 'click', (e) => {
+      if (!(e.target as Element).closest('.overflow')) return;
+      const max = Number(self.getAttribute('max') ?? '0');
+      const hidden = max > 0 ? Math.max(0, self.children.length - max) : 0;
+      self.dispatchEvent(
+        new CustomEvent('bq-overflow-click', {
+          detail: { hidden },
+          bubbles: true,
+          composed: true,
+        })
+      );
+    });
+  },
+  disconnected() {
+    release(this);
+  },
+  updated() {
+    syncGroup(this);
+  },
+  render({ props }) {
+    const label = props.label.trim() || t('avatarGroup.label');
+    const size = props.size || 'md';
+    return html`
+      <div
+        part="group"
+        class="group"
+        role="group"
+        aria-label="${escapeHtml(label)}"
+        data-spacing="${escapeHtml(props.spacing)}"
+      >
+        <slot></slot>
+        <span
+          class="overflow"
+          part="overflow"
+          data-size="${escapeHtml(size)}"
+          hidden
+        ></span>
+      </div>
+    `;
+  },
+};
+
+component<BqAvatarGroupProps>('bq-avatar-group', definition);
diff --git a/src/components/avatar-group/index.ts b/src/components/avatar-group/index.ts
new file mode 100644
index 0000000..a94e6b9
--- /dev/null
+++ b/src/components/avatar-group/index.ts
@@ -0,0 +1 @@
+export * as __bqComponentEntry from './BqAvatarGroup.js';
diff --git a/src/components/avatar/BqAvatar.ts b/src/components/avatar/BqAvatar.ts
index 151e899..e69d9ea 100644
--- a/src/components/avatar/BqAvatar.ts
+++ b/src/components/avatar/BqAvatar.ts
@@ -9,9 +9,9 @@
  * @slot - Custom content
  */
 import type { ComponentDefinition } from '@bquery/bquery/component';
-import { component, html } from '@bquery/bquery/component';
+import { component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
-import { getBaseStyles } from '../../utils/styles.js';
+import { baseStyles } from '../../utils/styles.js';
 
 type BqAvatarProps = {
   src: string;
@@ -77,8 +77,8 @@ const definition: ComponentDefinition<BqAvatarProps> = {
     shape: { type: String, default: 'circle' },
     status: { type: String, default: '' },
   },
-  styles: `
-    ${getBaseStyles()}
+  styles: css`
+    ${baseStyles}
     :host { display: inline-block; position: relative; }
     .avatar {
       overflow: hidden; display: flex; align-items: center; justify-content: center;
diff --git a/src/components/badge/BqBadge.ts b/src/components/badge/BqBadge.ts
index b31f00d..a4de6ca 100644
--- a/src/components/badge/BqBadge.ts
+++ b/src/components/badge/BqBadge.ts
@@ -6,10 +6,10 @@
  * @prop {boolean} pill    - fully-rounded
  * @slot - Badge content
  */
-import { component, html } from '@bquery/bquery/component';
+import { component, css, html } from '@bquery/bquery/component';
 import type { ComponentDefinition } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
-import { getBaseStyles } from '../../utils/styles.js';
+import { baseStyles } from '../../utils/styles.js';
 
 type BqBadgeProps = { variant: string; size: string; pill: boolean };
 
@@ -19,8 +19,8 @@ const definition: ComponentDefinition<BqBadgeProps> = {
     size:    { type: String, default: 'md' },
     pill:    { type: Boolean, default: false },
   },
-  styles: `
-    ${getBaseStyles()}
+  styles: css`
+    ${baseStyles}
     :host { display: inline-flex; }
     .badge {
       display: inline-flex; align-items: center; gap: 0.25rem;
diff --git a/src/components/banner/BqBanner.ts b/src/components/banner/BqBanner.ts
new file mode 100644
index 0000000..df9df60
--- /dev/null
+++ b/src/components/banner/BqBanner.ts
@@ -0,0 +1,123 @@
+/**
+ * Banner component — full-width page-level announcement.
+ * @element bq-banner
+ * @prop {string}  variant     - info | success | warning | danger | neutral
+ * @prop {boolean} dismissible - Show a dismiss button
+ * @prop {boolean} sticky      - Stick to the top of the viewport
+ * @prop {string}  label       - Accessible label for the banner region
+ * @slot           - Banner message
+ * @slot icon      - Leading icon
+ * @slot actions   - Trailing actions
+ * @fires bq-dismiss
+ */
+import { component, css, html } from '@bquery/bquery/component';
+import type { ComponentDefinition } from '@bquery/bquery/component';
+import { escapeHtml } from '@bquery/bquery/security';
+import { t } from '../../i18n/index.js';
+import { bind, host, release } from '../../utils/component.js';
+import { baseStyles, reset, srOnly } from '../../utils/styles.js';
+
+type BqBannerProps = {
+  variant: string;
+  dismissible: boolean;
+  sticky: boolean;
+  label: string;
+};
+
+/** Banners that report a problem need to interrupt; the rest can wait. */
+function liveSettings(variant: string): { role: string; live: string } {
+  return variant === 'danger'
+    ? { role: 'alert', live: 'assertive' }
+    : { role: 'status', live: 'polite' };
+}
+
+const definition: ComponentDefinition<BqBannerProps> = {
+  props: {
+    variant: { type: String, default: 'info' },
+    dismissible: { type: Boolean, default: false },
+    sticky: { type: Boolean, default: false },
+    label: { type: String, default: '' },
+  },
+  styles: css`
+    ${baseStyles}
+    ${reset}
+    ${srOnly}
+    :host { display: block; }
+    :host([sticky]) { position: sticky; top: 0; z-index: var(--bq-z-sticky, 100); }
+    .banner {
+      display: flex; align-items: center; gap: 0.75rem;
+      padding: 0.75rem 1rem;
+      font-family: var(--bq-font-family-sans);
+      font-size: var(--bq-font-size-sm,0.875rem);
+      line-height: 1.5;
+      border-bottom: 1px solid transparent;
+    }
+    .content { flex: 1 1 auto; min-width: 0; }
+    .actions { display: flex; align-items: center; gap: 0.5rem; flex: 0 0 auto; }
+    .icon { display: inline-flex; flex: 0 0 auto; }
+    .dismiss {
+      display: inline-flex; align-items: center; justify-content: center;
+      width: 1.75rem; height: 1.75rem; flex: 0 0 auto;
+      border: none; border-radius: var(--bq-radius-md,0.375rem);
+      background: transparent; color: inherit; cursor: pointer;
+      font-size: 1rem; line-height: 1;
+      transition: background-color var(--bq-duration-fast) var(--bq-easing-standard);
+    }
+    .dismiss:hover { background: rgba(0,0,0,0.08); }
+    .dismiss:focus-visible { outline: 2px solid transparent; box-shadow: var(--bq-focus-ring); }
+    .banner[data-variant="info"]    { background: var(--bq-color-info-100,#dbeafe);    color: var(--bq-color-info-700,#1d4ed8);    border-bottom-color: var(--bq-color-info-200,#bfdbfe); }
+    .banner[data-variant="success"] { background: var(--bq-color-success-100,#dcfce7); color: var(--bq-color-success-700,#15803d); border-bottom-color: var(--bq-color-success-200,#bbf7d0); }
+    .banner[data-variant="warning"] { background: var(--bq-color-warning-100,#fef3c7); color: var(--bq-color-warning-700,#b45309); border-bottom-color: var(--bq-color-warning-200,#fde68a); }
+    .banner[data-variant="danger"]  { background: var(--bq-color-danger-100,#fee2e2);  color: var(--bq-color-danger-700,#b91c1c);  border-bottom-color: var(--bq-color-danger-200,#fecaca); }
+    .banner[data-variant="neutral"] { background: var(--bq-bg-muted,#f1f5f9);          color: var(--bq-text-base,#0f172a);         border-bottom-color: var(--bq-border-base,#e2e8f0); }
+    @media (prefers-reduced-motion: reduce) {
+      .dismiss { transition: none; }
+    }
+  `,
+  connected() {
+    const self = host(this);
+    const scope = bind(self);
+    scope.on(self.shadowRoot, 'click', (e) => {
+      if (!(e.target as Element).closest('.dismiss')) return;
+      // Cancelling `bq-dismiss` lets the host keep the banner mounted, e.g. to
+      // run an exit animation or persist the dismissal first.
+      const proceed = self.dispatchEvent(
+        new CustomEvent('bq-dismiss', {
+          bubbles: true,
+          composed: true,
+          cancelable: true,
+        })
+      );
+      if (proceed) self.setAttribute('hidden', '');
+    });
+  },
+  disconnected() {
+    release(this);
+  },
+  render({ props }) {
+    const { role, live } = liveSettings(props.variant);
+    const label = props.label.trim();
+    const dismissLabel = t('banner.dismiss');
+    return html`
+      <div
+        part="banner"
+        class="banner"
+        data-variant="${escapeHtml(props.variant)}"
+        role="${role}"
+        aria-live="${live}"
+        ${label ? `aria-label="${escapeHtml(label)}"` : ''}
+      >
+        <span class="icon" part="icon"><slot name="icon"></slot></span>
+        <div class="content" part="content"><slot></slot></div>
+        <div class="actions" part="actions"><slot name="actions"></slot></div>
+        ${
+          props.dismissible
+            ? `<button type="button" part="dismiss" class="dismiss" aria-label="${escapeHtml(dismissLabel)}">&times;</button>`
+            : ''
+        }
+      </div>
+    `;
+  },
+};
+
+component<BqBannerProps>('bq-banner', definition);
diff --git a/src/components/banner/index.ts b/src/components/banner/index.ts
new file mode 100644
index 0000000..75757dd
--- /dev/null
+++ b/src/components/banner/index.ts
@@ -0,0 +1 @@
+export * as __bqComponentEntry from './BqBanner.js';
diff --git a/src/components/breadcrumbs/BqBreadcrumbs.ts b/src/components/breadcrumbs/BqBreadcrumbs.ts
index e2ee081..3f68113 100644
--- a/src/components/breadcrumbs/BqBreadcrumbs.ts
+++ b/src/components/breadcrumbs/BqBreadcrumbs.ts
@@ -7,9 +7,10 @@
  * @cssprop --bq-breadcrumb-separator - Override the separator string ("/" by default)
  */
 import type { ComponentDefinition } from '@bquery/bquery/component';
-import { component, html } from '@bquery/bquery/component';
+import { component, css, html } from '@bquery/bquery/component';
 import { t } from '../../i18n/index.js';
-import { getBaseStyles } from '../../utils/styles.js';
+import { host } from '../../utils/component.js';
+import { baseStyles } from '../../utils/styles.js';
 
 type BqBreadcrumbsProps = { separator: string };
 
@@ -24,8 +25,8 @@ const definition: ComponentDefinition<BqBreadcrumbsProps> = {
   props: {
     separator: { type: String, default: '/' },
   },
-  styles: `
-    ${getBaseStyles()}
+  styles: css`
+    ${baseStyles}
     *, *::before, *::after { box-sizing: border-box; }
     :host { display: block; }
     .breadcrumbs { display: flex; align-items: center; flex-wrap: wrap; list-style: none; margin: 0; padding: 0; font-family: var(--bq-font-family-sans); font-size: var(--bq-font-size-sm,0.875rem); gap: 0; }
@@ -46,7 +47,7 @@ const definition: ComponentDefinition<BqBreadcrumbsProps> = {
     }
   `,
   connected() {
-    const self = this;
+    const self = host(this);
     const applyAttrs = () => {
       const slot = self.shadowRoot?.querySelector(
         'slot'
diff --git a/src/components/button-group/BqButtonGroup.ts b/src/components/button-group/BqButtonGroup.ts
new file mode 100644
index 0000000..aaffb9c
--- /dev/null
+++ b/src/components/button-group/BqButtonGroup.ts
@@ -0,0 +1,115 @@
+/**
+ * Button group component — joins related buttons into a single control.
+ * @element bq-button-group
+ * @prop {string}  orientation - horizontal | vertical
+ * @prop {string}  size        - sm | md | lg — forwarded to slotted bq-button elements
+ * @prop {boolean} attached    - Collapse the gap so buttons share borders
+ * @prop {string}  label       - Accessible label for the group
+ * @slot - Buttons (`bq-button`, `bq-icon-button` or native `button`)
+ */
+import { component, css, html } from '@bquery/bquery/component';
+import type { ComponentDefinition } from '@bquery/bquery/component';
+import { escapeHtml } from '@bquery/bquery/security';
+import { t } from '../../i18n/index.js';
+import { bind, host, release } from '../../utils/component.js';
+import { baseStyles, reset } from '../../utils/styles.js';
+
+type BqButtonGroupProps = {
+  orientation: string;
+  size: string;
+  attached: boolean;
+  label: string;
+};
+
+const definition: ComponentDefinition<BqButtonGroupProps> = {
+  props: {
+    orientation: { type: String, default: 'horizontal' },
+    size: { type: String, default: '' },
+    attached: { type: Boolean, default: false },
+    label: { type: String, default: '' },
+  },
+  styles: css`
+    ${baseStyles}
+    ${reset}
+    :host { display: inline-flex; }
+    .group { display: inline-flex; gap: 0.5rem; }
+    .group[data-orientation="vertical"] { flex-direction: column; }
+    :host([attached]) .group { gap: 0; }
+
+    /* Attached groups share borders: only the outer edges stay rounded. */
+    :host([attached]) ::slotted(*) { --bq-radius-lg: 0; --bq-radius-md: 0; }
+    :host([attached]) .group[data-orientation="horizontal"] ::slotted(*:first-child) {
+      --bq-radius-lg: 0.5rem 0 0 0.5rem; --bq-radius-md: 0.375rem 0 0 0.375rem;
+    }
+    :host([attached]) .group[data-orientation="horizontal"] ::slotted(*:last-child) {
+      --bq-radius-lg: 0 0.5rem 0.5rem 0; --bq-radius-md: 0 0.375rem 0.375rem 0;
+    }
+    :host([attached]) .group[data-orientation="vertical"] ::slotted(*:first-child) {
+      --bq-radius-lg: 0.5rem 0.5rem 0 0; --bq-radius-md: 0.375rem 0.375rem 0 0;
+    }
+    :host([attached]) .group[data-orientation="vertical"] ::slotted(*:last-child) {
+      --bq-radius-lg: 0 0 0.5rem 0.5rem; --bq-radius-md: 0 0 0.375rem 0.375rem;
+    }
+    :host([attached]) .group[data-orientation="horizontal"] ::slotted(*:not(:first-child)) { margin-left: -1.5px; }
+    :host([attached]) .group[data-orientation="vertical"] ::slotted(*:not(:first-child)) { margin-top: -1.5px; }
+    /* Keep the focused button's ring above its neighbours' borders. */
+    ::slotted(*:focus-within) { position: relative; z-index: 1; }
+  `,
+  connected() {
+    const self = host(this);
+    const scope = bind(self);
+
+    // `size` is a convenience: set it once on the group instead of on every
+    // child. An explicit size on a child always wins.
+    const syncSize = () => {
+      const size = self.getAttribute('size')?.trim();
+      for (const child of Array.from(self.children)) {
+        if (!size) {
+          if (child.getAttribute('data-bq-group-size') === child.getAttribute('size'))
+            child.removeAttribute('size');
+          child.removeAttribute('data-bq-group-size');
+          continue;
+        }
+        const own = child.getAttribute('size');
+        if (own && child.getAttribute('data-bq-group-size') !== own) continue;
+        child.setAttribute('size', size);
+        child.setAttribute('data-bq-group-size', size);
+      }
+    };
+
+    const observer = new MutationObserver(syncSize);
+    observer.observe(self, { childList: true });
+    scope.add(() => observer.disconnect());
+    scope.frame(syncSize);
+  },
+  disconnected() {
+    release(this);
+  },
+  updated() {
+    const self = host(this);
+    const size = self.getAttribute('size')?.trim();
+    if (!size) return;
+    for (const child of Array.from(self.children)) {
+      const own = child.getAttribute('size');
+      if (own && child.getAttribute('data-bq-group-size') !== own) continue;
+      child.setAttribute('size', size);
+      child.setAttribute('data-bq-group-size', size);
+    }
+  },
+  render({ props }) {
+    const label = props.label.trim() || t('buttonGroup.defaultLabel');
+    return html`
+      <div
+        part="group"
+        class="group"
+        role="group"
+        aria-label="${escapeHtml(label)}"
+        data-orientation="${escapeHtml(props.orientation)}"
+      >
+        <slot></slot>
+      </div>
+    `;
+  },
+};
+
+component<BqButtonGroupProps>('bq-button-group', definition);
diff --git a/src/components/button-group/index.ts b/src/components/button-group/index.ts
new file mode 100644
index 0000000..a0f7a89
--- /dev/null
+++ b/src/components/button-group/index.ts
@@ -0,0 +1 @@
+export * as __bqComponentEntry from './BqButtonGroup.js';
diff --git a/src/components/button/BqButton.ts b/src/components/button/BqButton.ts
index befa9e0..8127a9a 100644
--- a/src/components/button/BqButton.ts
+++ b/src/components/button/BqButton.ts
@@ -14,12 +14,13 @@
  * @slot suffix-icon - Icon after content
  * @fires bq-click - { originalEvent: Event }
  */
-import { bool, component, html } from '@bquery/bquery/component';
+import { bool, component, css, html } from '@bquery/bquery/component';
 import type { ComponentDefinition } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { t } from '../../i18n/index.js';
 import { uniqueId } from '../../utils/dom.js';
-import { getBaseStyles } from '../../utils/styles.js';
+import { host } from '../../utils/component.js';
+import { baseStyles } from '../../utils/styles.js';
 
 type BqButtonProps = {
   variant: string;
@@ -47,8 +48,8 @@ const definition: ComponentDefinition<BqButtonProps, BqButtonState> = {
   state: {
     statusId: '',
   },
-  styles: `
-    ${getBaseStyles()}
+  styles: css`
+    ${baseStyles}
     *, *::before, *::after { box-sizing: border-box; }
     :host { display: inline-block; }
     :host([hidden]) { display: none; }
@@ -109,7 +110,7 @@ const definition: ComponentDefinition<BqButtonProps, BqButtonState> = {
     self.shadowRoot?.addEventListener('click', handler);
   },
   disconnected() {
-    const self = this;
+    const self = host(this);
     const handler = (self as unknown as Record<string, unknown>)['_clickHandler'] as EventListener | undefined;
     if (handler) self.shadowRoot?.removeEventListener('click', handler);
   },
diff --git a/src/components/card/BqCard.ts b/src/components/card/BqCard.ts
index dbb4dbc..b933629 100644
--- a/src/components/card/BqCard.ts
+++ b/src/components/card/BqCard.ts
@@ -9,9 +9,9 @@
  * @slot footer  - Card footer
  */
 import type { ComponentDefinition } from '@bquery/bquery/component';
-import { component, html } from '@bquery/bquery/component';
+import { component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
-import { getBaseStyles } from '../../utils/styles.js';
+import { baseStyles } from '../../utils/styles.js';
 
 type BqCardProps = { title: string; elevated: boolean; padding: string };
 
@@ -21,8 +21,8 @@ const definition: ComponentDefinition<BqCardProps> = {
     elevated: { type: Boolean, default: true },
     padding: { type: String, default: 'md' },
   },
-  styles: `
-    ${getBaseStyles()}
+  styles: css`
+    ${baseStyles}
     *, *::before, *::after { box-sizing: border-box; }
     :host { display: block; }
     .card {
diff --git a/src/components/checkbox/BqCheckbox.ts b/src/components/checkbox/BqCheckbox.ts
index 5ae6fa9..fed8a99 100644
--- a/src/components/checkbox/BqCheckbox.ts
+++ b/src/components/checkbox/BqCheckbox.ts
@@ -12,10 +12,11 @@
  * @fires bq-change - { value: string, checked: boolean }
  */
 import type { ComponentDefinition } from '@bquery/bquery/component';
-import { bool, component, html } from '@bquery/bquery/component';
+import { bool, component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { createFormProxy, type FormProxy } from '../../utils/form.js';
-import { getBaseStyles } from '../../utils/styles.js';
+import { host } from '../../utils/component.js';
+import { baseStyles } from '../../utils/styles.js';
 
 type BqCheckboxProps = {
   label: string;
@@ -39,8 +40,8 @@ const definition: ComponentDefinition<BqCheckboxProps> = {
     required: { type: Boolean, default: false },
     hint: { type: String, default: '' },
   },
-  styles: `
-    ${getBaseStyles()}
+  styles: css`
+    ${baseStyles}
     *, *::before, *::after { box-sizing: border-box; }
     :host { display: block; }
     .wrapper { display: flex; flex-direction: column; gap: 0.25rem; }
@@ -59,7 +60,7 @@ const definition: ComponentDefinition<BqCheckboxProps> = {
     .hint { font-size: var(--bq-font-size-sm,0.875rem); color: var(--bq-text-muted,#475569); font-family: var(--bq-font-family-sans); padding-inline-start: 1.75rem; }
   `,
   connected() {
-    const self = this;
+    const self = host(this);
 
     // Form proxy for native <form> participation
     const name = self.getAttribute('name') ?? '';
diff --git a/src/components/chip/BqChip.ts b/src/components/chip/BqChip.ts
index dc4d16f..2364bd8 100644
--- a/src/components/chip/BqChip.ts
+++ b/src/components/chip/BqChip.ts
@@ -11,10 +11,11 @@
  * @fires bq-click
  */
 import type { ComponentDefinition } from '@bquery/bquery/component';
-import { component, html } from '@bquery/bquery/component';
+import { component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { t } from '../../i18n/index.js';
-import { getBaseStyles } from '../../utils/styles.js';
+import { host } from '../../utils/component.js';
+import { baseStyles } from '../../utils/styles.js';
 
 type BqChipProps = {
   variant: string;
@@ -32,8 +33,8 @@ const definition: ComponentDefinition<BqChipProps> = {
     selected: { type: Boolean, default: false },
     disabled: { type: Boolean, default: false },
   },
-  styles: `
-    ${getBaseStyles()}
+  styles: css`
+    ${baseStyles}
     *, *::before, *::after { box-sizing: border-box; }
     :host { display: inline-flex; }
     .chip {
@@ -66,7 +67,7 @@ const definition: ComponentDefinition<BqChipProps> = {
     }
   `,
   connected() {
-    const self = this;
+    const self = host(this);
     const handler = (e: Event) => {
       if (self.hasAttribute('disabled')) return;
       const target = e.target as Element;
diff --git a/src/components/dialog/BqDialog.ts b/src/components/dialog/BqDialog.ts
index 5bbf2bd..91d1c59 100644
--- a/src/components/dialog/BqDialog.ts
+++ b/src/components/dialog/BqDialog.ts
@@ -10,17 +10,18 @@
  * @fires bq-close
  */
 import type { ComponentDefinition } from '@bquery/bquery/component';
-import { component, html } from '@bquery/bquery/component';
+import { component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { t } from '../../i18n/index.js';
+import { bind, host, release } from '../../utils/component.js';
 import type { OverlayFocusState } from '../../utils/dom.js';
 import {
   cleanupOverlayFocus,
-  getAnimationTimeoutMs,
+  createAnimatedClose,
   uniqueId,
   updateOverlayFocus,
 } from '../../utils/dom.js';
-import { getBaseStyles } from '../../utils/styles.js';
+import { baseStyles } from '../../utils/styles.js';
 
 type BqDialogProps = {
   open: boolean;
@@ -41,8 +42,8 @@ const definition: ComponentDefinition<BqDialogProps, BqDialogState> = {
   state: {
     titleId: '',
   },
-  styles: `
-    ${getBaseStyles()}
+  styles: css`
+    ${baseStyles}
     *, *::before, *::after { box-sizing: border-box; }
     :host { display: block; }
     :host(:not([open])) .overlay { display: none; }
@@ -84,86 +85,32 @@ const definition: ComponentDefinition<BqDialogProps, BqDialogState> = {
     }
   `,
   connected() {
-    type BQEl = HTMLElement & {
-      setState(k: 'titleId', v: string): void;
-      getState<T>(k: string): T;
-    };
-    const self = this as unknown as BQEl;
-    const record = self as unknown as Record<string, unknown>;
+    const self = host<BqDialogState>(this);
+    const scope = bind(self);
     if (!self.getState<string>('titleId'))
       self.setState('titleId', uniqueId('bq-dlg-title'));
-    // Escape key handler
-    const kh = (e: Event) => {
+
+    const close = createAnimatedClose({
+      host: self,
+      scope,
+      panelSelector: '.overlay',
+      fallbackDuration: NORMAL_DURATION,
+    });
+
+    scope.on(document, 'keydown', (e) => {
       if ((e as KeyboardEvent).key === 'Escape' && self.hasAttribute('open'))
         close();
-    };
-    // Click-outside handler
-    const oh = (e: Event) => {
+    });
+    scope.on(self.shadowRoot, 'click', (e) => {
       if ((e.target as Element).classList.contains('overlay')) close();
-    };
-    const close = () => {
-      if (self.hasAttribute('data-closing')) return;
-      const clearCloseTimer = () => {
-        const closeTimer = record['_closeTimer'] as
-          | ReturnType<typeof setTimeout>
-          | undefined;
-        if (closeTimer) {
-          clearTimeout(closeTimer);
-          delete record['_closeTimer'];
-        }
-      };
-      const reducedMotion = self.ownerDocument.defaultView?.matchMedia?.(
-        '(prefers-reduced-motion: reduce)'
-      )?.matches;
-      const finalize = () => {
-        clearCloseTimer();
-        self.removeAttribute('data-closing');
-        self.removeAttribute('open');
-        self.dispatchEvent(
-          new CustomEvent('bq-close', { bubbles: true, composed: true })
-        );
-      };
-      if (reducedMotion) {
-        finalize();
-      } else {
-        self.setAttribute('data-closing', '');
-        const overlay = self.shadowRoot?.querySelector('.overlay');
-        const timeoutMs = overlay
-          ? getAnimationTimeoutMs(overlay, NORMAL_DURATION)
-          : 0;
-        if (timeoutMs <= 0) {
-          finalize();
-        } else {
-          record['_closeTimer'] = setTimeout(finalize, Math.ceil(timeoutMs) + 20);
-        }
-      }
-    };
-    const ch = (e: Event) => {
+    });
+    scope.on(self.shadowRoot, 'click', (e) => {
       if ((e.target as Element).closest('.close-btn')) close();
-    };
-    (self as unknown as Record<string, unknown>)['_kh'] = kh;
-    (self as unknown as Record<string, unknown>)['_oh'] = oh;
-    (self as unknown as Record<string, unknown>)['_ch'] = ch;
-    document.addEventListener('keydown', kh);
-    self.shadowRoot?.addEventListener('click', oh);
-    self.shadowRoot?.addEventListener('click', ch);
+    });
   },
   disconnected() {
-    const s = this as unknown as Record<string, unknown>;
-    cleanupOverlayFocus(s as unknown as OverlayFocusState);
-    const kh = s['_kh'] as EventListener | undefined;
-    if (kh) document.removeEventListener('keydown', kh);
-    const oh = s['_oh'] as EventListener | undefined;
-    if (oh) this.shadowRoot?.removeEventListener('click', oh);
-    const ch = s['_ch'] as EventListener | undefined;
-    if (ch) this.shadowRoot?.removeEventListener('click', ch);
-    const closeTimer = s['_closeTimer'] as ReturnType<typeof setTimeout> | undefined;
-    if (closeTimer) {
-      clearTimeout(closeTimer);
-      delete s['_closeTimer'];
-      this.removeAttribute('data-closing');
-      this.removeAttribute('open');
-    }
+    cleanupOverlayFocus(this as unknown as OverlayFocusState);
+    release(this);
   },
   updated() {
     updateOverlayFocus(this, this as unknown as OverlayFocusState, '.dialog');
diff --git a/src/components/divider/BqDivider.ts b/src/components/divider/BqDivider.ts
index 846fe0a..a6375c3 100644
--- a/src/components/divider/BqDivider.ts
+++ b/src/components/divider/BqDivider.ts
@@ -6,9 +6,9 @@
  * @prop {string} label       - Optional center label
  */
 import type { ComponentDefinition } from '@bquery/bquery/component';
-import { component, html } from '@bquery/bquery/component';
+import { component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
-import { getBaseStyles } from '../../utils/styles.js';
+import { baseStyles } from '../../utils/styles.js';
 
 type BqDividerProps = { orientation: string; variant: string; label: string };
 
@@ -18,8 +18,8 @@ const definition: ComponentDefinition<BqDividerProps> = {
     variant: { type: String, default: 'solid' },
     label: { type: String, default: '' },
   },
-  styles: `
-    ${getBaseStyles()}
+  styles: css`
+    ${baseStyles}
     :host { display: block; }
     .divider {
       display: flex; align-items: center; gap: 0.75rem;
diff --git a/src/components/drawer/BqDrawer.ts b/src/components/drawer/BqDrawer.ts
index b785d0f..cc33b68 100644
--- a/src/components/drawer/BqDrawer.ts
+++ b/src/components/drawer/BqDrawer.ts
@@ -10,17 +10,18 @@
  * @fires bq-close
  */
 import type { ComponentDefinition } from '@bquery/bquery/component';
-import { component, html } from '@bquery/bquery/component';
+import { component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { t } from '../../i18n/index.js';
+import { bind, host, release } from '../../utils/component.js';
 import type { OverlayFocusState } from '../../utils/dom.js';
 import {
   cleanupOverlayFocus,
-  getAnimationTimeoutMs,
+  createAnimatedClose,
   uniqueId,
   updateOverlayFocus,
 } from '../../utils/dom.js';
-import { getBaseStyles } from '../../utils/styles.js';
+import { baseStyles } from '../../utils/styles.js';
 
 type BqDrawerProps = {
   open: boolean;
@@ -41,8 +42,8 @@ const definition: ComponentDefinition<BqDrawerProps, BqDrawerState> = {
   state: {
     titleId: '',
   },
-  styles: `
-    ${getBaseStyles()}
+  styles: css`
+    ${baseStyles}
     *, *::before, *::after { box-sizing: border-box; }
     :host { display: block; }
     :host(:not([open])) .backdrop { display: none; }
@@ -96,85 +97,32 @@ const definition: ComponentDefinition<BqDrawerProps, BqDrawerState> = {
     }
   `,
   connected() {
-    type BQEl = HTMLElement & {
-      setState(k: 'titleId', v: string): void;
-      getState<T>(k: string): T;
-    };
-    const self = this as unknown as BQEl;
-    const record = self as unknown as Record<string, unknown>;
+    const self = host<BqDrawerState>(this);
+    const scope = bind(self);
     if (!self.getState<string>('titleId'))
       self.setState('titleId', uniqueId('bq-drawer-title'));
-    const close = () => {
-      if (self.hasAttribute('data-closing')) return;
-      const clearCloseTimer = () => {
-        const closeTimer = record['_closeTimer'] as
-          | ReturnType<typeof setTimeout>
-          | undefined;
-        if (closeTimer) {
-          clearTimeout(closeTimer);
-          delete record['_closeTimer'];
-        }
-      };
-      const reducedMotion = self.ownerDocument.defaultView?.matchMedia?.(
-        '(prefers-reduced-motion: reduce)'
-      )?.matches;
-      const finalize = () => {
-        clearCloseTimer();
-        self.removeAttribute('data-closing');
-        self.removeAttribute('open');
-        self.dispatchEvent(
-          new CustomEvent('bq-close', { bubbles: true, composed: true })
-        );
-      };
-      if (reducedMotion) {
-        finalize();
-      } else {
-        self.setAttribute('data-closing', '');
-        const drawer = self.shadowRoot?.querySelector('.drawer');
-        const timeoutMs = drawer
-          ? getAnimationTimeoutMs(drawer, NORMAL_DURATION)
-          : 0;
-        if (timeoutMs <= 0) {
-          finalize();
-        } else {
-          record['_closeTimer'] = setTimeout(finalize, Math.ceil(timeoutMs) + 20);
-        }
-      }
-    };
-    const kh = (e: Event) => {
+
+    const close = createAnimatedClose({
+      host: self,
+      scope,
+      panelSelector: '.drawer',
+      fallbackDuration: NORMAL_DURATION,
+    });
+
+    scope.on(document, 'keydown', (e) => {
       if ((e as KeyboardEvent).key === 'Escape' && self.hasAttribute('open'))
         close();
-    };
-    const bh = (e: Event) => {
+    });
+    scope.on(self.shadowRoot, 'click', (e) => {
       if ((e.target as Element).classList.contains('backdrop')) close();
-    };
-    const ch = (e: Event) => {
+    });
+    scope.on(self.shadowRoot, 'click', (e) => {
       if ((e.target as Element).closest('.close-btn')) close();
-    };
-    const s = self as unknown as Record<string, unknown>;
-    s['_kh'] = kh;
-    s['_bh'] = bh;
-    s['_ch'] = ch;
-    document.addEventListener('keydown', kh);
-    self.shadowRoot?.addEventListener('click', bh);
-    self.shadowRoot?.addEventListener('click', ch);
+    });
   },
   disconnected() {
-    const s = this as unknown as Record<string, unknown>;
-    cleanupOverlayFocus(s as unknown as OverlayFocusState);
-    const kh = s['_kh'] as EventListener | undefined;
-    if (kh) document.removeEventListener('keydown', kh);
-    const bh = s['_bh'] as EventListener | undefined;
-    if (bh) this.shadowRoot?.removeEventListener('click', bh);
-    const ch = s['_ch'] as EventListener | undefined;
-    if (ch) this.shadowRoot?.removeEventListener('click', ch);
-    const closeTimer = s['_closeTimer'] as ReturnType<typeof setTimeout> | undefined;
-    if (closeTimer) {
-      clearTimeout(closeTimer);
-      delete s['_closeTimer'];
-      this.removeAttribute('data-closing');
-      this.removeAttribute('open');
-    }
+    cleanupOverlayFocus(this as unknown as OverlayFocusState);
+    release(this);
   },
   updated() {
     updateOverlayFocus(this, this as unknown as OverlayFocusState, '.drawer');
diff --git a/src/components/dropdown-menu/BqDropdownMenu.ts b/src/components/dropdown-menu/BqDropdownMenu.ts
index 701ea10..20e74bd 100644
--- a/src/components/dropdown-menu/BqDropdownMenu.ts
+++ b/src/components/dropdown-menu/BqDropdownMenu.ts
@@ -12,10 +12,12 @@
  * @fires bq-select - { value: string } — emitted when a menu item is activated
  */
 import type { ComponentDefinition } from '@bquery/bquery/component';
-import { component, html } from '@bquery/bquery/component';
+import { component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
+import type { Disposer } from '../../utils/component.js';
+import { bind, host, release, store } from '../../utils/component.js';
 import { getAnimationTimeoutMs, uniqueId } from '../../utils/dom.js';
-import { getBaseStyles } from '../../utils/styles.js';
+import { baseStyles } from '../../utils/styles.js';
 
 type BqDropdownMenuProps = {
   label: string;
@@ -26,6 +28,10 @@ type BqDropdownMenuProps = {
 type BqDropdownMenuState = { uid: string };
 const FAST_DURATION = '150ms';
 
+/** Per-instance handles that `updated()` needs after `connected()` set them up. */
+const menuStore = (owner: object) =>
+  store<{ syncOutsideListener?: () => void }>(owner, () => ({}));
+
 const definition: ComponentDefinition<
   BqDropdownMenuProps,
   BqDropdownMenuState
@@ -39,8 +45,8 @@ const definition: ComponentDefinition<
   state: {
     uid: '',
   },
-  styles: `
-    ${getBaseStyles()}
+  styles: css`
+    ${baseStyles}
     *, *::before, *::after { box-sizing: border-box; }
     :host { display: inline-block; position: relative; }
     .trigger-wrap { display: inline-flex; }
@@ -85,14 +91,12 @@ const definition: ComponentDefinition<
     }
   `,
   connected() {
-    type BQEl = HTMLElement & {
-      setState(k: 'uid', v: string): void;
-      getState<T>(k: string): T;
-    };
-    const self = this as unknown as BQEl;
-    const record = self as unknown as Record<string, unknown>;
+    const self = host<BqDropdownMenuState>(this);
+    const scope = bind(self);
     if (!self.getState<string>('uid')) self.setState('uid', uniqueId('bq-dm'));
 
+    let cancelClose: Disposer | null = null;
+
     const getTrigger = (): HTMLElement | null =>
       self.querySelector('[slot="trigger"]') as HTMLElement | null;
 
@@ -174,20 +178,12 @@ const definition: ComponentDefinition<
       if (!self.hasAttribute('open') || self.hasAttribute('data-closing'))
         return;
       clearTypeaheadBuffer();
-      const clearCloseTimer = () => {
-        const closeTimer = record['_closeTimer'] as
-          | ReturnType<typeof setTimeout>
-          | undefined;
-        if (closeTimer) {
-          clearTimeout(closeTimer);
-          delete record['_closeTimer'];
-        }
-      };
       const reducedMotion = self.ownerDocument.defaultView?.matchMedia?.(
         '(prefers-reduced-motion: reduce)'
       )?.matches;
       const finalize = () => {
-        clearCloseTimer();
+        cancelClose?.();
+        cancelClose = null;
         self.removeAttribute('data-closing');
         self.removeAttribute('open');
         syncTriggerA11y();
@@ -205,10 +201,7 @@ const definition: ComponentDefinition<
         if (timeoutMs <= 0) {
           finalize();
         } else {
-          record['_closeTimer'] = setTimeout(
-            finalize,
-            Math.ceil(timeoutMs) + 20
-          );
+          cancelClose = scope.timeout(finalize, Math.ceil(timeoutMs) + 20);
         }
       }
     };
@@ -218,15 +211,14 @@ const definition: ComponentDefinition<
     };
 
     let typeaheadBuffer = '';
-    let typeaheadTimeout = 0;
+    let cancelTypeahead: Disposer | null = null;
 
     const clearTypeaheadBuffer = () => {
       typeaheadBuffer = '';
-      if (typeaheadTimeout) {
-        clearTimeout(typeaheadTimeout);
-        typeaheadTimeout = 0;
-      }
+      cancelTypeahead?.();
+      cancelTypeahead = null;
     };
+    scope.add(clearTypeaheadBuffer);
 
     const focusTypeaheadMatch = (search: string, currentIndex: number) => {
       const items = getMenuItems();
@@ -380,10 +372,10 @@ const definition: ComponentDefinition<
           if (ke.isComposing || ke.keyCode === 229) break;
           if (ke.key.length === 1 && !ke.altKey && !ke.ctrlKey && !ke.metaKey) {
             typeaheadBuffer = `${typeaheadBuffer}${ke.key.toLowerCase()}`;
-            if (typeaheadTimeout) clearTimeout(typeaheadTimeout);
-            typeaheadTimeout = window.setTimeout(() => {
+            cancelTypeahead?.();
+            cancelTypeahead = scope.timeout(() => {
               typeaheadBuffer = '';
-              typeaheadTimeout = 0;
+              cancelTypeahead = null;
             }, 500);
             focusTypeaheadMatch(typeaheadBuffer, currentIndex);
           }
@@ -396,19 +388,16 @@ const definition: ComponentDefinition<
       if (!self.hasAttribute('open')) return;
       if (!self.contains(e.target as Node)) close({ restoreFocus: true });
     };
-    let outsideListening = false;
+    // The document listener only exists while the menu is open, but the scope
+    // owns its removal so a disconnect while open cannot strand it.
+    let stopListeningOutside: Disposer | null = null;
     const syncOutsideListener = () => {
       if (self.hasAttribute('open')) {
-        if (!outsideListening) {
-          document.addEventListener('click', outsideHandler);
-          outsideListening = true;
-        }
+        stopListeningOutside ??= scope.on(document, 'click', outsideHandler);
         return;
       }
-      if (outsideListening) {
-        document.removeEventListener('click', outsideHandler);
-        outsideListening = false;
-      }
+      stopListeningOutside?.();
+      stopListeningOutside = null;
     };
 
     const slotChangeHandler = () => {
@@ -416,74 +405,42 @@ const definition: ComponentDefinition<
       syncMenuItemRoles();
     };
 
-    const s = self as unknown as Record<string, unknown>;
-    s['_triggerHandler'] = triggerHandler;
-    s['_menuClickHandler'] = menuClickHandler;
-    s['_keyHandler'] = keyHandler;
-    s['_outsideHandler'] = outsideHandler;
-    s['_syncOutsideListener'] = syncOutsideListener;
-    s['_slotChangeHandler'] = slotChangeHandler;
-    s['_clearTypeaheadBuffer'] = clearTypeaheadBuffer;
-
-    self.addEventListener('click', triggerHandler);
-    self.addEventListener('click', menuClickHandler);
-    self.addEventListener('keydown', keyHandler);
-    self.shadowRoot
-      ?.querySelector('slot[name="trigger"]')
-      ?.addEventListener('slotchange', slotChangeHandler);
-    self.shadowRoot
-      ?.querySelector('slot:not([name])')
-      ?.addEventListener('slotchange', slotChangeHandler);
-
-    requestAnimationFrame(() => {
+    // `updated()` has to re-evaluate the outside listener after every render.
+    menuStore(self).syncOutsideListener = syncOutsideListener;
+
+    // An interrupted close animation must not strand the menu half-closed.
+    scope.add(() => {
+      if (!cancelClose) return;
+      cancelClose = null;
+      self.removeAttribute('data-closing');
+      self.removeAttribute('open');
+    });
+
+    scope.on(self, 'click', triggerHandler);
+    scope.on(self, 'click', menuClickHandler);
+    scope.on(self, 'keydown', keyHandler);
+    scope.on(
+      self.shadowRoot?.querySelector('slot[name="trigger"]'),
+      'slotchange',
+      slotChangeHandler
+    );
+    scope.on(
+      self.shadowRoot?.querySelector('slot:not([name])'),
+      'slotchange',
+      slotChangeHandler
+    );
+
+    scope.frame(() => {
       syncTriggerA11y();
       syncMenuItemRoles();
       syncOutsideListener();
     });
   },
   disconnected() {
-    const s = this as unknown as Record<string, unknown>;
-    const triggerHandler = s['_triggerHandler'] as EventListener | undefined;
-    const menuClickHandler = s['_menuClickHandler'] as
-      | EventListener
-      | undefined;
-    const keyHandler = s['_keyHandler'] as EventListener | undefined;
-    const outsideHandler = s['_outsideHandler'] as EventListener | undefined;
-    const slotChangeHandler = s['_slotChangeHandler'] as
-      | EventListener
-      | undefined;
-    const clearTypeaheadBuffer = s['_clearTypeaheadBuffer'] as
-      | (() => void)
-      | undefined;
-    const closeTimer = s['_closeTimer'] as
-      | ReturnType<typeof setTimeout>
-      | undefined;
-    if (triggerHandler) this.removeEventListener('click', triggerHandler);
-    if (menuClickHandler) this.removeEventListener('click', menuClickHandler);
-    if (keyHandler) this.removeEventListener('keydown', keyHandler);
-    if (outsideHandler) document.removeEventListener('click', outsideHandler);
-    clearTypeaheadBuffer?.();
-    if (closeTimer) {
-      clearTimeout(closeTimer);
-      delete s['_closeTimer'];
-      this.removeAttribute('data-closing');
-      this.removeAttribute('open');
-    }
-    if (slotChangeHandler) {
-      this.shadowRoot
-        ?.querySelector('slot[name="trigger"]')
-        ?.removeEventListener('slotchange', slotChangeHandler);
-      this.shadowRoot
-        ?.querySelector('slot:not([name])')
-        ?.removeEventListener('slotchange', slotChangeHandler);
-    }
+    release(this);
   },
   updated() {
-    const s = this as unknown as Record<string, unknown>;
-    const syncOutsideListener = s['_syncOutsideListener'] as
-      | (() => void)
-      | undefined;
-    syncOutsideListener?.();
+    menuStore(this).syncOutsideListener?.();
     const trigger = this.querySelector(
       '[slot="trigger"]'
     ) as HTMLElement | null;
diff --git a/src/components/empty-state/BqEmptyState.ts b/src/components/empty-state/BqEmptyState.ts
index 016700d..789494f 100644
--- a/src/components/empty-state/BqEmptyState.ts
+++ b/src/components/empty-state/BqEmptyState.ts
@@ -6,11 +6,11 @@
  * @prop {string} icon        - Icon character/emoji
  * @slot - Additional content (e.g. action button)
  */
-import { component, html } from '@bquery/bquery/component';
+import { component, css, html } from '@bquery/bquery/component';
 import type { ComponentDefinition } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { t } from '../../i18n/index.js';
-import { getBaseStyles } from '../../utils/styles.js';
+import { baseStyles } from '../../utils/styles.js';
 
 type BqEmptyStateProps = { title: string; description: string; icon: string };
 
@@ -20,8 +20,8 @@ const definition: ComponentDefinition<BqEmptyStateProps> = {
     description: { type: String, default: '' },
     icon:        { type: String, default: '' },
   },
-  styles: `
-    ${getBaseStyles()}
+  styles: css`
+    ${baseStyles}
     *, *::before, *::after { box-sizing: border-box; }
     :host { display: block; }
     .empty {
diff --git a/src/components/file-upload/BqFileUpload.ts b/src/components/file-upload/BqFileUpload.ts
new file mode 100644
index 0000000..af91024
--- /dev/null
+++ b/src/components/file-upload/BqFileUpload.ts
@@ -0,0 +1,371 @@
+/**
+ * File upload component — drop zone with a native file input behind it.
+ * @element bq-file-upload
+ * @prop {string}  accept    - Comma-separated accept list forwarded to the input
+ * @prop {boolean} multiple
+ * @prop {boolean} disabled
+ * @prop {number}  max-size  - Maximum size per file in bytes (0 = unlimited)
+ * @prop {string}  name      - Form field name
+ * @prop {string}  label
+ * @prop {string}  hint      - Helper text shown under the drop zone
+ * @prop {string}  error     - Error message; marks the field invalid
+ * @slot icon - Drop zone icon
+ * @fires bq-change   - { files: File[] }
+ * @fires bq-rejected - { files: { file: File, reason: string }[] }
+ */
+import { bool, component, css, html } from '@bquery/bquery/component';
+import type { ComponentDefinition } from '@bquery/bquery/component';
+import { escapeHtml } from '@bquery/bquery/security';
+import { t } from '../../i18n/index.js';
+import { bind, host, release, store } from '../../utils/component.js';
+import { uniqueId } from '../../utils/dom.js';
+import { baseStyles, reset, srOnly } from '../../utils/styles.js';
+
+type BqFileUploadProps = {
+  accept: string;
+  multiple: boolean;
+  disabled: boolean;
+  'max-size': number;
+  name: string;
+  label: string;
+  hint: string;
+  error: string;
+};
+type BqFileUploadState = { uid: string };
+
+const uploadStore = (owner: object) =>
+  store<{ files: File[]; renderFiles?: () => void }>(owner, () => ({
+    files: [],
+  }));
+
+/** Human-readable byte size, e.g. `1.4 MB`. */
+export function formatBytes(bytes: number): string {
+  if (!Number.isFinite(bytes) || bytes <= 0) return '0 B';
+  const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+  const exponent = Math.min(
+    Math.floor(Math.log(bytes) / Math.log(1024)),
+    units.length - 1
+  );
+  const value = bytes / 1024 ** exponent;
+  const rounded = exponent === 0 ? String(bytes) : value.toFixed(1);
+  return `${rounded} ${units[exponent]}`;
+}
+
+/** True when the file satisfies an `accept` list of extensions and MIME patterns. */
+export function matchesAccept(file: File, accept: string): boolean {
+  const patterns = accept
+    .split(',')
+    .map((entry) => entry.trim().toLowerCase())
+    .filter(Boolean);
+  if (patterns.length === 0) return true;
+
+  const name = file.name.toLowerCase();
+  const type = (file.type || '').toLowerCase();
+  return patterns.some((pattern) => {
+    if (pattern.startsWith('.')) return name.endsWith(pattern);
+    if (pattern.endsWith('/*')) return type.startsWith(pattern.slice(0, -1));
+    return type === pattern;
+  });
+}
+
+const definition: ComponentDefinition<BqFileUploadProps, BqFileUploadState> = {
+  // `accept` is outside the framework's base allowlist; the value is escaped
+  // and only ever comes from this component's own prop.
+  sanitize: { allowAttributes: ['accept'] },
+  props: {
+    accept: { type: String, default: '' },
+    multiple: { type: Boolean, default: false },
+    disabled: { type: Boolean, default: false },
+    'max-size': { type: Number, default: 0 },
+    name: { type: String, default: '' },
+    label: { type: String, default: '' },
+    hint: { type: String, default: '' },
+    error: { type: String, default: '' },
+  },
+  state: {
+    uid: '',
+  },
+  styles: css`
+    ${baseStyles}
+    ${reset}
+    ${srOnly}
+    :host { display: block; }
+    .field { font-family: var(--bq-font-family-sans); }
+    .label {
+      display: block;
+      font-size: var(--bq-font-size-sm,0.875rem);
+      font-weight: var(--bq-font-weight-medium,500);
+      color: var(--bq-text-base,#0f172a);
+      margin-bottom: 0.375rem;
+    }
+    .zone {
+      display: flex; flex-direction: column; align-items: center; gap: 0.375rem;
+      padding: 1.5rem 1rem; width: 100%;
+      border: 2px dashed var(--bq-border-emphasis,#cbd5e1);
+      border-radius: var(--bq-radius-lg,0.5rem);
+      background: var(--bq-bg-subtle,#f8fafc);
+      color: var(--bq-text-muted,#475569);
+      font: inherit; font-size: var(--bq-font-size-sm,0.875rem);
+      cursor: pointer; text-align: center;
+      transition: border-color var(--bq-duration-fast) var(--bq-easing-standard),
+                  background-color var(--bq-duration-fast) var(--bq-easing-standard);
+    }
+    .zone:hover:not(:disabled) { border-color: var(--bq-color-primary-600,#2563eb); background: var(--bq-color-primary-50,#eff6ff); }
+    .zone:focus-visible { outline: 2px solid transparent; box-shadow: var(--bq-focus-ring); }
+    .zone:disabled { opacity: 0.55; cursor: not-allowed; }
+    :host([data-dragging]) .zone { border-color: var(--bq-color-primary-600,#2563eb); background: var(--bq-color-primary-50,#eff6ff); }
+    :host([error]) .zone { border-color: var(--bq-color-danger-600,#dc2626); }
+    .browse { color: var(--bq-color-primary-600,#2563eb); font-weight: var(--bq-font-weight-semibold,600); }
+    .icon { display: inline-flex; font-size: 1.5rem; }
+
+    input[type="file"] {
+      position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px;
+      overflow: hidden; clip: rect(0,0,0,0); white-space: nowrap; border: 0;
+    }
+
+    .files { list-style: none; margin: 0.625rem 0 0; padding: 0; display: flex; flex-direction: column; gap: 0.375rem; }
+    .file {
+      display: flex; align-items: center; gap: 0.5rem;
+      padding: 0.375rem 0.5rem;
+      border: 1px solid var(--bq-border-base,#e2e8f0);
+      border-radius: var(--bq-radius-md,0.375rem);
+      background: var(--bq-bg-base,#fff);
+      font-size: var(--bq-font-size-xs,0.75rem);
+    }
+    .file-name { flex: 1 1 auto; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; color: var(--bq-text-base,#0f172a); }
+    .file-size { flex: 0 0 auto; color: var(--bq-text-subtle,#94a3b8); }
+    .remove {
+      flex: 0 0 auto;
+      display: inline-flex; align-items: center; justify-content: center;
+      width: 1.25rem; height: 1.25rem;
+      border: none; border-radius: var(--bq-radius-sm,0.25rem);
+      background: transparent; color: var(--bq-text-muted,#475569);
+      cursor: pointer; font-size: 0.875rem; line-height: 1;
+    }
+    .remove:hover { background: var(--bq-bg-muted,#f1f5f9); color: var(--bq-color-danger-600,#dc2626); }
+    .remove:focus-visible { outline: 2px solid transparent; box-shadow: var(--bq-focus-ring); }
+
+    .message { font-size: var(--bq-font-size-xs,0.75rem); margin-top: 0.375rem; }
+    .hint  { color: var(--bq-text-subtle,#94a3b8); }
+    .error { color: var(--bq-color-danger-600,#dc2626); }
+    @media (prefers-reduced-motion: reduce) {
+      .zone { transition: none; }
+    }
+  `,
+  connected() {
+    const self = host<BqFileUploadState>(this);
+    const scope = bind(self);
+    const local = uploadStore(self);
+    if (!self.getState<string>('uid')) self.setState('uid', uniqueId('bq-upload'));
+
+    const input = () =>
+      self.shadowRoot?.querySelector('input[type="file"]') as
+        | HTMLInputElement
+        | null;
+
+    const renderFiles = () => {
+      const list = self.shadowRoot?.querySelector('.files');
+      if (!list) return;
+      list.textContent = '';
+      const doc = self.ownerDocument;
+      for (const [index, file] of local.files.entries()) {
+        const item = doc.createElement('li');
+        item.className = 'file';
+        item.setAttribute('part', 'file');
+
+        const name = doc.createElement('span');
+        name.className = 'file-name';
+        // textContent, not innerHTML: file names are attacker-controlled.
+        name.textContent = file.name;
+
+        const size = doc.createElement('span');
+        size.className = 'file-size';
+        size.textContent = formatBytes(file.size);
+
+        const remove = doc.createElement('button');
+        remove.type = 'button';
+        remove.className = 'remove';
+        remove.setAttribute('data-index', String(index));
+        remove.setAttribute('aria-label', `${t('fileUpload.remove')}: ${file.name}`);
+        remove.textContent = '×';
+
+        item.append(name, size, remove);
+        list.appendChild(item);
+      }
+      const status = self.shadowRoot?.querySelector('.status');
+      if (status) {
+        status.textContent =
+          local.files.length > 0
+            ? t('fileUpload.selected', { count: local.files.length })
+            : '';
+      }
+    };
+
+    const accept = (incoming: File[]) => {
+      const acceptList = self.getAttribute('accept') ?? '';
+      const maxSize = Number(self.getAttribute('max-size') ?? '0');
+      const multiple = self.hasAttribute('multiple');
+
+      const accepted: File[] = [];
+      const rejected: { file: File; reason: string }[] = [];
+      for (const file of incoming) {
+        if (!matchesAccept(file, acceptList)) {
+          rejected.push({ file, reason: 'accept' });
+        } else if (maxSize > 0 && file.size > maxSize) {
+          rejected.push({ file, reason: 'max-size' });
+        } else {
+          accepted.push(file);
+        }
+      }
+
+      local.files = multiple
+        ? [...local.files, ...accepted]
+        : accepted.slice(0, 1);
+      renderFiles();
+
+      if (rejected.length > 0) {
+        self.dispatchEvent(
+          new CustomEvent('bq-rejected', {
+            detail: { files: rejected },
+            bubbles: true,
+            composed: true,
+          })
+        );
+      }
+      if (accepted.length > 0) {
+        self.dispatchEvent(
+          new CustomEvent('bq-change', {
+            detail: { files: [...local.files] },
+            bubbles: true,
+            composed: true,
+          })
+        );
+      }
+    };
+
+    scope.on(self.shadowRoot, 'click', (e) => {
+      const target = e.target as Element;
+      const remove = target.closest('.remove') as HTMLElement | null;
+      if (remove) {
+        const index = Number(remove.getAttribute('data-index') ?? '-1');
+        if (index < 0 || index >= local.files.length) return;
+        local.files = local.files.filter((_, i) => i !== index);
+        renderFiles();
+        self.dispatchEvent(
+          new CustomEvent('bq-change', {
+            detail: { files: [...local.files] },
+            bubbles: true,
+            composed: true,
+          })
+        );
+        return;
+      }
+      if (target.closest('.zone') && !self.hasAttribute('disabled')) {
+        input()?.click();
+      }
+    });
+
+    scope.on(self.shadowRoot, 'change', (e) => {
+      const field = e.target as HTMLInputElement | null;
+      if (!field || field.type !== 'file') return;
+      accept(Array.from(field.files ?? []));
+      // Reset so re-picking the same file still fires `change`.
+      field.value = '';
+    });
+
+    const setDragging = (dragging: boolean) => {
+      if (dragging) self.setAttribute('data-dragging', '');
+      else self.removeAttribute('data-dragging');
+    };
+
+    scope.on(self, 'dragover', (e) => {
+      if (self.hasAttribute('disabled')) return;
+      e.preventDefault();
+      setDragging(true);
+    });
+    scope.on(self, 'dragleave', (e) => {
+      // Ignore the dragleave fired when moving between descendants.
+      const related = (e as DragEvent).relatedTarget as Node | null;
+      if (related && self.contains(related)) return;
+      setDragging(false);
+    });
+    scope.on(self, 'drop', (e) => {
+      if (self.hasAttribute('disabled')) return;
+      e.preventDefault();
+      setDragging(false);
+      const dropped = (e as DragEvent).dataTransfer?.files;
+      if (dropped && dropped.length > 0) accept(Array.from(dropped));
+    });
+
+    // The list lives in the shadow root, which every re-render replaces, so
+    // `updated()` has to paint it again from the retained selection.
+    local.renderFiles = renderFiles;
+
+    scope.add(() => {
+      local.files = [];
+      delete local.renderFiles;
+    });
+    scope.frame(renderFiles);
+  },
+  disconnected() {
+    release(this);
+  },
+  updated() {
+    uploadStore(this).renderFiles?.();
+  },
+  render({ props, state }) {
+    const uid = state.uid || 'bq-upload';
+    const inputId = `${uid}-input`;
+    const hintId = `${uid}-hint`;
+    const errorId = `${uid}-error`;
+    const describedBy = [props.hint ? hintId : '', props.error ? errorId : '']
+      .filter(Boolean)
+      .join(' ');
+
+    return html`
+      <div class="field" part="field">
+        ${
+          props.label
+            ? `<label class="label" part="label" for="${escapeHtml(inputId)}">${escapeHtml(props.label)}</label>`
+            : ''
+        }
+        <input
+          id="${escapeHtml(inputId)}"
+          type="file"
+          part="input"
+          tabindex="-1"
+          aria-hidden="true"
+          ${props.accept ? `accept="${escapeHtml(props.accept)}"` : ''}
+          ${bool('multiple', props.multiple)}
+          ${bool('disabled', props.disabled)}
+          ${props.name ? `name="${escapeHtml(props.name)}"` : ''}
+        />
+        <button
+          type="button"
+          class="zone"
+          part="zone"
+          ${bool('disabled', props.disabled)}
+          ${props.error ? 'aria-invalid="true"' : ''}
+          ${describedBy ? `aria-describedby="${escapeHtml(describedBy)}"` : ''}
+        >
+          <span class="icon" part="icon"><slot name="icon"></slot></span>
+          <span
+            >${escapeHtml(t('fileUpload.hint'))}
+            <span class="browse">${escapeHtml(t('fileUpload.browse'))}</span></span
+          >
+        </button>
+        <ul class="files" part="files"></ul>
+        <span class="sr-only status" role="status" aria-live="polite"></span>
+        ${
+          props.error
+            ? `<p class="message error" part="error" id="${escapeHtml(errorId)}" role="alert">${escapeHtml(props.error)}</p>`
+            : props.hint
+              ? `<p class="message hint" part="hint" id="${escapeHtml(hintId)}">${escapeHtml(props.hint)}</p>`
+              : ''
+        }
+      </div>
+    `;
+  },
+};
+
+component<BqFileUploadProps, BqFileUploadState>('bq-file-upload', definition);
diff --git a/src/components/file-upload/index.ts b/src/components/file-upload/index.ts
new file mode 100644
index 0000000..b37c96a
--- /dev/null
+++ b/src/components/file-upload/index.ts
@@ -0,0 +1 @@
+export * as __bqComponentEntry from './BqFileUpload.js';
diff --git a/src/components/icon-button/BqIconButton.ts b/src/components/icon-button/BqIconButton.ts
index 97c369a..87b1a00 100644
--- a/src/components/icon-button/BqIconButton.ts
+++ b/src/components/icon-button/BqIconButton.ts
@@ -11,12 +11,12 @@
  * @slot - Icon content
  * @fires bq-click
  */
-import { bool, component, html } from '@bquery/bquery/component';
+import { bool, component, css, html } from '@bquery/bquery/component';
 import type { ComponentDefinition } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { t } from '../../i18n/index.js';
 import { uniqueId } from '../../utils/dom.js';
-import { getBaseStyles } from '../../utils/styles.js';
+import { baseStyles } from '../../utils/styles.js';
 
 type BqIconButtonProps = {
   variant: string; size: string; disabled: boolean; loading: boolean;
@@ -37,8 +37,8 @@ const definition: ComponentDefinition<BqIconButtonProps, BqIconButtonState> = {
   state: {
     statusId: '',
   },
-  styles: `
-    ${getBaseStyles()}
+  styles: css`
+    ${baseStyles}
     *, *::before, *::after { box-sizing: border-box; }
     :host { display: inline-block; }
     .btn {
diff --git a/src/components/index.ts b/src/components/index.ts
index 8f64d0e..9fc196f 100644
--- a/src/components/index.ts
+++ b/src/components/index.ts
@@ -4,9 +4,12 @@
 import './accordion/BqAccordion.js';
 import './alert/BqAlert.js';
 import './avatar/BqAvatar.js';
+import './avatar-group/BqAvatarGroup.js';
 import './badge/BqBadge.js';
+import './banner/BqBanner.js';
 import './breadcrumbs/BqBreadcrumbs.js';
 import './button/BqButton.js';
+import './button-group/BqButtonGroup.js';
 import './card/BqCard.js';
 import './checkbox/BqCheckbox.js';
 import './chip/BqChip.js';
@@ -15,21 +18,28 @@ import './divider/BqDivider.js';
 import './dropdown-menu/BqDropdownMenu.js';
 import './drawer/BqDrawer.js';
 import './empty-state/BqEmptyState.js';
+import './file-upload/BqFileUpload.js';
 import './icon-button/BqIconButton.js';
 import './input/BqInput.js';
+import './kbd/BqKbd.js';
+import './number-input/BqNumberInput.js';
 import './pagination/BqPagination.js';
+import './popover/BqPopover.js';
 import './progress/BqProgress.js';
 import './radio/BqRadio.js';
+import './rating/BqRating.js';
 import './select/BqSelect.js';
 import './segmented-control/BqSegmentedControl.js';
 import './skeleton/BqSkeleton.js';
 import './slider/BqSlider.js';
 import './spinner/BqSpinner.js';
+import './stepper/BqStepper.js';
 import './stat-card/BqStatCard.js';
 import './switch/BqSwitch.js';
 import './table/BqTable.js';
 import './tabs/BqTabs.js';
 import './textarea/BqTextarea.js';
+import './timeline/BqTimeline.js';
 import './toast/index.js';
 import './tooltip/BqTooltip.js';
 
diff --git a/src/components/input/BqInput.ts b/src/components/input/BqInput.ts
index 79eb277..82c6a32 100644
--- a/src/components/input/BqInput.ts
+++ b/src/components/input/BqInput.ts
@@ -22,12 +22,12 @@
  * @fires bq-blur
  */
 import type { ComponentDefinition } from '@bquery/bquery/component';
-import { bool, component, html } from '@bquery/bquery/component';
+import { bool, component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { t } from '../../i18n/index.js';
 import { uniqueId } from '../../utils/dom.js';
 import { createFormProxy, type FormProxy } from '../../utils/form.js';
-import { getBaseStyles } from '../../utils/styles.js';
+import { baseStyles } from '../../utils/styles.js';
 
 type BqInputProps = {
   label: string;
@@ -70,8 +70,8 @@ const definition: ComponentDefinition<BqInputProps, BqInputState> = {
     uid: '',
     passwordVisible: false,
   },
-  styles: `
-    ${getBaseStyles()}
+  styles: css`
+    ${baseStyles}
     *, *::before, *::after { box-sizing: border-box; }
     :host { display: block; }
     .field { display: flex; flex-direction: column; gap: 0.375rem; }
diff --git a/src/components/kbd/BqKbd.ts b/src/components/kbd/BqKbd.ts
new file mode 100644
index 0000000..7e4321b
--- /dev/null
+++ b/src/components/kbd/BqKbd.ts
@@ -0,0 +1,104 @@
+/**
+ * Keyboard key component — renders a keystroke or key combination.
+ * @element bq-kbd
+ * @prop {string}  keys    - Combination such as "Ctrl+Shift+K"; overrides slotted content
+ * @prop {string}  size    - sm | md | lg
+ * @prop {string}  variant - solid | outline
+ * @slot - Key content, used when `keys` is not set
+ */
+import { component, css, html } from '@bquery/bquery/component';
+import type { ComponentDefinition } from '@bquery/bquery/component';
+import { escapeHtml } from '@bquery/bquery/security';
+import { baseStyles, reset } from '../../utils/styles.js';
+
+type BqKbdProps = { keys: string; size: string; variant: string };
+
+/** Symbols shown instead of the written-out key name. */
+const KEY_SYMBOLS: Record<string, string> = {
+  cmd: '⌘',
+  command: '⌘',
+  meta: '⌘',
+  ctrl: 'Ctrl',
+  control: 'Ctrl',
+  alt: 'Alt',
+  option: '⌥',
+  shift: '⇧',
+  enter: '↵',
+  return: '↵',
+  backspace: '⌫',
+  delete: '⌦',
+  escape: 'Esc',
+  esc: 'Esc',
+  tab: '⇥',
+  up: '↑',
+  down: '↓',
+  left: '←',
+  right: '→',
+  space: 'Space',
+};
+
+/** Splits "Ctrl+Shift+K" into display-ready key names. */
+export function parseKeys(keys: string): string[] {
+  return keys
+    .split('+')
+    .map((key) => key.trim())
+    .filter(Boolean)
+    .map((key) => KEY_SYMBOLS[key.toLowerCase()] ?? key);
+}
+
+const definition: ComponentDefinition<BqKbdProps> = {
+  props: {
+    keys: { type: String, default: '' },
+    size: { type: String, default: 'md' },
+    variant: { type: String, default: 'solid' },
+  },
+  styles: css`
+    ${baseStyles}
+    ${reset}
+    :host { display: inline-flex; }
+    .kbd {
+      display: inline-flex; align-items: center; gap: 0.25rem;
+      font-family: var(--bq-font-family-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
+      color: var(--bq-text-base,#0f172a);
+      line-height: 1;
+    }
+    .key {
+      display: inline-flex; align-items: center; justify-content: center;
+      border-radius: var(--bq-radius-md,0.375rem);
+      font-weight: var(--bq-font-weight-medium,500);
+      white-space: nowrap;
+    }
+    .sep { color: var(--bq-text-subtle,#94a3b8); }
+    .kbd[data-size="sm"] .key { font-size: 0.6875rem; min-width: 1.25rem; height: 1.25rem; padding: 0 0.3rem; }
+    .kbd[data-size="md"] .key { font-size: 0.75rem;   min-width: 1.5rem;  height: 1.5rem;  padding: 0 0.4rem; }
+    .kbd[data-size="lg"] .key { font-size: 0.875rem;  min-width: 1.75rem; height: 1.75rem; padding: 0 0.5rem; }
+    .kbd[data-variant="solid"] .key {
+      background: var(--bq-bg-muted,#f1f5f9);
+      border: 1px solid var(--bq-border-emphasis,#cbd5e1);
+      border-bottom-width: 2px;
+    }
+    .kbd[data-variant="outline"] .key {
+      background: transparent;
+      border: 1px solid var(--bq-border-emphasis,#cbd5e1);
+    }
+  `,
+  render({ props }) {
+    const keys = parseKeys(props.keys);
+    const body =
+      keys.length > 0
+        ? keys
+            .map((key) => `<kbd class="key" part="key">${escapeHtml(key)}</kbd>`)
+            .join('<span class="sep" aria-hidden="true">+</span>')
+        : '<kbd class="key" part="key"><slot></slot></kbd>';
+    return html`
+      <span
+        part="kbd"
+        class="kbd"
+        data-size="${escapeHtml(props.size)}"
+        data-variant="${escapeHtml(props.variant)}"
+      >${body}</span>
+    `;
+  },
+};
+
+component<BqKbdProps>('bq-kbd', definition);
diff --git a/src/components/kbd/index.ts b/src/components/kbd/index.ts
new file mode 100644
index 0000000..6d58af8
--- /dev/null
+++ b/src/components/kbd/index.ts
@@ -0,0 +1 @@
+export * as __bqComponentEntry from './BqKbd.js';
diff --git a/src/components/number-input/BqNumberInput.ts b/src/components/number-input/BqNumberInput.ts
new file mode 100644
index 0000000..6f00471
--- /dev/null
+++ b/src/components/number-input/BqNumberInput.ts
@@ -0,0 +1,346 @@
+/**
+ * Number input component — numeric field with stepper buttons.
+ * @element bq-number-input
+ * @prop {number}  value
+ * @prop {number}  min
+ * @prop {number}  max
+ * @prop {number}  step
+ * @prop {number}  precision - Decimal places to display (-1 = derive from step)
+ * @prop {string}  label
+ * @prop {string}  placeholder
+ * @prop {string}  name      - Form field name
+ * @prop {string}  size      - sm | md | lg
+ * @prop {boolean} disabled
+ * @prop {boolean} readonly
+ * @prop {boolean} required
+ * @prop {string}  error     - Error message; marks the field invalid
+ * @prop {string}  hint      - Helper text
+ * @slot prefix - Content before the field (e.g. a currency symbol)
+ * @slot suffix - Content after the field (e.g. a unit)
+ * @fires bq-input  - { value: number }
+ * @fires bq-change - { value: number }
+ */
+import { bool, component, css, html } from '@bquery/bquery/component';
+import type { ComponentDefinition } from '@bquery/bquery/component';
+import { escapeHtml } from '@bquery/bquery/security';
+import { t } from '../../i18n/index.js';
+import { bind, host, release, store } from '../../utils/component.js';
+import { uniqueId } from '../../utils/dom.js';
+import { createFormProxy, type FormProxy } from '../../utils/form.js';
+import { baseStyles, reset, srOnly } from '../../utils/styles.js';
+
+type BqNumberInputProps = {
+  value: number;
+  min: number;
+  max: number;
+  step: number;
+  precision: number;
+  label: string;
+  placeholder: string;
+  name: string;
+  size: string;
+  disabled: boolean;
+  readonly: boolean;
+  required: boolean;
+  error: string;
+  hint: string;
+};
+type BqNumberInputState = { uid: string };
+
+const inputStore = (owner: object) =>
+  store<{ proxy?: FormProxy }>(owner, () => ({}));
+
+/** Decimal places implied by `step`, so 0.1 + 0.2 does not surface as 0.30000000000000004. */
+export function precisionFor(step: number, explicit: number): number {
+  if (explicit >= 0) return Math.trunc(explicit);
+  if (!Number.isFinite(step)) return 0;
+  const text = String(step);
+  const dot = text.indexOf('.');
+  return dot < 0 ? 0 : text.length - dot - 1;
+}
+
+/** Clamps to `[min, max]` and snaps to the nearest `step` offset from `min`. */
+export function normalizeNumber(
+  raw: number,
+  min: number,
+  max: number,
+  step: number,
+  precision: number
+): number {
+  if (!Number.isFinite(raw)) return Number.isFinite(min) ? min : 0;
+  let value = raw;
+  if (Number.isFinite(step) && step > 0) {
+    const origin = Number.isFinite(min) ? min : 0;
+    value = origin + Math.round((value - origin) / step) * step;
+  }
+  if (Number.isFinite(min)) value = Math.max(value, min);
+  if (Number.isFinite(max)) value = Math.min(value, max);
+  return Number(value.toFixed(precision));
+}
+
+const definition: ComponentDefinition<BqNumberInputProps, BqNumberInputState> = {
+  // `inputmode` is outside the framework's base allowlist; it is a fixed
+  // literal here, not user input.
+  sanitize: { allowAttributes: ['inputmode'] },
+  props: {
+    value: { type: Number, default: 0 },
+    min: { type: Number, default: Number.NEGATIVE_INFINITY },
+    max: { type: Number, default: Number.POSITIVE_INFINITY },
+    step: { type: Number, default: 1 },
+    precision: { type: Number, default: -1 },
+    label: { type: String, default: '' },
+    placeholder: { type: String, default: '' },
+    name: { type: String, default: '' },
+    size: { type: String, default: 'md' },
+    disabled: { type: Boolean, default: false },
+    readonly: { type: Boolean, default: false },
+    required: { type: Boolean, default: false },
+    error: { type: String, default: '' },
+    hint: { type: String, default: '' },
+  },
+  state: {
+    uid: '',
+  },
+  styles: css`
+    ${baseStyles}
+    ${reset}
+    ${srOnly}
+    :host { display: block; }
+    .field { font-family: var(--bq-font-family-sans); }
+    .label {
+      display: block;
+      font-size: var(--bq-font-size-sm,0.875rem);
+      font-weight: var(--bq-font-weight-medium,500);
+      color: var(--bq-text-base,#0f172a);
+      margin-bottom: 0.375rem;
+    }
+    .required { color: var(--bq-color-danger-600,#dc2626); margin-left: 0.125rem; }
+    .control {
+      display: flex; align-items: stretch;
+      border: 1.5px solid var(--bq-border-emphasis,#cbd5e1);
+      border-radius: var(--bq-radius-lg,0.5rem);
+      background: var(--bq-bg-base,#fff);
+      overflow: hidden;
+      transition: border-color var(--bq-duration-fast) var(--bq-easing-standard),
+                  box-shadow var(--bq-duration-fast) var(--bq-easing-standard);
+    }
+    .control:focus-within { border-color: var(--bq-border-focus,#2563eb); box-shadow: var(--bq-focus-ring); }
+    :host([error]) .control { border-color: var(--bq-color-danger-600,#dc2626); }
+    :host([error]) .control:focus-within { box-shadow: var(--bq-focus-ring-danger); }
+    :host([disabled]) .control { opacity: 0.55; background: var(--bq-bg-muted,#f1f5f9); }
+
+    input {
+      flex: 1 1 auto; min-width: 0; width: 100%;
+      border: none; outline: none; background: transparent;
+      font-family: inherit; color: var(--bq-text-base,#0f172a);
+      text-align: var(--bq-number-input-align, left);
+      /* The custom stepper replaces the native one. */
+      -moz-appearance: textfield; appearance: textfield;
+    }
+    input::-webkit-outer-spin-button, input::-webkit-inner-spin-button {
+      -webkit-appearance: none; margin: 0;
+    }
+    .control[data-size="sm"] input { font-size: 0.875rem; padding: 0.375rem 0.625rem; }
+    .control[data-size="md"] input { font-size: 1rem;     padding: 0.5rem 0.75rem; }
+    .control[data-size="lg"] input { font-size: 1.125rem; padding: 0.625rem 0.875rem; }
+
+    .step {
+      display: inline-flex; align-items: center; justify-content: center;
+      width: 2rem; flex: 0 0 auto;
+      border: none; background: var(--bq-bg-subtle,#f8fafc);
+      color: var(--bq-text-muted,#475569);
+      cursor: pointer; font-size: 1rem; line-height: 1;
+      transition: background-color var(--bq-duration-fast) var(--bq-easing-standard);
+    }
+    .step:hover:not(:disabled) { background: var(--bq-bg-emphasis,#e2e8f0); color: var(--bq-text-base,#0f172a); }
+    .step:disabled { opacity: 0.4; cursor: not-allowed; }
+    .step:focus-visible { outline: 2px solid transparent; box-shadow: var(--bq-focus-ring); z-index: 1; }
+    .step[data-action="decrement"] { border-right: 1px solid var(--bq-border-base,#e2e8f0); }
+    .step[data-action="increment"] { border-left: 1px solid var(--bq-border-base,#e2e8f0); }
+
+    .affix { display: inline-flex; align-items: center; padding: 0 0.5rem; color: var(--bq-text-subtle,#94a3b8); }
+    .message { font-size: var(--bq-font-size-xs,0.75rem); margin-top: 0.375rem; }
+    .hint  { color: var(--bq-text-subtle,#94a3b8); }
+    .error { color: var(--bq-color-danger-600,#dc2626); }
+    @media (prefers-reduced-motion: reduce) {
+      .control, .step { transition: none; }
+    }
+  `,
+  connected() {
+    const self = host<BqNumberInputState>(this);
+    const scope = bind(self);
+    const local = inputStore(self);
+    if (!self.getState<string>('uid')) self.setState('uid', uniqueId('bq-number'));
+
+    const numAttr = (name: string, fallback: number): number => {
+      const raw = self.getAttribute(name);
+      if (raw === null || raw.trim() === '') return fallback;
+      const parsed = Number(raw);
+      return Number.isFinite(parsed) ? parsed : fallback;
+    };
+    const readSettings = () => {
+      const step = numAttr('step', 1);
+      return {
+        min: numAttr('min', Number.NEGATIVE_INFINITY),
+        max: numAttr('max', Number.POSITIVE_INFINITY),
+        step,
+        precision: precisionFor(step, numAttr('precision', -1)),
+      };
+    };
+    const readValue = (): number => {
+      const { min, max, step, precision } = readSettings();
+      return normalizeNumber(numAttr('value', 0), min, max, step, precision);
+    };
+
+    const name = self.getAttribute('name') ?? '';
+    if (name) {
+      local.proxy = createFormProxy(
+        self,
+        name,
+        String(readValue()),
+        self.hasAttribute('disabled'),
+        { getLiveValue: () => String(readValue()) }
+      );
+      scope.add(() => {
+        local.proxy?.cleanup();
+        delete local.proxy;
+      });
+    }
+
+    const commit = (next: number, eventName: 'bq-input' | 'bq-change') => {
+      if (self.hasAttribute('disabled') || self.hasAttribute('readonly')) return;
+      const { min, max, step, precision } = readSettings();
+      const value = normalizeNumber(next, min, max, step, precision);
+      self.setAttribute('value', String(value));
+      local.proxy?.setValue(String(value));
+      self.dispatchEvent(
+        new CustomEvent(eventName, {
+          detail: { value },
+          bubbles: true,
+          composed: true,
+        })
+      );
+    };
+
+    scope.on(self.shadowRoot, 'click', (e) => {
+      const button = (e.target as Element).closest(
+        '.step'
+      ) as HTMLButtonElement | null;
+      if (!button || button.disabled) return;
+      const { step } = readSettings();
+      const delta = button.getAttribute('data-action') === 'increment' ? step : -step;
+      commit(readValue() + delta, 'bq-change');
+    });
+
+    // Typing must not fight the user: the raw field value is only normalized
+    // on commit (change/blur), not on every keystroke.
+    scope.on(self.shadowRoot, 'input', (e) => {
+      const input = e.target as HTMLInputElement | null;
+      if (!input || input.type !== 'number') return;
+      const raw = Number(input.value);
+      if (!Number.isFinite(raw)) return;
+      self.dispatchEvent(
+        new CustomEvent('bq-input', {
+          detail: { value: raw },
+          bubbles: true,
+          composed: true,
+        })
+      );
+      local.proxy?.setValue(input.value);
+    });
+
+    scope.on(self.shadowRoot, 'change', (e) => {
+      const input = e.target as HTMLInputElement | null;
+      if (!input || input.type !== 'number') return;
+      commit(Number(input.value), 'bq-change');
+    });
+  },
+  disconnected() {
+    release(this);
+  },
+  updated() {
+    const self = host<BqNumberInputState>(this);
+    const local = inputStore(self);
+    local.proxy?.setDisabled(self.hasAttribute('disabled'));
+  },
+  render({ props, state }) {
+    const uid = state.uid || 'bq-number';
+    const inputId = `${uid}-input`;
+    const hintId = `${uid}-hint`;
+    const errorId = `${uid}-error`;
+    const precision = precisionFor(props.step, props.precision);
+    const value = normalizeNumber(
+      props.value,
+      props.min,
+      props.max,
+      props.step,
+      precision
+    );
+    const atMin = Number.isFinite(props.min) && value <= props.min;
+    const atMax = Number.isFinite(props.max) && value >= props.max;
+    const locked = props.disabled || props.readonly;
+    const describedBy = [props.hint ? hintId : '', props.error ? errorId : '']
+      .filter(Boolean)
+      .join(' ');
+
+    return html`
+      <div class="field" part="field">
+        ${
+          props.label
+            ? `<label class="label" part="label" for="${escapeHtml(inputId)}">${escapeHtml(props.label)}${props.required ? '<span class="required" aria-hidden="true">*</span>' : ''}</label>`
+            : ''
+        }
+        <div class="control" part="control" data-size="${escapeHtml(props.size)}">
+          <button
+            type="button"
+            class="step"
+            part="decrement"
+            data-action="decrement"
+            aria-label="${escapeHtml(t('numberInput.decrement'))}"
+            ${bool('disabled', locked || atMin)}
+            tabindex="-1"
+          >&minus;</button>
+          <span class="affix"><slot name="prefix"></slot></span>
+          <input
+            id="${escapeHtml(inputId)}"
+            part="input"
+            type="number"
+            inputmode="decimal"
+            value="${escapeHtml(String(value))}"
+            ${Number.isFinite(props.min) ? `min="${escapeHtml(String(props.min))}"` : ''}
+            ${Number.isFinite(props.max) ? `max="${escapeHtml(String(props.max))}"` : ''}
+            step="${escapeHtml(String(props.step))}"
+            ${props.placeholder ? `placeholder="${escapeHtml(props.placeholder)}"` : ''}
+            ${bool('disabled', props.disabled)}
+            ${bool('readonly', props.readonly)}
+            ${bool('required', props.required)}
+            ${props.error ? 'aria-invalid="true"' : ''}
+            ${describedBy ? `aria-describedby="${escapeHtml(describedBy)}"` : ''}
+          />
+          <span class="affix"><slot name="suffix"></slot></span>
+          <button
+            type="button"
+            class="step"
+            part="increment"
+            data-action="increment"
+            aria-label="${escapeHtml(t('numberInput.increment'))}"
+            ${bool('disabled', locked || atMax)}
+            tabindex="-1"
+          >&plus;</button>
+        </div>
+        ${
+          props.error
+            ? `<p class="message error" part="error" id="${escapeHtml(errorId)}" role="alert">${escapeHtml(props.error)}</p>`
+            : props.hint
+              ? `<p class="message hint" part="hint" id="${escapeHtml(hintId)}">${escapeHtml(props.hint)}</p>`
+              : ''
+        }
+      </div>
+    `;
+  },
+};
+
+component<BqNumberInputProps, BqNumberInputState>(
+  'bq-number-input',
+  definition
+);
diff --git a/src/components/number-input/index.ts b/src/components/number-input/index.ts
new file mode 100644
index 0000000..5b27bb9
--- /dev/null
+++ b/src/components/number-input/index.ts
@@ -0,0 +1 @@
+export * as __bqComponentEntry from './BqNumberInput.js';
diff --git a/src/components/pagination/BqPagination.ts b/src/components/pagination/BqPagination.ts
index 31e889a..d79563b 100644
--- a/src/components/pagination/BqPagination.ts
+++ b/src/components/pagination/BqPagination.ts
@@ -9,9 +9,10 @@
  * @fires bq-page-change - { page: number }
  */
 import type { ComponentDefinition } from '@bquery/bquery/component';
-import { bool, component, html } from '@bquery/bquery/component';
+import { bool, component, css, html } from '@bquery/bquery/component';
 import { t } from '../../i18n/index.js';
-import { getBaseStyles } from '../../utils/styles.js';
+import { host } from '../../utils/component.js';
+import { baseStyles } from '../../utils/styles.js';
 
 type BqPaginationProps = {
   page: number;
@@ -50,8 +51,8 @@ const definition: ComponentDefinition<BqPaginationProps> = {
     'show-first-last': { type: Boolean, default: false },
     disabled: { type: Boolean, default: false },
   },
-  styles: `
-    ${getBaseStyles()}
+  styles: css`
+    ${baseStyles}
     *, *::before, *::after { box-sizing: border-box; }
     :host { display: block; }
     .pagination { display: flex; align-items: center; gap: 0.25rem; flex-wrap: wrap; font-family: var(--bq-font-family-sans); }
@@ -76,7 +77,7 @@ const definition: ComponentDefinition<BqPaginationProps> = {
     }
   `,
   connected() {
-    const self = this;
+    const self = host(this);
     const handler = (e: Event) => {
       const btn = (e.target as Element).closest(
         '.page-btn'
diff --git a/src/components/popover/BqPopover.ts b/src/components/popover/BqPopover.ts
new file mode 100644
index 0000000..2b6fd3b
--- /dev/null
+++ b/src/components/popover/BqPopover.ts
@@ -0,0 +1,242 @@
+/**
+ * Popover component — rich anchored overlay opened from a trigger.
+ *
+ * Unlike Tooltip (hover, text only) a popover holds interactive content and
+ * opens on click, so it manages focus and closes on Escape or outside click.
+ *
+ * @element bq-popover
+ * @prop {boolean} open
+ * @prop {string}  placement   - top | bottom | left | right (with -start/-end suffixes)
+ * @prop {string}  heading     - Optional popover title
+ * @prop {boolean} dismissible - Show a close button
+ * @prop {boolean} arrow       - Render a pointer arrow
+ * @slot trigger - Element that toggles the popover
+ * @slot         - Popover content
+ * @slot footer  - Footer actions
+ * @fires bq-open
+ * @fires bq-close
+ */
+import { component, css, html } from '@bquery/bquery/component';
+import type { ComponentDefinition } from '@bquery/bquery/component';
+import { escapeHtml } from '@bquery/bquery/security';
+import { t } from '../../i18n/index.js';
+import type { Disposer } from '../../utils/component.js';
+import { bind, host, release, store } from '../../utils/component.js';
+import { uniqueId } from '../../utils/dom.js';
+import { baseStyles, reset } from '../../utils/styles.js';
+
+type BqPopoverProps = {
+  open: boolean;
+  placement: string;
+  heading: string;
+  dismissible: boolean;
+  arrow: boolean;
+};
+type BqPopoverState = { uid: string };
+
+const popoverStore = (owner: object) =>
+  store<{ sync?: () => void }>(owner, () => ({}));
+
+const definition: ComponentDefinition<BqPopoverProps, BqPopoverState> = {
+  props: {
+    open: { type: Boolean, default: false },
+    placement: { type: String, default: 'bottom' },
+    heading: { type: String, default: '' },
+    dismissible: { type: Boolean, default: true },
+    arrow: { type: Boolean, default: true },
+  },
+  state: {
+    uid: '',
+  },
+  styles: css`
+    ${baseStyles}
+    ${reset}
+    :host { display: inline-block; position: relative; }
+    .panel {
+      position: absolute; z-index: var(--bq-z-popover, 1100);
+      min-width: 12rem; max-width: min(20rem, 90vw);
+      background: var(--bq-bg-base,#fff);
+      color: var(--bq-text-base,#0f172a);
+      border: 1px solid var(--bq-border-base,#e2e8f0);
+      border-radius: var(--bq-radius-lg,0.5rem);
+      box-shadow: var(--bq-shadow-lg, 0 10px 15px -3px rgba(0,0,0,0.1));
+      font-family: var(--bq-font-family-sans);
+      font-size: var(--bq-font-size-sm,0.875rem);
+      opacity: 0; visibility: hidden;
+      transition: opacity var(--bq-duration-fast) var(--bq-easing-standard),
+                  visibility var(--bq-duration-fast) var(--bq-easing-standard);
+    }
+    :host([open]) .panel { opacity: 1; visibility: visible; }
+
+    .panel[data-placement^="bottom"] { top: calc(100% + 8px); }
+    .panel[data-placement^="top"]    { bottom: calc(100% + 8px); }
+    .panel[data-placement^="left"]   { right: calc(100% + 8px); top: 0; }
+    .panel[data-placement^="right"]  { left: calc(100% + 8px); top: 0; }
+    .panel[data-placement="bottom"], .panel[data-placement="top"] { left: 50%; transform: translateX(-50%); }
+    .panel[data-placement$="-start"] { left: 0; transform: none; }
+    .panel[data-placement$="-end"]   { right: 0; left: auto; transform: none; }
+
+    .header {
+      display: flex; align-items: flex-start; gap: 0.5rem;
+      padding: 0.75rem 0.875rem 0;
+    }
+    .heading {
+      flex: 1 1 auto; margin: 0;
+      font-size: var(--bq-font-size-sm,0.875rem);
+      font-weight: var(--bq-font-weight-semibold,600);
+    }
+    .close {
+      flex: 0 0 auto;
+      display: inline-flex; align-items: center; justify-content: center;
+      width: 1.5rem; height: 1.5rem;
+      border: none; border-radius: var(--bq-radius-md,0.375rem);
+      background: transparent; color: var(--bq-text-muted,#475569);
+      cursor: pointer; font-size: 1rem; line-height: 1;
+    }
+    .close:hover { background: var(--bq-bg-muted,#f1f5f9); color: var(--bq-text-base,#0f172a); }
+    .close:focus-visible { outline: 2px solid transparent; box-shadow: var(--bq-focus-ring); }
+    .content { padding: 0.75rem 0.875rem; color: var(--bq-text-muted,#475569); }
+    .header + .content { padding-top: 0.5rem; }
+    .footer { padding: 0 0.875rem 0.75rem; display: flex; justify-content: flex-end; gap: 0.5rem; }
+
+    .arrow {
+      position: absolute; width: 0.5rem; height: 0.5rem;
+      background: var(--bq-bg-base,#fff);
+      border: 1px solid var(--bq-border-base,#e2e8f0);
+      transform: rotate(45deg);
+    }
+    .panel[data-placement^="bottom"] .arrow { top: -5px; left: 50%; margin-left: -0.25rem; border-right: none; border-bottom: none; }
+    .panel[data-placement^="top"]    .arrow { bottom: -5px; left: 50%; margin-left: -0.25rem; border-left: none; border-top: none; }
+    .panel[data-placement^="left"]   .arrow { right: -5px; top: 0.75rem; border-left: none; border-bottom: none; }
+    .panel[data-placement^="right"]  .arrow { left: -5px; top: 0.75rem; border-right: none; border-top: none; }
+    .panel[data-placement$="-start"] .arrow { left: 1rem; margin-left: 0; }
+    .panel[data-placement$="-end"]   .arrow { left: auto; right: 1rem; margin-left: 0; }
+
+    @media (prefers-reduced-motion: reduce) {
+      .panel { transition: none; }
+    }
+  `,
+  connected() {
+    const self = host<BqPopoverState>(this);
+    const scope = bind(self);
+    const local = popoverStore(self);
+    if (!self.getState<string>('uid')) self.setState('uid', uniqueId('bq-popover'));
+
+    const getTrigger = (): HTMLElement | null =>
+      self.querySelector('[slot="trigger"]');
+
+    const open = () => {
+      if (self.hasAttribute('open')) return;
+      self.setAttribute('open', '');
+      self.dispatchEvent(
+        new CustomEvent('bq-open', { bubbles: true, composed: true })
+      );
+      scope.frame(() => {
+        if (!self.hasAttribute('open')) return;
+        const panel = self.shadowRoot?.querySelector('.panel');
+        const focusable = panel?.querySelector<HTMLElement>(
+          'button, a[href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+        );
+        focusable?.focus();
+      });
+    };
+
+    const close = ({ restoreFocus = false } = {}) => {
+      if (!self.hasAttribute('open')) return;
+      self.removeAttribute('open');
+      self.dispatchEvent(
+        new CustomEvent('bq-close', { bubbles: true, composed: true })
+      );
+      if (restoreFocus) getTrigger()?.focus();
+    };
+
+    // The outside-click listener only exists while open; the scope owns its
+    // removal so a disconnect while open cannot strand it on `document`.
+    let stopOutside: Disposer | null = null;
+    const syncOutside = () => {
+      if (self.hasAttribute('open')) {
+        stopOutside ??= scope.on(document, 'click', (e) => {
+          if (!self.hasAttribute('open')) return;
+          if (!self.contains(e.target as Node)) close();
+        });
+        return;
+      }
+      stopOutside?.();
+      stopOutside = null;
+    };
+    local.sync = syncOutside;
+
+    scope.on(self, 'click', (e) => {
+      const trigger = getTrigger();
+      const target = e.target as Node;
+      if (!trigger || !(trigger === target || trigger.contains(target))) return;
+      e.preventDefault();
+      if (self.hasAttribute('open')) close({ restoreFocus: true });
+      else open();
+    });
+
+    scope.on(self.shadowRoot, 'click', (e) => {
+      if ((e.target as Element).closest('.close')) close({ restoreFocus: true });
+    });
+
+    scope.on(self, 'keydown', (e) => {
+      const ke = e as KeyboardEvent;
+      if (ke.key === 'Escape' && self.hasAttribute('open')) {
+        ke.preventDefault();
+        close({ restoreFocus: true });
+      }
+    });
+
+    scope.frame(syncOutside);
+  },
+  disconnected() {
+    release(this);
+  },
+  updated() {
+    const self = host<BqPopoverState>(this);
+    popoverStore(self).sync?.();
+    const trigger = self.querySelector('[slot="trigger"]');
+    if (!trigger) return;
+    trigger.setAttribute(
+      'aria-expanded',
+      self.hasAttribute('open') ? 'true' : 'false'
+    );
+    trigger.setAttribute('aria-haspopup', 'dialog');
+    trigger.setAttribute(
+      'aria-controls',
+      `${self.getState<string>('uid') || 'bq-popover'}-panel`
+    );
+  },
+  render({ props, state }) {
+    const uid = state.uid || 'bq-popover';
+    const panelId = `${uid}-panel`;
+    const headingId = `${uid}-heading`;
+    const heading = props.heading.trim();
+    return html`
+      <slot name="trigger"></slot>
+      <div
+        id="${escapeHtml(panelId)}"
+        part="panel"
+        class="panel"
+        role="dialog"
+        data-placement="${escapeHtml(props.placement)}"
+        aria-hidden="${props.open ? 'false' : 'true'}"
+        ${heading ? `aria-labelledby="${escapeHtml(headingId)}"` : ''}
+      >
+        ${props.arrow ? '<span class="arrow" part="arrow" aria-hidden="true"></span>' : ''}
+        ${
+          heading || props.dismissible
+            ? `<div class="header" part="header">
+                 ${heading ? `<h2 class="heading" part="heading" id="${escapeHtml(headingId)}">${escapeHtml(heading)}</h2>` : '<span class="heading"></span>'}
+                 ${props.dismissible ? `<button type="button" class="close" part="close" aria-label="${escapeHtml(t('popover.close'))}">&times;</button>` : ''}
+               </div>`
+            : ''
+        }
+        <div class="content" part="content"><slot></slot></div>
+        <div class="footer" part="footer"><slot name="footer"></slot></div>
+      </div>
+    `;
+  },
+};
+
+component<BqPopoverProps, BqPopoverState>('bq-popover', definition);
diff --git a/src/components/popover/index.ts b/src/components/popover/index.ts
new file mode 100644
index 0000000..60e4ee7
--- /dev/null
+++ b/src/components/popover/index.ts
@@ -0,0 +1 @@
+export * as __bqComponentEntry from './BqPopover.js';
diff --git a/src/components/progress/BqProgress.ts b/src/components/progress/BqProgress.ts
index bd87983..6333183 100644
--- a/src/components/progress/BqProgress.ts
+++ b/src/components/progress/BqProgress.ts
@@ -9,10 +9,10 @@
  * @prop {string}  label         - Accessible label
  */
 import type { ComponentDefinition } from '@bquery/bquery/component';
-import { component, html } from '@bquery/bquery/component';
+import { component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { t } from '../../i18n/index.js';
-import { getBaseStyles } from '../../utils/styles.js';
+import { baseStyles } from '../../utils/styles.js';
 
 type BqProgressProps = {
   value: number;
@@ -35,8 +35,8 @@ const definition: ComponentDefinition<BqProgressProps> = {
   sanitize: {
     allowAttributes: ['style'],
   },
-  styles: `
-    ${getBaseStyles()}
+  styles: css`
+    ${baseStyles}
     :host { display: block; }
     .track {
       background: var(--bq-bg-emphasis,#e2e8f0); border-radius: var(--bq-radius-full,9999px);
diff --git a/src/components/radio/BqRadio.ts b/src/components/radio/BqRadio.ts
index 88f47ff..ff58106 100644
--- a/src/components/radio/BqRadio.ts
+++ b/src/components/radio/BqRadio.ts
@@ -11,10 +11,11 @@
  * @fires bq-change - { value: string, checked: boolean }
  */
 import type { ComponentDefinition } from '@bquery/bquery/component';
-import { bool, component, html } from '@bquery/bquery/component';
+import { bool, component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { createFormProxy, type FormProxy } from '../../utils/form.js';
-import { getBaseStyles } from '../../utils/styles.js';
+import { host } from '../../utils/component.js';
+import { baseStyles } from '../../utils/styles.js';
 
 type BqRadioProps = {
   label: string;
@@ -36,8 +37,8 @@ const definition: ComponentDefinition<BqRadioProps> = {
     required: { type: Boolean, default: false },
     hint: { type: String, default: '' },
   },
-  styles: `
-    ${getBaseStyles()}
+  styles: css`
+    ${baseStyles}
     *, *::before, *::after { box-sizing: border-box; }
     :host { display: block; }
     .wrapper { display: flex; flex-direction: column; gap: 0.25rem; }
@@ -55,7 +56,7 @@ const definition: ComponentDefinition<BqRadioProps> = {
     .hint { font-size: var(--bq-font-size-sm,0.875rem); color: var(--bq-text-muted,#475569); font-family: var(--bq-font-family-sans); padding-inline-start: 1.75rem; }
   `,
   connected() {
-    const self = this;
+    const self = host(this);
 
     // Form proxy for native <form> participation
     const name = self.getAttribute('name') ?? '';
diff --git a/src/components/rating/BqRating.ts b/src/components/rating/BqRating.ts
new file mode 100644
index 0000000..41c3b83
--- /dev/null
+++ b/src/components/rating/BqRating.ts
@@ -0,0 +1,214 @@
+/**
+ * Rating component — star rating input.
+ * @element bq-rating
+ * @prop {number}  value     - Current rating
+ * @prop {number}  max       - Number of stars
+ * @prop {boolean} readonly  - Display only, not interactive
+ * @prop {boolean} disabled
+ * @prop {boolean} clearable - Re-selecting the current value clears it
+ * @prop {string}  size      - sm | md | lg
+ * @prop {string}  label     - Accessible label
+ * @prop {string}  name      - Form field name
+ * @fires bq-change - { value: number }
+ */
+import { component, css, html } from '@bquery/bquery/component';
+import type { ComponentDefinition } from '@bquery/bquery/component';
+import { escapeHtml } from '@bquery/bquery/security';
+import { t } from '../../i18n/index.js';
+import { bind, host, release, store } from '../../utils/component.js';
+import { createFormProxy, type FormProxy } from '../../utils/form.js';
+import { baseStyles, reset, srOnly } from '../../utils/styles.js';
+
+type BqRatingProps = {
+  value: number;
+  max: number;
+  readonly: boolean;
+  disabled: boolean;
+  clearable: boolean;
+  size: string;
+  label: string;
+  name: string;
+};
+
+const ratingStore = (owner: object) =>
+  store<{ proxy?: FormProxy }>(owner, () => ({}));
+
+/** Clamps a rating to `0..max`, treating anything unparseable as 0. */
+export function clampRating(value: number, max: number): number {
+  if (!Number.isFinite(value)) return 0;
+  return Math.min(Math.max(value, 0), Math.max(max, 0));
+}
+
+const definition: ComponentDefinition<BqRatingProps> = {
+  props: {
+    value: { type: Number, default: 0 },
+    max: { type: Number, default: 5 },
+    readonly: { type: Boolean, default: false },
+    disabled: { type: Boolean, default: false },
+    clearable: { type: Boolean, default: false },
+    size: { type: String, default: 'md' },
+    label: { type: String, default: '' },
+    name: { type: String, default: '' },
+  },
+  styles: css`
+    ${baseStyles}
+    ${reset}
+    ${srOnly}
+    :host { display: inline-flex; }
+    .rating {
+      display: inline-flex; align-items: center; gap: 0.125rem;
+      font-family: var(--bq-font-family-sans);
+    }
+    .star {
+      display: inline-flex; align-items: center; justify-content: center;
+      background: none; border: none; padding: 0.125rem; margin: 0;
+      color: var(--bq-border-emphasis,#cbd5e1);
+      cursor: pointer; line-height: 1;
+      transition: color var(--bq-duration-fast) var(--bq-easing-standard),
+                  transform var(--bq-duration-fast) var(--bq-easing-standard);
+    }
+    .star[data-filled="true"] { color: var(--bq-color-warning-500,#f59e0b); }
+    .rating[data-size="sm"] .star { font-size: 1rem; }
+    .rating[data-size="md"] .star { font-size: 1.375rem; }
+    .rating[data-size="lg"] .star { font-size: 1.75rem; }
+    .star:focus-visible { outline: 2px solid transparent; box-shadow: var(--bq-focus-ring); border-radius: var(--bq-radius-sm,0.25rem); }
+    :host(:not([readonly]):not([disabled])) .star:hover { transform: scale(1.12); }
+    :host([readonly]) .star, :host([disabled]) .star { cursor: default; }
+    :host([disabled]) .rating { opacity: 0.55; }
+    @media (prefers-reduced-motion: reduce) {
+      .star { transition: none; }
+      :host(:not([readonly]):not([disabled])) .star:hover { transform: none; }
+    }
+  `,
+  connected() {
+    const self = host(this);
+    const scope = bind(self);
+    const local = ratingStore(self);
+
+    const readValue = () => clampRating(
+      Number(self.getAttribute('value') ?? '0'),
+      Number(self.getAttribute('max') ?? '5')
+    );
+
+    const name = self.getAttribute('name') ?? '';
+    if (name) {
+      local.proxy = createFormProxy(
+        self,
+        name,
+        String(readValue()),
+        self.hasAttribute('disabled'),
+        { getLiveValue: () => String(readValue()) }
+      );
+      scope.add(() => {
+        local.proxy?.cleanup();
+        delete local.proxy;
+      });
+    }
+
+    const commit = (next: number) => {
+      if (self.hasAttribute('readonly') || self.hasAttribute('disabled')) return;
+      const max = Number(self.getAttribute('max') ?? '5');
+      const value = clampRating(next, max);
+      const final =
+        self.hasAttribute('clearable') && value === readValue() ? 0 : value;
+      self.setAttribute('value', String(final));
+      local.proxy?.setValue(String(final));
+      self.dispatchEvent(
+        new CustomEvent('bq-change', {
+          detail: { value: final },
+          bubbles: true,
+          composed: true,
+        })
+      );
+    };
+
+    scope.on(self.shadowRoot, 'click', (e) => {
+      const star = (e.target as Element).closest(
+        '.star'
+      ) as HTMLElement | null;
+      if (!star) return;
+      commit(Number(star.getAttribute('data-value') ?? '0'));
+    });
+
+    // Arrow keys adjust by one, Home/End jump to the ends — the radiogroup
+    // keyboard contract screen-reader users expect.
+    scope.on(self.shadowRoot, 'keydown', (e) => {
+      if (self.hasAttribute('readonly') || self.hasAttribute('disabled')) return;
+      const ke = e as KeyboardEvent;
+      const max = Number(self.getAttribute('max') ?? '5');
+      const current = readValue();
+      let next: number | null = null;
+      if (ke.key === 'ArrowRight' || ke.key === 'ArrowUp') next = current + 1;
+      else if (ke.key === 'ArrowLeft' || ke.key === 'ArrowDown') next = current - 1;
+      else if (ke.key === 'Home') next = 0;
+      else if (ke.key === 'End') next = max;
+      if (next === null) return;
+      ke.preventDefault();
+      commit(next);
+      const focusIndex = Math.max(1, Math.min(clampRating(next, max), max));
+      (
+        self.shadowRoot?.querySelector(
+          `.star[data-value="${focusIndex}"]`
+        ) as HTMLElement | null
+      )?.focus();
+    });
+  },
+  disconnected() {
+    release(this);
+  },
+  updated() {
+    const self = host(this);
+    const local = ratingStore(self);
+    const value = clampRating(
+      Number(self.getAttribute('value') ?? '0'),
+      Number(self.getAttribute('max') ?? '5')
+    );
+    local.proxy?.setValue(String(value));
+    local.proxy?.setDisabled(self.hasAttribute('disabled'));
+  },
+  render({ props }) {
+    const max = Math.max(0, Math.trunc(props.max) || 0);
+    const value = clampRating(props.value, max);
+    const interactive = !props.readonly && !props.disabled;
+    const label = props.label.trim() || t('rating.label');
+    const valueText = t('rating.valueText', { value, max });
+
+    const stars = Array.from({ length: max }, (_, i) => {
+      const index = i + 1;
+      const filled = index <= value;
+      return `
+        <button
+          type="button"
+          class="star"
+          part="star"
+          data-value="${index}"
+          data-filled="${filled ? 'true' : 'false'}"
+          role="radio"
+          aria-checked="${filled && index === Math.ceil(value) ? 'true' : 'false'}"
+          aria-label="${escapeHtml(t('rating.valueText', { value: index, max }))}"
+          tabindex="${interactive && (index === Math.max(1, Math.ceil(value)) || (value === 0 && index === 1)) ? '0' : '-1'}"
+          ${interactive ? '' : 'disabled'}
+        >${filled ? '★' : '☆'}</button>
+      `;
+    }).join('');
+
+    return html`
+      <div
+        part="rating"
+        class="rating"
+        data-size="${escapeHtml(props.size)}"
+        role="radiogroup"
+        aria-label="${escapeHtml(label)}"
+        aria-readonly="${props.readonly ? 'true' : 'false'}"
+        aria-disabled="${props.disabled ? 'true' : 'false'}"
+      >
+        ${stars}
+      </div>
+      <span class="sr-only" role="status" aria-live="polite"
+        >${escapeHtml(valueText)}</span
+      >
+    `;
+  },
+};
+
+component<BqRatingProps>('bq-rating', definition);
diff --git a/src/components/rating/index.ts b/src/components/rating/index.ts
new file mode 100644
index 0000000..f1af6c9
--- /dev/null
+++ b/src/components/rating/index.ts
@@ -0,0 +1 @@
+export * as __bqComponentEntry from './BqRating.js';
diff --git a/src/components/segmented-control/BqSegmentedControl.ts b/src/components/segmented-control/BqSegmentedControl.ts
index f9e449c..210b226 100644
--- a/src/components/segmented-control/BqSegmentedControl.ts
+++ b/src/components/segmented-control/BqSegmentedControl.ts
@@ -13,12 +13,12 @@
  * @fires bq-change - { value: string }
  */
 import type { ComponentDefinition } from '@bquery/bquery/component';
-import { component, html } from '@bquery/bquery/component';
+import { component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { t } from '../../i18n/index.js';
 import { uniqueId } from '../../utils/dom.js';
 import { createFormProxy, type FormProxy } from '../../utils/form.js';
-import { getBaseStyles } from '../../utils/styles.js';
+import { baseStyles } from '../../utils/styles.js';
 
 type BqSegmentedControlProps = {
   label: string;
@@ -52,8 +52,8 @@ const definition: ComponentDefinition<
   state: {
     uid: '',
   },
-  styles: `
-    ${getBaseStyles()}
+  styles: css`
+    ${baseStyles}
     *, *::before, *::after { box-sizing: border-box; }
     :host { display: block; }
     .field { display: flex; flex-direction: column; gap: 0.375rem; }
diff --git a/src/components/select/BqSelect.ts b/src/components/select/BqSelect.ts
index 8ca1f26..7de449b 100644
--- a/src/components/select/BqSelect.ts
+++ b/src/components/select/BqSelect.ts
@@ -14,11 +14,11 @@
  * @fires bq-change - { value: string }
  */
 import type { ComponentDefinition } from '@bquery/bquery/component';
-import { bool, component, html } from '@bquery/bquery/component';
+import { bool, component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { uniqueId } from '../../utils/dom.js';
 import { createFormProxy, type FormProxy } from '../../utils/form.js';
-import { getBaseStyles } from '../../utils/styles.js';
+import { baseStyles } from '../../utils/styles.js';
 
 type BqSelectProps = {
   label: string;
@@ -127,8 +127,8 @@ const definition: ComponentDefinition<BqSelectProps, BqSelectState> = {
     uid: '',
     optionsMarkup: '',
   },
-  styles: `
-    ${getBaseStyles()}
+  styles: css`
+    ${baseStyles}
     *, *::before, *::after { box-sizing: border-box; }
     :host { display: block; }
     .field { display: flex; flex-direction: column; gap: 0.375rem; }
diff --git a/src/components/skeleton/BqSkeleton.ts b/src/components/skeleton/BqSkeleton.ts
index ca69648..2cae3b6 100644
--- a/src/components/skeleton/BqSkeleton.ts
+++ b/src/components/skeleton/BqSkeleton.ts
@@ -7,9 +7,9 @@
  * @prop {number}  lines    - Number of text lines
  */
 import type { ComponentDefinition } from '@bquery/bquery/component';
-import { component, html } from '@bquery/bquery/component';
+import { component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
-import { getBaseStyles } from '../../utils/styles.js';
+import { baseStyles } from '../../utils/styles.js';
 
 type BqSkeletonProps = {
   variant: string;
@@ -55,8 +55,8 @@ const definition: ComponentDefinition<BqSkeletonProps> = {
   sanitize: {
     allowAttributes: ['style'],
   },
-  styles: `
-    ${getBaseStyles()}
+  styles: css`
+    ${baseStyles}
     :host { display: block; }
     .skeleton {
       background: var(--bq-bg-emphasis,#e2e8f0);
diff --git a/src/components/slider/BqSlider.ts b/src/components/slider/BqSlider.ts
index e63869c..88b6517 100644
--- a/src/components/slider/BqSlider.ts
+++ b/src/components/slider/BqSlider.ts
@@ -12,11 +12,12 @@
  * @fires bq-change - { value: number }
  */
 import type { ComponentDefinition } from '@bquery/bquery/component';
-import { bool, component, html } from '@bquery/bquery/component';
+import { bool, component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { t } from '../../i18n/index.js';
 import { createFormProxy, type FormProxy } from '../../utils/form.js';
-import { getBaseStyles } from '../../utils/styles.js';
+import { host } from '../../utils/component.js';
+import { baseStyles } from '../../utils/styles.js';
 
 type BqSliderProps = {
   value: number;
@@ -43,8 +44,8 @@ const definition: ComponentDefinition<BqSliderProps> = {
     disabled: { type: Boolean, default: false },
     'show-value': { type: Boolean, default: false },
   },
-  styles: `
-    ${getBaseStyles()}
+  styles: css`
+    ${baseStyles}
     *, *::before, *::after { box-sizing: border-box; }
     :host { display: block; }
     .wrapper { display: flex; flex-direction: column; gap: 0.375rem; font-family: var(--bq-font-family-sans); }
@@ -59,7 +60,7 @@ const definition: ComponentDefinition<BqSliderProps> = {
     input[type="range"]:focus-visible { outline: 2px solid transparent; box-shadow: var(--bq-focus-ring); }
   `,
   connected() {
-    const self = this;
+    const self = host(this);
 
     // Form proxy for native <form> participation
     const name = self.getAttribute('name') ?? '';
diff --git a/src/components/spinner/BqSpinner.ts b/src/components/spinner/BqSpinner.ts
index eb94bc0..4650b16 100644
--- a/src/components/spinner/BqSpinner.ts
+++ b/src/components/spinner/BqSpinner.ts
@@ -6,10 +6,10 @@
  * @prop {string} label   - Accessible label (sr-only)
  */
 import type { ComponentDefinition } from '@bquery/bquery/component';
-import { component, html } from '@bquery/bquery/component';
+import { component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { t } from '../../i18n/index.js';
-import { getBaseStyles } from '../../utils/styles.js';
+import { baseStyles } from '../../utils/styles.js';
 
 type BqSpinnerProps = { size: string; variant: string; label: string };
 
@@ -19,8 +19,8 @@ const definition: ComponentDefinition<BqSpinnerProps> = {
     variant: { type: String, default: 'primary' },
     label: { type: String, default: '' },
   },
-  styles: `
-    ${getBaseStyles()}
+  styles: css`
+    ${baseStyles}
     :host { display: inline-flex; align-items: center; justify-content: center; }
     .spinner {
       border-radius: 50%; border-style: solid; border-width: 2.5px; border-color: transparent;
diff --git a/src/components/stat-card/BqStatCard.ts b/src/components/stat-card/BqStatCard.ts
index f376d16..9d2f5d2 100644
--- a/src/components/stat-card/BqStatCard.ts
+++ b/src/components/stat-card/BqStatCard.ts
@@ -12,11 +12,11 @@
  * @slot icon   - Optional icon or badge for the metric
  */
 import type { ComponentDefinition } from '@bquery/bquery/component';
-import { component, html } from '@bquery/bquery/component';
+import { component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { t } from '../../i18n/index.js';
 import { uniqueId } from '../../utils/dom.js';
-import { getBaseStyles, srOnlyStyles } from '../../utils/styles.js';
+import { baseStyles, srOnly } from '../../utils/styles.js';
 
 type BqStatCardProps = {
   label: string;
@@ -51,9 +51,9 @@ const definition: ComponentDefinition<BqStatCardProps, BqStatCardState> = {
   state: {
     uid: '',
   },
-  styles: `
-    ${getBaseStyles()}
-    ${srOnlyStyles}
+  styles: css`
+    ${baseStyles}
+    ${srOnly}
     *, *::before, *::after { box-sizing: border-box; }
     :host { display: block; }
     .card {
diff --git a/src/components/stepper/BqStepper.ts b/src/components/stepper/BqStepper.ts
new file mode 100644
index 0000000..9080e58
--- /dev/null
+++ b/src/components/stepper/BqStepper.ts
@@ -0,0 +1,247 @@
+/**
+ * Stepper component — progress indicator for multi-step flows.
+ * @element bq-stepper
+ * @prop {number}  current     - Zero-based index of the active step
+ * @prop {string}  orientation - horizontal | vertical
+ * @prop {boolean} clickable   - Allow completed steps to be selected
+ * @prop {string}  label       - Accessible label for the step list
+ *
+ * Steps are declared as light-DOM children carrying `[data-step]`, with an
+ * optional `label` attribute and `description` attribute:
+ * `<div data-step label="Account" description="Your details"></div>`
+ *
+ * @fires bq-step-change - { index: number, label: string }
+ */
+import { component, css, html } from '@bquery/bquery/component';
+import type { ComponentDefinition } from '@bquery/bquery/component';
+import { escapeHtml } from '@bquery/bquery/security';
+import { t } from '../../i18n/index.js';
+import { bind, host, release } from '../../utils/component.js';
+import { baseStyles, reset, srOnly } from '../../utils/styles.js';
+
+type BqStepperProps = {
+  current: number;
+  orientation: string;
+  clickable: boolean;
+  label: string;
+};
+type BqStepperState = { steps: StepItem[] };
+
+type StepItem = { label: string; description: string; disabled: boolean };
+
+/** Reads the declarative `[data-step]` children into render-ready data. */
+export function readSteps(el: Element): StepItem[] {
+  return Array.from(el.querySelectorAll('[data-step]')).map((step) => ({
+    label:
+      step.getAttribute('label') ??
+      step.getAttribute('data-step') ??
+      step.textContent?.trim() ??
+      '',
+    description: step.getAttribute('description') ?? '',
+    disabled: step.hasAttribute('disabled'),
+  }));
+}
+
+/** Where a step sits relative to the active one. */
+export function stepStatus(
+  index: number,
+  current: number
+): 'complete' | 'current' | 'upcoming' {
+  if (index < current) return 'complete';
+  if (index === current) return 'current';
+  return 'upcoming';
+}
+
+const definition: ComponentDefinition<BqStepperProps, BqStepperState> = {
+  props: {
+    current: { type: Number, default: 0 },
+    orientation: { type: String, default: 'horizontal' },
+    clickable: { type: Boolean, default: false },
+    label: { type: String, default: '' },
+  },
+  state: {
+    steps: [],
+  },
+  styles: css`
+    ${baseStyles}
+    ${reset}
+    ${srOnly}
+    :host { display: block; }
+    .stepper { display: flex; font-family: var(--bq-font-family-sans); }
+    .stepper[data-orientation="horizontal"] { flex-direction: row; align-items: flex-start; }
+    .stepper[data-orientation="vertical"] { flex-direction: column; }
+
+    .step { display: flex; flex: 1 1 0; min-width: 0; gap: 0.625rem; }
+    .stepper[data-orientation="horizontal"] .step { flex-direction: column; align-items: center; text-align: center; position: relative; }
+    .stepper[data-orientation="vertical"] .step { flex-direction: row; align-items: flex-start; flex: 0 0 auto; padding-bottom: 1.5rem; position: relative; }
+
+    .marker {
+      display: inline-flex; align-items: center; justify-content: center;
+      width: 2rem; height: 2rem; flex: 0 0 auto;
+      border-radius: var(--bq-radius-full,9999px);
+      border: 2px solid var(--bq-border-emphasis,#cbd5e1);
+      background: var(--bq-bg-base,#fff);
+      color: var(--bq-text-muted,#475569);
+      font-size: var(--bq-font-size-sm,0.875rem);
+      font-weight: var(--bq-font-weight-semibold,600);
+      line-height: 1;
+      transition: background-color var(--bq-duration-fast) var(--bq-easing-standard),
+                  border-color var(--bq-duration-fast) var(--bq-easing-standard),
+                  color var(--bq-duration-fast) var(--bq-easing-standard);
+    }
+    .step[data-status="complete"] .marker {
+      background: var(--bq-color-primary-600,#2563eb);
+      border-color: var(--bq-color-primary-600,#2563eb);
+      color: #fff;
+    }
+    .step[data-status="current"] .marker {
+      border-color: var(--bq-color-primary-600,#2563eb);
+      color: var(--bq-color-primary-600,#2563eb);
+      box-shadow: var(--bq-focus-ring);
+    }
+
+    .body { min-width: 0; }
+    .label {
+      font-size: var(--bq-font-size-sm,0.875rem);
+      font-weight: var(--bq-font-weight-medium,500);
+      color: var(--bq-text-muted,#475569);
+    }
+    .step[data-status="current"] .label { color: var(--bq-text-base,#0f172a); font-weight: var(--bq-font-weight-semibold,600); }
+    .step[data-status="complete"] .label { color: var(--bq-text-base,#0f172a); }
+    .description { font-size: var(--bq-font-size-xs,0.75rem); color: var(--bq-text-subtle,#94a3b8); margin-top: 0.125rem; }
+
+    /* Connector between markers. */
+    .step:not(:last-child)::after {
+      content: ""; background: var(--bq-border-base,#e2e8f0); position: absolute;
+    }
+    .stepper[data-orientation="horizontal"] .step:not(:last-child)::after {
+      top: 1rem; left: calc(50% + 1.25rem); right: calc(-50% + 1.25rem); height: 2px;
+    }
+    .stepper[data-orientation="vertical"] .step:not(:last-child)::after {
+      left: 1rem; top: 2.25rem; bottom: 0.25rem; width: 2px; transform: translateX(-1px);
+    }
+    .step[data-status="complete"]:not(:last-child)::after { background: var(--bq-color-primary-600,#2563eb); }
+
+    button.step {
+      background: none; border: none; padding: 0; font: inherit; color: inherit;
+      cursor: pointer; text-align: inherit;
+    }
+    button.step:disabled { cursor: not-allowed; opacity: 0.55; }
+    button.step:focus-visible { outline: 2px solid transparent; box-shadow: var(--bq-focus-ring); border-radius: var(--bq-radius-md,0.375rem); }
+    @media (prefers-reduced-motion: reduce) {
+      .marker { transition: none; }
+    }
+  `,
+  connected() {
+    const self = host<BqStepperState>(this);
+    const scope = bind(self);
+
+    const sync = () => {
+      const steps = readSteps(self);
+      const previous = self.getState<StepItem[]>('steps') ?? [];
+      // setState always re-renders; skip when the declarative source is
+      // unchanged so a MutationObserver burst cannot loop.
+      if (JSON.stringify(previous) === JSON.stringify(steps)) return;
+      self.setState('steps', steps);
+    };
+    sync();
+
+    const observer = new MutationObserver(sync);
+    observer.observe(self, {
+      childList: true,
+      subtree: true,
+      attributes: true,
+      attributeFilter: ['label', 'description', 'disabled', 'data-step'],
+    });
+    scope.add(() => observer.disconnect());
+
+    const activate = (index: number) => {
+      const steps = self.getState<StepItem[]>('steps') ?? [];
+      const step = steps[index];
+      if (!step || step.disabled) return;
+      self.setAttribute('current', String(index));
+      self.dispatchEvent(
+        new CustomEvent('bq-step-change', {
+          detail: { index, label: step.label },
+          bubbles: true,
+          composed: true,
+        })
+      );
+    };
+
+    scope.on(self.shadowRoot, 'click', (e) => {
+      if (!self.hasAttribute('clickable')) return;
+      const button = (e.target as Element).closest(
+        'button.step'
+      ) as HTMLButtonElement | null;
+      if (!button || button.disabled) return;
+      activate(Number(button.getAttribute('data-index') ?? '-1'));
+    });
+  },
+  disconnected() {
+    release(this);
+  },
+  render({ props, state }) {
+    const steps = state.steps ?? [];
+    const current = Number.isFinite(props.current) ? props.current : 0;
+    const clickable = props.clickable;
+    const listLabel = props.label.trim() || t('stepper.nav');
+
+    const items = steps
+      .map((step, index) => {
+        const status = stepStatus(index, current);
+        const tag = clickable ? 'button' : 'div';
+        const statusLabel = t(
+          status === 'complete'
+            ? 'stepper.completed'
+            : status === 'current'
+              ? 'stepper.current'
+              : 'stepper.upcoming'
+        );
+        const marker = status === 'complete' ? '✓' : String(index + 1);
+        return `
+          <${tag}
+            class="step"
+            part="step"
+            data-index="${index}"
+            data-status="${status}"
+            ${clickable ? 'type="button"' : ''}
+            ${clickable && step.disabled ? 'disabled' : ''}
+            ${status === 'current' ? 'aria-current="step"' : ''}
+          >
+            <span class="marker" part="marker" aria-hidden="true">${escapeHtml(marker)}</span>
+            <span class="body">
+              <span class="label" part="label">${escapeHtml(step.label)}</span>
+              <span class="sr-only">${escapeHtml(` (${statusLabel})`)}</span>
+              ${step.description ? `<span class="description" part="description">${escapeHtml(step.description)}</span>` : ''}
+            </span>
+          </${tag}>
+        `;
+      })
+      .join('');
+
+    return html`
+      <div
+        part="stepper"
+        class="stepper"
+        role="group"
+        aria-label="${escapeHtml(listLabel)}"
+        data-orientation="${escapeHtml(props.orientation)}"
+      >
+        ${items}
+      </div>
+      <span class="sr-only" role="status" aria-live="polite"
+        >${escapeHtml(
+          steps.length > 0
+            ? t('stepper.stepOf', {
+                current: Math.min(current + 1, steps.length),
+                total: steps.length,
+              })
+            : ''
+        )}</span
+      >
+    `;
+  },
+};
+
+component<BqStepperProps, BqStepperState>('bq-stepper', definition);
diff --git a/src/components/stepper/index.ts b/src/components/stepper/index.ts
new file mode 100644
index 0000000..bf8aee5
--- /dev/null
+++ b/src/components/stepper/index.ts
@@ -0,0 +1 @@
+export * as __bqComponentEntry from './BqStepper.js';
diff --git a/src/components/switch/BqSwitch.ts b/src/components/switch/BqSwitch.ts
index ec2eb0c..de1cd89 100644
--- a/src/components/switch/BqSwitch.ts
+++ b/src/components/switch/BqSwitch.ts
@@ -9,10 +9,11 @@
  * @fires bq-change - { value: string, checked: boolean }
  */
 import type { ComponentDefinition } from '@bquery/bquery/component';
-import { bool, component, html } from '@bquery/bquery/component';
+import { bool, component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { createFormProxy, type FormProxy } from '../../utils/form.js';
-import { getBaseStyles } from '../../utils/styles.js';
+import { host } from '../../utils/component.js';
+import { baseStyles } from '../../utils/styles.js';
 
 type BqSwitchProps = {
   label: string;
@@ -30,8 +31,8 @@ const definition: ComponentDefinition<BqSwitchProps> = {
     disabled: { type: Boolean, default: false },
     size: { type: String, default: 'md' },
   },
-  styles: `
-    ${getBaseStyles()}
+  styles: css`
+    ${baseStyles}
     *, *::before, *::after { box-sizing: border-box; }
     :host { display: inline-flex; }
     .control { display: inline-flex; align-items: center; gap: 0.625rem; cursor: pointer; font-family: var(--bq-font-family-sans); }
@@ -65,7 +66,7 @@ const definition: ComponentDefinition<BqSwitchProps> = {
     }
   `,
   connected() {
-    const self = this;
+    const self = host(this);
 
     // Form proxy for native <form> participation
     const name = self.getAttribute('name') ?? '';
diff --git a/src/components/table/BqTable.ts b/src/components/table/BqTable.ts
index b929b51..f571003 100644
--- a/src/components/table/BqTable.ts
+++ b/src/components/table/BqTable.ts
@@ -13,10 +13,11 @@
  * @fires bq-sort - { key: string, dir: string }
  */
 import type { ComponentDefinition } from '@bquery/bquery/component';
-import { component, html } from '@bquery/bquery/component';
+import { component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { t } from '../../i18n/index.js';
-import { getBaseStyles } from '../../utils/styles.js';
+import { host } from '../../utils/component.js';
+import { baseStyles } from '../../utils/styles.js';
 
 type ColDef = { key: string; label: string; sortable?: boolean };
 type BqTableProps = {
@@ -43,8 +44,8 @@ const definition: ComponentDefinition<BqTableProps> = {
     hover: { type: Boolean, default: false },
     loading: { type: Boolean, default: false },
   },
-  styles: `
-    ${getBaseStyles()}
+  styles: css`
+    ${baseStyles}
     *, *::before, *::after { box-sizing: border-box; }
     :host { display: block; overflow-x: auto; }
     table { width: 100%; border-collapse: collapse; font-family: var(--bq-font-family-sans); font-size: var(--bq-font-size-sm,0.875rem); }
@@ -64,7 +65,7 @@ const definition: ComponentDefinition<BqTableProps> = {
     .loading-overlay { text-align: center; padding: 2rem; color: var(--bq-text-muted,#475569); }
   `,
   connected() {
-    const self = this;
+    const self = host(this);
     const sortHandler = (th: HTMLElement) => {
       const key = th.getAttribute('data-sort-key') ?? '';
       const curDir = self.getAttribute('sort-dir') ?? 'asc';
diff --git a/src/components/tabs/BqTabs.ts b/src/components/tabs/BqTabs.ts
index c6cc78e..60d8436 100644
--- a/src/components/tabs/BqTabs.ts
+++ b/src/components/tabs/BqTabs.ts
@@ -7,10 +7,10 @@
  * @fires bq-tab-change - { tabId: string }
  */
 import type { ComponentDefinition } from '@bquery/bquery/component';
-import { component, html } from '@bquery/bquery/component';
+import { component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { t } from '../../i18n/index.js';
-import { getBaseStyles } from '../../utils/styles.js';
+import { baseStyles } from '../../utils/styles.js';
 
 type BqTabsProps = { 'active-tab': string; variant: string };
 
@@ -34,8 +34,8 @@ const definition: ComponentDefinition<BqTabsProps> = {
     'active-tab': { type: String, default: '' },
     variant: { type: String, default: 'default' },
   },
-  styles: `
-    ${getBaseStyles()}
+  styles: css`
+    ${baseStyles}
     *, *::before, *::after { box-sizing: border-box; }
     :host { display: block; }
     .tabs { display: flex; flex-direction: column; }
diff --git a/src/components/textarea/BqTextarea.ts b/src/components/textarea/BqTextarea.ts
index 3bc3bc2..96a8e15 100644
--- a/src/components/textarea/BqTextarea.ts
+++ b/src/components/textarea/BqTextarea.ts
@@ -19,12 +19,12 @@
  * @fires bq-blur
  */
 import type { ComponentDefinition } from '@bquery/bquery/component';
-import { bool, component, html } from '@bquery/bquery/component';
+import { bool, component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { t } from '../../i18n/index.js';
 import { uniqueId } from '../../utils/dom.js';
 import { createFormProxy, type FormProxy } from '../../utils/form.js';
-import { getBaseStyles } from '../../utils/styles.js';
+import { baseStyles } from '../../utils/styles.js';
 
 type BqTextareaProps = {
   label: string;
@@ -60,8 +60,8 @@ const definition: ComponentDefinition<BqTextareaProps, BqTextareaState> = {
   state: {
     uid: '',
   },
-  styles: `
-    ${getBaseStyles()}
+  styles: css`
+    ${baseStyles}
     *, *::before, *::after { box-sizing: border-box; }
     :host { display: block; }
     .field { display: flex; flex-direction: column; gap: 0.375rem; }
diff --git a/src/components/timeline/BqTimeline.ts b/src/components/timeline/BqTimeline.ts
new file mode 100644
index 0000000..408465e
--- /dev/null
+++ b/src/components/timeline/BqTimeline.ts
@@ -0,0 +1,144 @@
+/**
+ * Timeline component — ordered list of events along a connecting line.
+ * @element bq-timeline
+ * @prop {string}  variant - default | compact
+ * @prop {string}  align   - start | alternate
+ * @prop {string}  label   - Accessible label for the timeline
+ * @slot - `bq-timeline-item` elements
+ */
+/**
+ * Timeline item.
+ * @element bq-timeline-item
+ * @prop {string}  variant  - primary | success | danger | warning | info | neutral
+ * @prop {string}  headline - Item title
+ * @prop {string}  datetime - Machine-readable timestamp for the `<time>` element
+ * @prop {string}  timestamp - Human-readable timestamp
+ * @prop {boolean} last     - Hide the trailing connector
+ * @slot          - Item body
+ * @slot marker   - Custom marker content
+ */
+import { component, css, html } from '@bquery/bquery/component';
+import type { ComponentDefinition } from '@bquery/bquery/component';
+import { escapeHtml } from '@bquery/bquery/security';
+import { t } from '../../i18n/index.js';
+import { baseStyles, reset } from '../../utils/styles.js';
+
+type BqTimelineProps = { variant: string; align: string; label: string };
+type BqTimelineItemProps = {
+  variant: string;
+  headline: string;
+  datetime: string;
+  timestamp: string;
+  last: boolean;
+};
+
+const timelineDefinition: ComponentDefinition<BqTimelineProps> = {
+  props: {
+    variant: { type: String, default: 'default' },
+    align: { type: String, default: 'start' },
+    label: { type: String, default: '' },
+  },
+  styles: css`
+    ${baseStyles}
+    ${reset}
+    :host { display: block; }
+    .timeline { list-style: none; margin: 0; padding: 0; font-family: var(--bq-font-family-sans); }
+    :host([variant="compact"]) { --bq-timeline-gap: 0.75rem; }
+    :host { --bq-timeline-gap: 1.5rem; }
+  `,
+  render({ props }) {
+    const label = props.label.trim() || t('timeline.nav');
+    return html`
+      <ol
+        part="timeline"
+        class="timeline"
+        aria-label="${escapeHtml(label)}"
+        data-align="${escapeHtml(props.align)}"
+      >
+        <slot></slot>
+      </ol>
+    `;
+  },
+};
+
+const itemDefinition: ComponentDefinition<BqTimelineItemProps> = {
+  // `datetime` is outside the framework's base allowlist; the value is
+  // escaped and only ever comes from this component's own prop.
+  sanitize: { allowAttributes: ['datetime'] },
+  props: {
+    variant: { type: String, default: 'primary' },
+    headline: { type: String, default: '' },
+    datetime: { type: String, default: '' },
+    timestamp: { type: String, default: '' },
+    last: { type: Boolean, default: false },
+  },
+  styles: css`
+    ${baseStyles}
+    ${reset}
+    :host { display: block; }
+    .item {
+      display: grid;
+      grid-template-columns: auto 1fr;
+      column-gap: 0.875rem;
+      font-family: var(--bq-font-family-sans);
+    }
+    .rail { display: flex; flex-direction: column; align-items: center; }
+    .marker {
+      display: inline-flex; align-items: center; justify-content: center;
+      width: 0.875rem; height: 0.875rem; margin-top: 0.25rem; flex: 0 0 auto;
+      border-radius: var(--bq-radius-full,9999px);
+      background: var(--bq-color-primary-600,#2563eb);
+      box-shadow: 0 0 0 3px var(--bq-color-primary-100,#dbeafe);
+      color: #fff; font-size: 0.5rem; line-height: 1;
+    }
+    .item[data-variant="success"] .marker { background: var(--bq-color-success-600,#16a34a); box-shadow: 0 0 0 3px var(--bq-color-success-100,#dcfce7); }
+    .item[data-variant="danger"]  .marker { background: var(--bq-color-danger-600,#dc2626);  box-shadow: 0 0 0 3px var(--bq-color-danger-100,#fee2e2); }
+    .item[data-variant="warning"] .marker { background: var(--bq-color-warning-600,#d97706); box-shadow: 0 0 0 3px var(--bq-color-warning-100,#fef3c7); }
+    .item[data-variant="info"]    .marker { background: var(--bq-color-info-600,#2563eb);    box-shadow: 0 0 0 3px var(--bq-color-info-100,#dbeafe); }
+    .item[data-variant="neutral"] .marker { background: var(--bq-text-subtle,#94a3b8);       box-shadow: 0 0 0 3px var(--bq-bg-emphasis,#e2e8f0); }
+
+    .connector { flex: 1 1 auto; width: 2px; background: var(--bq-border-base,#e2e8f0); margin-top: 0.25rem; min-height: 0.5rem; }
+    :host([last]) .connector { display: none; }
+
+    .content { padding-bottom: var(--bq-timeline-gap, 1.5rem); min-width: 0; }
+    :host([last]) .content { padding-bottom: 0; }
+    .headline {
+      font-size: var(--bq-font-size-sm,0.875rem);
+      font-weight: var(--bq-font-weight-semibold,600);
+      color: var(--bq-text-base,#0f172a);
+      margin: 0;
+    }
+    .timestamp {
+      display: block;
+      font-size: var(--bq-font-size-xs,0.75rem);
+      color: var(--bq-text-subtle,#94a3b8);
+      margin-top: 0.125rem;
+    }
+    .body { font-size: var(--bq-font-size-sm,0.875rem); color: var(--bq-text-muted,#475569); margin-top: 0.375rem; }
+  `,
+  render({ props }) {
+    const headline = props.headline.trim();
+    const timestamp = props.timestamp.trim();
+    const datetime = props.datetime.trim();
+    return html`
+      <li part="item" class="item" data-variant="${escapeHtml(props.variant)}">
+        <div class="rail">
+          <span class="marker" part="marker"><slot name="marker"></slot></span>
+          <span class="connector" part="connector"></span>
+        </div>
+        <div class="content" part="content">
+          ${headline ? `<p class="headline" part="headline">${escapeHtml(headline)}</p>` : ''}
+          ${
+            timestamp
+              ? `<time class="timestamp" part="timestamp"${datetime ? ` datetime="${escapeHtml(datetime)}"` : ''}>${escapeHtml(timestamp)}</time>`
+              : ''
+          }
+          <div class="body" part="body"><slot></slot></div>
+        </div>
+      </li>
+    `;
+  },
+};
+
+component<BqTimelineProps>('bq-timeline', timelineDefinition);
+component<BqTimelineItemProps>('bq-timeline-item', itemDefinition);
diff --git a/src/components/timeline/index.ts b/src/components/timeline/index.ts
new file mode 100644
index 0000000..2450052
--- /dev/null
+++ b/src/components/timeline/index.ts
@@ -0,0 +1 @@
+export * as __bqComponentEntry from './BqTimeline.js';
diff --git a/src/components/toast/BqToast.ts b/src/components/toast/BqToast.ts
index 7c3d4c8..eea17d8 100644
--- a/src/components/toast/BqToast.ts
+++ b/src/components/toast/BqToast.ts
@@ -8,10 +8,11 @@
  * @fires bq-close
  */
 import type { ComponentDefinition } from '@bquery/bquery/component';
-import { component, html } from '@bquery/bquery/component';
+import { component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { t } from '../../i18n/index.js';
-import { getBaseStyles } from '../../utils/styles.js';
+import { host } from '../../utils/component.js';
+import { baseStyles } from '../../utils/styles.js';
 
 type BqToastProps = {
   variant: string;
@@ -27,8 +28,8 @@ const definition: ComponentDefinition<BqToastProps> = {
     duration: { type: Number, default: 4000 },
     dismissible: { type: Boolean, default: true },
   },
-  styles: `
-    ${getBaseStyles()}
+  styles: css`
+    ${baseStyles}
     *, *::before, *::after { box-sizing: border-box; }
     :host { display: block; }
     .toast {
@@ -53,7 +54,7 @@ const definition: ComponentDefinition<BqToastProps> = {
     }
   `,
   connected() {
-    const self = this;
+    const self = host(this);
     const close = () => {
       self.dispatchEvent(
         new CustomEvent('bq-close', { bubbles: true, composed: true })
diff --git a/src/components/tooltip/BqTooltip.ts b/src/components/tooltip/BqTooltip.ts
index d79583f..4338b3c 100644
--- a/src/components/tooltip/BqTooltip.ts
+++ b/src/components/tooltip/BqTooltip.ts
@@ -7,14 +7,23 @@
  * @slot - The trigger element
  */
 import type { ComponentDefinition } from '@bquery/bquery/component';
-import { component, html } from '@bquery/bquery/component';
+import { component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
+import type { Disposer } from '../../utils/component.js';
+import { bind, host, release, store } from '../../utils/component.js';
 import { uniqueId } from '../../utils/dom.js';
-import { getBaseStyles } from '../../utils/styles.js';
+import { baseStyles } from '../../utils/styles.js';
 
 type BqTooltipProps = { content: string; placement: string; delay: number };
 type BqTooltipState = { visible: boolean; uid: string };
 
+/** Per-instance handles shared between `connected()` and `updated()`. */
+const tooltipStore = (owner: object) =>
+  store<{ syncTrigger?: () => void; triggerElements: HTMLElement[] }>(
+    owner,
+    () => ({ triggerElements: [] })
+  );
+
 function addDescribedBy(element: HTMLElement, tooltipId: string): void {
   const current = element.getAttribute('aria-describedby');
   const tokens = new Set((current ?? '').split(/\s+/).filter(Boolean));
@@ -42,8 +51,8 @@ const definition: ComponentDefinition<BqTooltipProps, BqTooltipState> = {
     delay: { type: Number, default: 200 },
   },
   state: { visible: false, uid: '' },
-  styles: `
-    ${getBaseStyles()}
+  styles: css`
+    ${baseStyles}
     :host { display: inline-block; position: relative; }
     .tip {
       position: absolute; z-index: var(--bq-z-tooltip,700);
@@ -63,30 +72,22 @@ const definition: ComponentDefinition<BqTooltipProps, BqTooltipState> = {
     }
   `,
   connected() {
-    type BQEl = HTMLElement & {
-      setState(k: 'visible' | 'uid', v: unknown): void;
-      getState<T>(k: string): T;
-    };
-    const self = this as unknown as BQEl;
-    const internalState = self as unknown as Record<string, unknown>;
+    const self = host<BqTooltipState>(this);
+    const scope = bind(self);
+    const local = tooltipStore(self);
     if (!self.getState<string>('uid')) {
       self.setState('uid', uniqueId('bq-tooltip'));
     }
+    let cancelShow: Disposer | null = null;
     const clearShowTimer = () => {
-      const timer = internalState['_showTimer'] as
-        | ReturnType<typeof setTimeout>
-        | null
-        | undefined;
-      if (timer) {
-        clearTimeout(timer);
-      }
-      internalState['_showTimer'] = null;
+      cancelShow?.();
+      cancelShow = null;
     };
     const show = () => {
       clearShowTimer();
       const d = parseInt(self.getAttribute('delay') ?? '200', 10);
-      internalState['_showTimer'] = setTimeout(() => {
-        internalState['_showTimer'] = null;
+      cancelShow = scope.timeout(() => {
+        cancelShow = null;
         self.setState('visible', true);
       }, d);
     };
@@ -98,17 +99,16 @@ const definition: ComponentDefinition<BqTooltipProps, BqTooltipState> = {
       if ((e as KeyboardEvent).key === 'Escape') hide();
     };
     const syncTrigger = () => {
-      const state = self as unknown as Record<string, unknown>;
       const tooltipId = self.getState<string>('uid');
-      const previous =
-        (state['_triggerElements'] as HTMLElement[] | undefined) ?? [];
-      previous.forEach((element) => removeDescribedBy(element, tooltipId));
+      local.triggerElements.forEach((element) =>
+        removeDescribedBy(element, tooltipId)
+      );
 
       const slot = self.shadowRoot?.querySelector(
         'slot'
       ) as HTMLSlotElement | null;
       if (!slot) {
-        state['_triggerElements'] = [];
+        local.triggerElements = [];
         return;
       }
 
@@ -122,58 +122,42 @@ const definition: ComponentDefinition<BqTooltipProps, BqTooltipState> = {
       if (content) {
         next.forEach((element) => addDescribedBy(element, tooltipId));
       }
-      state['_triggerElements'] = next;
+      local.triggerElements = next;
     };
-    internalState['_show'] = show;
-    internalState['_hide'] = hide;
-    internalState['_kh'] = kh;
-    internalState['_syncTrigger'] = syncTrigger;
-    internalState['_clearShowTimer'] = clearShowTimer;
-    self.addEventListener('mouseenter', show);
-    self.addEventListener('mouseleave', hide);
-    self.addEventListener('focusin', show);
-    self.addEventListener('focusout', hide);
-    document.addEventListener('keydown', kh);
+    // `updated()` re-syncs the trigger wiring after every render.
+    local.syncTrigger = syncTrigger;
+
+    // The tooltip writes aria-describedby onto slotted light-DOM elements that
+    // outlive it, so those references must be withdrawn on teardown.
+    scope.add(() => {
+      const tooltipId = self.getState<string>('uid') ?? self.id;
+      local.triggerElements.forEach((element) =>
+        removeDescribedBy(element, tooltipId)
+      );
+      local.triggerElements = [];
+    });
+
+    scope.on(self, 'mouseenter', show);
+    scope.on(self, 'mouseleave', hide);
+    scope.on(self, 'focusin', show);
+    scope.on(self, 'focusout', hide);
+    scope.on(document, 'keydown', kh);
+
     queueMicrotask(() => {
       if (!self.isConnected) return;
       const slot = self.shadowRoot?.querySelector(
         'slot'
       ) as HTMLSlotElement | null;
       if (!slot) return;
-      slot.addEventListener('slotchange', syncTrigger);
-      internalState['_slot'] = slot;
+      scope.on(slot, 'slotchange', syncTrigger);
       syncTrigger();
     });
   },
   disconnected() {
-    const self = this as unknown as Record<string, unknown>;
-    const show = self['_show'] as EventListener;
-    const hide = self['_hide'] as EventListener;
-    const kh = self['_kh'] as EventListener;
-    const slot = self['_slot'] as HTMLSlotElement | undefined;
-    const syncTrigger = self['_syncTrigger'] as EventListener | undefined;
-    const clearShowTimer = self['_clearShowTimer'] as (() => void) | undefined;
-    const triggerElements =
-      (self['_triggerElements'] as HTMLElement[] | undefined) ?? [];
-    const tooltipId =
-      (this as unknown as { getState?<T>(key: string): T }).getState?.<string>(
-        'uid'
-      ) ?? this.id;
-    clearShowTimer?.();
-    this.removeEventListener('mouseenter', show);
-    this.removeEventListener('mouseleave', hide);
-    this.removeEventListener('focusin', show);
-    this.removeEventListener('focusout', hide);
-    document.removeEventListener('keydown', kh);
-    if (slot && syncTrigger)
-      slot.removeEventListener('slotchange', syncTrigger);
-    triggerElements.forEach((element) => removeDescribedBy(element, tooltipId));
+    release(this);
   },
   updated() {
-    const syncTrigger = (this as unknown as Record<string, unknown>)[
-      '_syncTrigger'
-    ] as (() => void) | undefined;
-    syncTrigger?.();
+    tooltipStore(this).syncTrigger?.();
   },
   render({ props, state }) {
     const visible = Boolean(state['visible']);
diff --git a/src/i18n/en.ts b/src/i18n/en.ts
index 0bbf37f..6b29308 100644
--- a/src/i18n/en.ts
+++ b/src/i18n/en.ts
@@ -95,6 +95,44 @@ export const en = {
   segmentedControl: {
     defaultLabel: 'Options',
   },
+  popover: {
+    close: 'Close popover',
+  },
+  banner: {
+    dismiss: 'Dismiss announcement',
+  },
+  avatarGroup: {
+    overflow: '{count} more',
+    label: 'Group of people',
+  },
+  buttonGroup: {
+    defaultLabel: 'Button group',
+  },
+  stepper: {
+    nav: 'Progress',
+    stepOf: 'Step {current} of {total}',
+    completed: 'Completed',
+    current: 'Current step',
+    upcoming: 'Upcoming step',
+  },
+  timeline: {
+    nav: 'Timeline',
+  },
+  rating: {
+    label: 'Rating',
+    valueText: '{value} of {max} stars',
+    clear: 'Clear rating',
+  },
+  numberInput: {
+    increment: 'Increase value',
+    decrement: 'Decrease value',
+  },
+  fileUpload: {
+    hint: 'Drag files here or browse',
+    browse: 'Browse files',
+    remove: 'Remove file',
+    selected: '{count} selected',
+  },
 } as const;
 
 export type EnLocale = typeof en;
diff --git a/src/index.ts b/src/index.ts
index 19071d3..7bcbcdc 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -22,6 +22,16 @@ import { registerAll } from './register.js';
 import { __bqComponentEntry as accordionComponentEntry } from './components/accordion/index.js';
 import { __bqComponentEntry as alertComponentEntry } from './components/alert/index.js';
 import { __bqComponentEntry as avatarComponentEntry } from './components/avatar/index.js';
+import { __bqComponentEntry as avatarGroupComponentEntry } from './components/avatar-group/index.js';
+import { __bqComponentEntry as bannerComponentEntry } from './components/banner/index.js';
+import { __bqComponentEntry as buttonGroupComponentEntry } from './components/button-group/index.js';
+import { __bqComponentEntry as fileUploadComponentEntry } from './components/file-upload/index.js';
+import { __bqComponentEntry as kbdComponentEntry } from './components/kbd/index.js';
+import { __bqComponentEntry as numberInputComponentEntry } from './components/number-input/index.js';
+import { __bqComponentEntry as popoverComponentEntry } from './components/popover/index.js';
+import { __bqComponentEntry as ratingComponentEntry } from './components/rating/index.js';
+import { __bqComponentEntry as stepperComponentEntry } from './components/stepper/index.js';
+import { __bqComponentEntry as timelineComponentEntry } from './components/timeline/index.js';
 import { __bqComponentEntry as badgeComponentEntry } from './components/badge/index.js';
 import { __bqComponentEntry as breadcrumbsComponentEntry } from './components/breadcrumbs/index.js';
 import { __bqComponentEntry as buttonComponentEntry } from './components/button/index.js';
@@ -61,6 +71,16 @@ Object.defineProperty(registerAll, COMPONENT_ENTRY_MAP_KEY, {
     'accordion': accordionComponentEntry,
     'alert': alertComponentEntry,
     'avatar': avatarComponentEntry,
+    'avatar-group': avatarGroupComponentEntry,
+    'banner': bannerComponentEntry,
+    'button-group': buttonGroupComponentEntry,
+    'file-upload': fileUploadComponentEntry,
+    'kbd': kbdComponentEntry,
+    'number-input': numberInputComponentEntry,
+    'popover': popoverComponentEntry,
+    'rating': ratingComponentEntry,
+    'stepper': stepperComponentEntry,
+    'timeline': timelineComponentEntry,
     'badge': badgeComponentEntry,
     'breadcrumbs': breadcrumbsComponentEntry,
     'button': buttonComponentEntry,
diff --git a/src/utils/component.ts b/src/utils/component.ts
new file mode 100644
index 0000000..888eaae
--- /dev/null
+++ b/src/utils/component.ts
@@ -0,0 +1,167 @@
+/**
+ * Lifecycle helpers for @bquery/ui components.
+ *
+ * Components repeatedly stashed listener references on the host element
+ * (`self['_keyHandler'] = ...`) in `connected()` and unwound them by hand in
+ * `disconnected()`. That pattern is verbose and easy to get wrong — every new
+ * listener needs a matching, correctly-typed removal, and a forgotten one is a
+ * leak that survives the element.
+ *
+ * `bind()` gives a component a disposer scope instead: register teardown at
+ * the same place the resource is created, then `release()` unwinds everything
+ * in one call.
+ *
+ * ```ts
+ * connected() {
+ *   const el = host(this);
+ *   const scope = bind(el);
+ *   scope.on(document, 'keydown', onKeyDown);
+ *   scope.on(el.shadowRoot, 'click', onClick);
+ * },
+ * disconnected() {
+ *   release(this);
+ * },
+ * ```
+ */
+import type { ComponentElement } from '@bquery/bquery/component';
+
+/** A teardown function registered on a component scope. */
+export type Disposer = () => void;
+
+/**
+ * Typed view of `this` inside a component lifecycle hook.
+ *
+ * The `ComponentDefinition` hooks are declared with overloads (`(this: ...)`
+ * and `()`), so TypeScript contextually types `this` as the bare signature.
+ * This helper restores the `setState`/`getState`/`setProp` surface without
+ * each component redeclaring its own local cast type.
+ */
+export function host<
+  TState extends Record<string, unknown> | undefined = undefined,
+>(ctx: unknown): ComponentElement<TState> {
+  return ctx as ComponentElement<TState>;
+}
+
+const stores = new WeakMap<object, object>();
+
+/**
+ * Per-instance mutable store, created on first access.
+ *
+ * Replaces stashing loose `_foo` properties on the host element when a value
+ * created in `connected()` has to stay reachable from `updated()` or a later
+ * hook. The store is typed, invisible to consumers of the element, and
+ * garbage-collected with the instance.
+ */
+export function store<T extends object>(owner: object, init: () => T): T {
+  const existing = stores.get(owner);
+  if (existing) return existing as T;
+  const created = init();
+  stores.set(owner, created);
+  return created;
+}
+
+/** Disposer scope attached to a single component instance. */
+export interface ComponentScope {
+  /**
+   * Adds an event listener and registers its removal.
+   * A nullish target is ignored, so optional shadow-root queries can be
+   * passed directly. Returns a disposer that also deregisters itself.
+   */
+  on(
+    target: EventTarget | null | undefined,
+    type: string,
+    handler: EventListener,
+    options?: AddEventListenerOptions | boolean,
+  ): Disposer;
+  /** Registers an arbitrary teardown function. Returns a self-deregistering disposer. */
+  add(dispose: Disposer): Disposer;
+  /** `setTimeout` whose pending timer is cleared on release. */
+  timeout(handler: () => void, ms: number): Disposer;
+  /** `requestAnimationFrame` whose pending frame is cancelled on release. */
+  frame(handler: () => void): Disposer;
+  /** Runs every registered disposer and empties the scope. */
+  dispose(): void;
+}
+
+const scopes = new WeakMap<object, Set<Disposer>>();
+
+function scopeSet(owner: object): Set<Disposer> {
+  let set = scopes.get(owner);
+  if (!set) {
+    set = new Set<Disposer>();
+    scopes.set(owner, set);
+  }
+  return set;
+}
+
+/**
+ * Returns the disposer scope for a component instance, creating it on first
+ * use. Calling `bind()` twice returns a scope backed by the same registry, so
+ * it is safe to call from any hook.
+ */
+export function bind(owner: object): ComponentScope {
+  const set = scopeSet(owner);
+
+  const add = (dispose: Disposer): Disposer => {
+    set.add(dispose);
+    return () => {
+      if (!set.delete(dispose)) return;
+      dispose();
+    };
+  };
+
+  return {
+    add,
+    on(target, type, handler, options) {
+      if (!target) return () => {};
+      target.addEventListener(type, handler, options);
+      return add(() => target.removeEventListener(type, handler, options));
+    },
+    timeout(handler, ms) {
+      let done = false;
+      const id = setTimeout(() => {
+        done = true;
+        remove();
+        handler();
+      }, ms);
+      const remove = add(() => {
+        if (!done) clearTimeout(id);
+      });
+      return remove;
+    },
+    frame(handler) {
+      let done = false;
+      const id = requestAnimationFrame(() => {
+        done = true;
+        remove();
+        handler();
+      });
+      const remove = add(() => {
+        if (!done) cancelAnimationFrame(id);
+      });
+      return remove;
+    },
+    dispose() {
+      // Snapshot first: a disposer may register or remove others while running.
+      const pending = Array.from(set);
+      set.clear();
+      for (const dispose of pending) {
+        try {
+          dispose();
+        } catch {
+          /* teardown must never block the rest of the unwind */
+        }
+      }
+    },
+  };
+}
+
+/**
+ * Runs every teardown registered on the component instance. Safe to call for
+ * an element that never created a scope, and safe to call repeatedly.
+ */
+export function release(owner: object): void {
+  const set = scopes.get(owner);
+  if (!set || set.size === 0) return;
+  bind(owner).dispose();
+}
diff --git a/src/utils/dom.ts b/src/utils/dom.ts
index e14d855..e34b5d1 100644
--- a/src/utils/dom.ts
+++ b/src/utils/dom.ts
@@ -1,6 +1,7 @@
 /**
  * DOM utility helpers for @bquery/ui components.
  */
+import type { ComponentScope, Disposer } from './component.js';
 
 /** Dispatch a custom event from a host element with bubbles + composed. */
 export function dispatch<T = unknown>(
@@ -131,6 +132,79 @@ export function getAnimationTimeoutMs(
   return longest;
 }
 
+/**
+ * Builds the animated-close routine shared by the overlay components
+ * (Dialog, Drawer).
+ *
+ * Closing sets `data-closing` so the exit animation can run, then drops
+ * `open` once the animation reports done. Users who prefer reduced motion skip
+ * straight to the final state. The pending timer is owned by the component
+ * scope, so a disconnect mid-animation cannot strand the overlay in its
+ * half-closed state.
+ */
+export function createAnimatedClose(options: {
+  /** The component host element. */
+  host: HTMLElement;
+  /** Component scope owning the pending close timer. */
+  scope: ComponentScope;
+  /** Selector for the animated element inside the shadow root. */
+  panelSelector: string;
+  /** Duration assumed when the animated element reports none. */
+  fallbackDuration: string;
+  /** Event emitted once the overlay has fully closed. */
+  eventName?: string;
+}): () => void {
+  const {
+    host: el,
+    scope,
+    panelSelector,
+    fallbackDuration,
+    eventName = 'bq-close',
+  } = options;
+
+  let cancelPending: Disposer | null = null;
+
+  scope.add(() => {
+    if (!cancelPending) return;
+    cancelPending = null;
+    el.removeAttribute('data-closing');
+    el.removeAttribute('open');
+  });
+
+  return function close(): void {
+    if (el.hasAttribute('data-closing')) return;
+
+    const finalize = () => {
+      cancelPending?.();
+      cancelPending = null;
+      el.removeAttribute('data-closing');
+      el.removeAttribute('open');
+      el.dispatchEvent(
+        new CustomEvent(eventName, { bubbles: true, composed: true })
+      );
+    };
+
+    const reducedMotion = el.ownerDocument.defaultView?.matchMedia?.(
+      '(prefers-reduced-motion: reduce)'
+    )?.matches;
+    if (reducedMotion) {
+      finalize();
+      return;
+    }
+
+    el.setAttribute('data-closing', '');
+    const panel = el.shadowRoot?.querySelector(panelSelector);
+    const timeoutMs = panel
+      ? getAnimationTimeoutMs(panel, fallbackDuration)
+      : 0;
+    if (timeoutMs <= 0) {
+      finalize();
+    } else {
+      cancelPending = scope.timeout(finalize, Math.ceil(timeoutMs) + 20);
+    }
+  };
+}
+
 /**
  * Manages focus trapping, initial focus, and focus restoration for overlay
  * components (Dialog, Drawer). Call from `updated()`.
diff --git a/src/utils/index.ts b/src/utils/index.ts
index 1c1bc15..e532224 100644
--- a/src/utils/index.ts
+++ b/src/utils/index.ts
@@ -9,6 +9,8 @@ export {
   unlinkDescribedBy,
 } from './aria.js';
 export { cn } from './cn.js';
+export { bind, host, release, store } from './component.js';
+export type { ComponentScope, Disposer } from './component.js';
 export {
   dispatch,
   getFocusableElements,
@@ -19,4 +21,13 @@ export {
 } from './dom.js';
 export { createFormProxy } from './form.js';
 export type { FormProxy } from './form.js';
-export { focusVisibleStyles, getBaseStyles, srOnlyStyles } from './styles.js';
+export {
+  baseStyles,
+  focusVisible,
+  focusVisibleStyles,
+  getBaseStyles,
+  rawCss,
+  reset,
+  srOnly,
+  srOnlyStyles,
+} from './styles.js';
diff --git a/src/utils/styles.ts b/src/utils/styles.ts
index fc1752b..8c250db 100644
--- a/src/utils/styles.ts
+++ b/src/utils/styles.ts
@@ -1,16 +1,61 @@
 /**
- * Shared style utilities – generates inline CSS strings for use in Shadow DOM.
+ * Shared style utilities – provides the token/theme CSS consumed by every
+ * component's Shadow DOM.
+ *
+ * Components should compose their styles with the `css` tagged template from
+ * `@bquery/bquery/component` and interpolate the {@link ComponentStyles}
+ * exports from this module (`baseStyles`, `focusVisible`, `srOnly`, `reset`):
+ *
+ * ```ts
+ * styles: css`
+ *   ${baseStyles}
+ *   .thing { color: var(--bq-text-base); }
+ * `
+ * ```
+ *
+ * Doing so lets the bQuery component runtime hand the CSS to
+ * `adoptedStyleSheets`, which means the stylesheet is constructed once and
+ * shared by every instance of that component instead of being duplicated into
+ * — and rewritten on every re-render of — a per-instance `<style>` element.
+ * Environments without Constructable Stylesheets transparently fall back to
+ * the `<style>` element.
+ *
+ * Interpolating a plain string into `css` escapes it, so raw CSS fragments
+ * must be `ComponentStyles` values to survive composition intact.
  */
+import { css } from '@bquery/bquery/component';
+import type { ComponentStyles } from '@bquery/bquery/component';
 import { getDefaultThemeCSS } from '../theme/default.js';
 import { getDarkThemeCSS } from '../theme/dark.js';
 
+/**
+ * Wraps already-trusted CSS text in a {@link ComponentStyles} payload.
+ *
+ * `css` only escapes *interpolated* values; the static template chunks are
+ * passed through verbatim. Calling the tag directly with a single-chunk
+ * template therefore preserves the text exactly, which is what we need for
+ * CSS we generate ourselves from the token/theme modules.
+ */
+export function rawCss(text: string): ComponentStyles {
+  const chunks = [text] as string[] & { raw?: readonly string[] };
+  chunks.raw = [text];
+  return css(chunks as unknown as TemplateStringsArray);
+}
+
+const BASE_STYLE_TEXT = `${getDefaultThemeCSS()}\n${getDarkThemeCSS()}`;
+
+/**
+ * The full token + light/dark theme CSS block, ready to interpolate into a
+ * component's `css` template. Shared across every component instance.
+ */
+export const baseStyles: ComponentStyles = rawCss(BASE_STYLE_TEXT);
+
 /** Returns the full theme + token CSS block suitable for embedding in a :host style block. */
 export function getBaseStyles(): string {
-  return `${getDefaultThemeCSS()}\n${getDarkThemeCSS()}`;
+  return BASE_STYLE_TEXT;
 }
 
-/** Focus-visible outline using the CSS custom property --bq-focus-ring. */
-export const focusVisibleStyles = `
+const FOCUS_VISIBLE_TEXT = `
   :host(:focus-within) *:focus-visible,
   *:focus-visible {
     outline: 2px solid transparent;
@@ -19,8 +64,13 @@ export const focusVisibleStyles = `
   }
 `;
 
-/** Visually-hidden utility for screen-reader-only text. */
-export const srOnlyStyles = `
+/** Focus-visible outline using the CSS custom property --bq-focus-ring. */
+export const focusVisibleStyles = FOCUS_VISIBLE_TEXT;
+
+/** {@link focusVisibleStyles} as a composable `css` payload. */
+export const focusVisible: ComponentStyles = rawCss(FOCUS_VISIBLE_TEXT);
+
+const SR_ONLY_TEXT = `
   .sr-only {
     position: absolute;
     width: 1px;
@@ -33,3 +83,20 @@ export const srOnlyStyles = `
     border-width: 0;
   }
 `;
+
+/** Visually-hidden utility for screen-reader-only text. */
+export const srOnlyStyles = SR_ONLY_TEXT;
+
+/** {@link srOnlyStyles} as a composable `css` payload. */
+export const srOnly: ComponentStyles = rawCss(SR_ONLY_TEXT);
+
+const RESET_TEXT = `
+  *, *::before, *::after { box-sizing: border-box; }
+  :host([hidden]) { display: none !important; }
+`;
+
+/**
+ * Minimal per-component reset. Every component repeats the same box-sizing and
+ * `[hidden]` rules, so they live here once.
+ */
+export const reset: ComponentStyles = rawCss(RESET_TEXT);
diff --git a/stories/avatar-group.stories.ts b/stories/avatar-group.stories.ts
new file mode 100644
index 0000000..92d6786
--- /dev/null
+++ b/stories/avatar-group.stories.ts
@@ -0,0 +1,32 @@
+import type { Meta, StoryObj } from '@storybook/web-components';
+import { storyHtml } from '@bquery/bquery/storybook';
+
+/**
+ * Stacks avatars and collapses the remainder into a `+N` counter.
+ */
+const meta: Meta = {
+  title: 'Components/Avatar Group',
+  tags: ['autodocs'],
+  render: (args) => storyHtml`
+    <bq-avatar-group max=${args.max} size=${args.size} spacing=${args.spacing}>
+      <bq-avatar initials="AB"></bq-avatar>
+      <bq-avatar initials="CD"></bq-avatar>
+      <bq-avatar initials="EF"></bq-avatar>
+      <bq-avatar initials="GH"></bq-avatar>
+      <bq-avatar initials="IJ"></bq-avatar>
+    </bq-avatar-group>
+  `,
+  argTypes: {
+    max:     { control: { type: 'number', min: 0, max: 5 } },
+    size:    { control: 'select', options: ['xs','sm','md','lg','xl'] },
+    spacing: { control: 'select', options: ['tight','normal','loose'] },
+  },
+  args: { max: 3, size: 'md', spacing: 'normal' },
+};
+export default meta;
+type Story = StoryObj;
+
+export const Default: Story = {};
+export const ShowAll: Story = { args: { max: 0 } };
+export const Small: Story = { args: { size: 'sm', max: 3 } };
+export const Tight: Story = { args: { spacing: 'tight' } };
diff --git a/stories/banner.stories.ts b/stories/banner.stories.ts
new file mode 100644
index 0000000..a962edc
--- /dev/null
+++ b/stories/banner.stories.ts
@@ -0,0 +1,55 @@
+import type { Meta, StoryObj } from '@storybook/web-components';
+import { storyHtml } from '@bquery/bquery/storybook';
+
+/**
+ * Full-width page-level announcement. Use `bq-alert` for section-scoped messages
+ * and `bq-toast` for transient notifications.
+ */
+const meta: Meta = {
+  title: 'Components/Banner',
+  tags: ['autodocs'],
+  render: (args) => storyHtml`
+    <bq-banner variant=${args.variant} ?dismissible=${args.dismissible} ?sticky=${args.sticky}>
+      ${args.message}
+    </bq-banner>
+  `,
+  argTypes: {
+    variant:     { control: 'select', options: ['info','success','warning','danger','neutral'] },
+    dismissible: { control: 'boolean' },
+    sticky:      { control: 'boolean' },
+    message:     { control: 'text' },
+  },
+  args: {
+    variant: 'info',
+    dismissible: false,
+    sticky: false,
+    message: 'Scheduled maintenance on Sunday, 02:00–04:00 UTC.',
+  },
+};
+export default meta;
+type Story = StoryObj;
+
+export const Info: Story = {};
+export const Warning: Story = { args: { variant: 'warning', message: 'Your trial ends in 3 days.' } };
+export const Danger: Story = { args: { variant: 'danger', message: 'We could not process your last payment.' } };
+export const Dismissible: Story = { args: { dismissible: true, variant: 'warning', message: 'Your trial ends in 3 days.' } };
+export const WithIconAndActions: Story = {
+  render: () => storyHtml`
+    <bq-banner variant="warning" dismissible>
+      <span slot="icon">⚠️</span>
+      Your trial ends in 3 days.
+      <bq-button slot="actions" size="sm">Upgrade</bq-button>
+    </bq-banner>
+  `,
+};
+export const AllVariants: Story = {
+  render: () => storyHtml`
+    <div style="display:flex;flex-direction:column;gap:0.5rem">
+      <bq-banner variant="info">Informational message</bq-banner>
+      <bq-banner variant="success">Everything worked</bq-banner>
+      <bq-banner variant="warning">Something needs attention</bq-banner>
+      <bq-banner variant="danger">Something went wrong</bq-banner>
+      <bq-banner variant="neutral">Neutral notice</bq-banner>
+    </div>
+  `,
+};
diff --git a/stories/button-group.stories.ts b/stories/button-group.stories.ts
new file mode 100644
index 0000000..58ea505
--- /dev/null
+++ b/stories/button-group.stories.ts
@@ -0,0 +1,36 @@
+import type { Meta, StoryObj } from '@storybook/web-components';
+import { storyHtml } from '@bquery/bquery/storybook';
+
+/**
+ * Joins related buttons into a single visual control. For a single-choice
+ * control prefer `bq-segmented-control`, which has radio-group semantics.
+ */
+const meta: Meta = {
+  title: 'Components/Button Group',
+  tags: ['autodocs'],
+  render: (args) => storyHtml`
+    <bq-button-group
+      orientation=${args.orientation}
+      size=${args.size}
+      ?attached=${args.attached}
+      label="Text alignment"
+    >
+      <bq-button variant="outline">Left</bq-button>
+      <bq-button variant="outline">Center</bq-button>
+      <bq-button variant="outline">Right</bq-button>
+    </bq-button-group>
+  `,
+  argTypes: {
+    orientation: { control: 'select', options: ['horizontal','vertical'] },
+    size:        { control: 'select', options: ['sm','md','lg'] },
+    attached:    { control: 'boolean' },
+  },
+  args: { orientation: 'horizontal', size: 'md', attached: false },
+};
+export default meta;
+type Story = StoryObj;
+
+export const Default: Story = {};
+export const Attached: Story = { args: { attached: true } };
+export const Vertical: Story = { args: { orientation: 'vertical', attached: true } };
+export const Small: Story = { args: { size: 'sm', attached: true } };
diff --git a/stories/file-upload.stories.ts b/stories/file-upload.stories.ts
new file mode 100644
index 0000000..f37541b
--- /dev/null
+++ b/stories/file-upload.stories.ts
@@ -0,0 +1,44 @@
+import type { Meta, StoryObj } from '@storybook/web-components';
+import { storyHtml } from '@bquery/bquery/storybook';
+
+/**
+ * Drop zone backed by a native file input, with client-side type and size
+ * filtering. Drag and drop is an enhancement; the zone is a real button.
+ */
+const meta: Meta = {
+  title: 'Components/File Upload',
+  tags: ['autodocs'],
+  render: (args) => storyHtml`
+    <bq-file-upload
+      label=${args.label}
+      accept=${args.accept}
+      hint=${args.hint}
+      error=${args.error}
+      max-size=${args.maxSize}
+      ?multiple=${args.multiple}
+      ?disabled=${args.disabled}
+    ></bq-file-upload>
+  `,
+  argTypes: {
+    label:    { control: 'text' },
+    accept:   { control: 'text' },
+    hint:     { control: 'text' },
+    error:    { control: 'text' },
+    maxSize:  { control: 'number' },
+    multiple: { control: 'boolean' },
+    disabled: { control: 'boolean' },
+  },
+  args: {
+    label: 'Attachments', accept: '', hint: '', error: '',
+    maxSize: 0, multiple: false, disabled: false,
+  },
+};
+export default meta;
+type Story = StoryObj;
+
+export const Default: Story = {};
+export const Multiple: Story = { args: { multiple: true, hint: 'Select as many files as you like' } };
+export const ImagesOnly: Story = { args: { accept: 'image/*', hint: 'Images only' } };
+export const SizeLimited: Story = { args: { maxSize: 5242880, hint: 'Up to 5 MB per file' } };
+export const WithError: Story = { args: { error: 'Upload failed, please try again' } };
+export const Disabled: Story = { args: { disabled: true } };
diff --git a/stories/kbd.stories.ts b/stories/kbd.stories.ts
new file mode 100644
index 0000000..fb7fde5
--- /dev/null
+++ b/stories/kbd.stories.ts
@@ -0,0 +1,33 @@
+import type { Meta, StoryObj } from '@storybook/web-components';
+import { storyHtml } from '@bquery/bquery/storybook';
+
+/**
+ * Renders a keystroke or key combination. Common key names are replaced with their symbol.
+ */
+const meta: Meta = {
+  title: 'Components/Kbd',
+  tags: ['autodocs'],
+  render: (args) => storyHtml`<bq-kbd keys=${args.keys} size=${args.size} variant=${args.variant}></bq-kbd>`,
+  argTypes: {
+    keys:    { control: 'text' },
+    size:    { control: 'select', options: ['sm','md','lg'] },
+    variant: { control: 'select', options: ['solid','outline'] },
+  },
+  args: { keys: 'Ctrl+K', size: 'md', variant: 'solid' },
+};
+export default meta;
+type Story = StoryObj;
+
+export const Default: Story = {};
+export const Outline: Story = { args: { variant: 'outline' } };
+export const SingleKey: Story = { args: { keys: 'Esc' } };
+export const Symbols: Story = { args: { keys: 'Cmd+Shift+Enter' } };
+export const Sizes: Story = {
+  render: () => storyHtml`
+    <div style="display:flex;gap:0.75rem;align-items:center">
+      <bq-kbd size="sm" keys="Ctrl+C"></bq-kbd>
+      <bq-kbd size="md" keys="Ctrl+C"></bq-kbd>
+      <bq-kbd size="lg" keys="Ctrl+C"></bq-kbd>
+    </div>
+  `,
+};
diff --git a/stories/number-input.stories.ts b/stories/number-input.stories.ts
new file mode 100644
index 0000000..ef48b66
--- /dev/null
+++ b/stories/number-input.stories.ts
@@ -0,0 +1,60 @@
+import type { Meta, StoryObj } from '@storybook/web-components';
+import { storyHtml } from '@bquery/bquery/storybook';
+
+/**
+ * Numeric field with stepper buttons, range clamping and step snapping.
+ */
+const meta: Meta = {
+  title: 'Components/Number Input',
+  tags: ['autodocs'],
+  render: (args) => storyHtml`
+    <bq-number-input
+      label=${args.label}
+      value=${args.value}
+      min=${args.min}
+      max=${args.max}
+      step=${args.step}
+      size=${args.size}
+      hint=${args.hint}
+      error=${args.error}
+      ?disabled=${args.disabled}
+      ?readonly=${args.readonly}
+    ></bq-number-input>
+  `,
+  argTypes: {
+    label:    { control: 'text' },
+    value:    { control: 'number' },
+    min:      { control: 'number' },
+    max:      { control: 'number' },
+    step:     { control: 'number' },
+    size:     { control: 'select', options: ['sm','md','lg'] },
+    hint:     { control: 'text' },
+    error:    { control: 'text' },
+    disabled: { control: 'boolean' },
+    readonly: { control: 'boolean' },
+  },
+  args: {
+    label: 'Quantity', value: 1, min: 1, max: 99, step: 1,
+    size: 'md', hint: '', error: '', disabled: false, readonly: false,
+  },
+};
+export default meta;
+type Story = StoryObj;
+
+export const Default: Story = {};
+export const WithHint: Story = { args: { hint: 'Between 1 and 99' } };
+export const WithError: Story = { args: { value: 99, error: 'Maximum is 20' } };
+export const Decimals: Story = { args: { label: 'Weight', value: 2.5, min: 0, max: 10, step: 0.5 } };
+export const Disabled: Story = { args: { disabled: true, value: 5 } };
+export const WithAffixes: Story = {
+  render: () => storyHtml`
+    <div style="display:flex;flex-direction:column;gap:1rem;max-width:16rem">
+      <bq-number-input label="Price" value="20" min="0" step="0.01">
+        <span slot="prefix">€</span>
+      </bq-number-input>
+      <bq-number-input label="Duration" value="30" min="0" step="5">
+        <span slot="suffix">min</span>
+      </bq-number-input>
+    </div>
+  `,
+};
diff --git a/stories/popover.stories.ts b/stories/popover.stories.ts
new file mode 100644
index 0000000..50876b0
--- /dev/null
+++ b/stories/popover.stories.ts
@@ -0,0 +1,49 @@
+import type { Meta, StoryObj } from '@storybook/web-components';
+import { storyHtml } from '@bquery/bquery/storybook';
+
+/**
+ * Rich overlay anchored to a trigger. Unlike `bq-tooltip` it holds interactive
+ * content, opens on click, and manages focus.
+ */
+const meta: Meta = {
+  title: 'Components/Popover',
+  tags: ['autodocs'],
+  render: (args) => storyHtml`
+    <div style="padding:5rem;display:flex;justify-content:center">
+      <bq-popover
+        placement=${args.placement}
+        heading=${args.heading}
+        ?dismissible=${args.dismissible}
+        ?arrow=${args.arrow}
+      >
+        <bq-button slot="trigger">Open popover</bq-button>
+        Choose how results are sorted and filtered.
+      </bq-popover>
+    </div>
+  `,
+  argTypes: {
+    placement:   { control: 'select', options: ['top','bottom','left','right','bottom-start','bottom-end','top-start','top-end'] },
+    heading:     { control: 'text' },
+    dismissible: { control: 'boolean' },
+    arrow:       { control: 'boolean' },
+  },
+  args: { placement: 'bottom', heading: 'Filters', dismissible: true, arrow: true },
+};
+export default meta;
+type Story = StoryObj;
+
+export const Default: Story = {};
+export const Top: Story = { args: { placement: 'top' } };
+export const NoHeading: Story = { args: { heading: '', dismissible: false } };
+export const WithFooter: Story = {
+  render: () => storyHtml`
+    <div style="padding:5rem;display:flex;justify-content:center">
+      <bq-popover heading="Delete project">
+        <bq-button slot="trigger" variant="danger">Delete</bq-button>
+        This cannot be undone.
+        <bq-button slot="footer" variant="ghost" size="sm">Cancel</bq-button>
+        <bq-button slot="footer" variant="danger" size="sm">Delete</bq-button>
+      </bq-popover>
+    </div>
+  `,
+};
diff --git a/stories/rating.stories.ts b/stories/rating.stories.ts
new file mode 100644
index 0000000..957a6e3
--- /dev/null
+++ b/stories/rating.stories.ts
@@ -0,0 +1,46 @@
+import type { Meta, StoryObj } from '@storybook/web-components';
+import { storyHtml } from '@bquery/bquery/storybook';
+
+/**
+ * Star rating input with radio-group semantics and full keyboard support.
+ */
+const meta: Meta = {
+  title: 'Components/Rating',
+  tags: ['autodocs'],
+  render: (args) => storyHtml`
+    <bq-rating
+      value=${args.value}
+      max=${args.max}
+      size=${args.size}
+      ?readonly=${args.readonly}
+      ?disabled=${args.disabled}
+      ?clearable=${args.clearable}
+    ></bq-rating>
+  `,
+  argTypes: {
+    value:     { control: { type: 'number', min: 0, max: 10 } },
+    max:       { control: { type: 'number', min: 1, max: 10 } },
+    size:      { control: 'select', options: ['sm','md','lg'] },
+    readonly:  { control: 'boolean' },
+    disabled:  { control: 'boolean' },
+    clearable: { control: 'boolean' },
+  },
+  args: { value: 3, max: 5, size: 'md', readonly: false, disabled: false, clearable: false },
+};
+export default meta;
+type Story = StoryObj;
+
+export const Default: Story = {};
+export const ReadOnly: Story = { args: { readonly: true, value: 4 } };
+export const Disabled: Story = { args: { disabled: true, value: 2 } };
+export const Clearable: Story = { args: { clearable: true } };
+export const TenStars: Story = { args: { max: 10, value: 7 } };
+export const Sizes: Story = {
+  render: () => storyHtml`
+    <div style="display:flex;flex-direction:column;gap:0.5rem;align-items:flex-start">
+      <bq-rating size="sm" value="3"></bq-rating>
+      <bq-rating size="md" value="3"></bq-rating>
+      <bq-rating size="lg" value="3"></bq-rating>
+    </div>
+  `,
+};
diff --git a/stories/stepper.stories.ts b/stories/stepper.stories.ts
new file mode 100644
index 0000000..6a318e3
--- /dev/null
+++ b/stories/stepper.stories.ts
@@ -0,0 +1,40 @@
+import type { Meta, StoryObj } from '@storybook/web-components';
+import { storyHtml } from '@bquery/bquery/storybook';
+
+/**
+ * Progress indicator for multi-step flows. Steps are declared as light-DOM
+ * children carrying `data-step`.
+ */
+const meta: Meta = {
+  title: 'Components/Stepper',
+  tags: ['autodocs'],
+  render: (args) => storyHtml`
+    <bq-stepper current=${args.current} orientation=${args.orientation} ?clickable=${args.clickable}>
+      <div data-step label="Account" description="Your details"></div>
+      <div data-step label="Shipping" description="Where it goes"></div>
+      <div data-step label="Payment" description="How you pay"></div>
+    </bq-stepper>
+  `,
+  argTypes: {
+    current:     { control: { type: 'number', min: 0, max: 2 } },
+    orientation: { control: 'select', options: ['horizontal','vertical'] },
+    clickable:   { control: 'boolean' },
+  },
+  args: { current: 1, orientation: 'horizontal', clickable: false },
+};
+export default meta;
+type Story = StoryObj;
+
+export const Default: Story = {};
+export const Vertical: Story = { args: { orientation: 'vertical' } };
+export const Clickable: Story = { args: { clickable: true, current: 2 } };
+export const FirstStep: Story = { args: { current: 0 } };
+export const WithoutDescriptions: Story = {
+  render: () => storyHtml`
+    <bq-stepper current="1">
+      <div data-step label="Cart"></div>
+      <div data-step label="Checkout"></div>
+      <div data-step label="Done"></div>
+    </bq-stepper>
+  `,
+};
diff --git a/stories/timeline.stories.ts b/stories/timeline.stories.ts
new file mode 100644
index 0000000..9ec0c28
--- /dev/null
+++ b/stories/timeline.stories.ts
@@ -0,0 +1,58 @@
+import type { Meta, StoryObj } from '@storybook/web-components';
+import { storyHtml } from '@bquery/bquery/storybook';
+
+/**
+ * Ordered list of events along a connecting line. Mark the final entry with
+ * `last` to drop its trailing connector.
+ */
+const meta: Meta = {
+  title: 'Components/Timeline',
+  tags: ['autodocs'],
+  render: (args) => storyHtml`
+    <bq-timeline variant=${args.variant}>
+      <bq-timeline-item headline="Order placed" timestamp="Mar 1" datetime="2026-03-01">
+        Payment authorized.
+      </bq-timeline-item>
+      <bq-timeline-item headline="Shipped" timestamp="Mar 3" datetime="2026-03-03" variant="info">
+        Left the warehouse.
+      </bq-timeline-item>
+      <bq-timeline-item headline="Delivered" timestamp="Mar 5" datetime="2026-03-05" variant="success" last>
+        Signed for by A. Berger.
+      </bq-timeline-item>
+    </bq-timeline>
+  `,
+  argTypes: {
+    variant: { control: 'select', options: ['default','compact'] },
+  },
+  args: { variant: 'default' },
+};
+export default meta;
+type Story = StoryObj;
+
+export const Default: Story = {};
+export const Compact: Story = { args: { variant: 'compact' } };
+export const Variants: Story = {
+  render: () => storyHtml`
+    <bq-timeline>
+      <bq-timeline-item variant="primary" headline="Created" timestamp="09:00"></bq-timeline-item>
+      <bq-timeline-item variant="info" headline="Commented" timestamp="10:15"></bq-timeline-item>
+      <bq-timeline-item variant="warning" headline="Needs review" timestamp="11:30"></bq-timeline-item>
+      <bq-timeline-item variant="danger" headline="Rejected" timestamp="13:00"></bq-timeline-item>
+      <bq-timeline-item variant="success" headline="Approved" timestamp="15:45" last></bq-timeline-item>
+    </bq-timeline>
+  `,
+};
+export const CustomMarker: Story = {
+  render: () => storyHtml`
+    <bq-timeline>
+      <bq-timeline-item headline="Deployed" timestamp="Today">
+        <span slot="marker">🚀</span>
+        Release 1.15.0 is live.
+      </bq-timeline-item>
+      <bq-timeline-item headline="Tagged" timestamp="Yesterday" last>
+        <span slot="marker">🏷️</span>
+        Version bumped.
+      </bq-timeline-item>
+    </bq-timeline>
+  `,
+};
diff --git a/tests/component-utils.test.ts b/tests/component-utils.test.ts
new file mode 100644
index 0000000..f0030e0
--- /dev/null
+++ b/tests/component-utils.test.ts
@@ -0,0 +1,191 @@
+import { beforeAll, describe, expect, it } from 'bun:test';
+import { bind, host, release, store } from '../src/utils/component.js';
+import { waitForFrame } from './helpers.js';
+
+const win = (globalThis as unknown as Record<string, unknown>)[
+  'window'
+] as Window & typeof globalThis;
+const doc = win.document as unknown as Document;
+
+describe('component scope', () => {
+  it('removes listeners registered through the scope on release', () => {
+    const owner = {};
+    const target = doc.createElement('div');
+    let calls = 0;
+    bind(owner).on(target, 'click', () => {
+      calls += 1;
+    });
+
+    target.dispatchEvent(new win.Event('click'));
+    expect(calls).toBe(1);
+
+    release(owner);
+    target.dispatchEvent(new win.Event('click'));
+    expect(calls).toBe(1);
+  });
+
+  it('ignores a nullish listener target', () => {
+    const owner = {};
+    expect(() => bind(owner).on(null, 'click', () => {})).not.toThrow();
+    expect(() => bind(owner).on(undefined, 'click', () => {})).not.toThrow();
+    release(owner);
+  });
+
+  it('runs registered disposers exactly once', () => {
+    const owner = {};
+    let disposed = 0;
+    bind(owner).add(() => {
+      disposed += 1;
+    });
+
+    release(owner);
+    release(owner);
+    expect(disposed).toBe(1);
+  });
+
+  it('lets a returned disposer deregister itself early', () => {
+    const owner = {};
+    let disposed = 0;
+    const dispose = bind(owner).add(() => {
+      disposed += 1;
+    });
+
+    dispose();
+    expect(disposed).toBe(1);
+    release(owner);
+    expect(disposed).toBe(1);
+  });
+
+  it('keeps unwinding after a disposer throws', () => {
+    const owner = {};
+    const scope = bind(owner);
+    let reached = false;
+    scope.add(() => {
+      throw new Error('boom');
+    });
+    scope.add(() => {
+      reached = true;
+    });
+
+    expect(() => release(owner)).not.toThrow();
+    expect(reached).toBe(true);
+  });
+
+  it('cancels pending timeouts on release', async () => {
+    const owner = {};
+    let fired = false;
+    bind(owner).timeout(() => {
+      fired = true;
+    }, 1);
+
+    release(owner);
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(fired).toBe(false);
+  });
+
+  it('cancels pending frames on release', async () => {
+    const owner = {};
+    let fired = false;
+    bind(owner).frame(() => {
+      fired = true;
+    });
+
+    release(owner);
+    await waitForFrame(2);
+    expect(fired).toBe(false);
+  });
+
+  it('drops a fired timeout from the scope so release stays cheap', async () => {
+    const owner = {};
+    let fired = false;
+    bind(owner).timeout(() => {
+      fired = true;
+    }, 1);
+
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(fired).toBe(true);
+    expect(() => release(owner)).not.toThrow();
+  });
+
+  it('is safe to release an owner that never bound a scope', () => {
+    expect(() => release({})).not.toThrow();
+  });
+});
+
+describe('component store', () => {
+  it('returns a stable per-owner record', () => {
+    const owner = {};
+    const first = store<{ n: number }>(owner, () => ({ n: 1 }));
+    first.n = 5;
+    const second = store<{ n: number }>(owner, () => ({ n: 1 }));
+    expect(second).toBe(first);
+    expect(second.n).toBe(5);
+  });
+
+  it('keeps separate owners isolated', () => {
+    const a = store<{ n: number }>({}, () => ({ n: 1 }));
+    const b = store<{ n: number }>({}, () => ({ n: 1 }));
+    a.n = 9;
+    expect(b.n).toBe(1);
+  });
+});
+
+describe('host()', () => {
+  it('exposes the component element state API', async () => {
+    await import('../src/components/tooltip/index.js');
+    const el = doc.createElement('bq-tooltip');
+    doc.body.appendChild(el);
+    expect(typeof host(el).getState).toBe('function');
+    expect(typeof host(el).setState).toBe('function');
+    el.remove();
+  });
+});
+
+describe('overlay teardown', () => {
+  beforeAll(async () => {
+    await import('../src/components/dialog/index.js');
+    await import('../src/components/drawer/index.js');
+    await import('../src/components/dropdown-menu/index.js');
+    await import('../src/components/tooltip/index.js');
+  });
+
+  // These components attach keydown/click listeners to `document`, which
+  // outlives the element. A missed removal keeps the whole element alive.
+  for (const tag of [
+    'bq-dialog',
+    'bq-drawer',
+    'bq-dropdown-menu',
+    'bq-tooltip',
+  ]) {
+    it(`${tag} removes its document listeners when disconnected`, async () => {
+      const added: string[] = [];
+      const removed: string[] = [];
+      const realAdd = doc.addEventListener.bind(doc);
+      const realRemove = doc.removeEventListener.bind(doc);
+      doc.addEventListener = ((type: string, ...rest: unknown[]) => {
+        added.push(type);
+        return (realAdd as (...a: unknown[]) => void)(type, ...rest);
+      }) as typeof doc.addEventListener;
+      doc.removeEventListener = ((type: string, ...rest: unknown[]) => {
+        removed.push(type);
+        return (realRemove as (...a: unknown[]) => void)(type, ...rest);
+      }) as typeof doc.removeEventListener;
+
+      try {
+        const el = doc.createElement(tag);
+        if (tag === 'bq-dropdown-menu') el.setAttribute('open', '');
+        doc.body.appendChild(el);
+        await waitForFrame(2);
+        el.remove();
+        await waitForFrame();
+
+        for (const type of new Set(added)) {
+          expect(removed).toContain(type);
+        }
+      } finally {
+        doc.addEventListener = realAdd;
+        doc.removeEventListener = realRemove;
+      }
+    });
+  }
+});
diff --git a/tests/new-components.test.ts b/tests/new-components.test.ts
new file mode 100644
index 0000000..e54d0da
--- /dev/null
+++ b/tests/new-components.test.ts
@@ -0,0 +1,461 @@
+import { beforeAll, describe, expect, it } from 'bun:test';
+import { parseKeys } from '../src/components/kbd/BqKbd.js';
+import { clampRating } from '../src/components/rating/BqRating.js';
+import {
+  normalizeNumber,
+  precisionFor,
+} from '../src/components/number-input/BqNumberInput.js';
+import {
+  formatBytes,
+  matchesAccept,
+} from '../src/components/file-upload/BqFileUpload.js';
+import { readSteps, stepStatus } from '../src/components/stepper/BqStepper.js';
+import { waitForFrame } from './helpers.js';
+
+const win = (globalThis as unknown as Record<string, unknown>)[
+  'window'
+] as Window & typeof globalThis;
+const doc = win.document as unknown as Document;
+
+function mount(tag: string, attrs: Record<string, string> = {}): HTMLElement {
+  const el = doc.createElement(tag);
+  for (const [name, value] of Object.entries(attrs)) el.setAttribute(name, value);
+  doc.body.appendChild(el);
+  return el;
+}
+
+describe('BqKbd', () => {
+  beforeAll(async () => {
+    await import('../src/components/kbd/index.js');
+  });
+
+  it('splits a combination into one key element per key', () => {
+    const el = mount('bq-kbd', { keys: 'Ctrl+Shift+K' });
+    const keys = Array.from(el.shadowRoot?.querySelectorAll('.key') ?? []);
+    expect(keys.map((k) => k.textContent)).toEqual(['Ctrl', '⇧', 'K']);
+  });
+
+  it('falls back to slotted content without `keys`', () => {
+    const el = mount('bq-kbd');
+    expect(el.shadowRoot?.querySelector('.key slot')).not.toBeNull();
+  });
+
+  it('maps known key names to symbols and passes others through', () => {
+    expect(parseKeys('cmd+enter')).toEqual(['⌘', '↵']);
+    expect(parseKeys('Ctrl + F5')).toEqual(['Ctrl', 'F5']);
+    expect(parseKeys('')).toEqual([]);
+    expect(parseKeys('a++b')).toEqual(['a', 'b']);
+  });
+});
+
+describe('BqBanner', () => {
+  beforeAll(async () => {
+    await import('../src/components/banner/index.js');
+  });
+
+  it('uses an assertive alert only for the danger variant', () => {
+    const danger = mount('bq-banner', { variant: 'danger' });
+    expect(danger.shadowRoot?.querySelector('.banner')?.getAttribute('role')).toBe('alert');
+    const info = mount('bq-banner', { variant: 'info' });
+    expect(info.shadowRoot?.querySelector('.banner')?.getAttribute('role')).toBe('status');
+  });
+
+  it('hides itself and emits bq-dismiss when dismissed', () => {
+    const el = mount('bq-banner', { dismissible: '' });
+    let detailSeen = false;
+    el.addEventListener('bq-dismiss', () => {
+      detailSeen = true;
+    });
+    (el.shadowRoot?.querySelector('.dismiss') as HTMLElement).click();
+    expect(detailSeen).toBe(true);
+    expect(el.hasAttribute('hidden')).toBe(true);
+  });
+
+  it('stays mounted when bq-dismiss is cancelled', () => {
+    const el = mount('bq-banner', { dismissible: '' });
+    el.addEventListener('bq-dismiss', (e) => e.preventDefault());
+    (el.shadowRoot?.querySelector('.dismiss') as HTMLElement).click();
+    expect(el.hasAttribute('hidden')).toBe(false);
+  });
+
+  it('omits the dismiss button unless dismissible', () => {
+    const el = mount('bq-banner');
+    expect(el.shadowRoot?.querySelector('.dismiss')).toBeNull();
+  });
+});
+
+describe('BqAvatarGroup', () => {
+  beforeAll(async () => {
+    await import('../src/components/avatar-group/index.js');
+    await import('../src/components/avatar/index.js');
+  });
+
+  it('collapses avatars past `max` into a counter', async () => {
+    const el = mount('bq-avatar-group', { max: '2' });
+    el.innerHTML = '<bq-avatar></bq-avatar>'.repeat(5);
+    await waitForFrame(2);
+
+    const overflow = el.shadowRoot?.querySelector('.overflow');
+    expect(overflow?.textContent).toBe('+3');
+    expect(overflow?.hasAttribute('hidden')).toBe(false);
+    expect(el.children[2]?.hasAttribute('data-bq-overflow-hidden')).toBe(true);
+    expect(el.children[1]?.hasAttribute('data-bq-overflow-hidden')).toBe(false);
+  });
+
+  it('shows every avatar when max is 0', async () => {
+    const el = mount('bq-avatar-group');
+    el.innerHTML = '<bq-avatar></bq-avatar>'.repeat(3);
+    await waitForFrame(2);
+    expect(el.shadowRoot?.querySelector('.overflow')?.hasAttribute('hidden')).toBe(true);
+  });
+
+  it('emits bq-overflow-click with the hidden count', async () => {
+    const el = mount('bq-avatar-group', { max: '1' });
+    el.innerHTML = '<bq-avatar></bq-avatar>'.repeat(4);
+    await waitForFrame(2);
+
+    let hidden = -1;
+    el.addEventListener('bq-overflow-click', (e) => {
+      hidden = (e as CustomEvent<{ hidden: number }>).detail.hidden;
+    });
+    (el.shadowRoot?.querySelector('.overflow') as HTMLElement).click();
+    expect(hidden).toBe(3);
+  });
+});
+
+describe('BqButtonGroup', () => {
+  beforeAll(async () => {
+    await import('../src/components/button-group/index.js');
+  });
+
+  it('exposes a labelled group role', () => {
+    const el = mount('bq-button-group', { label: 'Actions' });
+    const group = el.shadowRoot?.querySelector('.group');
+    expect(group?.getAttribute('role')).toBe('group');
+    expect(group?.getAttribute('aria-label')).toBe('Actions');
+  });
+
+  it('forwards its size to children that have none of their own', async () => {
+    const el = mount('bq-button-group', { size: 'lg' });
+    el.innerHTML = '<button></button><button size="sm"></button>';
+    await waitForFrame(2);
+    expect(el.children[0]?.getAttribute('size')).toBe('lg');
+    // An explicit child size wins over the group default.
+    expect(el.children[1]?.getAttribute('size')).toBe('sm');
+  });
+});
+
+describe('BqStepper', () => {
+  beforeAll(async () => {
+    await import('../src/components/stepper/index.js');
+  });
+
+  it('classifies steps relative to the current index', () => {
+    expect(stepStatus(0, 1)).toBe('complete');
+    expect(stepStatus(1, 1)).toBe('current');
+    expect(stepStatus(2, 1)).toBe('upcoming');
+  });
+
+  it('reads declarative [data-step] children', () => {
+    const holder = doc.createElement('div');
+    holder.innerHTML =
+      '<div data-step label="A" description="first"></div><div data-step label="B" disabled></div>';
+    expect(readSteps(holder)).toEqual([
+      { label: 'A', description: 'first', disabled: false },
+      { label: 'B', description: '', disabled: true },
+    ]);
+  });
+
+  it('marks the active step and renders a check for completed ones', () => {
+    // Steps are read in connected(), so the markup has to exist before mount.
+    const el = doc.createElement('bq-stepper');
+    el.setAttribute('current', '1');
+    el.innerHTML =
+      '<div data-step label="One"></div><div data-step label="Two"></div><div data-step label="Three"></div>';
+    doc.body.appendChild(el);
+
+    const steps = Array.from(el.shadowRoot?.querySelectorAll('.step') ?? []);
+    expect(steps).toHaveLength(3);
+    expect(steps[0]?.getAttribute('data-status')).toBe('complete');
+    expect(steps[0]?.querySelector('.marker')?.textContent).toBe('✓');
+    expect(steps[1]?.getAttribute('data-status')).toBe('current');
+    expect(steps[1]?.getAttribute('aria-current')).toBe('step');
+    expect(steps[2]?.getAttribute('data-status')).toBe('upcoming');
+  });
+
+  it('emits bq-step-change only when clickable', () => {
+    const el = doc.createElement('bq-stepper');
+    el.setAttribute('current', '2');
+    el.setAttribute('clickable', '');
+    el.innerHTML = '<div data-step label="One"></div><div data-step label="Two"></div>';
+    doc.body.appendChild(el);
+
+    let index = -1;
+    el.addEventListener('bq-step-change', (e) => {
+      index = (e as CustomEvent<{ index: number }>).detail.index;
+    });
+    (el.shadowRoot?.querySelector('button.step[data-index="0"]') as HTMLElement)?.click();
+    expect(index).toBe(0);
+    expect(el.getAttribute('current')).toBe('0');
+  });
+
+  it('renders non-interactive steps when not clickable', () => {
+    const el = doc.createElement('bq-stepper');
+    el.innerHTML = '<div data-step label="One"></div>';
+    doc.body.appendChild(el);
+    expect(el.shadowRoot?.querySelector('.step')).not.toBeNull();
+    expect(el.shadowRoot?.querySelector('button.step')).toBeNull();
+  });
+});
+
+describe('BqTimeline', () => {
+  beforeAll(async () => {
+    await import('../src/components/timeline/index.js');
+  });
+
+  it('renders an ordered list with an accessible name', () => {
+    const el = mount('bq-timeline');
+    const list = el.shadowRoot?.querySelector('ol');
+    expect(list).not.toBeNull();
+    expect(list?.getAttribute('aria-label')).toBe('Timeline');
+  });
+
+  it('renders a machine-readable time when datetime is set', () => {
+    const el = mount('bq-timeline-item', {
+      headline: 'Shipped',
+      timestamp: 'Mar 3',
+      datetime: '2026-03-03',
+    });
+    const time = el.shadowRoot?.querySelector('time');
+    expect(time?.getAttribute('datetime')).toBe('2026-03-03');
+    expect(time?.textContent).toBe('Mar 3');
+    expect(el.shadowRoot?.querySelector('.headline')?.textContent).toBe('Shipped');
+  });
+
+  it('omits the time element when no timestamp is given', () => {
+    const el = mount('bq-timeline-item', { headline: 'Only headline' });
+    expect(el.shadowRoot?.querySelector('time')).toBeNull();
+  });
+});
+
+describe('BqRating', () => {
+  beforeAll(async () => {
+    await import('../src/components/rating/index.js');
+  });
+
+  it('clamps values into range', () => {
+    expect(clampRating(7, 5)).toBe(5);
+    expect(clampRating(-2, 5)).toBe(0);
+    expect(clampRating(Number.NaN, 5)).toBe(0);
+    expect(clampRating(3, 5)).toBe(3);
+  });
+
+  it('fills stars up to the current value', () => {
+    const el = mount('bq-rating', { value: '3', max: '5' });
+    const stars = Array.from(el.shadowRoot?.querySelectorAll('.star') ?? []);
+    expect(stars).toHaveLength(5);
+    expect(stars.filter((s) => s.getAttribute('data-filled') === 'true')).toHaveLength(3);
+    expect(el.shadowRoot?.querySelector('.rating')?.getAttribute('role')).toBe('radiogroup');
+  });
+
+  it('commits a new value on click', () => {
+    const el = mount('bq-rating', { value: '1', max: '5' });
+    let value = -1;
+    el.addEventListener('bq-change', (e) => {
+      value = (e as CustomEvent<{ value: number }>).detail.value;
+    });
+    (el.shadowRoot?.querySelector('.star[data-value="4"]') as HTMLElement).click();
+    expect(value).toBe(4);
+    expect(el.getAttribute('value')).toBe('4');
+  });
+
+  it('ignores clicks when readonly or disabled', () => {
+    for (const attr of ['readonly', 'disabled']) {
+      const el = mount('bq-rating', { value: '2', max: '5', [attr]: '' });
+      (el.shadowRoot?.querySelector('.star[data-value="5"]') as HTMLElement).click();
+      expect(el.getAttribute('value')).toBe('2');
+    }
+  });
+
+  it('clears back to zero when clearable and re-selected', () => {
+    const el = mount('bq-rating', { value: '3', max: '5', clearable: '' });
+    (el.shadowRoot?.querySelector('.star[data-value="3"]') as HTMLElement).click();
+    expect(el.getAttribute('value')).toBe('0');
+  });
+
+  it('registers a hidden input for form participation', () => {
+    const form = doc.createElement('form');
+    doc.body.appendChild(form);
+    const el = doc.createElement('bq-rating');
+    el.setAttribute('name', 'score');
+    el.setAttribute('value', '4');
+    form.appendChild(el);
+
+    const proxy = form.querySelector('input[data-bq-form-proxy]') as HTMLInputElement | null;
+    expect(proxy?.name).toBe('score');
+    expect(proxy?.value).toBe('4');
+  });
+});
+
+describe('BqNumberInput', () => {
+  beforeAll(async () => {
+    await import('../src/components/number-input/index.js');
+  });
+
+  it('derives display precision from step', () => {
+    expect(precisionFor(1, -1)).toBe(0);
+    expect(precisionFor(0.25, -1)).toBe(2);
+    expect(precisionFor(0.1, 3)).toBe(3);
+  });
+
+  it('clamps and snaps to the step grid', () => {
+    expect(normalizeNumber(7, 0, 5, 1, 0)).toBe(5);
+    expect(normalizeNumber(-3, 0, 5, 1, 0)).toBe(0);
+    expect(normalizeNumber(2.4, 0, 10, 0.5, 1)).toBe(2.5);
+    expect(normalizeNumber(Number.NaN, 2, 10, 1, 0)).toBe(2);
+  });
+
+  it('avoids float drift when stepping by tenths', () => {
+    expect(normalizeNumber(0.1 + 0.2, 0, 1, 0.1, 1)).toBe(0.3);
+  });
+
+  it('increments and decrements through the stepper buttons', () => {
+    const el = mount('bq-number-input', { value: '5', min: '0', max: '10', step: '1' });
+    let value = -1;
+    el.addEventListener('bq-change', (e) => {
+      value = (e as CustomEvent<{ value: number }>).detail.value;
+    });
+
+    (el.shadowRoot?.querySelector('[data-action="increment"]') as HTMLElement).click();
+    expect(value).toBe(6);
+    expect(el.getAttribute('value')).toBe('6');
+
+    (el.shadowRoot?.querySelector('[data-action="decrement"]') as HTMLElement).click();
+    expect(value).toBe(5);
+  });
+
+  it('disables the stepper button at each bound', () => {
+    const atMax = mount('bq-number-input', { value: '10', min: '0', max: '10' });
+    expect(
+      (atMax.shadowRoot?.querySelector('[data-action="increment"]') as HTMLButtonElement).disabled
+    ).toBe(true);
+
+    const atMin = mount('bq-number-input', { value: '0', min: '0', max: '10' });
+    expect(
+      (atMin.shadowRoot?.querySelector('[data-action="decrement"]') as HTMLButtonElement).disabled
+    ).toBe(true);
+  });
+
+  it('links hint and error text to the field', () => {
+    const el = mount('bq-number-input', { hint: 'Between 1 and 9', label: 'Qty' });
+    const input = el.shadowRoot?.querySelector('input');
+    const hint = el.shadowRoot?.querySelector('.hint');
+    expect(input?.getAttribute('aria-describedby')).toBe(hint?.id);
+
+    const invalid = mount('bq-number-input', { error: 'Too large' });
+    const field = invalid.shadowRoot?.querySelector('input');
+    expect(field?.getAttribute('aria-invalid')).toBe('true');
+    expect(invalid.shadowRoot?.querySelector('.error')?.getAttribute('role')).toBe('alert');
+  });
+});
+
+describe('BqFileUpload', () => {
+  beforeAll(async () => {
+    await import('../src/components/file-upload/index.js');
+  });
+
+  it('formats byte sizes', () => {
+    expect(formatBytes(0)).toBe('0 B');
+    expect(formatBytes(512)).toBe('512 B');
+    expect(formatBytes(2048)).toBe('2.0 KB');
+    expect(formatBytes(5 * 1024 * 1024)).toBe('5.0 MB');
+  });
+
+  it('matches extensions, wildcards and exact MIME types', () => {
+    const png = { name: 'a.PNG', type: 'image/png', size: 1 } as File;
+    expect(matchesAccept(png, '')).toBe(true);
+    expect(matchesAccept(png, '.png')).toBe(true);
+    expect(matchesAccept(png, 'image/*')).toBe(true);
+    expect(matchesAccept(png, 'image/png')).toBe(true);
+    expect(matchesAccept(png, '.pdf,text/plain')).toBe(false);
+  });
+
+  it('renders an accessible drop zone', () => {
+    const el = mount('bq-file-upload', { label: 'Attachments' });
+    expect(el.shadowRoot?.querySelector('.zone')).not.toBeNull();
+    expect(el.shadowRoot?.querySelector('input[type="file"]')).not.toBeNull();
+    expect(el.shadowRoot?.querySelector('.label')?.textContent).toBe('Attachments');
+  });
+
+  it('forwards accept and multiple to the native input', () => {
+    const el = mount('bq-file-upload', { accept: '.png,.jpg', multiple: '' });
+    const input = el.shadowRoot?.querySelector('input[type="file"]') as HTMLInputElement;
+    expect(input.getAttribute('accept')).toBe('.png,.jpg');
+    expect(input.hasAttribute('multiple')).toBe(true);
+  });
+
+  it('flags the drop zone while a drag is over it', () => {
+    const el = mount('bq-file-upload');
+    const over = new win.Event('dragover', { bubbles: true, cancelable: true });
+    el.dispatchEvent(over);
+    expect(el.hasAttribute('data-dragging')).toBe(true);
+
+    el.dispatchEvent(new win.Event('dragleave', { bubbles: true }));
+    expect(el.hasAttribute('data-dragging')).toBe(false);
+  });
+});
+
+describe('BqPopover', () => {
+  beforeAll(async () => {
+    await import('../src/components/popover/index.js');
+  });
+
+  it('toggles open on trigger click and closes on Escape', async () => {
+    const el = mount('bq-popover', { heading: 'Details' });
+    el.innerHTML = '<button slot="trigger">Open</button>Body';
+    await waitForFrame(2);
+
+    const trigger = el.querySelector('[slot="trigger"]') as HTMLElement;
+    trigger.click();
+    expect(el.hasAttribute('open')).toBe(true);
+
+    el.dispatchEvent(
+      new win.KeyboardEvent('keydown', { key: 'Escape', bubbles: true })
+    );
+    expect(el.hasAttribute('open')).toBe(false);
+  });
+
+  it('marks the panel as a labelled dialog', () => {
+    const el = mount('bq-popover', { heading: 'Details' });
+    const panel = el.shadowRoot?.querySelector('.panel');
+    expect(panel?.getAttribute('role')).toBe('dialog');
+    expect(panel?.getAttribute('aria-labelledby')).toBe(
+      el.shadowRoot?.querySelector('.heading')?.id
+    );
+  });
+
+  it('closes through the dismiss button', async () => {
+    const el = mount('bq-popover', { heading: 'Details', open: '' });
+    el.innerHTML = '<button slot="trigger">Open</button>';
+    await waitForFrame(2);
+
+    let closed = false;
+    el.addEventListener('bq-close', () => {
+      closed = true;
+    });
+    (el.shadowRoot?.querySelector('.close') as HTMLElement).click();
+    expect(closed).toBe(true);
+    expect(el.hasAttribute('open')).toBe(false);
+  });
+
+  it('reflects expanded state onto the trigger', async () => {
+    const el = mount('bq-popover');
+    el.innerHTML = '<button slot="trigger">Open</button>';
+    await waitForFrame(2);
+
+    const trigger = el.querySelector('[slot="trigger"]') as HTMLElement;
+    trigger.click();
+    expect(trigger.getAttribute('aria-expanded')).toBe('true');
+    expect(trigger.getAttribute('aria-haspopup')).toBe('dialog');
+  });
+});
diff --git a/tests/styles.test.ts b/tests/styles.test.ts
new file mode 100644
index 0000000..3d8044d
--- /dev/null
+++ b/tests/styles.test.ts
@@ -0,0 +1,74 @@
+import { describe, expect, it } from 'bun:test';
+import { isComponentStyles } from '@bquery/bquery/component';
+import {
+  baseStyles,
+  focusVisible,
+  focusVisibleStyles,
+  getBaseStyles,
+  rawCss,
+  reset,
+  srOnly,
+  srOnlyStyles,
+} from '../src/utils/styles.js';
+
+describe('style payloads', () => {
+  it('exposes the shared fragments as ComponentStyles payloads', () => {
+    for (const payload of [baseStyles, focusVisible, srOnly, reset]) {
+      expect(isComponentStyles(payload)).toBe(true);
+    }
+  });
+
+  it('keeps the string exports in sync with the css payloads', () => {
+    expect(baseStyles.text).toBe(getBaseStyles());
+    expect(focusVisible.text).toBe(focusVisibleStyles);
+    expect(srOnly.text).toBe(srOnlyStyles);
+  });
+
+  it('round-trips CSS through rawCss without escaping', () => {
+    // `css` escapes interpolated *values*; rawCss must pass trusted CSS text
+    // through verbatim or every composed stylesheet would be corrupted.
+    const source = `.a { content: "x"; font-family: 'y'; }\n@media (min-width: 10px) { .b { color: red; } }`;
+    expect(rawCss(source).text).toBe(source);
+  });
+
+  it('preserves braces, quotes and semicolons when composed into a css template', () => {
+    const composed = rawCss(`${baseStyles.text}`);
+    expect(composed.text).toContain('{');
+    expect(composed.text).toContain('}');
+    expect(composed.text).toContain(';');
+    expect(composed.text).not.toContain('\\7b');
+  });
+
+  it('produces an adoptable stylesheet when the environment supports it', () => {
+    // happy-dom does not ship Constructable Stylesheets, so stand one up to
+    // prove the payloads take the shared-stylesheet path in real browsers
+    // rather than the per-instance <style> fallback.
+    const g = globalThis as unknown as Record<string, unknown>;
+    const original = g['CSSStyleSheet'];
+    class FakeSheet {
+      cssText = '';
+      replaceSync(text: string): void {
+        this.cssText = text;
+      }
+    }
+    g['CSSStyleSheet'] = FakeSheet;
+    try {
+      const payload = rawCss('.adoptable { color: red; }');
+      const sheet = payload.toAdoptableSheet();
+      expect(sheet).not.toBeNull();
+      expect((sheet as unknown as FakeSheet).cssText).toBe(payload.text);
+      // Repeated construction for identical text reuses one shared sheet.
+      expect(rawCss('.adoptable { color: red; }').toAdoptableSheet()).toBe(sheet);
+    } finally {
+      if (original === undefined) delete g['CSSStyleSheet'];
+      else g['CSSStyleSheet'] = original;
+    }
+  });
+
+  it('emits the token block and both color schemes exactly once', () => {
+    const text = baseStyles.text;
+    expect(text).toContain('--bq-color-primary-600');
+    expect(text).toContain('--bq-bg-base: #ffffff');
+    expect(text).toContain('[data-theme="dark"]');
+  });
+});

From 9175a82b946b59b1c8105165606099bcaa2e4a73 Mon Sep 17 00:00:00 2001
From: Jonas Pfalzgraf <jolun.swtor@gmail.com>
Date: Fri, 31 Jul 2026 12:43:11 +0000
Subject: [PATCH 2/5] expanding

---
 src/components/accordion/BqAccordion.ts       |  41 +-
 src/components/alert/BqAlert.ts               |  11 +-
 src/components/breadcrumbs/BqBreadcrumbs.ts   |  35 +-
 src/components/button/BqButton.ts             |  15 +-
 src/components/checkbox/BqCheckbox.ts         |  40 +-
 src/components/chip/BqChip.ts                 |  21 +-
 src/components/combobox/BqCombobox.ts         | 732 ++++++++++++++++++
 src/components/combobox/index.ts              |   1 +
 .../dropdown-menu/BqDropdownMenu.ts           |  38 +-
 src/components/icon-button/BqIconButton.ts    |  13 +-
 src/components/index.ts                       |   2 +
 src/components/input/BqInput.ts               |  78 +-
 src/components/number-input/BqNumberInput.ts  |   8 +
 src/components/pagination/BqPagination.ts     |  10 +-
 src/components/popover/BqPopover.ts           |  45 +-
 src/components/radio/BqRadio.ts               |  39 +-
 .../segmented-control/BqSegmentedControl.ts   |  82 +-
 src/components/select/BqSelect.ts             |  89 ++-
 src/components/slider/BqSlider.ts             |  42 +-
 src/components/switch/BqSwitch.ts             |  34 +-
 src/components/table/BqTable.ts               |  18 +-
 src/components/tabs/BqTabs.ts                 |  18 +-
 src/components/tag-input/BqTagInput.ts        | 398 ++++++++++
 src/components/tag-input/index.ts             |   1 +
 src/components/textarea/BqTextarea.ts         |  79 +-
 src/components/toast/BqToast.ts               |  19 +-
 src/components/tooltip/BqTooltip.ts           |  50 +-
 src/i18n/en.ts                                |  30 +
 src/index.ts                                  |   4 +
 src/utils/focus.ts                            | 161 ++++
 src/utils/form.ts                             |  96 +++
 src/utils/index.ts                            |  39 +-
 src/utils/position.ts                         | 558 +++++++++++++
 src/utils/validation.ts                       | 424 ++++++++++
 tests/combobox.test.ts                        | 469 +++++++++++
 tests/focus-preservation.test.ts              | 169 ++++
 tests/position.test.ts                        | 408 ++++++++++
 tests/segmented-control.test.ts               |  46 +-
 tests/tag-input.test.ts                       | 314 ++++++++
 tests/validation.test.ts                      | 391 ++++++++++
 40 files changed, 4622 insertions(+), 446 deletions(-)
 create mode 100644 src/components/combobox/BqCombobox.ts
 create mode 100644 src/components/combobox/index.ts
 create mode 100644 src/components/tag-input/BqTagInput.ts
 create mode 100644 src/components/tag-input/index.ts
 create mode 100644 src/utils/focus.ts
 create mode 100644 src/utils/position.ts
 create mode 100644 src/utils/validation.ts
 create mode 100644 tests/combobox.test.ts
 create mode 100644 tests/focus-preservation.test.ts
 create mode 100644 tests/position.test.ts
 create mode 100644 tests/tag-input.test.ts
 create mode 100644 tests/validation.test.ts

diff --git a/src/components/accordion/BqAccordion.ts b/src/components/accordion/BqAccordion.ts
index a25e1c0..2c6c9c2 100644
--- a/src/components/accordion/BqAccordion.ts
+++ b/src/components/accordion/BqAccordion.ts
@@ -11,6 +11,8 @@
 import type { ComponentDefinition } from '@bquery/bquery/component';
 import { bool, component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
+import type { Disposer } from '../../utils/component.js';
+import { bind, release } from '../../utils/component.js';
 import { getAnimationTimeoutMs, uniqueId } from '../../utils/dom.js';
 import { baseStyles } from '../../utils/styles.js';
 
@@ -73,18 +75,17 @@ const definition: ComponentDefinition<BqAccordionProps, BqAccordionState> = {
     };
 
     const self = this as unknown as BQEl;
-    const record = self as unknown as Record<string, unknown>;
+    const scope = bind(self);
 
     if (!self.getState<string>('uid')) self.setState('uid', uniqueId('bq-acc'));
 
+    // The exit-animation fallback timer is scope-owned so an accordion
+    // collapsed and then removed mid-animation cannot fire against a
+    // detached element.
+    let cancelCloseFallback: Disposer | null = null;
     const clearCloseFallback = () => {
-      const timeoutId = record['_closeTimeout'] as
-        | ReturnType<typeof setTimeout>
-        | undefined;
-      if (timeoutId) {
-        clearTimeout(timeoutId);
-        delete record['_closeTimeout'];
-      }
+      cancelCloseFallback?.();
+      cancelCloseFallback = null;
     };
 
     const finishClose = () => {
@@ -137,7 +138,7 @@ const definition: ComponentDefinition<BqAccordionProps, BqAccordionState> = {
         if (timeoutMs <= 0) {
           finishClose();
         } else {
-          record['_closeTimeout'] = setTimeout(
+          cancelCloseFallback = scope.timeout(
             finishClose,
             Math.ceil(timeoutMs) + 20
           );
@@ -183,26 +184,12 @@ const definition: ComponentDefinition<BqAccordionProps, BqAccordionState> = {
       finishClose();
     };
 
-    record['_handler'] = handler;
-    record['_kh'] = kh;
-    record['_ah'] = ah;
-
-    self.shadowRoot?.addEventListener('click', handler);
-    self.shadowRoot?.addEventListener('keydown', kh);
-    self.shadowRoot?.addEventListener('animationend', ah);
+    scope.on(self.shadowRoot, 'click', handler);
+    scope.on(self.shadowRoot, 'keydown', kh);
+    scope.on(self.shadowRoot, 'animationend', ah);
   },
   disconnected() {
-    const self = this as unknown as Record<string, unknown>;
-    const h = self['_handler'] as EventListener | undefined;
-    const kh = self['_kh'] as EventListener | undefined;
-    const ah = self['_ah'] as EventListener | undefined;
-    const closeTimeout = self['_closeTimeout'] as
-      | ReturnType<typeof setTimeout>
-      | undefined;
-    if (h) this.shadowRoot?.removeEventListener('click', h);
-    if (kh) this.shadowRoot?.removeEventListener('keydown', kh);
-    if (ah) this.shadowRoot?.removeEventListener('animationend', ah);
-    if (closeTimeout) clearTimeout(closeTimeout);
+    release(this);
   },
   render({ props, state }) {
     const uid = state.uid || 'bq-acc';
diff --git a/src/components/alert/BqAlert.ts b/src/components/alert/BqAlert.ts
index 62369fe..0cb75e4 100644
--- a/src/components/alert/BqAlert.ts
+++ b/src/components/alert/BqAlert.ts
@@ -10,7 +10,7 @@
 import { component, css, html } from '@bquery/bquery/component';
 import type { ComponentDefinition } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
-import { host } from '../../utils/component.js';
+import { bind, host, release } from '../../utils/component.js';
 import { baseStyles } from '../../utils/styles.js';
 import { t } from '../../i18n/index.js';
 
@@ -46,18 +46,15 @@ const definition: ComponentDefinition<BqAlertProps> = {
   `,
   connected() {
     const self = host(this);
-    const handler = (e: Event) => {
+    bind(self).on(self.shadowRoot, 'click', (e) => {
       if ((e.target as Element).closest('.close')) {
         self.setAttribute('hidden', '');
         self.dispatchEvent(new CustomEvent('bq-close', { bubbles: true, composed: true }));
       }
-    };
-    (self as unknown as Record<string, unknown>)['_handler'] = handler;
-    self.shadowRoot?.addEventListener('click', handler);
+    });
   },
   disconnected() {
-    const handler = (this as unknown as Record<string, unknown>)['_handler'] as EventListener | undefined;
-    if (handler) this.shadowRoot?.removeEventListener('click', handler);
+    release(this);
   },
   render({ props }) {
     const icons: Record<string, string> = { info: 'ℹ', success: '✓', warning: '⚠', danger: '✕' };
diff --git a/src/components/breadcrumbs/BqBreadcrumbs.ts b/src/components/breadcrumbs/BqBreadcrumbs.ts
index 3f68113..4698ad7 100644
--- a/src/components/breadcrumbs/BqBreadcrumbs.ts
+++ b/src/components/breadcrumbs/BqBreadcrumbs.ts
@@ -9,11 +9,18 @@
 import type { ComponentDefinition } from '@bquery/bquery/component';
 import { component, css, html } from '@bquery/bquery/component';
 import { t } from '../../i18n/index.js';
-import { host } from '../../utils/component.js';
+import { bind, host, release, store } from '../../utils/component.js';
 import { baseStyles } from '../../utils/styles.js';
 
 type BqBreadcrumbsProps = { separator: string };
 
+/** Per-instance callbacks `updated()` re-runs after every render. */
+const breadcrumbsStore = (owner: object) =>
+  store<{ applyAttrs?: () => void; applySeparatorVar?: () => void }>(
+    owner,
+    () => ({})
+  );
+
 /**
  * Escape a string for safe use as a CSS `content` value.
  * Wraps in quotes and backslash-escapes embedded backslashes / quotes.
@@ -48,6 +55,7 @@ const definition: ComponentDefinition<BqBreadcrumbsProps> = {
   `,
   connected() {
     const self = host(this);
+    const scope = bind(self);
     const applyAttrs = () => {
       const slot = self.shadowRoot?.querySelector(
         'slot'
@@ -70,30 +78,31 @@ const definition: ComponentDefinition<BqBreadcrumbsProps> = {
       }
       self.style.setProperty('--bq-breadcrumb-separator', cssQuote(attr));
     };
-    (self as unknown as Record<string, unknown>)['_applyAttrs'] = applyAttrs;
-    (self as unknown as Record<string, unknown>)['_applySeparatorVar'] =
-      applySeparatorVar;
+    const local = breadcrumbsStore(self);
+    local.applyAttrs = applyAttrs;
+    local.applySeparatorVar = applySeparatorVar;
     applySeparatorVar();
+
+    // The slot only exists once the first render has run. Registering the
+    // listener on the scope means an element disconnected before this
+    // microtask settles still unwinds cleanly.
     queueMicrotask(() => {
+      if (!self.isConnected) return;
       const slot = self.shadowRoot?.querySelector(
         'slot'
       ) as HTMLSlotElement | null;
       if (!slot) return;
-      slot.addEventListener('slotchange', applyAttrs);
-      (self as unknown as Record<string, unknown>)['_slot'] = slot;
+      scope.on(slot, 'slotchange', applyAttrs);
       applyAttrs();
     });
   },
   disconnected() {
-    const self = this as unknown as Record<string, unknown>;
-    const applyAttrs = self['_applyAttrs'] as EventListener | undefined;
-    const slot = self['_slot'] as HTMLSlotElement | null | undefined;
-    if (slot && applyAttrs) slot.removeEventListener('slotchange', applyAttrs);
+    release(this);
   },
   updated() {
-    const s = this as unknown as Record<string, unknown>;
-    (s['_applySeparatorVar'] as (() => void) | undefined)?.();
-    (s['_applyAttrs'] as (() => void) | undefined)?.();
+    const local = breadcrumbsStore(this);
+    local.applySeparatorVar?.();
+    local.applyAttrs?.();
   },
   render() {
     return html`
diff --git a/src/components/button/BqButton.ts b/src/components/button/BqButton.ts
index 8127a9a..bb24cf5 100644
--- a/src/components/button/BqButton.ts
+++ b/src/components/button/BqButton.ts
@@ -19,7 +19,7 @@ import type { ComponentDefinition } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { t } from '../../i18n/index.js';
 import { uniqueId } from '../../utils/dom.js';
-import { host } from '../../utils/component.js';
+import { bind, host, release } from '../../utils/component.js';
 import { baseStyles } from '../../utils/styles.js';
 
 type BqButtonProps = {
@@ -97,22 +97,17 @@ const definition: ComponentDefinition<BqButtonProps, BqButtonState> = {
     }
   `,
   connected() {
-    type BqButtonElement = HTMLElement & { setState(k: 'statusId', v: string): void; getState<T>(k: string): T };
-    const self = this as unknown as BqButtonElement;
+    const self = host<BqButtonState>(this);
     if (!self.getState<string>('statusId')) self.setState('statusId', uniqueId('bq-button-status'));
-    const handler = (e: Event) => {
+    bind(self).on(self.shadowRoot, 'click', (e) => {
       if (self.hasAttribute('disabled') || self.hasAttribute('loading')) {
         e.preventDefault(); e.stopPropagation(); return;
       }
       self.dispatchEvent(new CustomEvent('bq-click', { detail: { originalEvent: e }, bubbles: true, composed: true }));
-    };
-    (self as unknown as Record<string, unknown>)['_clickHandler'] = handler;
-    self.shadowRoot?.addEventListener('click', handler);
+    });
   },
   disconnected() {
-    const self = host(this);
-    const handler = (self as unknown as Record<string, unknown>)['_clickHandler'] as EventListener | undefined;
-    if (handler) self.shadowRoot?.removeEventListener('click', handler);
+    release(this);
   },
   render({ props, state }) {
     const tag = props.href ? 'a' : 'button';
diff --git a/src/components/checkbox/BqCheckbox.ts b/src/components/checkbox/BqCheckbox.ts
index fed8a99..046c7e3 100644
--- a/src/components/checkbox/BqCheckbox.ts
+++ b/src/components/checkbox/BqCheckbox.ts
@@ -14,8 +14,8 @@
 import type { ComponentDefinition } from '@bquery/bquery/component';
 import { bool, component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
-import { createFormProxy, type FormProxy } from '../../utils/form.js';
-import { host } from '../../utils/component.js';
+import { bindFormProxy, syncFormProxy } from '../../utils/form.js';
+import { bind, host, release } from '../../utils/component.js';
 import { baseStyles } from '../../utils/styles.js';
 
 type BqCheckboxProps = {
@@ -61,15 +61,12 @@ const definition: ComponentDefinition<BqCheckboxProps> = {
   `,
   connected() {
     const self = host(this);
+    const scope = bind(self);
 
     // Form proxy for native <form> participation
-    const name = self.getAttribute('name') ?? '';
-    const value = self.hasAttribute('checked')
-      ? self.getAttribute('value') || 'on'
-      : '';
-    const disabled = self.hasAttribute('disabled');
-    const proxy = createFormProxy(self, name, value, disabled);
-    (self as unknown as Record<string, unknown>)['_formProxy'] = proxy;
+    const readValue = () =>
+      self.hasAttribute('checked') ? self.getAttribute('value') || 'on' : '';
+    const proxy = bindFormProxy(self, scope, { value: readValue });
 
     const handler = (e: Event) => {
       const input = e.target as HTMLInputElement | null;
@@ -88,34 +85,19 @@ const definition: ComponentDefinition<BqCheckboxProps> = {
         })
       );
     };
-    (self as unknown as Record<string, unknown>)['_handler'] = handler;
-    self.shadowRoot?.addEventListener('change', handler);
+    scope.on(self.shadowRoot, 'change', handler);
   },
   disconnected() {
-    const h = (this as unknown as Record<string, unknown>)['_handler'] as
-      | EventListener
-      | undefined;
-    if (h) this.shadowRoot?.removeEventListener('change', h);
-    (
-      (this as unknown as Record<string, unknown>)['_formProxy'] as
-        | FormProxy
-        | undefined
-    )?.cleanup();
+    release(this);
   },
   updated() {
     const input = this.shadowRoot?.querySelector(
       'input'
     ) as HTMLInputElement | null;
+    // `indeterminate` is an IDL-only property, so it cannot be expressed in the
+    // rendered markup and has to be reapplied after every render.
     if (input) input.indeterminate = this.hasAttribute('indeterminate');
-    const s = this as unknown as Record<string, unknown>;
-    const proxy = s['_formProxy'] as FormProxy | undefined;
-    if (proxy) {
-      proxy.setName(this.getAttribute('name') ?? '');
-      proxy.setValue(
-        this.hasAttribute('checked') ? this.getAttribute('value') || 'on' : ''
-      );
-      proxy.setDisabled(this.hasAttribute('disabled'));
-    }
+    syncFormProxy(this);
   },
   render({ props }) {
     return html`
diff --git a/src/components/chip/BqChip.ts b/src/components/chip/BqChip.ts
index 2364bd8..b5eb42d 100644
--- a/src/components/chip/BqChip.ts
+++ b/src/components/chip/BqChip.ts
@@ -14,7 +14,7 @@ import type { ComponentDefinition } from '@bquery/bquery/component';
 import { component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { t } from '../../i18n/index.js';
-import { host } from '../../utils/component.js';
+import { bind, host, release } from '../../utils/component.js';
 import { baseStyles } from '../../utils/styles.js';
 
 type BqChipProps = {
@@ -109,22 +109,13 @@ const definition: ComponentDefinition<BqChipProps> = {
         new CustomEvent('bq-click', { bubbles: true, composed: true })
       );
     };
-    (self as unknown as Record<string, unknown>)['_handler'] = handler;
-    (self as unknown as Record<string, unknown>)['_keyHandler'] = keyHandler;
-    self.shadowRoot?.addEventListener('click', handler);
-    self.shadowRoot?.addEventListener('keydown', keyHandler);
-    self.shadowRoot?.addEventListener('keyup', keyHandler);
+    const scope = bind(self);
+    scope.on(self.shadowRoot, 'click', handler);
+    scope.on(self.shadowRoot, 'keydown', keyHandler);
+    scope.on(self.shadowRoot, 'keyup', keyHandler);
   },
   disconnected() {
-    const handler = (this as unknown as Record<string, unknown>)['_handler'] as
-      | EventListener
-      | undefined;
-    const keyHandler = (this as unknown as Record<string, unknown>)[
-      '_keyHandler'
-    ] as EventListener | undefined;
-    if (handler) this.shadowRoot?.removeEventListener('click', handler);
-    if (keyHandler) this.shadowRoot?.removeEventListener('keydown', keyHandler);
-    if (keyHandler) this.shadowRoot?.removeEventListener('keyup', keyHandler);
+    release(this);
   },
   render({ props }) {
     return html`
diff --git a/src/components/combobox/BqCombobox.ts b/src/components/combobox/BqCombobox.ts
new file mode 100644
index 0000000..a5d9ef3
--- /dev/null
+++ b/src/components/combobox/BqCombobox.ts
@@ -0,0 +1,732 @@
+/**
+ * Combobox — a text input that filters a list of options.
+ *
+ * Implements the ARIA 1.2 combobox pattern with a non-editable-or-editable
+ * text field and a popup listbox: the input carries `role="combobox"`,
+ * `aria-expanded` and `aria-controls`, and the active option is pointed at
+ * with `aria-activedescendant` rather than by moving DOM focus — so the user
+ * keeps typing while arrowing through results.
+ *
+ * Options are declared as light-DOM `<option>` elements, matching `bq-select`,
+ * so the same markup works with or without JavaScript filtering.
+ *
+ * @element bq-combobox
+ * @prop {string}  label       - Field label
+ * @prop {string}  value       - Selected value; comma-separated when `multiple`
+ * @prop {string}  placeholder
+ * @prop {string}  name        - Form field name
+ * @prop {boolean} disabled
+ * @prop {boolean} required
+ * @prop {boolean} multiple    - Allow more than one selection
+ * @prop {boolean} clearable   - Show a button that clears the selection
+ * @prop {boolean} no-filter   - Show every option; filtering is done by the host app
+ * @prop {string}  filter-mode - contains | starts-with
+ * @prop {string}  error
+ * @prop {string}  hint
+ * @prop {string}  size        - sm | md | lg
+ * @slot - `<option>` elements
+ * @fires bq-change - { value: string, values: string[] }
+ * @fires bq-input  - { query: string }
+ * @fires bq-open
+ * @fires bq-close
+ */
+import type { ComponentDefinition } from '@bquery/bquery/component';
+import { component, css, html } from '@bquery/bquery/component';
+import { escapeHtml } from '@bquery/bquery/security';
+import { t } from '../../i18n/index.js';
+import { bind, host, release, store } from '../../utils/component.js';
+import type { Disposer } from '../../utils/component.js';
+import { uniqueId } from '../../utils/dom.js';
+import { captureFocus, restoreFocus } from '../../utils/focus.js';
+import type { FocusSnapshot } from '../../utils/focus.js';
+import { bindFormProxy, syncFormProxy } from '../../utils/form.js';
+import { autoPosition } from '../../utils/position.js';
+import { baseStyles, reset, srOnly } from '../../utils/styles.js';
+import { bindValidation } from '../../utils/validation.js';
+
+type BqComboboxProps = {
+  label: string;
+  value: string;
+  placeholder: string;
+  name: string;
+  disabled: boolean;
+  required: boolean;
+  multiple: boolean;
+  clearable: boolean;
+  'no-filter': boolean;
+  'filter-mode': string;
+  error: string;
+  hint: string;
+  size: string;
+};
+
+type BqComboboxState = {
+  uid: string;
+  open: boolean;
+  query: string;
+  activeIndex: number;
+  /**
+   * Mirror of the light-DOM `<option>` children. `render()` receives only
+   * props and state — it cannot reach the host's children — so the
+   * declarative option list is synced into state by `connected()`,
+   * `updated()` and a MutationObserver.
+   */
+  options: ComboboxOption[];
+};
+
+/** A single selectable entry, read from a light-DOM `<option>`. */
+export interface ComboboxOption {
+  value: string;
+  label: string;
+  disabled: boolean;
+  group: string;
+}
+
+const comboboxStore = (owner: object) =>
+  store<{
+    snapshot?: FocusSnapshot | null;
+    syncPosition?: () => void;
+    syncOptions?: () => void;
+    stopPosition?: Disposer | null;
+  }>(owner, () => ({}));
+
+/** Reads the declarative `<option>` / `<optgroup>` children. */
+export function readOptions(el: Element): ComboboxOption[] {
+  const options: ComboboxOption[] = [];
+  const visit = (parent: Element, group: string) => {
+    for (const child of Array.from(parent.children)) {
+      const tag = child.tagName.toLowerCase();
+      if (tag === 'optgroup') {
+        visit(child, child.getAttribute('label') ?? '');
+        continue;
+      }
+      if (tag !== 'option') continue;
+      const label = child.textContent?.trim() ?? '';
+      options.push({
+        value: child.getAttribute('value') ?? label,
+        label,
+        disabled: child.hasAttribute('disabled'),
+        group,
+      });
+    }
+  };
+  visit(el, '');
+  return options;
+}
+
+/** Structural comparison, so a re-sync only re-renders on a real change. */
+function sameOptions(a: ComboboxOption[], b: ComboboxOption[]): boolean {
+  if (a.length !== b.length) return false;
+  return a.every((option, i) => {
+    const other = b[i];
+    return (
+      other !== undefined &&
+      option.value === other.value &&
+      option.label === other.label &&
+      option.disabled === other.disabled &&
+      option.group === other.group
+    );
+  });
+}
+
+/**
+ * Filters options against a query.
+ *
+ * Matching is case- and diacritic-insensitive so that typing `jose` finds
+ * `José` — a plain `toLowerCase()` comparison would not.
+ */
+export function filterOptions(
+  options: ComboboxOption[],
+  query: string,
+  mode: string = 'contains'
+): ComboboxOption[] {
+  const needle = normalizeText(query);
+  if (!needle) return options;
+  return options.filter((option) => {
+    const haystack = normalizeText(option.label);
+    return mode === 'starts-with'
+      ? haystack.startsWith(needle)
+      : haystack.includes(needle);
+  });
+}
+
+function normalizeText(value: string): string {
+  return value
+    .trim()
+    .toLowerCase()
+    .normalize('NFD')
+    .replace(/[̀-ͯ]/g, '');
+}
+
+/** Splits the `value` attribute into individual selected values. */
+export function parseValues(raw: string): string[] {
+  return raw
+    .split(',')
+    .map((part) => part.trim())
+    .filter(Boolean);
+}
+
+/**
+ * Moves the active index past disabled options.
+ * Returns `-1` when no option can be activated at all.
+ */
+export function nextEnabledIndex(
+  options: ComboboxOption[],
+  from: number,
+  step: 1 | -1
+): number {
+  if (options.length === 0) return -1;
+  let index = from;
+  for (let i = 0; i < options.length; i += 1) {
+    index = (index + step + options.length) % options.length;
+    if (!options[index]?.disabled) return index;
+  }
+  return -1;
+}
+
+const definition: ComponentDefinition<BqComboboxProps, BqComboboxState> = {
+  props: {
+    label: { type: String, default: '' },
+    value: { type: String, default: '' },
+    placeholder: { type: String, default: '' },
+    name: { type: String, default: '' },
+    disabled: { type: Boolean, default: false },
+    required: { type: Boolean, default: false },
+    multiple: { type: Boolean, default: false },
+    clearable: { type: Boolean, default: false },
+    'no-filter': { type: Boolean, default: false },
+    'filter-mode': { type: String, default: 'contains' },
+    error: { type: String, default: '' },
+    hint: { type: String, default: '' },
+    size: { type: String, default: 'md' },
+  },
+  state: { uid: '', open: false, query: '', activeIndex: -1, options: [] },
+  styles: css`
+    ${baseStyles}
+    ${reset}
+    ${srOnly}
+    :host { display: block; position: relative; }
+    .field { display: flex; flex-direction: column; gap: 0.375rem; }
+    .label {
+      font-size: var(--bq-font-size-sm,0.875rem);
+      font-weight: var(--bq-font-weight-medium,500);
+      color: var(--bq-text-base,#0f172a);
+      font-family: var(--bq-font-family-sans);
+    }
+    .required-mark { color: var(--bq-color-danger-600,#dc2626); }
+
+    .control {
+      display: flex; align-items: center; gap: 0.25rem; flex-wrap: wrap;
+      border: 1.5px solid var(--bq-border-emphasis,#cbd5e1);
+      border-radius: var(--bq-radius-lg,0.5rem);
+      background: var(--bq-bg-base,#fff);
+      padding: 0.25rem 0.375rem;
+      transition: border-color var(--bq-duration-fast) var(--bq-easing-standard),
+                  box-shadow var(--bq-duration-fast) var(--bq-easing-standard);
+    }
+    .control:focus-within { border-color: var(--bq-border-focus,#2563eb); box-shadow: var(--bq-focus-ring); }
+    :host([error]:not([error=""])) .control { border-color: var(--bq-color-danger-500,#ef4444); }
+    :host([disabled]) .control { opacity: 0.5; cursor: not-allowed; background: var(--bq-bg-muted,#f1f5f9); }
+
+    input {
+      flex: 1 1 6rem; min-width: 4rem;
+      border: none; outline: none; background: transparent;
+      color: var(--bq-text-base,#0f172a);
+      font-family: var(--bq-font-family-sans);
+    }
+    :host([size="sm"]) input { font-size: 0.875rem; padding: 0.25rem 0.375rem; }
+    :host([size="md"]) input, :host(:not([size])) input { font-size: 1rem; padding: 0.375rem 0.5rem; }
+    :host([size="lg"]) input { font-size: 1.125rem; padding: 0.5rem 0.625rem; }
+
+    .token {
+      display: inline-flex; align-items: center; gap: 0.25rem;
+      background: var(--bq-bg-muted,#f1f5f9);
+      color: var(--bq-text-base,#0f172a);
+      border-radius: var(--bq-radius-sm,0.25rem);
+      padding: 0.125rem 0.25rem 0.125rem 0.5rem;
+      font-size: var(--bq-font-size-sm,0.875rem);
+      font-family: var(--bq-font-family-sans);
+    }
+    .token button {
+      border: none; background: none; cursor: pointer; line-height: 1;
+      color: var(--bq-text-muted,#475569); padding: 0 0.125rem;
+      border-radius: var(--bq-radius-sm,0.25rem);
+    }
+    .token button:hover { color: var(--bq-color-danger-600,#dc2626); }
+    .token button:focus-visible { outline: 2px solid transparent; box-shadow: var(--bq-focus-ring); }
+
+    .actions { display: inline-flex; align-items: center; gap: 0.125rem; margin-inline-start: auto; }
+    .action {
+      display: inline-flex; align-items: center; justify-content: center;
+      width: 1.5rem; height: 1.5rem; border: none; background: none;
+      color: var(--bq-text-muted,#475569); cursor: pointer; line-height: 1;
+      border-radius: var(--bq-radius-sm,0.25rem); font-size: 0.75rem;
+    }
+    .action:hover { background: var(--bq-bg-muted,#f1f5f9); color: var(--bq-text-base,#0f172a); }
+    .action:focus-visible { outline: 2px solid transparent; box-shadow: var(--bq-focus-ring); }
+
+    .listbox {
+      position: absolute; z-index: var(--bq-z-dropdown,100);
+      inset-inline-start: 0; min-width: 100%;
+      max-height: 16rem; overflow-y: auto;
+      margin-top: 0.25rem;
+      background: var(--bq-bg-base,#fff);
+      border: 1px solid var(--bq-border-base,#e2e8f0);
+      border-radius: var(--bq-radius-lg,0.5rem);
+      box-shadow: var(--bq-shadow-lg);
+      padding: 0.25rem 0;
+      font-family: var(--bq-font-family-sans);
+      font-size: var(--bq-font-size-sm,0.875rem);
+    }
+    :host(:not([data-open])) .listbox { display: none; }
+    .listbox[data-placement^="top"] { margin-top: 0; margin-bottom: 0.25rem; }
+
+    .option {
+      display: flex; align-items: center; gap: 0.5rem;
+      padding: 0.375rem 0.75rem; cursor: pointer;
+      color: var(--bq-text-base,#0f172a);
+    }
+    .option[data-active="true"] { background: var(--bq-bg-muted,#f1f5f9); }
+    .option[aria-selected="true"] { font-weight: var(--bq-font-weight-semibold,600); }
+    .option[aria-selected="true"]::after { content: "✓"; margin-inline-start: auto; color: var(--bq-color-primary-600,#2563eb); }
+    .option[aria-disabled="true"] { opacity: 0.5; cursor: not-allowed; }
+
+    .group-label {
+      padding: 0.375rem 0.75rem 0.125rem;
+      font-size: var(--bq-font-size-xs,0.75rem);
+      font-weight: var(--bq-font-weight-semibold,600);
+      color: var(--bq-text-muted,#475569);
+      text-transform: uppercase; letter-spacing: 0.04em;
+    }
+    .empty { padding: 0.625rem 0.75rem; color: var(--bq-text-muted,#475569); }
+    /* The declarative <option> children are a data source, not display
+       content — the listbox above is rendered from their mirrored state. */
+    .source { display: none; }
+
+    .hint { font-size: var(--bq-font-size-sm,0.875rem); color: var(--bq-text-muted,#475569); font-family: var(--bq-font-family-sans); }
+    .error-msg { font-size: var(--bq-font-size-sm,0.875rem); color: var(--bq-color-danger-600,#dc2626); font-family: var(--bq-font-family-sans); }
+    @media (prefers-reduced-motion: reduce) {
+      .control { transition: none; }
+    }
+  `,
+  connected() {
+    const self = host<BqComboboxState>(this);
+    const scope = bind(self);
+    const local = comboboxStore(self);
+    if (!self.getState<string>('uid')) self.setState('uid', uniqueId('bq-cb'));
+
+    const readValues = (): string[] =>
+      parseValues(self.getAttribute('value') ?? '');
+    const isMultiple = () => self.hasAttribute('multiple');
+    const isInteractive = () => !self.hasAttribute('disabled');
+
+    /**
+     * Pulls the light-DOM options into state. Guarded by a value comparison
+     * because `setState` always re-renders, and `updated()` calls this — an
+     * unconditional write would loop forever.
+     */
+    const syncOptions = () => {
+      const next = readOptions(self);
+      const current = self.getState<ComboboxOption[]>('options') ?? [];
+      if (sameOptions(current, next)) return;
+      self.setState('options', next);
+    };
+    local.syncOptions = syncOptions;
+
+    const visibleOptions = (): ComboboxOption[] => {
+      const all = self.getState<ComboboxOption[]>('options') ?? [];
+      if (self.hasAttribute('no-filter')) return all;
+      return filterOptions(
+        all,
+        self.getState<string>('query') ?? '',
+        self.getAttribute('filter-mode') ?? 'contains'
+      );
+    };
+
+    bindFormProxy(self, scope, {
+      value: () => self.getAttribute('value') ?? '',
+    });
+    bindValidation(self, scope, {
+      value: () => self.getAttribute('value') ?? '',
+    });
+
+    const emitChange = () => {
+      const values = readValues();
+      self.dispatchEvent(
+        new CustomEvent('bq-change', {
+          detail: { value: values.join(','), values },
+          bubbles: true,
+          composed: true,
+        })
+      );
+    };
+
+    const open = () => {
+      if (!isInteractive() || self.getState<boolean>('open')) return;
+      self.setState('open', true);
+      // `data-open` drives the CSS; state alone is not visible to selectors.
+      self.setAttribute('data-open', '');
+      self.dispatchEvent(
+        new CustomEvent('bq-open', { bubbles: true, composed: true })
+      );
+    };
+
+    const close = () => {
+      if (!self.getState<boolean>('open')) return;
+      self.setState('open', false);
+      self.setState('activeIndex', -1);
+      self.removeAttribute('data-open');
+      self.dispatchEvent(
+        new CustomEvent('bq-close', { bubbles: true, composed: true })
+      );
+    };
+
+    const selectValue = (value: string) => {
+      if (!value) return;
+      if (isMultiple()) {
+        const values = readValues();
+        const next = values.includes(value)
+          ? values.filter((v) => v !== value)
+          : [...values, value];
+        self.setAttribute('value', next.join(','));
+        // Multi-select keeps the list open so several picks cost one trip,
+        // but the query is cleared so the next one starts fresh.
+        self.setState('query', '');
+      } else {
+        self.setAttribute('value', value);
+        const option = (self.getState<ComboboxOption[]>('options') ?? []).find(
+          (o) => o.value === value
+        );
+        self.setState('query', option?.label ?? value);
+        close();
+      }
+      emitChange();
+    };
+
+    const clear = () => {
+      self.setAttribute('value', '');
+      self.setState('query', '');
+      emitChange();
+    };
+
+    // ── Positioning ──────────────────────────────────────────────────────
+    const syncPosition = () => {
+      local.stopPosition?.();
+      local.stopPosition = null;
+      if (!self.getState<boolean>('open')) return;
+      const listbox = self.shadowRoot?.querySelector(
+        '.listbox'
+      ) as HTMLElement | null;
+      if (!listbox) return;
+      local.stopPosition = scope.add(
+        autoPosition(self, listbox, { placement: 'bottom-start', offset: 4 })
+      );
+    };
+    local.syncPosition = syncPosition;
+
+    // ── Input ────────────────────────────────────────────────────────────
+    scope.on(self.shadowRoot, 'input', (event) => {
+      const input = event.target as HTMLInputElement | null;
+      if (input?.tagName !== 'INPUT') return;
+      self.setState('query', input.value);
+      self.setState('activeIndex', -1);
+      open();
+      self.dispatchEvent(
+        new CustomEvent('bq-input', {
+          detail: { query: input.value },
+          bubbles: true,
+          composed: true,
+        })
+      );
+    });
+
+    scope.on(self.shadowRoot, 'keydown', (event) => {
+      const ke = event as KeyboardEvent;
+      if (!isInteractive()) return;
+      const options = visibleOptions();
+      const isOpen = self.getState<boolean>('open') === true;
+      const current = self.getState<number>('activeIndex') ?? -1;
+
+      switch (ke.key) {
+        case 'ArrowDown':
+          ke.preventDefault();
+          if (!isOpen) {
+            open();
+            self.setState('activeIndex', nextEnabledIndex(options, -1, 1));
+            return;
+          }
+          self.setState('activeIndex', nextEnabledIndex(options, current, 1));
+          return;
+        case 'ArrowUp':
+          ke.preventDefault();
+          if (!isOpen) {
+            open();
+            self.setState('activeIndex', nextEnabledIndex(options, 0, -1));
+            return;
+          }
+          self.setState('activeIndex', nextEnabledIndex(options, current, -1));
+          return;
+        case 'Home':
+          if (!isOpen) return;
+          ke.preventDefault();
+          self.setState('activeIndex', nextEnabledIndex(options, -1, 1));
+          return;
+        case 'End':
+          if (!isOpen) return;
+          ke.preventDefault();
+          self.setState('activeIndex', nextEnabledIndex(options, 0, -1));
+          return;
+        case 'Enter': {
+          if (!isOpen) return;
+          const option = options[current];
+          if (!option || option.disabled) return;
+          // Only swallow the key once it actually selects something, so a
+          // combobox in a form can still submit with Enter.
+          ke.preventDefault();
+          selectValue(option.value);
+          return;
+        }
+        case 'Escape':
+          if (!isOpen) return;
+          ke.preventDefault();
+          close();
+          return;
+        case 'Tab':
+          close();
+          return;
+        case 'Backspace': {
+          // An empty query plus Backspace removes the last token, the
+          // convention every tag-style multiselect uses.
+          const input = ke.target as HTMLInputElement | null;
+          if (!isMultiple() || input?.value !== '') return;
+          const values = readValues();
+          if (values.length === 0) return;
+          self.setAttribute('value', values.slice(0, -1).join(','));
+          emitChange();
+          return;
+        }
+      }
+    });
+
+    scope.on(self.shadowRoot, 'mousedown', (event) => {
+      const target = event.target as Element;
+      const option = target.closest('.option') as HTMLElement | null;
+      if (option) {
+        // Prevent the input from losing focus, which would close the list
+        // before the click resolves.
+        event.preventDefault();
+        if (option.getAttribute('aria-disabled') === 'true') return;
+        selectValue(option.getAttribute('data-value') ?? '');
+        return;
+      }
+      if (target.closest('.clear')) {
+        event.preventDefault();
+        clear();
+        return;
+      }
+      if (target.closest('.toggle')) {
+        event.preventDefault();
+        if (self.getState<boolean>('open')) close();
+        else open();
+        return;
+      }
+      const token = target.closest('.token button') as HTMLElement | null;
+      if (token) {
+        event.preventDefault();
+        const value = token.getAttribute('data-value') ?? '';
+        self.setAttribute(
+          'value',
+          readValues()
+            .filter((v) => v !== value)
+            .join(',')
+        );
+        emitChange();
+      }
+    });
+
+    scope.on(self.shadowRoot, 'focusin', (event) => {
+      if ((event.target as Element)?.tagName === 'INPUT') open();
+    });
+
+    // Closing on outside click is registered once and gated on `open`, so the
+    // listener count does not depend on how often the user toggles.
+    scope.on(document, 'mousedown', (event) => {
+      if (!self.getState<boolean>('open')) return;
+      if (self.contains(event.target as Node)) return;
+      close();
+    });
+
+    // Light-DOM options are the source of truth. `slotchange` is the platform
+    // signal for "the distributed children changed" — cheaper than a subtree
+    // MutationObserver and, unlike one, it fires for a slot that was created
+    // by this component's own first render.
+    //
+    // It does not cover attribute edits on an existing <option> (a `disabled`
+    // toggle, say); a MutationObserver adds that, scoped to those attributes.
+    const observer = new MutationObserver(() => syncOptions());
+    observer.observe(self, {
+      subtree: true,
+      attributes: true,
+      attributeFilter: ['value', 'disabled', 'label'],
+    });
+    scope.add(() => observer.disconnect());
+
+    queueMicrotask(() => {
+      if (!self.isConnected) return;
+      const slot = self.shadowRoot?.querySelector(
+        'slot.source'
+      ) as HTMLSlotElement | null;
+      if (!slot) return;
+      scope.on(slot, 'slotchange', syncOptions);
+      syncOptions();
+    });
+
+    syncOptions();
+
+    // A single selection shows its label in the field; seed it on connect so
+    // a server-rendered `value` is not displayed as a raw key.
+    if (!isMultiple() && !self.getState<string>('query')) {
+      const initial = readValues()[0];
+      if (initial) {
+        const option = readOptions(self).find((o) => o.value === initial);
+        if (option) self.setState('query', option.label);
+      }
+    }
+  },
+  beforeUpdate() {
+    comboboxStore(this).snapshot = captureFocus(this.shadowRoot);
+  },
+  disconnected() {
+    release(this);
+  },
+  updated() {
+    const local = comboboxStore(this);
+    restoreFocus(this.shadowRoot, local.snapshot);
+    local.snapshot = null;
+    local.syncOptions?.();
+    local.syncPosition?.();
+    syncFormProxy(this);
+
+    // Keep the active option in view during keyboard navigation.
+    const active = this.shadowRoot?.querySelector(
+      '.option[data-active="true"]'
+    ) as HTMLElement | null;
+    active?.scrollIntoView?.({ block: 'nearest' });
+  },
+  render({ props, state }) {
+    const uid = state.uid || 'bq-cb';
+    const listboxId = `${uid}-listbox`;
+    const inputId = `${uid}-input`;
+    const isOpen = state.open === true;
+    const values = parseValues(props.value);
+    const every = (state.options ?? []) as ComboboxOption[];
+    const options = props['no-filter']
+      ? every
+      : filterOptions(every, state.query ?? '', props['filter-mode']);
+    const activeIndex = state.activeIndex ?? -1;
+    const activeOption = options[activeIndex];
+    const hasError = Boolean(props.error);
+    const hasHint = Boolean(props.hint) && !hasError;
+
+    const describedBy: string[] = [];
+    if (hasError) describedBy.push(`${uid}-err`);
+    if (hasHint) describedBy.push(`${uid}-hint`);
+
+    const tokens =
+      props.multiple && values.length > 0
+        ? values
+            .map((value) => {
+              const label =
+                every.find((o) => o.value === value)?.label ?? value;
+              return `<span class="token" part="token">${escapeHtml(label)}<button
+                  type="button"
+                  data-value="${escapeHtml(value)}"
+                  tabindex="-1"
+                  aria-label="${escapeHtml(t('combobox.removeOption', { label }))}"
+                >&times;</button></span>`;
+            })
+            .join('')
+        : '';
+
+    let lastGroup = '';
+    const optionMarkup = options
+      .map((option, index) => {
+        const selected = values.includes(option.value);
+        const groupHeader =
+          option.group && option.group !== lastGroup
+            ? `<div class="group-label" role="presentation">${escapeHtml(option.group)}</div>`
+            : '';
+        lastGroup = option.group;
+        return `${groupHeader}<div
+            id="${escapeHtml(`${uid}-opt-${index}`)}"
+            class="option"
+            part="option"
+            role="option"
+            data-value="${escapeHtml(option.value)}"
+            data-active="${index === activeIndex ? 'true' : 'false'}"
+            aria-selected="${selected ? 'true' : 'false'}"
+            aria-disabled="${option.disabled ? 'true' : 'false'}"
+          >${escapeHtml(option.label)}</div>`;
+      })
+      .join('');
+
+    const emptyMarkup = `<div class="empty" role="presentation">${escapeHtml(t('combobox.noResults'))}</div>`;
+
+    return html`
+      <slot class="source" aria-hidden="true"></slot>
+      <div class="field" part="field">
+        ${
+          props.label
+            ? `<label class="label" part="label" for="${escapeHtml(inputId)}">${escapeHtml(props.label)}${props.required ? '<span class="required-mark" aria-hidden="true"> *</span>' : ''}</label>`
+            : ''
+        }
+        <div class="control" part="control">
+          ${tokens}
+          <input
+            id="${escapeHtml(inputId)}"
+            part="input"
+            type="text"
+            role="combobox"
+            autocomplete="off"
+            spellcheck="false"
+            value="${escapeHtml(state.query ?? '')}"
+            placeholder="${escapeHtml(props.placeholder || t('combobox.placeholder'))}"
+            aria-expanded="${isOpen ? 'true' : 'false'}"
+            aria-controls="${escapeHtml(listboxId)}"
+            aria-autocomplete="list"
+            aria-invalid="${hasError ? 'true' : 'false'}"
+            ${props.required ? 'aria-required="true"' : ''}
+            ${activeOption ? `aria-activedescendant="${escapeHtml(`${uid}-opt-${activeIndex}`)}"` : ''}
+            ${describedBy.length > 0 ? `aria-describedby="${escapeHtml(describedBy.join(' '))}"` : ''}
+            ${props.disabled ? 'disabled' : ''}
+          />
+          <span class="actions">
+            ${
+              props.clearable && values.length > 0
+                ? `<button type="button" class="action clear" part="clear" tabindex="-1" aria-label="${escapeHtml(t('combobox.clear'))}">&times;</button>`
+                : ''
+            }
+            <button type="button" class="action toggle" part="toggle" tabindex="-1" aria-label="${escapeHtml(t('combobox.toggle'))}">&#9660;</button>
+          </span>
+        </div>
+        <div
+          id="${escapeHtml(listboxId)}"
+          class="listbox"
+          part="listbox"
+          role="listbox"
+          ${props.multiple ? 'aria-multiselectable="true"' : ''}
+          ${props.label ? `aria-label="${escapeHtml(props.label)}"` : ''}
+        >
+          ${options.length > 0 ? optionMarkup : emptyMarkup}
+        </div>
+        ${hasHint ? `<span class="hint" id="${uid}-hint" part="hint">${escapeHtml(props.hint)}</span>` : ''}
+        ${hasError ? `<span class="error-msg" id="${uid}-err" role="alert" part="error">${escapeHtml(props.error)}</span>` : ''}
+        <span class="sr-only" role="status" aria-live="polite">
+          ${isOpen ? escapeHtml(t('combobox.resultCount', { count: options.length })) : ''}
+        </span>
+      </div>
+    `;
+  },
+};
+
+component<BqComboboxProps, BqComboboxState>('bq-combobox', definition);
diff --git a/src/components/combobox/index.ts b/src/components/combobox/index.ts
new file mode 100644
index 0000000..e0af24d
--- /dev/null
+++ b/src/components/combobox/index.ts
@@ -0,0 +1 @@
+export * as __bqComponentEntry from './BqCombobox.js';
diff --git a/src/components/dropdown-menu/BqDropdownMenu.ts b/src/components/dropdown-menu/BqDropdownMenu.ts
index 20e74bd..ed44fbe 100644
--- a/src/components/dropdown-menu/BqDropdownMenu.ts
+++ b/src/components/dropdown-menu/BqDropdownMenu.ts
@@ -17,6 +17,7 @@ import { escapeHtml } from '@bquery/bquery/security';
 import type { Disposer } from '../../utils/component.js';
 import { bind, host, release, store } from '../../utils/component.js';
 import { getAnimationTimeoutMs, uniqueId } from '../../utils/dom.js';
+import { autoPosition } from '../../utils/position.js';
 import { baseStyles } from '../../utils/styles.js';
 
 type BqDropdownMenuProps = {
@@ -30,7 +31,10 @@ const FAST_DURATION = '150ms';
 
 /** Per-instance handles that `updated()` needs after `connected()` set them up. */
 const menuStore = (owner: object) =>
-  store<{ syncOutsideListener?: () => void }>(owner, () => ({}));
+  store<{ syncOutsideListener?: () => void; syncPosition?: () => void }>(
+    owner,
+    () => ({})
+  );
 
 const definition: ComponentDefinition<
   BqDropdownMenuProps,
@@ -164,8 +168,10 @@ const definition: ComponentDefinition<
       self.dispatchEvent(
         new CustomEvent('bq-open', { bubbles: true, composed: true })
       );
-      // Focus first item
-      requestAnimationFrame(() => {
+      // Focus first item once the open render has landed. Scope-owned so a
+      // menu closed or disconnected within the same frame cannot pull focus
+      // afterwards.
+      scope.frame(() => {
         if (!self.hasAttribute('open') || self.hasAttribute('data-closing'))
           return;
         const items = getMenuItems();
@@ -405,8 +411,32 @@ const definition: ComponentDefinition<
       syncMenuItemRoles();
     };
 
+    // A menu opened near the bottom of the viewport used to render past the
+    // fold; the engine flips it above the trigger instead. Tracking only runs
+    // while the menu is open and is rebuilt after each render.
+    let stopPosition: Disposer | null = null;
+    const syncPosition = () => {
+      stopPosition?.();
+      stopPosition = null;
+      // `data-closing` still shows the menu, but repositioning mid-exit only
+      // makes the animation jump.
+      if (!self.hasAttribute('open') || self.hasAttribute('data-closing'))
+        return;
+      const menu = self.shadowRoot?.querySelector(
+        '.menu'
+      ) as HTMLElement | null;
+      if (!menu) return;
+      stopPosition = scope.add(
+        autoPosition(self, menu, {
+          placement: self.getAttribute('placement') ?? 'bottom-start',
+          offset: 4,
+        })
+      );
+    };
+
     // `updated()` has to re-evaluate the outside listener after every render.
     menuStore(self).syncOutsideListener = syncOutsideListener;
+    menuStore(self).syncPosition = syncPosition;
 
     // An interrupted close animation must not strand the menu half-closed.
     scope.add(() => {
@@ -434,6 +464,7 @@ const definition: ComponentDefinition<
       syncTriggerA11y();
       syncMenuItemRoles();
       syncOutsideListener();
+      syncPosition();
     });
   },
   disconnected() {
@@ -441,6 +472,7 @@ const definition: ComponentDefinition<
   },
   updated() {
     menuStore(this).syncOutsideListener?.();
+    menuStore(this).syncPosition?.();
     const trigger = this.querySelector(
       '[slot="trigger"]'
     ) as HTMLElement | null;
diff --git a/src/components/icon-button/BqIconButton.ts b/src/components/icon-button/BqIconButton.ts
index 87b1a00..5433c46 100644
--- a/src/components/icon-button/BqIconButton.ts
+++ b/src/components/icon-button/BqIconButton.ts
@@ -15,6 +15,7 @@ import { bool, component, css, html } from '@bquery/bquery/component';
 import type { ComponentDefinition } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { t } from '../../i18n/index.js';
+import { bind, host, release } from '../../utils/component.js';
 import { uniqueId } from '../../utils/dom.js';
 import { baseStyles } from '../../utils/styles.js';
 
@@ -69,19 +70,15 @@ const definition: ComponentDefinition<BqIconButtonProps, BqIconButtonState> = {
     }
   `,
   connected() {
-    type BqIconButtonElement = HTMLElement & { setState(k: 'statusId', v: string): void; getState<T>(k: string): T };
-    const self = this as unknown as BqIconButtonElement;
+    const self = host<BqIconButtonState>(this);
     if (!self.getState<string>('statusId')) self.setState('statusId', uniqueId('bq-icon-button-status'));
-    const handler = (e: Event) => {
+    bind(self).on(self.shadowRoot, 'click', (e) => {
       if (self.hasAttribute('disabled') || self.hasAttribute('loading')) { e.preventDefault(); e.stopPropagation(); return; }
       self.dispatchEvent(new CustomEvent('bq-click', { detail: { originalEvent: e }, bubbles: true, composed: true }));
-    };
-    (self as unknown as Record<string, unknown>)['_clickHandler'] = handler;
-    self.shadowRoot?.addEventListener('click', handler);
+    });
   },
   disconnected() {
-    const handler = (this as unknown as Record<string, unknown>)['_clickHandler'] as EventListener | undefined;
-    if (handler) this.shadowRoot?.removeEventListener('click', handler);
+    release(this);
   },
   render({ props, state }) {
     const tag = props.href ? 'a' : 'button';
diff --git a/src/components/index.ts b/src/components/index.ts
index 9fc196f..df1843b 100644
--- a/src/components/index.ts
+++ b/src/components/index.ts
@@ -13,6 +13,7 @@ import './button-group/BqButtonGroup.js';
 import './card/BqCard.js';
 import './checkbox/BqCheckbox.js';
 import './chip/BqChip.js';
+import './combobox/BqCombobox.js';
 import './dialog/BqDialog.js';
 import './divider/BqDivider.js';
 import './dropdown-menu/BqDropdownMenu.js';
@@ -37,6 +38,7 @@ import './stepper/BqStepper.js';
 import './stat-card/BqStatCard.js';
 import './switch/BqSwitch.js';
 import './table/BqTable.js';
+import './tag-input/BqTagInput.js';
 import './tabs/BqTabs.js';
 import './textarea/BqTextarea.js';
 import './timeline/BqTimeline.js';
diff --git a/src/components/input/BqInput.ts b/src/components/input/BqInput.ts
index 82c6a32..580e4dc 100644
--- a/src/components/input/BqInput.ts
+++ b/src/components/input/BqInput.ts
@@ -26,7 +26,10 @@ import { bool, component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { t } from '../../i18n/index.js';
 import { uniqueId } from '../../utils/dom.js';
-import { createFormProxy, type FormProxy } from '../../utils/form.js';
+import { bindFormProxy, syncFormProxy } from '../../utils/form.js';
+import { bind, release, store } from '../../utils/component.js';
+import { captureFocus, restoreFocus, type FocusSnapshot } from '../../utils/focus.js';
+import { bindValidation } from '../../utils/validation.js';
 import { baseStyles } from '../../utils/styles.js';
 
 type BqInputProps = {
@@ -50,6 +53,14 @@ type BqInputEl = HTMLElement & {
   getState<T>(k: string): T;
 };
 
+/**
+ * Holds the pre-render focus snapshot. Rendering replaces the whole shadow
+ * tree, so without this the field the user is typing in is destroyed on
+ * every keystroke that reflects a value to an attribute.
+ */
+const inputFocusStore = (owner: object) =>
+  store<{ snapshot?: FocusSnapshot | null }>(owner, () => ({}));
+
 const definition: ComponentDefinition<BqInputProps, BqInputState> = {
   props: {
     label: { type: String, default: '' },
@@ -126,19 +137,22 @@ const definition: ComponentDefinition<BqInputProps, BqInputState> = {
     if (!self.getState<string>('uid'))
       self.setState('uid', uniqueId('bq-input'));
 
-    // Form proxy for native <form> participation
-    const name = self.getAttribute('name') ?? '';
-    const value = self.getAttribute('value') ?? '';
-    const disabled = self.hasAttribute('disabled');
-    const proxy = createFormProxy(self, name, value, disabled, {
-      getLiveValue: () => {
+    const scope = bind(self);
+
+    const readValue = () => {
         const input = self.shadowRoot?.querySelector(
           'input'
         ) as HTMLInputElement | null;
         return input ? input.value : (self.getAttribute('value') ?? '');
-      },
-    });
-    (self as unknown as Record<string, unknown>)['_formProxy'] = proxy;
+    };
+
+    // Form proxy for native <form> participation
+    const proxy = bindFormProxy(self, scope, { value: readValue });
+
+    // The proxy submits through a hidden input, which the platform bars from
+    // constraint validation — so `required`/`pattern`/`minlength` have to be
+    // enforced here or they would render but never apply.
+    bindValidation(self, scope, { value: readValue });
 
     const ih = (e: Event) => {
       const input = e.target as HTMLInputElement | null;
@@ -186,34 +200,22 @@ const definition: ComponentDefinition<BqInputProps, BqInputState> = {
         self.setState('passwordVisible', !current);
       }
     };
-    const s = self as unknown as Record<string, unknown>;
-    s['_ih'] = ih;
-    s['_ch'] = ch;
-    s['_fh'] = fh;
-    s['_bh'] = bh;
-    s['_pwToggle'] = pwToggle;
-    self.shadowRoot?.addEventListener('input', ih);
-    self.shadowRoot?.addEventListener('change', ch);
-    self.shadowRoot?.addEventListener('focusin', fh);
-    self.shadowRoot?.addEventListener('focusout', bh);
-    self.shadowRoot?.addEventListener('click', pwToggle);
+    const shadow = self.shadowRoot;
+    scope.on(shadow, 'input', ih);
+    scope.on(shadow, 'change', ch);
+    scope.on(shadow, 'focusin', fh);
+    scope.on(shadow, 'focusout', bh);
+    scope.on(shadow, 'click', pwToggle);
   },
   disconnected() {
-    const s = this as unknown as Record<string, unknown>;
-    const sr = this.shadowRoot;
-    const ih = s['_ih'] as EventListener | undefined;
-    if (ih) sr?.removeEventListener('input', ih);
-    const ch = s['_ch'] as EventListener | undefined;
-    if (ch) sr?.removeEventListener('change', ch);
-    const fh = s['_fh'] as EventListener | undefined;
-    if (fh) sr?.removeEventListener('focusin', fh);
-    const bh = s['_bh'] as EventListener | undefined;
-    if (bh) sr?.removeEventListener('focusout', bh);
-    const pwToggle = s['_pwToggle'] as EventListener | undefined;
-    if (pwToggle) sr?.removeEventListener('click', pwToggle);
-    (s['_formProxy'] as FormProxy | undefined)?.cleanup();
+    release(this);
+  },
+  beforeUpdate() {
+    inputFocusStore(this).snapshot = captureFocus(this.shadowRoot);
   },
   updated() {
+    restoreFocus(this.shadowRoot, inputFocusStore(this).snapshot);
+    inputFocusStore(this).snapshot = null;
     const self = this as unknown as BqInputEl;
     if (
       this.getAttribute('type') !== 'password' &&
@@ -221,13 +223,7 @@ const definition: ComponentDefinition<BqInputProps, BqInputState> = {
     ) {
       self.setState('passwordVisible', false);
     }
-    const s = this as unknown as Record<string, unknown>;
-    const proxy = s['_formProxy'] as FormProxy | undefined;
-    if (proxy) {
-      proxy.setName(this.getAttribute('name') ?? '');
-      proxy.setValue(this.getAttribute('value') ?? '');
-      proxy.setDisabled(this.hasAttribute('disabled'));
-    }
+    syncFormProxy(this);
   },
   render({ props, state }) {
     const hasError = Boolean(props.error);
diff --git a/src/components/number-input/BqNumberInput.ts b/src/components/number-input/BqNumberInput.ts
index 6f00471..7370286 100644
--- a/src/components/number-input/BqNumberInput.ts
+++ b/src/components/number-input/BqNumberInput.ts
@@ -27,6 +27,7 @@ import { t } from '../../i18n/index.js';
 import { bind, host, release, store } from '../../utils/component.js';
 import { uniqueId } from '../../utils/dom.js';
 import { createFormProxy, type FormProxy } from '../../utils/form.js';
+import { bindValidation } from '../../utils/validation.js';
 import { baseStyles, reset, srOnly } from '../../utils/styles.js';
 
 type BqNumberInputProps = {
@@ -207,6 +208,13 @@ const definition: ComponentDefinition<BqNumberInputProps, BqNumberInputState> =
       });
     }
 
+    // The value is already clamped into range on commit, so in practice this
+    // enforces `required` — but reading the constraints generically keeps the
+    // control honest if a value is written straight to the attribute.
+    bindValidation(self, scope, {
+      value: () => (self.getAttribute('value') ?? '').trim(),
+    });
+
     const commit = (next: number, eventName: 'bq-input' | 'bq-change') => {
       if (self.hasAttribute('disabled') || self.hasAttribute('readonly')) return;
       const { min, max, step, precision } = readSettings();
diff --git a/src/components/pagination/BqPagination.ts b/src/components/pagination/BqPagination.ts
index d79563b..d5667f4 100644
--- a/src/components/pagination/BqPagination.ts
+++ b/src/components/pagination/BqPagination.ts
@@ -11,7 +11,7 @@
 import type { ComponentDefinition } from '@bquery/bquery/component';
 import { bool, component, css, html } from '@bquery/bquery/component';
 import { t } from '../../i18n/index.js';
-import { host } from '../../utils/component.js';
+import { bind, host, release } from '../../utils/component.js';
 import { baseStyles } from '../../utils/styles.js';
 
 type BqPaginationProps = {
@@ -95,14 +95,10 @@ const definition: ComponentDefinition<BqPaginationProps> = {
         })
       );
     };
-    (self as unknown as Record<string, unknown>)['_handler'] = handler;
-    self.shadowRoot?.addEventListener('click', handler);
+    bind(self).on(self.shadowRoot, 'click', handler);
   },
   disconnected() {
-    const h = (this as unknown as Record<string, unknown>)['_handler'] as
-      | EventListener
-      | undefined;
-    if (h) this.shadowRoot?.removeEventListener('click', h);
+    release(this);
   },
   render({ props }) {
     const page = Math.max(1, Math.min(props.page, props.total || 1));
diff --git a/src/components/popover/BqPopover.ts b/src/components/popover/BqPopover.ts
index 2b6fd3b..e3d9335 100644
--- a/src/components/popover/BqPopover.ts
+++ b/src/components/popover/BqPopover.ts
@@ -23,6 +23,7 @@ import { t } from '../../i18n/index.js';
 import type { Disposer } from '../../utils/component.js';
 import { bind, host, release, store } from '../../utils/component.js';
 import { uniqueId } from '../../utils/dom.js';
+import { autoPosition } from '../../utils/position.js';
 import { baseStyles, reset } from '../../utils/styles.js';
 
 type BqPopoverProps = {
@@ -35,7 +36,7 @@ type BqPopoverProps = {
 type BqPopoverState = { uid: string };
 
 const popoverStore = (owner: object) =>
-  store<{ sync?: () => void }>(owner, () => ({}));
+  store<{ sync?: () => void; syncPosition?: () => void }>(owner, () => ({}));
 
 const definition: ComponentDefinition<BqPopoverProps, BqPopoverState> = {
   props: {
@@ -68,6 +69,8 @@ const definition: ComponentDefinition<BqPopoverProps, BqPopoverState> = {
     }
     :host([open]) .panel { opacity: 1; visibility: visible; }
 
+    /* Static fallback until the positioning engine has real geometry to work
+       with; its inline styles override these once the panel is measurable. */
     .panel[data-placement^="bottom"] { top: calc(100% + 8px); }
     .panel[data-placement^="top"]    { bottom: calc(100% + 8px); }
     .panel[data-placement^="left"]   { right: calc(100% + 8px); top: 0; }
@@ -105,12 +108,23 @@ const definition: ComponentDefinition<BqPopoverProps, BqPopoverState> = {
       border: 1px solid var(--bq-border-base,#e2e8f0);
       transform: rotate(45deg);
     }
+    /* Which edge the arrow hangs off, and which of its borders are visible,
+       follows the *effective* side so a flipped panel still points correctly.
+       The cross-axis offset is supplied inline by the positioning engine; the
+       percentage rules below only cover the unmeasured fallback. */
+    .panel[data-side="bottom"] .arrow { top: -5px; border-right: none; border-bottom: none; }
+    .panel[data-side="top"]    .arrow { bottom: -5px; border-left: none; border-top: none; }
+    .panel[data-side="left"]   .arrow { right: -5px; border-left: none; border-bottom: none; }
+    .panel[data-side="right"]  .arrow { left: -5px; border-right: none; border-top: none; }
     .panel[data-placement^="bottom"] .arrow { top: -5px; left: 50%; margin-left: -0.25rem; border-right: none; border-bottom: none; }
     .panel[data-placement^="top"]    .arrow { bottom: -5px; left: 50%; margin-left: -0.25rem; border-left: none; border-top: none; }
     .panel[data-placement^="left"]   .arrow { right: -5px; top: 0.75rem; border-left: none; border-bottom: none; }
     .panel[data-placement^="right"]  .arrow { left: -5px; top: 0.75rem; border-right: none; border-top: none; }
     .panel[data-placement$="-start"] .arrow { left: 1rem; margin-left: 0; }
     .panel[data-placement$="-end"]   .arrow { left: auto; right: 1rem; margin-left: 0; }
+    /* The engine writes an absolute cross-axis offset, so the centring margin
+       must not be added on top of it. */
+    .panel[data-side] .arrow { margin-left: 0; }
 
     @media (prefers-reduced-motion: reduce) {
       .panel { transition: none; }
@@ -150,6 +164,31 @@ const definition: ComponentDefinition<BqPopoverProps, BqPopoverState> = {
       if (restoreFocus) getTrigger()?.focus();
     };
 
+    // Anchored positioning is only tracked while the panel is open, and is
+    // re-established after every render because the shadow tree — panel and
+    // arrow included — is rebuilt from scratch each time.
+    let stopPosition: Disposer | null = null;
+    const syncPosition = () => {
+      stopPosition?.();
+      stopPosition = null;
+      if (!self.hasAttribute('open')) return;
+      const panel = self.shadowRoot?.querySelector(
+        '.panel'
+      ) as HTMLElement | null;
+      if (!panel) return;
+      const arrow = self.shadowRoot?.querySelector(
+        '.arrow'
+      ) as HTMLElement | null;
+      stopPosition = scope.add(
+        autoPosition(self, panel, {
+          placement: self.getAttribute('placement') ?? 'bottom',
+          offset: 8,
+          arrowElement: arrow,
+        })
+      );
+    };
+    local.syncPosition = syncPosition;
+
     // The outside-click listener only exists while open; the scope owns its
     // removal so a disconnect while open cannot strand it on `document`.
     let stopOutside: Disposer | null = null;
@@ -194,7 +233,9 @@ const definition: ComponentDefinition<BqPopoverProps, BqPopoverState> = {
   },
   updated() {
     const self = host<BqPopoverState>(this);
-    popoverStore(self).sync?.();
+    const local = popoverStore(self);
+    local.sync?.();
+    local.syncPosition?.();
     const trigger = self.querySelector('[slot="trigger"]');
     if (!trigger) return;
     trigger.setAttribute(
diff --git a/src/components/radio/BqRadio.ts b/src/components/radio/BqRadio.ts
index ff58106..5ea83bb 100644
--- a/src/components/radio/BqRadio.ts
+++ b/src/components/radio/BqRadio.ts
@@ -13,8 +13,8 @@
 import type { ComponentDefinition } from '@bquery/bquery/component';
 import { bool, component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
-import { createFormProxy, type FormProxy } from '../../utils/form.js';
-import { host } from '../../utils/component.js';
+import { bindFormProxy, syncFormProxy } from '../../utils/form.js';
+import { bind, host, release } from '../../utils/component.js';
 import { baseStyles } from '../../utils/styles.js';
 
 type BqRadioProps = {
@@ -57,15 +57,13 @@ const definition: ComponentDefinition<BqRadioProps> = {
   `,
   connected() {
     const self = host(this);
+    const scope = bind(self);
 
     // Form proxy for native <form> participation
-    const name = self.getAttribute('name') ?? '';
-    const value = self.hasAttribute('checked')
-      ? (self.getAttribute('value') ?? '')
-      : '';
-    const disabled = self.hasAttribute('disabled');
-    const proxy = createFormProxy(self, name, value, disabled);
-    (self as unknown as Record<string, unknown>)['_formProxy'] = proxy;
+    const proxy = bindFormProxy(self, scope, {
+      value: () =>
+        self.hasAttribute('checked') ? (self.getAttribute('value') ?? '') : '',
+    });
 
     const handler = (e: Event) => {
       const input = e.target as HTMLInputElement | null;
@@ -84,30 +82,13 @@ const definition: ComponentDefinition<BqRadioProps> = {
         })
       );
     };
-    (self as unknown as Record<string, unknown>)['_handler'] = handler;
-    self.shadowRoot?.addEventListener('change', handler);
+    scope.on(self.shadowRoot, 'change', handler);
   },
   disconnected() {
-    const h = (this as unknown as Record<string, unknown>)['_handler'] as
-      | EventListener
-      | undefined;
-    if (h) this.shadowRoot?.removeEventListener('change', h);
-    (
-      (this as unknown as Record<string, unknown>)['_formProxy'] as
-        | FormProxy
-        | undefined
-    )?.cleanup();
+    release(this);
   },
   updated() {
-    const s = this as unknown as Record<string, unknown>;
-    const proxy = s['_formProxy'] as FormProxy | undefined;
-    if (proxy) {
-      proxy.setName(this.getAttribute('name') ?? '');
-      proxy.setValue(
-        this.hasAttribute('checked') ? (this.getAttribute('value') ?? '') : ''
-      );
-      proxy.setDisabled(this.hasAttribute('disabled'));
-    }
+    syncFormProxy(this);
   },
   render({ props }) {
     return html`
diff --git a/src/components/segmented-control/BqSegmentedControl.ts b/src/components/segmented-control/BqSegmentedControl.ts
index 210b226..48b6874 100644
--- a/src/components/segmented-control/BqSegmentedControl.ts
+++ b/src/components/segmented-control/BqSegmentedControl.ts
@@ -17,7 +17,8 @@ import { component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { t } from '../../i18n/index.js';
 import { uniqueId } from '../../utils/dom.js';
-import { createFormProxy, type FormProxy } from '../../utils/form.js';
+import { bindFormProxy, syncFormProxy } from '../../utils/form.js';
+import { bind, release, store } from '../../utils/component.js';
 import { baseStyles } from '../../utils/styles.js';
 
 type BqSegmentedControlProps = {
@@ -35,6 +36,10 @@ type BqSegmentedControlState = {
   uid: string;
 };
 
+/** Per-instance callbacks `updated()` re-runs after every render. */
+const segmentedStore = (owner: object) =>
+  store<{ syncButtons?: () => void }>(owner, () => ({}));
+
 const definition: ComponentDefinition<
   BqSegmentedControlProps,
   BqSegmentedControlState
@@ -156,19 +161,16 @@ const definition: ComponentDefinition<
       getState<T>(key: string): T;
     };
 
-    const self = this as unknown as BQEl & Record<string, unknown>;
+    const self = this as unknown as BQEl;
+    const scope = bind(self);
 
     if (!self.getState<string>('uid')) {
       self.setState('uid', uniqueId('bq-segmented'));
     }
 
-    const proxy = createFormProxy(
-      self,
-      self.getAttribute('name') ?? '',
-      self.getAttribute('value') ?? '',
-      self.hasAttribute('disabled')
-    );
-    self['_formProxy'] = proxy;
+    const proxy = bindFormProxy(self, scope, {
+      value: () => self.getAttribute('value') ?? '',
+    });
 
     const getButtons = (): HTMLButtonElement[] => {
       const slot = self.shadowRoot?.querySelector(
@@ -252,14 +254,10 @@ const definition: ComponentDefinition<
           'tabindex',
           !disabled && value === focusValue ? '0' : '-1'
         );
-
-        button.removeEventListener('keydown', keyHandler);
-        button.addEventListener('keydown', keyHandler);
       });
 
-      proxy.setName(self.getAttribute('name') ?? '');
       proxy.setValue(selectedValue);
-      proxy.setDisabled(self.hasAttribute('disabled'));
+      syncFormProxy(self);
     };
 
     const selectButton = (
@@ -392,51 +390,27 @@ const definition: ComponentDefinition<
       attributeFilter: ['disabled', 'value', 'data-value'],
     });
 
-    self['_syncButtons'] = syncButtons;
-    self['_clickHandler'] = clickHandler;
-    self['_keyHandler'] = keyHandler;
-    self['_slotChangeHandler'] = slotChangeHandler;
-    self['_observer'] = observer;
-
-    self.addEventListener('click', clickHandler);
-    self.shadowRoot
-      ?.querySelector('slot:not([name])')
-      ?.addEventListener('slotchange', slotChangeHandler);
+    scope.add(() => observer.disconnect());
+    segmentedStore(self).syncButtons = syncButtons;
+
+    scope.on(self, 'click', clickHandler);
+    // Delegated rather than bound per button: `keyHandler` already resolves
+    // its button from the event target, and binding each button meant a
+    // button removed from the light DOM kept its listener behind.
+    scope.on(self, 'keydown', keyHandler);
+    scope.on(
+      self.shadowRoot?.querySelector('slot:not([name])'),
+      'slotchange',
+      slotChangeHandler
+    );
 
-    requestAnimationFrame(syncButtons);
+    scope.frame(syncButtons);
   },
   disconnected() {
-    const self = this as unknown as Record<string, unknown>;
-
-    const clickHandler = self['_clickHandler'] as EventListener | undefined;
-    const keyHandler = self['_keyHandler'] as EventListener | undefined;
-    const slotChangeHandler = self['_slotChangeHandler'] as
-      | EventListener
-      | undefined;
-    const observer = self['_observer'] as MutationObserver | undefined;
-    const proxy = self['_formProxy'] as FormProxy | undefined;
-
-    if (clickHandler) this.removeEventListener('click', clickHandler);
-    if (keyHandler) {
-      const buttons = this.querySelectorAll('button');
-      buttons.forEach((button) =>
-        button.removeEventListener('keydown', keyHandler)
-      );
-    }
-    if (slotChangeHandler) {
-      this.shadowRoot
-        ?.querySelector('slot:not([name])')
-        ?.removeEventListener('slotchange', slotChangeHandler);
-    }
-
-    observer?.disconnect();
-    proxy?.cleanup();
+    release(this);
   },
   updated() {
-    const syncButtons = (this as unknown as Record<string, unknown>)[
-      '_syncButtons'
-    ] as (() => void) | undefined;
-    syncButtons?.();
+    segmentedStore(this).syncButtons?.();
   },
   render({ props, state }) {
     const uid = state.uid || 'bq-segmented';
diff --git a/src/components/select/BqSelect.ts b/src/components/select/BqSelect.ts
index 7de449b..247c53b 100644
--- a/src/components/select/BqSelect.ts
+++ b/src/components/select/BqSelect.ts
@@ -17,7 +17,13 @@ import type { ComponentDefinition } from '@bquery/bquery/component';
 import { bool, component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { uniqueId } from '../../utils/dom.js';
-import { createFormProxy, type FormProxy } from '../../utils/form.js';
+import {
+  bindFormProxy,
+  syncFormProxy,
+  type FormProxyBinding,
+} from '../../utils/form.js';
+import { bind, host, release, store } from '../../utils/component.js';
+import { bindValidation } from '../../utils/validation.js';
 import { baseStyles } from '../../utils/styles.js';
 
 type BqSelectProps = {
@@ -85,6 +91,12 @@ const buildOptionsMarkup = (host: HTMLElement, placeholder: string): string => {
   return `${placeholderMarkup}${childrenMarkup}`;
 };
 
+const selectStore = (owner: object) =>
+  store<{ syncOptions?: () => void; proxy?: FormProxyBinding }>(
+    owner,
+    () => ({})
+  );
+
 const syncSelectValue = (host: HTMLElement): void => {
   const select = host.shadowRoot?.querySelector(
     'select'
@@ -105,10 +117,7 @@ const syncSelectValue = (host: HTMLElement): void => {
     host.setAttribute('value', normalizedValue);
   }
 
-  const proxy = (host as unknown as Record<string, unknown>)['_formProxy'] as
-    | FormProxy
-    | undefined;
-  proxy?.setValue(normalizedValue);
+  selectStore(host).proxy?.setValue(normalizedValue);
 };
 
 const definition: ComponentDefinition<BqSelectProps, BqSelectState> = {
@@ -158,13 +167,12 @@ const definition: ComponentDefinition<BqSelectProps, BqSelectState> = {
     }
   `,
   connected() {
-    type BQEl = HTMLElement & {
-      setState(k: 'uid' | 'optionsMarkup', v: string): void;
-      getState<T>(k: string): T;
-    };
-    const self = this as unknown as BQEl;
+    const self = host<BqSelectState>(this);
+    const scope = bind(self);
+    const local = selectStore(self);
     if (!self.getState<string>('uid'))
       self.setState('uid', uniqueId('bq-select'));
+
     const syncOptions = () => {
       const markup = buildOptionsMarkup(
         self,
@@ -173,24 +181,28 @@ const definition: ComponentDefinition<BqSelectProps, BqSelectState> = {
       if (self.getState<string>('optionsMarkup') !== markup) {
         self.setState('optionsMarkup', markup);
       }
-      requestAnimationFrame(() => syncSelectValue(self));
+      // The shadow `<select>` only exists after the render that markup
+      // triggers, so the value has to be reapplied a frame later.
+      scope.frame(() => syncSelectValue(self));
+    };
+    local.syncOptions = syncOptions;
+
+    const readValue = () => {
+      const select = self.shadowRoot?.querySelector(
+        'select'
+      ) as HTMLSelectElement | null;
+      return select ? select.value : (self.getAttribute('value') ?? '');
     };
 
     // Form proxy for native <form> participation
-    const name = self.getAttribute('name') ?? '';
-    const value = self.getAttribute('value') ?? '';
-    const disabled = self.hasAttribute('disabled');
-    const proxy = createFormProxy(self, name, value, disabled, {
-      getLiveValue: () => {
-        const select = self.shadowRoot?.querySelector(
-          'select'
-        ) as HTMLSelectElement | null;
-        return select ? select.value : (self.getAttribute('value') ?? '');
-      },
-    });
-    (self as unknown as Record<string, unknown>)['_formProxy'] = proxy;
+    const proxy = bindFormProxy(self, scope, { value: readValue });
+    local.proxy = proxy;
+
+    // The hidden proxy input is barred from constraint validation, so a
+    // `required` select would otherwise submit with nothing chosen.
+    bindValidation(self, scope, { value: readValue });
 
-    const handler = (e: Event) => {
+    scope.on(self.shadowRoot, 'change', (e) => {
       const select = e.target as HTMLSelectElement | null;
       if (select?.tagName === 'SELECT') {
         self.setAttribute('value', select.value);
@@ -203,10 +215,11 @@ const definition: ComponentDefinition<BqSelectProps, BqSelectState> = {
           })
         );
       }
-    };
-    const observer = new MutationObserver(() => {
-      syncOptions();
     });
+
+    // Light-DOM <option>/<optgroup> children are the source of truth, so the
+    // shadow <select> is rebuilt whenever they change.
+    const observer = new MutationObserver(() => syncOptions());
     observer.observe(self, {
       childList: true,
       subtree: true,
@@ -214,30 +227,16 @@ const definition: ComponentDefinition<BqSelectProps, BqSelectState> = {
       attributes: true,
       attributeFilter: ['disabled', 'label', 'selected', 'value'],
     });
+    scope.add(() => observer.disconnect());
 
-    (self as unknown as Record<string, unknown>)['_handler'] = handler;
-    (self as unknown as Record<string, unknown>)['_syncOptions'] = syncOptions;
-    (self as unknown as Record<string, unknown>)['_observer'] = observer;
-    self.shadowRoot?.addEventListener('change', handler);
     syncOptions();
   },
   disconnected() {
-    const s = this as unknown as Record<string, unknown>;
-    const h = s['_handler'] as EventListener | undefined;
-    if (h) this.shadowRoot?.removeEventListener('change', h);
-    const observer = s['_observer'] as MutationObserver | undefined;
-    observer?.disconnect();
-    (s['_formProxy'] as FormProxy | undefined)?.cleanup();
+    release(this);
   },
   updated() {
-    const s = this as unknown as Record<string, unknown>;
-    const proxy = s['_formProxy'] as FormProxy | undefined;
-    if (proxy) {
-      proxy.setName(this.getAttribute('name') ?? '');
-      proxy.setValue(this.getAttribute('value') ?? '');
-      proxy.setDisabled(this.hasAttribute('disabled'));
-    }
-    (s['_syncOptions'] as (() => void) | undefined)?.();
+    syncFormProxy(this);
+    selectStore(this).syncOptions?.();
   },
   render({ props, state }) {
     const hasError = Boolean(props.error);
diff --git a/src/components/slider/BqSlider.ts b/src/components/slider/BqSlider.ts
index 88b6517..ef39438 100644
--- a/src/components/slider/BqSlider.ts
+++ b/src/components/slider/BqSlider.ts
@@ -15,8 +15,8 @@ import type { ComponentDefinition } from '@bquery/bquery/component';
 import { bool, component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { t } from '../../i18n/index.js';
-import { createFormProxy, type FormProxy } from '../../utils/form.js';
-import { host } from '../../utils/component.js';
+import { bindFormProxy, syncFormProxy } from '../../utils/form.js';
+import { bind, host, release } from '../../utils/component.js';
 import { baseStyles } from '../../utils/styles.js';
 
 type BqSliderProps = {
@@ -61,20 +61,19 @@ const definition: ComponentDefinition<BqSliderProps> = {
   `,
   connected() {
     const self = host(this);
+    const scope = bind(self);
 
-    // Form proxy for native <form> participation
-    const name = self.getAttribute('name') ?? '';
-    const value = self.getAttribute('value') ?? '50';
-    const disabled = self.hasAttribute('disabled');
-    const proxy = createFormProxy(self, name, value, disabled, {
-      getLiveValue: () => {
+    // Form proxy for native <form> participation. The live read matters here:
+    // dragging updates the range input without committing an attribute, so a
+    // submit mid-drag would otherwise post the pre-drag value.
+    const proxy = bindFormProxy(self, scope, {
+      value: () => {
         const input = self.shadowRoot?.querySelector(
           'input[type="range"]'
         ) as HTMLInputElement | null;
         return input ? input.value : (self.getAttribute('value') ?? '50');
       },
     });
-    (self as unknown as Record<string, unknown>)['_formProxy'] = proxy;
 
     const ih = (e: Event) => {
       const input = e.target as HTMLInputElement | null;
@@ -109,31 +108,14 @@ const definition: ComponentDefinition<BqSliderProps> = {
         })
       );
     };
-    (self as unknown as Record<string, unknown>)['_ih'] = ih;
-    (self as unknown as Record<string, unknown>)['_ch'] = ch;
-    self.shadowRoot?.addEventListener('input', ih);
-    self.shadowRoot?.addEventListener('change', ch);
+    scope.on(self.shadowRoot, 'input', ih);
+    scope.on(self.shadowRoot, 'change', ch);
   },
   disconnected() {
-    const s = this as unknown as Record<string, unknown>;
-    const ih = s['_ih'] as EventListener | undefined;
-    const ch = s['_ch'] as EventListener | undefined;
-    if (ih) this.shadowRoot?.removeEventListener('input', ih);
-    if (ch) this.shadowRoot?.removeEventListener('change', ch);
-    (
-      (this as unknown as Record<string, unknown>)['_formProxy'] as
-        | FormProxy
-        | undefined
-    )?.cleanup();
+    release(this);
   },
   updated() {
-    const s = this as unknown as Record<string, unknown>;
-    const proxy = s['_formProxy'] as FormProxy | undefined;
-    if (proxy) {
-      proxy.setName(this.getAttribute('name') ?? '');
-      proxy.setValue(this.getAttribute('value') ?? '50');
-      proxy.setDisabled(this.hasAttribute('disabled'));
-    }
+    syncFormProxy(this);
   },
   render({ props }) {
     return html`
diff --git a/src/components/switch/BqSwitch.ts b/src/components/switch/BqSwitch.ts
index de1cd89..61f12da 100644
--- a/src/components/switch/BqSwitch.ts
+++ b/src/components/switch/BqSwitch.ts
@@ -11,8 +11,8 @@
 import type { ComponentDefinition } from '@bquery/bquery/component';
 import { bool, component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
-import { createFormProxy, type FormProxy } from '../../utils/form.js';
-import { host } from '../../utils/component.js';
+import { bindFormProxy, syncFormProxy } from '../../utils/form.js';
+import { bind, host, release } from '../../utils/component.js';
 import { baseStyles } from '../../utils/styles.js';
 
 type BqSwitchProps = {
@@ -67,13 +67,12 @@ const definition: ComponentDefinition<BqSwitchProps> = {
   `,
   connected() {
     const self = host(this);
+    const scope = bind(self);
 
     // Form proxy for native <form> participation
-    const name = self.getAttribute('name') ?? '';
-    const value = self.hasAttribute('checked') ? 'on' : '';
-    const disabled = self.hasAttribute('disabled');
-    const proxy = createFormProxy(self, name, value, disabled);
-    (self as unknown as Record<string, unknown>)['_formProxy'] = proxy;
+    const proxy = bindFormProxy(self, scope, {
+      value: () => (self.hasAttribute('checked') ? 'on' : ''),
+    });
 
     const handler = (e: Event) => {
       const input = e.target as HTMLInputElement | null;
@@ -92,28 +91,13 @@ const definition: ComponentDefinition<BqSwitchProps> = {
         })
       );
     };
-    (self as unknown as Record<string, unknown>)['_handler'] = handler;
-    self.shadowRoot?.addEventListener('change', handler);
+    scope.on(self.shadowRoot, 'change', handler);
   },
   disconnected() {
-    const h = (this as unknown as Record<string, unknown>)['_handler'] as
-      | EventListener
-      | undefined;
-    if (h) this.shadowRoot?.removeEventListener('change', h);
-    (
-      (this as unknown as Record<string, unknown>)['_formProxy'] as
-        | FormProxy
-        | undefined
-    )?.cleanup();
+    release(this);
   },
   updated() {
-    const s = this as unknown as Record<string, unknown>;
-    const proxy = s['_formProxy'] as FormProxy | undefined;
-    if (proxy) {
-      proxy.setName(this.getAttribute('name') ?? '');
-      proxy.setValue(this.hasAttribute('checked') ? 'on' : '');
-      proxy.setDisabled(this.hasAttribute('disabled'));
-    }
+    syncFormProxy(this);
   },
   render({ props }) {
     return html`
diff --git a/src/components/table/BqTable.ts b/src/components/table/BqTable.ts
index f571003..dc85b65 100644
--- a/src/components/table/BqTable.ts
+++ b/src/components/table/BqTable.ts
@@ -16,7 +16,7 @@ import type { ComponentDefinition } from '@bquery/bquery/component';
 import { component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { t } from '../../i18n/index.js';
-import { host } from '../../utils/component.js';
+import { bind, host, release } from '../../utils/component.js';
 import { baseStyles } from '../../utils/styles.js';
 
 type ColDef = { key: string; label: string; sortable?: boolean };
@@ -106,19 +106,13 @@ const definition: ComponentDefinition<BqTableProps> = {
       e.preventDefault();
       sortHandler(th);
     };
-    (self as unknown as Record<string, unknown>)['_handler'] = handler;
-    (self as unknown as Record<string, unknown>)['_keyHandler'] = keyHandler;
-    self.shadowRoot?.addEventListener('click', handler);
-    self.shadowRoot?.addEventListener('keydown', keyHandler);
-    self.shadowRoot?.addEventListener('keyup', keyHandler);
+    const scope = bind(self);
+    scope.on(self.shadowRoot, 'click', handler);
+    scope.on(self.shadowRoot, 'keydown', keyHandler);
+    scope.on(self.shadowRoot, 'keyup', keyHandler);
   },
   disconnected() {
-    const s = this as unknown as Record<string, unknown>;
-    const h = s['_handler'] as EventListener | undefined;
-    const kh = s['_keyHandler'] as EventListener | undefined;
-    if (h) this.shadowRoot?.removeEventListener('click', h);
-    if (kh) this.shadowRoot?.removeEventListener('keydown', kh);
-    if (kh) this.shadowRoot?.removeEventListener('keyup', kh);
+    release(this);
   },
   render({ props }) {
     let cols: ColDef[] = [];
diff --git a/src/components/tabs/BqTabs.ts b/src/components/tabs/BqTabs.ts
index 60d8436..14fcf8f 100644
--- a/src/components/tabs/BqTabs.ts
+++ b/src/components/tabs/BqTabs.ts
@@ -10,6 +10,7 @@ import type { ComponentDefinition } from '@bquery/bquery/component';
 import { component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { t } from '../../i18n/index.js';
+import { bind, release } from '../../utils/component.js';
 import { baseStyles } from '../../utils/styles.js';
 
 type BqTabsProps = { 'active-tab': string; variant: string };
@@ -72,6 +73,7 @@ const definition: ComponentDefinition<BqTabsProps> = {
     const self = this as unknown as BQEl &
       HTMLElement &
       Record<string, unknown>;
+    const scope = bind(self);
 
     const readTabs = () => {
       const items = Array.from(
@@ -98,7 +100,7 @@ const definition: ComponentDefinition<BqTabsProps> = {
       attributes: true,
       attributeFilter: ['label', 'disabled', 'id'],
     });
-    self['_obs'] = obs;
+    scope.add(() => obs.disconnect());
 
     const clickH = (e: Event) => {
       const btn = (e.target as Element).closest(
@@ -145,19 +147,11 @@ const definition: ComponentDefinition<BqTabsProps> = {
           panel.hidden = panel.getAttribute('data-tab') !== activeId;
         });
     };
-    self['_clickH'] = clickH;
-    self['_keyH'] = keyH;
-    (self as HTMLElement).shadowRoot?.addEventListener('click', clickH);
-    (self as HTMLElement).shadowRoot?.addEventListener('keydown', keyH);
+    scope.on((self as HTMLElement).shadowRoot, 'click', clickH);
+    scope.on((self as HTMLElement).shadowRoot, 'keydown', keyH);
   },
   disconnected() {
-    const s = this as unknown as Record<string, unknown>;
-    const obs = s['_obs'] as MutationObserver | undefined;
-    if (obs) obs.disconnect();
-    const ch = s['_clickH'] as EventListener | undefined;
-    if (ch) this.shadowRoot?.removeEventListener('click', ch);
-    const kh = s['_keyH'] as EventListener | undefined;
-    if (kh) this.shadowRoot?.removeEventListener('keydown', kh);
+    release(this);
   },
   updated() {
     // Sync panel visibility after each render
diff --git a/src/components/tag-input/BqTagInput.ts b/src/components/tag-input/BqTagInput.ts
new file mode 100644
index 0000000..d9b912b
--- /dev/null
+++ b/src/components/tag-input/BqTagInput.ts
@@ -0,0 +1,398 @@
+/**
+ * Tag input — free-form entry that turns text into removable tokens.
+ *
+ * Distinct from `bq-combobox`: there is no predefined option list. The user
+ * types whatever they want and commits it with Enter (or one of the
+ * `delimiters`), which is the right control for keywords, recipients and
+ * labels.
+ *
+ * The token list is exposed to assistive technology as a real list, and each
+ * remove button names the tag it removes, so a screen-reader user is never
+ * left with an unlabelled "×".
+ *
+ * @element bq-tag-input
+ * @prop {string}  label
+ * @prop {string}  value       - Current tags, joined by `separator`
+ * @prop {string}  placeholder
+ * @prop {string}  name        - Form field name
+ * @prop {string}  separator   - Character joining the submitted value @default ','
+ * @prop {string}  delimiters  - Characters that commit a tag while typing @default ','
+ * @prop {number}  max         - Maximum number of tags; 0 means unlimited
+ * @prop {boolean} allow-duplicates
+ * @prop {boolean} disabled
+ * @prop {boolean} required
+ * @prop {string}  error
+ * @prop {string}  hint
+ * @prop {string}  size        - sm | md | lg
+ * @fires bq-change - { value: string, tags: string[] }
+ * @fires bq-add    - { tag: string }
+ * @fires bq-remove - { tag: string }
+ */
+import type { ComponentDefinition } from '@bquery/bquery/component';
+import { component, css, html } from '@bquery/bquery/component';
+import { escapeHtml } from '@bquery/bquery/security';
+import { t } from '../../i18n/index.js';
+import { bind, host, release, store } from '../../utils/component.js';
+import { uniqueId } from '../../utils/dom.js';
+import { captureFocus, restoreFocus } from '../../utils/focus.js';
+import type { FocusSnapshot } from '../../utils/focus.js';
+import { bindFormProxy, syncFormProxy } from '../../utils/form.js';
+import { baseStyles, reset, srOnly } from '../../utils/styles.js';
+import { bindValidation } from '../../utils/validation.js';
+
+type BqTagInputProps = {
+  label: string;
+  value: string;
+  placeholder: string;
+  name: string;
+  separator: string;
+  delimiters: string;
+  max: number;
+  'allow-duplicates': boolean;
+  disabled: boolean;
+  required: boolean;
+  error: string;
+  hint: string;
+  size: string;
+};
+
+type BqTagInputState = { uid: string; draft: string };
+
+const tagStore = (owner: object) =>
+  store<{ snapshot?: FocusSnapshot | null }>(owner, () => ({}));
+
+/** Splits a joined value into individual tags. */
+export function parseTags(raw: string, separator = ','): string[] {
+  const sep = separator || ',';
+  return raw
+    .split(sep)
+    .map((tag) => tag.trim())
+    .filter(Boolean);
+}
+
+/**
+ * Adds a tag, returning the new list — or `null` when nothing changed.
+ *
+ * Returning `null` rather than an unchanged copy lets the caller skip both the
+ * re-render and the `bq-add` event when the tag was rejected as a duplicate or
+ * because the list is full.
+ */
+export function addTag(
+  tags: string[],
+  candidate: string,
+  options: { max?: number; allowDuplicates?: boolean } = {}
+): string[] | null {
+  const tag = candidate.trim();
+  if (!tag) return null;
+  const { max = 0, allowDuplicates = false } = options;
+  if (max > 0 && tags.length >= max) return null;
+  if (!allowDuplicates && tags.includes(tag)) return null;
+  return [...tags, tag];
+}
+
+const definition: ComponentDefinition<BqTagInputProps, BqTagInputState> = {
+  props: {
+    label: { type: String, default: '' },
+    value: { type: String, default: '' },
+    placeholder: { type: String, default: '' },
+    name: { type: String, default: '' },
+    separator: { type: String, default: ',' },
+    delimiters: { type: String, default: ',' },
+    max: { type: Number, default: 0 },
+    'allow-duplicates': { type: Boolean, default: false },
+    disabled: { type: Boolean, default: false },
+    required: { type: Boolean, default: false },
+    error: { type: String, default: '' },
+    hint: { type: String, default: '' },
+    size: { type: String, default: 'md' },
+  },
+  state: { uid: '', draft: '' },
+  styles: css`
+    ${baseStyles}
+    ${reset}
+    ${srOnly}
+    :host { display: block; }
+    .field { display: flex; flex-direction: column; gap: 0.375rem; }
+    .label {
+      font-size: var(--bq-font-size-sm,0.875rem);
+      font-weight: var(--bq-font-weight-medium,500);
+      color: var(--bq-text-base,#0f172a);
+      font-family: var(--bq-font-family-sans);
+    }
+    .required-mark { color: var(--bq-color-danger-600,#dc2626); }
+    .control {
+      display: flex; align-items: center; flex-wrap: wrap; gap: 0.25rem;
+      border: 1.5px solid var(--bq-border-emphasis,#cbd5e1);
+      border-radius: var(--bq-radius-lg,0.5rem);
+      background: var(--bq-bg-base,#fff);
+      padding: 0.25rem 0.375rem;
+      transition: border-color var(--bq-duration-fast) var(--bq-easing-standard),
+                  box-shadow var(--bq-duration-fast) var(--bq-easing-standard);
+    }
+    .control:focus-within { border-color: var(--bq-border-focus,#2563eb); box-shadow: var(--bq-focus-ring); }
+    :host([error]:not([error=""])) .control { border-color: var(--bq-color-danger-500,#ef4444); }
+    :host([disabled]) .control { opacity: 0.5; cursor: not-allowed; background: var(--bq-bg-muted,#f1f5f9); }
+
+    .tags { display: contents; list-style: none; margin: 0; padding: 0; }
+    .tag {
+      display: inline-flex; align-items: center; gap: 0.25rem;
+      background: var(--bq-color-primary-50,#eff6ff);
+      color: var(--bq-color-primary-700,#1d4ed8);
+      border: 1px solid var(--bq-color-primary-200,#bfdbfe);
+      border-radius: var(--bq-radius-sm,0.25rem);
+      padding: 0.125rem 0.25rem 0.125rem 0.5rem;
+      font-size: var(--bq-font-size-sm,0.875rem);
+      font-family: var(--bq-font-family-sans);
+    }
+    .tag button {
+      border: none; background: none; cursor: pointer; line-height: 1;
+      color: inherit; padding: 0 0.125rem;
+      border-radius: var(--bq-radius-sm,0.25rem);
+    }
+    .tag button:hover { color: var(--bq-color-danger-600,#dc2626); }
+    .tag button:focus-visible { outline: 2px solid transparent; box-shadow: var(--bq-focus-ring); }
+
+    input {
+      flex: 1 1 6rem; min-width: 4rem;
+      border: none; outline: none; background: transparent;
+      color: var(--bq-text-base,#0f172a);
+      font-family: var(--bq-font-family-sans);
+    }
+    :host([size="sm"]) input { font-size: 0.875rem; padding: 0.25rem 0.375rem; }
+    :host([size="md"]) input, :host(:not([size])) input { font-size: 1rem; padding: 0.375rem 0.5rem; }
+    :host([size="lg"]) input { font-size: 1.125rem; padding: 0.5rem 0.625rem; }
+    input:disabled { cursor: not-allowed; }
+
+    .hint { font-size: var(--bq-font-size-sm,0.875rem); color: var(--bq-text-muted,#475569); font-family: var(--bq-font-family-sans); }
+    .error-msg { font-size: var(--bq-font-size-sm,0.875rem); color: var(--bq-color-danger-600,#dc2626); font-family: var(--bq-font-family-sans); }
+    .count { margin-inline-start: auto; font-size: var(--bq-font-size-xs,0.75rem); color: var(--bq-text-muted,#475569); }
+    @media (prefers-reduced-motion: reduce) {
+      .control { transition: none; }
+    }
+  `,
+  connected() {
+    const self = host<BqTagInputState>(this);
+    const scope = bind(self);
+    if (!self.getState<string>('uid')) self.setState('uid', uniqueId('bq-tags'));
+
+    const separator = () => self.getAttribute('separator') || ',';
+    const readTags = () =>
+      parseTags(self.getAttribute('value') ?? '', separator());
+    const isInteractive = () => !self.hasAttribute('disabled');
+
+    bindFormProxy(self, scope, {
+      value: () => self.getAttribute('value') ?? '',
+    });
+    bindValidation(self, scope, {
+      value: () => self.getAttribute('value') ?? '',
+    });
+
+    const commitTags = (tags: string[]) => {
+      self.setAttribute('value', tags.join(separator()));
+      self.dispatchEvent(
+        new CustomEvent('bq-change', {
+          detail: { value: tags.join(separator()), tags },
+          bubbles: true,
+          composed: true,
+        })
+      );
+    };
+
+    const commitDraft = (raw: string): boolean => {
+      const next = addTag(readTags(), raw, {
+        max: Number(self.getAttribute('max') ?? '0') || 0,
+        allowDuplicates: self.hasAttribute('allow-duplicates'),
+      });
+      if (!next) return false;
+      const tag = raw.trim();
+      commitTags(next);
+      self.dispatchEvent(
+        new CustomEvent('bq-add', {
+          detail: { tag },
+          bubbles: true,
+          composed: true,
+        })
+      );
+      return true;
+    };
+
+    const removeAt = (index: number) => {
+      const tags = readTags();
+      const tag = tags[index];
+      if (tag === undefined) return;
+      commitTags(tags.filter((_, i) => i !== index));
+      self.dispatchEvent(
+        new CustomEvent('bq-remove', {
+          detail: { tag },
+          bubbles: true,
+          composed: true,
+        })
+      );
+    };
+
+    const delimiters = (): string[] =>
+      Array.from(self.getAttribute('delimiters') ?? ',').filter(
+        (ch) => ch !== ''
+      );
+
+    scope.on(self.shadowRoot, 'input', (event) => {
+      const input = event.target as HTMLInputElement | null;
+      if (input?.tagName !== 'INPUT') return;
+
+      // A delimiter typed (or pasted) mid-string splits the draft into as many
+      // tags as it contains, so pasting "a, b, c" yields three tags.
+      const chars = delimiters();
+      if (chars.some((ch) => input.value.includes(ch))) {
+        const pattern = new RegExp(
+          `[${chars.map((ch) => ch.replace(/[.*+?^${}()|[\]\\-]/g, '\\$&')).join('')}]`
+        );
+        const parts = input.value.split(pattern);
+        const trailing = parts.pop() ?? '';
+        for (const part of parts) commitDraft(part);
+        input.value = trailing;
+        self.setState('draft', trailing);
+        return;
+      }
+      self.setState('draft', input.value);
+    });
+
+    scope.on(self.shadowRoot, 'keydown', (event) => {
+      const ke = event as KeyboardEvent;
+      if (!isInteractive()) return;
+      const input = ke.target as HTMLInputElement | null;
+
+      if (ke.key === 'Enter') {
+        if (!input || input.tagName !== 'INPUT') return;
+        // Only swallow Enter when it actually creates a tag, so an empty
+        // field still submits the surrounding form.
+        if (input.value.trim() === '') return;
+        ke.preventDefault();
+        if (commitDraft(input.value)) {
+          input.value = '';
+          self.setState('draft', '');
+        }
+        return;
+      }
+
+      if (ke.key === 'Backspace') {
+        if (!input || input.value !== '') return;
+        const tags = readTags();
+        if (tags.length === 0) return;
+        ke.preventDefault();
+        removeAt(tags.length - 1);
+        return;
+      }
+
+      if (ke.key === 'Escape') {
+        if (!input || input.value === '') return;
+        ke.preventDefault();
+        input.value = '';
+        self.setState('draft', '');
+      }
+    });
+
+    // Committing on blur means a half-typed tag is not silently discarded
+    // when the user tabs away.
+    scope.on(self.shadowRoot, 'focusout', (event) => {
+      const input = event.target as HTMLInputElement | null;
+      if (input?.tagName !== 'INPUT' || input.value.trim() === '') return;
+      if (commitDraft(input.value)) {
+        input.value = '';
+        self.setState('draft', '');
+      }
+    });
+
+    scope.on(self.shadowRoot, 'click', (event) => {
+      const button = (event.target as Element).closest(
+        '.tag button'
+      ) as HTMLElement | null;
+      if (button) {
+        if (!isInteractive()) return;
+        removeAt(Number(button.getAttribute('data-index') ?? '-1'));
+        return;
+      }
+      // Clicking anywhere in the field should put the caret in the input,
+      // the way a native multi-value field behaves.
+      if ((event.target as Element).closest('.control')) {
+        (
+          self.shadowRoot?.querySelector('input') as HTMLInputElement | null
+        )?.focus();
+      }
+    });
+  },
+  beforeUpdate() {
+    tagStore(this).snapshot = captureFocus(this.shadowRoot);
+  },
+  disconnected() {
+    release(this);
+  },
+  updated() {
+    const local = tagStore(this);
+    restoreFocus(this.shadowRoot, local.snapshot);
+    local.snapshot = null;
+    syncFormProxy(this);
+  },
+  render({ props, state }) {
+    const uid = state.uid || 'bq-tags';
+    const inputId = `${uid}-input`;
+    const tags = parseTags(props.value, props.separator || ',');
+    const hasError = Boolean(props.error);
+    const hasHint = Boolean(props.hint) && !hasError;
+    const max = Math.max(0, Math.trunc(props.max) || 0);
+    const full = max > 0 && tags.length >= max;
+
+    const describedBy: string[] = [];
+    if (hasError) describedBy.push(`${uid}-err`);
+    if (hasHint) describedBy.push(`${uid}-hint`);
+
+    const tagMarkup = tags
+      .map(
+        (tag, index) => `<li class="tag" part="tag">${escapeHtml(tag)}<button
+            type="button"
+            part="tag-remove"
+            data-index="${index}"
+            aria-label="${escapeHtml(t('tagInput.remove', { tag }))}"
+            ${props.disabled ? 'disabled' : ''}
+          >&times;</button></li>`
+      )
+      .join('');
+
+    return html`
+      <div class="field" part="field">
+        ${
+          props.label
+            ? `<label class="label" part="label" for="${escapeHtml(inputId)}">${escapeHtml(props.label)}${props.required ? '<span class="required-mark" aria-hidden="true"> *</span>' : ''}</label>`
+            : ''
+        }
+        <div class="control" part="control">
+          <ul
+            class="tags"
+            part="tags"
+            aria-label="${escapeHtml(t('tagInput.listLabel'))}"
+          >${tagMarkup}</ul>
+          <input
+            id="${escapeHtml(inputId)}"
+            part="input"
+            type="text"
+            autocomplete="off"
+            value="${escapeHtml(state.draft ?? '')}"
+            placeholder="${escapeHtml(full ? '' : props.placeholder || t('tagInput.placeholder'))}"
+            aria-invalid="${hasError ? 'true' : 'false'}"
+            aria-describedby="${escapeHtml([...describedBy, `${uid}-help`].join(' '))}"
+            ${props.required ? 'aria-required="true"' : ''}
+            ${props.disabled || full ? 'disabled' : ''}
+          />
+          ${max > 0 ? `<span class="count" part="count">${tags.length}/${max}</span>` : ''}
+        </div>
+        ${hasHint ? `<span class="hint" id="${uid}-hint" part="hint">${escapeHtml(props.hint)}</span>` : ''}
+        ${hasError ? `<span class="error-msg" id="${uid}-err" role="alert" part="error">${escapeHtml(props.error)}</span>` : ''}
+        <span class="sr-only" id="${uid}-help">${escapeHtml(t('tagInput.help'))}</span>
+        <span class="sr-only" role="status" aria-live="polite"
+          >${escapeHtml(t('tagInput.count', { count: tags.length }))}</span
+        >
+      </div>
+    `;
+  },
+};
+
+component<BqTagInputProps, BqTagInputState>('bq-tag-input', definition);
diff --git a/src/components/tag-input/index.ts b/src/components/tag-input/index.ts
new file mode 100644
index 0000000..d014f65
--- /dev/null
+++ b/src/components/tag-input/index.ts
@@ -0,0 +1 @@
+export * as __bqComponentEntry from './BqTagInput.js';
diff --git a/src/components/textarea/BqTextarea.ts b/src/components/textarea/BqTextarea.ts
index 96a8e15..9f4dabb 100644
--- a/src/components/textarea/BqTextarea.ts
+++ b/src/components/textarea/BqTextarea.ts
@@ -23,7 +23,10 @@ import { bool, component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { t } from '../../i18n/index.js';
 import { uniqueId } from '../../utils/dom.js';
-import { createFormProxy, type FormProxy } from '../../utils/form.js';
+import { bindFormProxy, syncFormProxy } from '../../utils/form.js';
+import { bind, release, store } from '../../utils/component.js';
+import { captureFocus, restoreFocus, type FocusSnapshot } from '../../utils/focus.js';
+import { bindValidation } from '../../utils/validation.js';
 import { baseStyles } from '../../utils/styles.js';
 
 type BqTextareaProps = {
@@ -42,6 +45,14 @@ type BqTextareaProps = {
 };
 type BqTextareaState = { uid: string };
 
+/**
+ * Holds the pre-render focus snapshot. Rendering replaces the whole shadow
+ * tree, so without this the field the user is typing in is destroyed on
+ * every keystroke that reflects a value to an attribute.
+ */
+const textareaFocusStore = (owner: object) =>
+  store<{ snapshot?: FocusSnapshot | null }>(owner, () => ({}));
+
 const definition: ComponentDefinition<BqTextareaProps, BqTextareaState> = {
   props: {
     label: { type: String, default: '' },
@@ -97,19 +108,22 @@ const definition: ComponentDefinition<BqTextareaProps, BqTextareaState> = {
     const self = this as unknown as BQEl;
     if (!self.getState<string>('uid')) self.setState('uid', uniqueId('bq-ta'));
 
-    // Form proxy for native <form> participation
-    const name = self.getAttribute('name') ?? '';
-    const value = self.getAttribute('value') ?? '';
-    const disabled = self.hasAttribute('disabled');
-    const proxy = createFormProxy(self, name, value, disabled, {
-      getLiveValue: () => {
+    const scope = bind(self);
+
+    const readValue = () => {
         const ta = self.shadowRoot?.querySelector(
           'textarea'
         ) as HTMLTextAreaElement | null;
         return ta ? ta.value : (self.getAttribute('value') ?? '');
-      },
-    });
-    (self as unknown as Record<string, unknown>)['_formProxy'] = proxy;
+    };
+
+    // Form proxy for native <form> participation
+    const proxy = bindFormProxy(self, scope, { value: readValue });
+
+    // The proxy submits through a hidden input, which the platform bars from
+    // constraint validation — so `required`/`pattern`/`minlength` have to be
+    // enforced here or they would render but never apply.
+    bindValidation(self, scope, { value: readValue });
 
     const ih = (e: Event) => {
       const t = e.target as HTMLTextAreaElement | null;
@@ -148,43 +162,22 @@ const definition: ComponentDefinition<BqTextareaProps, BqTextareaState> = {
           new CustomEvent('bq-blur', { bubbles: true, composed: true })
         );
     };
-    const s = self as unknown as Record<string, unknown>;
-    s['_ih'] = ih;
-    s['_ch'] = ch;
-    s['_fh'] = fh;
-    s['_bh'] = bh;
-    self.shadowRoot?.addEventListener('input', ih);
-    self.shadowRoot?.addEventListener('change', ch);
-    self.shadowRoot?.addEventListener('focusin', fh);
-    self.shadowRoot?.addEventListener('focusout', bh);
+    const shadow = self.shadowRoot;
+    scope.on(shadow, 'input', ih);
+    scope.on(shadow, 'change', ch);
+    scope.on(shadow, 'focusin', fh);
+    scope.on(shadow, 'focusout', bh);
   },
   disconnected() {
-    const s = this as unknown as Record<string, unknown>;
-    const sr = this.shadowRoot;
-    (['_ih', '_ch', '_fh', '_bh'] as const).forEach((k) => {
-      const h = s[k] as EventListener | undefined;
-      if (h)
-        sr?.removeEventListener(
-          k === '_ih'
-            ? 'input'
-            : k === '_ch'
-              ? 'change'
-              : k === '_fh'
-                ? 'focusin'
-                : 'focusout',
-          h
-        );
-    });
-    (s['_formProxy'] as FormProxy | undefined)?.cleanup();
+    release(this);
+  },
+  beforeUpdate() {
+    textareaFocusStore(this).snapshot = captureFocus(this.shadowRoot);
   },
   updated() {
-    const s = this as unknown as Record<string, unknown>;
-    const proxy = s['_formProxy'] as FormProxy | undefined;
-    if (proxy) {
-      proxy.setName(this.getAttribute('name') ?? '');
-      proxy.setValue(this.getAttribute('value') ?? '');
-      proxy.setDisabled(this.hasAttribute('disabled'));
-    }
+    restoreFocus(this.shadowRoot, textareaFocusStore(this).snapshot);
+    textareaFocusStore(this).snapshot = null;
+    syncFormProxy(this);
   },
   render({ props, state }) {
     const hasError = Boolean(props.error);
diff --git a/src/components/toast/BqToast.ts b/src/components/toast/BqToast.ts
index eea17d8..d8171f9 100644
--- a/src/components/toast/BqToast.ts
+++ b/src/components/toast/BqToast.ts
@@ -11,7 +11,7 @@ import type { ComponentDefinition } from '@bquery/bquery/component';
 import { component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { t } from '../../i18n/index.js';
-import { host } from '../../utils/component.js';
+import { bind, host, release } from '../../utils/component.js';
 import { baseStyles } from '../../utils/styles.js';
 
 type BqToastProps = {
@@ -64,20 +64,15 @@ const definition: ComponentDefinition<BqToastProps> = {
     const ch = (e: Event) => {
       if ((e.target as Element).closest('.close')) close();
     };
+    const scope = bind(self);
     const dur = parseInt(self.getAttribute('duration') ?? '4000', 10);
-    if (dur > 0) {
-      const timer = setTimeout(close, dur);
-      (self as unknown as Record<string, unknown>)['_timer'] = timer;
-    }
-    (self as unknown as Record<string, unknown>)['_ch'] = ch;
-    self.shadowRoot?.addEventListener('click', ch);
+    // The auto-dismiss timer is scope-owned, so a toast removed by hand
+    // cannot fire `close()` on an already-detached element afterwards.
+    if (dur > 0) scope.timeout(close, dur);
+    scope.on(self.shadowRoot, 'click', ch);
   },
   disconnected() {
-    const s = this as unknown as Record<string, unknown>;
-    const timer = s['_timer'] as ReturnType<typeof setTimeout> | undefined;
-    if (timer) clearTimeout(timer);
-    const ch = s['_ch'] as EventListener | undefined;
-    if (ch) this.shadowRoot?.removeEventListener('click', ch);
+    release(this);
   },
   render({ props }) {
     const icons: Record<string, string> = {
diff --git a/src/components/tooltip/BqTooltip.ts b/src/components/tooltip/BqTooltip.ts
index 4338b3c..14b7f4e 100644
--- a/src/components/tooltip/BqTooltip.ts
+++ b/src/components/tooltip/BqTooltip.ts
@@ -12,6 +12,7 @@ import { escapeHtml } from '@bquery/bquery/security';
 import type { Disposer } from '../../utils/component.js';
 import { bind, host, release, store } from '../../utils/component.js';
 import { uniqueId } from '../../utils/dom.js';
+import { autoPosition } from '../../utils/position.js';
 import { baseStyles } from '../../utils/styles.js';
 
 type BqTooltipProps = { content: string; placement: string; delay: number };
@@ -19,10 +20,11 @@ type BqTooltipState = { visible: boolean; uid: string };
 
 /** Per-instance handles shared between `connected()` and `updated()`. */
 const tooltipStore = (owner: object) =>
-  store<{ syncTrigger?: () => void; triggerElements: HTMLElement[] }>(
-    owner,
-    () => ({ triggerElements: [] })
-  );
+  store<{
+    syncTrigger?: () => void;
+    syncPosition?: () => void;
+    triggerElements: HTMLElement[];
+  }>(owner, () => ({ triggerElements: [] }));
 
 function addDescribedBy(element: HTMLElement, tooltipId: string): void {
   const current = element.getAttribute('aria-describedby');
@@ -59,14 +61,18 @@ const definition: ComponentDefinition<BqTooltipProps, BqTooltipState> = {
       background: var(--bq-color-secondary-900,#0f172a); color: #fff;
       font-family: var(--bq-font-family-sans); font-size: var(--bq-font-size-sm,0.875rem);
       padding: 0.375rem 0.625rem; border-radius: var(--bq-radius-md,0.375rem);
-      white-space: nowrap; pointer-events: none;
+      max-width: min(20rem, 90vw); width: max-content;
+      pointer-events: none;
       opacity: 0; transition: opacity var(--bq-duration-fast);
     }
     .tip[data-visible="true"] { opacity: 1; }
-    .tip[data-placement="top"]    { bottom: calc(100% + 6px); left: 50%; transform: translateX(-50%); }
-    .tip[data-placement="bottom"] { top:  calc(100% + 6px); left: 50%; transform: translateX(-50%); }
-    .tip[data-placement="left"]   { right: calc(100% + 6px); top: 50%; transform: translateY(-50%); }
-    .tip[data-placement="right"]  { left:  calc(100% + 6px); top: 50%; transform: translateY(-50%); }
+    /* Static fallback for the frame before the positioning engine measures,
+       and for anchors that were never laid out. Inline styles from
+       positionElement() take over as soon as real geometry is available. */
+    .tip[data-placement^="top"]    { bottom: calc(100% + 6px); left: 50%; transform: translateX(-50%); }
+    .tip[data-placement^="bottom"] { top:  calc(100% + 6px); left: 50%; transform: translateX(-50%); }
+    .tip[data-placement^="left"]   { right: calc(100% + 6px); top: 50%; transform: translateY(-50%); }
+    .tip[data-placement^="right"]  { left:  calc(100% + 6px); top: 50%; transform: translateY(-50%); }
     @media (prefers-reduced-motion: reduce) {
       .tip { transition: none; }
     }
@@ -95,6 +101,28 @@ const definition: ComponentDefinition<BqTooltipProps, BqTooltipState> = {
       clearShowTimer();
       self.setState('visible', false);
     };
+
+    // Anchored positioning only runs while the tip is on screen: an idle
+    // tooltip has no reason to hold scroll/resize listeners. Each render
+    // replaces the shadow tree, so the tracker is rebuilt against the fresh
+    // `.tip` element rather than a detached one.
+    let stopPosition: Disposer | null = null;
+    const syncPosition = () => {
+      stopPosition?.();
+      stopPosition = null;
+      if (self.getState<boolean>('visible') !== true) return;
+      const tip = self.shadowRoot?.querySelector(
+        '.tip'
+      ) as HTMLElement | null;
+      if (!tip) return;
+      stopPosition = scope.add(
+        autoPosition(self, tip, {
+          placement: self.getAttribute('placement') ?? 'top',
+          offset: 6,
+        })
+      );
+    };
+    local.syncPosition = syncPosition;
     const kh = (e: Event) => {
       if ((e as KeyboardEvent).key === 'Escape') hide();
     };
@@ -157,7 +185,9 @@ const definition: ComponentDefinition<BqTooltipProps, BqTooltipState> = {
     release(this);
   },
   updated() {
-    tooltipStore(this).syncTrigger?.();
+    const local = tooltipStore(this);
+    local.syncTrigger?.();
+    local.syncPosition?.();
   },
   render({ props, state }) {
     const visible = Boolean(state['visible']);
diff --git a/src/i18n/en.ts b/src/i18n/en.ts
index 6b29308..b055bb8 100644
--- a/src/i18n/en.ts
+++ b/src/i18n/en.ts
@@ -133,6 +133,36 @@ export const en = {
     remove: 'Remove file',
     selected: '{count} selected',
   },
+  combobox: {
+    placeholder: 'Search…',
+    noResults: 'No matches found',
+    clear: 'Clear selection',
+    toggle: 'Toggle options',
+    removeOption: 'Remove {label}',
+    resultCount: '{count} options available',
+    selected: '{count} selected',
+  },
+  tagInput: {
+    placeholder: 'Add a tag…',
+    remove: 'Remove {tag}',
+    listLabel: 'Tags',
+    help: 'Press Enter to add a tag, Backspace to remove the last one.',
+    count: '{count} tags',
+    limitReached: 'Tag limit reached',
+  },
+  validation: {
+    valueMissing: 'Please fill out this field.',
+    typeMismatchEmail: 'Please enter a valid email address.',
+    typeMismatchUrl: 'Please enter a valid URL.',
+    typeMismatchNumber: 'Please enter a number.',
+    patternMismatch: 'Please match the requested format.',
+    tooShort: 'Please use at least {min} characters.',
+    tooLong: 'Please use no more than {max} characters.',
+    rangeUnderflow: 'Value must be {min} or more.',
+    rangeOverflow: 'Value must be {max} or less.',
+    stepMismatch: 'Please enter a valid value.',
+    invalid: 'Please correct this field.',
+  },
 } as const;
 
 export type EnLocale = typeof en;
diff --git a/src/index.ts b/src/index.ts
index 7bcbcdc..0cdf728 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -38,6 +38,7 @@ import { __bqComponentEntry as buttonComponentEntry } from './components/button/
 import { __bqComponentEntry as cardComponentEntry } from './components/card/index.js';
 import { __bqComponentEntry as checkboxComponentEntry } from './components/checkbox/index.js';
 import { __bqComponentEntry as chipComponentEntry } from './components/chip/index.js';
+import { __bqComponentEntry as comboboxComponentEntry } from './components/combobox/index.js';
 import { __bqComponentEntry as dialogComponentEntry } from './components/dialog/index.js';
 import { __bqComponentEntry as dividerComponentEntry } from './components/divider/index.js';
 import { __bqComponentEntry as drawerComponentEntry } from './components/drawer/index.js';
@@ -56,6 +57,7 @@ import { __bqComponentEntry as spinnerComponentEntry } from './components/spinne
 import { __bqComponentEntry as statCardComponentEntry } from './components/stat-card/index.js';
 import { __bqComponentEntry as switchComponentEntry } from './components/switch/index.js';
 import { __bqComponentEntry as tableComponentEntry } from './components/table/index.js';
+import { __bqComponentEntry as tagInputComponentEntry } from './components/tag-input/index.js';
 import { __bqComponentEntry as tabsComponentEntry } from './components/tabs/index.js';
 import { __bqComponentEntry as textareaComponentEntry } from './components/textarea/index.js';
 import { __bqComponentEntry as tooltipComponentEntry } from './components/tooltip/index.js';
@@ -87,6 +89,7 @@ Object.defineProperty(registerAll, COMPONENT_ENTRY_MAP_KEY, {
     'card': cardComponentEntry,
     'checkbox': checkboxComponentEntry,
     'chip': chipComponentEntry,
+    'combobox': comboboxComponentEntry,
     'dialog': dialogComponentEntry,
     'divider': dividerComponentEntry,
     'drawer': drawerComponentEntry,
@@ -105,6 +108,7 @@ Object.defineProperty(registerAll, COMPONENT_ENTRY_MAP_KEY, {
     'stat-card': statCardComponentEntry,
     'switch': switchComponentEntry,
     'table': tableComponentEntry,
+    'tag-input': tagInputComponentEntry,
     'tabs': tabsComponentEntry,
     'textarea': textareaComponentEntry,
     'tooltip': tooltipComponentEntry,
diff --git a/src/utils/focus.ts b/src/utils/focus.ts
new file mode 100644
index 0000000..0aa08c1
--- /dev/null
+++ b/src/utils/focus.ts
@@ -0,0 +1,161 @@
+/**
+ * Focus and caret preservation across re-renders.
+ *
+ * The component runtime renders by assigning `shadowRoot.innerHTML`, which
+ * discards every node in the shadow tree and builds new ones. For a purely
+ * presentational component that is invisible. For a component containing a
+ * focused text field it is not: the focused node is destroyed, focus falls
+ * back to the document body, and the caret position is gone.
+ *
+ * Concretely, a control that reflects its value to an attribute on every
+ * keystroke re-renders on every keystroke, so the user can type exactly one
+ * character before losing the field.
+ *
+ * These helpers bracket a render — capture in `beforeUpdate()`, restore in
+ * `updated()` — and put focus and selection back on the node that replaced
+ * the one the user was in.
+ *
+ * ```ts
+ * beforeUpdate() { focusStore(this).snapshot = captureFocus(this.shadowRoot); },
+ * updated() { restoreFocus(this.shadowRoot, focusStore(this).snapshot); },
+ * ```
+ */
+
+/** Where focus and the text selection were before a render. */
+export interface FocusSnapshot {
+  /** Selector that re-finds the equivalent node in the new shadow tree. */
+  selector: string;
+  /** Caret/selection start, for text-entry elements. */
+  selectionStart: number | null;
+  /** Caret/selection end, for text-entry elements. */
+  selectionEnd: number | null;
+  /** Selection direction, for text-entry elements. */
+  selectionDirection: 'forward' | 'backward' | 'none' | null;
+}
+
+/** Elements whose selection range is worth preserving. */
+function isTextEntry(
+  el: Element
+): el is HTMLInputElement | HTMLTextAreaElement {
+  const tag = el.tagName;
+  if (tag === 'TEXTAREA') return true;
+  if (tag !== 'INPUT') return false;
+  // `selectionStart` throws on input types that have no text selection
+  // (number, email, checkbox, …), so only the text-like ones qualify.
+  const type = (el as HTMLInputElement).type;
+  return (
+    type === 'text' ||
+    type === 'search' ||
+    type === 'url' ||
+    type === 'tel' ||
+    type === 'password'
+  );
+}
+
+function cssEscape(value: string): string {
+  // Attribute values go inside a quoted selector, so only the quote and
+  // backslash need escaping.
+  return value.replace(/["\\]/g, '\\$&');
+}
+
+/**
+ * Derives a selector that will match the equivalent node after a re-render.
+ *
+ * `part` first: it is this library's convention for naming the meaningful
+ * elements of a shadow tree, it is stable across renders, and it is unique
+ * per component. Falls back to `id`, then to a tag/class shape.
+ */
+function describeElement(el: Element): string | null {
+  const part = el.getAttribute('part');
+  if (part) {
+    const first = part.trim().split(/\s+/)[0];
+    if (first) return `[part~="${cssEscape(first)}"]`;
+  }
+  const id = el.getAttribute('id');
+  if (id) return `[id="${cssEscape(id)}"]`;
+
+  const tag = el.tagName.toLowerCase();
+  const classes = Array.from(el.classList);
+  if (classes.length > 0) {
+    return `${tag}.${classes.map((c) => CSS_ESCAPE(c)).join('.')}`;
+  }
+  return tag;
+}
+
+// Class names may contain characters that are invalid bare in a selector.
+function CSS_ESCAPE(value: string): string {
+  return value.replace(/[^\w-]/g, (ch) => `\\${ch}`);
+}
+
+/**
+ * Records the focused element inside a shadow root, if any.
+ * Returns `null` when nothing in the tree holds focus, which is the common
+ * case and costs a single property read.
+ */
+export function captureFocus(root: ShadowRoot | null): FocusSnapshot | null {
+  const active = root?.activeElement as HTMLElement | null;
+  if (!active) return null;
+
+  const selector = describeElement(active);
+  if (!selector) return null;
+
+  const snapshot: FocusSnapshot = {
+    selector,
+    selectionStart: null,
+    selectionEnd: null,
+    selectionDirection: null,
+  };
+
+  if (isTextEntry(active)) {
+    try {
+      snapshot.selectionStart = active.selectionStart;
+      snapshot.selectionEnd = active.selectionEnd;
+      snapshot.selectionDirection = active.selectionDirection ?? null;
+    } catch {
+      /* selection unavailable for this input type — focus alone is enough */
+    }
+  }
+
+  return snapshot;
+}
+
+/**
+ * Restores a snapshot taken by {@link captureFocus}.
+ *
+ * Does nothing when something in the tree already has focus: that means the
+ * render did not disturb it, or the user has moved on, and stealing focus back
+ * would be worse than leaving it.
+ *
+ * @returns whether focus was actually restored.
+ */
+export function restoreFocus(
+  root: ShadowRoot | null,
+  snapshot: FocusSnapshot | null | undefined
+): boolean {
+  if (!root || !snapshot) return false;
+  if (root.activeElement) return false;
+
+  let next: HTMLElement | null = null;
+  try {
+    next = root.querySelector<HTMLElement>(snapshot.selector);
+  } catch {
+    return false;
+  }
+  if (!next || typeof next.focus !== 'function') return false;
+
+  next.focus();
+
+  if (snapshot.selectionStart !== null && isTextEntry(next)) {
+    try {
+      next.setSelectionRange(
+        snapshot.selectionStart,
+        snapshot.selectionEnd ?? snapshot.selectionStart,
+        snapshot.selectionDirection ?? undefined
+      );
+    } catch {
+      /* caret restore is best-effort */
+    }
+  }
+
+  return true;
+}
diff --git a/src/utils/form.ts b/src/utils/form.ts
index b542c00..1ec0c16 100644
--- a/src/utils/form.ts
+++ b/src/utils/form.ts
@@ -6,6 +6,8 @@
  * elements to participate in native `<form>` submission.
  */
 
+import type { ComponentScope } from './component.js';
+
 export type FormProxyOptions = {
   /**
    * Optional callback invoked just before native form submission to
@@ -98,3 +100,97 @@ export function createFormProxy(
     },
   };
 }
+
+// ─── Scope-managed binding ───────────────────────────────────────────────────
+
+/**
+ * How a component derives the values mirrored into its hidden input.
+ *
+ * `name` and `disabled` default to reading the host's `name` attribute and
+ * `disabled` presence, which is what every current caller wants; pass them
+ * only when the component's public API differs.
+ */
+export interface FormProxyBindingOptions {
+  /** The value to submit. Read on every sync and on `formdata`. */
+  value: () => string;
+  /** Field name. @default the host's `name` attribute */
+  name?: () => string;
+  /** Whether the field is excluded from submission. @default the host's `disabled` attribute */
+  disabled?: () => boolean;
+}
+
+/** Handle returned by {@link bindFormProxy}. */
+export interface FormProxyBinding {
+  /** Pushes name, value and disabled onto the hidden input. */
+  sync(): void;
+  /** Mirrors a value directly, for use inside change handlers. */
+  setValue(value: string): void;
+}
+
+const bindings = new WeakMap<object, FormProxyBinding>();
+
+/**
+ * Creates a form proxy owned by the component's disposer scope and registers
+ * it for {@link syncFormProxy}.
+ *
+ * Every form control repeated the same four steps: create the proxy in
+ * `connected()`, stash it on the host, push name/value/disabled from
+ * `updated()`, and tear it down in `disconnected()`. That boilerplate is what
+ * this collapses — the scope owns the teardown, so a control removed from the
+ * DOM can no longer leave its hidden input behind.
+ *
+ * ```ts
+ * connected() {
+ *   const self = host(this);
+ *   const scope = bind(self);
+ *   bindFormProxy(self, scope, { value: () => readValue(self) });
+ * },
+ * updated() { syncFormProxy(this); },
+ * disconnected() { release(this); },
+ * ```
+ */
+export function bindFormProxy(
+  el: HTMLElement,
+  scope: ComponentScope,
+  options: FormProxyBindingOptions
+): FormProxyBinding {
+  const readName = options.name ?? (() => el.getAttribute('name') ?? '');
+  const readDisabled = options.disabled ?? (() => el.hasAttribute('disabled'));
+
+  const proxy = createFormProxy(
+    el,
+    readName(),
+    options.value(),
+    readDisabled(),
+    // The lazy read matters for controls whose value changes faster than
+    // their attributes settle — a slider released as the form submits, say.
+    { getLiveValue: options.value }
+  );
+
+  const binding: FormProxyBinding = {
+    sync() {
+      proxy.setName(readName());
+      proxy.setValue(options.value());
+      proxy.setDisabled(readDisabled());
+    },
+    setValue(value: string) {
+      proxy.setValue(value);
+    },
+  };
+
+  bindings.set(el, binding);
+  scope.add(() => {
+    bindings.delete(el);
+    proxy.cleanup();
+  });
+
+  return binding;
+}
+
+/**
+ * Syncs the form proxy registered for a component instance, if any.
+ * Safe to call from `updated()` before `connected()` has ever run.
+ */
+export function syncFormProxy(owner: object): void {
+  bindings.get(owner)?.sync();
+}
diff --git a/src/utils/index.ts b/src/utils/index.ts
index e532224..881b6f5 100644
--- a/src/utils/index.ts
+++ b/src/utils/index.ts
@@ -9,6 +9,8 @@ export {
   unlinkDescribedBy,
 } from './aria.js';
 export { cn } from './cn.js';
+export { captureFocus, restoreFocus } from './focus.js';
+export type { FocusSnapshot } from './focus.js';
 export { bind, host, release, store } from './component.js';
 export type { ComponentScope, Disposer } from './component.js';
 export {
@@ -19,8 +21,41 @@ export {
   trapFocus,
   uniqueId,
 } from './dom.js';
-export { createFormProxy } from './form.js';
-export type { FormProxy } from './form.js';
+export { bindFormProxy, createFormProxy, syncFormProxy } from './form.js';
+export type {
+  FormProxy,
+  FormProxyBinding,
+  FormProxyBindingOptions,
+} from './form.js';
+export {
+  bindValidation,
+  validateValue,
+  validationMessageFor,
+} from './validation.js';
+export type {
+  ValidatableElement,
+  ValidationBindingOptions,
+  ValidationRules,
+  ValidityFlags,
+} from './validation.js';
+export {
+  autoPosition,
+  computePosition,
+  formatPlacement,
+  parsePlacement,
+  positionElement,
+  resolvePosition,
+} from './position.js';
+export type {
+  Align,
+  Placement,
+  PlacementInput,
+  PositionOptions,
+  PositionResult,
+  Rect,
+  ResolvePositionInput,
+  Side,
+} from './position.js';
 export {
   baseStyles,
   focusVisible,
diff --git a/src/utils/position.ts b/src/utils/position.ts
new file mode 100644
index 0000000..ce8dfeb
--- /dev/null
+++ b/src/utils/position.ts
@@ -0,0 +1,558 @@
+/**
+ * Anchored-positioning engine for the overlay components.
+ *
+ * Tooltip, Popover and Dropdown-Menu used to place their panels with static
+ * CSS (`top: 100%`, `left: 0`, …). That is fine in the middle of a page and
+ * wrong everywhere else: a menu opened near the bottom of the viewport renders
+ * past the fold, a tooltip on a right-aligned toolbar button is clipped by the
+ * window edge, and neither can react to the page scrolling underneath them.
+ *
+ * This module computes a placement that actually fits:
+ *
+ * - **flip** — when the preferred side overflows, try the opposite side and
+ *   keep whichever has more room.
+ * - **shift** — slide the panel along its cross axis to stay inside the
+ *   viewport, without detaching it from the anchor.
+ * - **arrow** — report where a pointer arrow has to sit so it still points at
+ *   the anchor after flipping and shifting.
+ *
+ * The geometry lives in {@link resolvePosition}, a pure function over plain
+ * rectangles. The DOM-reading wrappers ({@link computePosition},
+ * {@link positionElement}, {@link autoPosition}) only gather rects and write
+ * styles, so the interesting behaviour stays unit-testable in an environment
+ * whose layout engine reports everything as zero.
+ */
+import type { Disposer } from './component.js';
+
+/** The edge of the anchor a floating element is placed against. */
+export type Side = 'top' | 'bottom' | 'left' | 'right';
+
+/** How the floating element lines up along the anchor's cross axis. */
+export type Align = 'start' | 'center' | 'end';
+
+/** A side, optionally qualified by a cross-axis alignment. */
+export type Placement = Side | `${Side}-${Align}`;
+
+/**
+ * A placement as it arrives from an attribute: any string is accepted (and
+ * normalised by {@link parsePlacement}), while the known values still surface
+ * in editor completion.
+ */
+export type PlacementInput = Placement | (string & {});
+
+/** Minimal rectangle shape — a structural subset of `DOMRect`. */
+export interface Rect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/** Geometry inputs for {@link resolvePosition}. */
+export interface ResolvePositionInput {
+  /** Rect of the element being pointed at, in viewport coordinates. */
+  anchor: Rect;
+  /** Rect of the element being placed. Only `width`/`height` are read. */
+  floating: Rect;
+  /** Available space, in viewport coordinates. */
+  viewport: Rect;
+  /** Preferred placement. @default 'bottom' */
+  placement?: PlacementInput;
+  /** Gap between anchor and floating element, in pixels. @default 8 */
+  offset?: number;
+  /** Minimum distance to keep from the viewport edges. @default 8 */
+  padding?: number;
+  /** Allow falling back to the opposite side. @default true */
+  flip?: boolean;
+  /** Allow sliding along the cross axis to stay in view. @default true */
+  shift?: boolean;
+  /** Size of the arrow along the cross axis, used to clamp it. @default 0 */
+  arrowSize?: number;
+  /** Corner radius the arrow must stay clear of. @default 4 */
+  arrowPadding?: number;
+}
+
+/** Result of {@link resolvePosition}, in viewport coordinates. */
+export interface PositionResult {
+  /** Left edge of the floating element. */
+  x: number;
+  /** Top edge of the floating element. */
+  y: number;
+  /** The placement actually used, after flipping. */
+  placement: Placement;
+  /** Side component of {@link PositionResult.placement}. */
+  side: Side;
+  /** Align component of {@link PositionResult.placement}. */
+  align: Align;
+  /** True when the preferred side was abandoned. */
+  flipped: boolean;
+  /** Pixels the element was slid along its cross axis. */
+  shifted: number;
+  /**
+   * Offset of the arrow from the floating element's leading edge along its
+   * cross axis, or `null` when no arrow size was supplied.
+   */
+  arrow: number | null;
+  /**
+   * False when the anchor reported no extent, meaning the coordinates are not
+   * trustworthy and callers should leave the CSS fallback in place.
+   */
+  measured: boolean;
+}
+
+const OPPOSITE: Record<Side, Side> = {
+  top: 'bottom',
+  bottom: 'top',
+  left: 'right',
+  right: 'left',
+};
+
+const SIDES: readonly Side[] = ['top', 'bottom', 'left', 'right'];
+const ALIGNS: readonly Align[] = ['start', 'center', 'end'];
+
+/**
+ * Splits a placement string into its parts, falling back to `bottom-center`
+ * for anything unrecognised so a typo in an attribute cannot throw.
+ */
+export function parsePlacement(placement: string | undefined | null): {
+  side: Side;
+  align: Align;
+} {
+  const raw = (placement ?? '').trim().toLowerCase();
+  const [sidePart, alignPart] = raw.split('-') as [string, string | undefined];
+  const side = (SIDES as readonly string[]).includes(sidePart)
+    ? (sidePart as Side)
+    : 'bottom';
+  const align =
+    alignPart && (ALIGNS as readonly string[]).includes(alignPart)
+      ? (alignPart as Align)
+      : 'center';
+  return { side, align };
+}
+
+/** Rebuilds a placement string from its parts. */
+export function formatPlacement(side: Side, align: Align): Placement {
+  return align === 'center' ? side : (`${side}-${align}` as Placement);
+}
+
+/** True when the side runs along the vertical axis. */
+function isVertical(side: Side): boolean {
+  return side === 'top' || side === 'bottom';
+}
+
+const rectRight = (r: Rect) => r.x + r.width;
+const rectBottom = (r: Rect) => r.y + r.height;
+
+/** Main-axis coordinate for a side, before any shifting. */
+function mainAxis(
+  side: Side,
+  anchor: Rect,
+  floating: Rect,
+  offset: number
+): number {
+  switch (side) {
+    case 'top':
+      return anchor.y - floating.height - offset;
+    case 'bottom':
+      return rectBottom(anchor) + offset;
+    case 'left':
+      return anchor.x - floating.width - offset;
+    case 'right':
+      return rectRight(anchor) + offset;
+  }
+}
+
+/** Cross-axis coordinate for an alignment, before any shifting. */
+function crossAxis(
+  side: Side,
+  align: Align,
+  anchor: Rect,
+  floating: Rect
+): number {
+  const vertical = isVertical(side);
+  const anchorStart = vertical ? anchor.x : anchor.y;
+  const anchorSize = vertical ? anchor.width : anchor.height;
+  const floatingSize = vertical ? floating.width : floating.height;
+  switch (align) {
+    case 'start':
+      return anchorStart;
+    case 'end':
+      return anchorStart + anchorSize - floatingSize;
+    case 'center':
+      return anchorStart + (anchorSize - floatingSize) / 2;
+  }
+}
+
+/**
+ * Free space between the anchor and the viewport edge on a given side.
+ * Used to decide whether flipping actually buys anything.
+ */
+function spaceOn(
+  side: Side,
+  anchor: Rect,
+  viewport: Rect,
+  padding: number
+): number {
+  switch (side) {
+    case 'top':
+      return anchor.y - viewport.y - padding;
+    case 'bottom':
+      return rectBottom(viewport) - rectBottom(anchor) - padding;
+    case 'left':
+      return anchor.x - viewport.x - padding;
+    case 'right':
+      return rectRight(viewport) - rectRight(anchor) - padding;
+  }
+}
+
+/** Size the floating element consumes along a side's main axis. */
+function mainSize(side: Side, floating: Rect, offset: number): number {
+  return (isVertical(side) ? floating.height : floating.width) + offset;
+}
+
+/**
+ * Computes a viewport-relative position for a floating element.
+ *
+ * Pure geometry: no DOM access, no side effects. Every input is a plain
+ * rectangle, which is what makes the flip/shift behaviour testable without a
+ * real layout engine.
+ *
+ * Degenerate input is handled rather than rejected — a zero-sized viewport
+ * (which is what a headless DOM reports) disables collision handling and the
+ * preferred placement is returned untouched, so components behave predictably
+ * under test and in browsers alike.
+ */
+export function resolvePosition(input: ResolvePositionInput): PositionResult {
+  const {
+    anchor,
+    floating,
+    viewport,
+    offset = 8,
+    padding = 8,
+    flip = true,
+    shift = true,
+    arrowSize = 0,
+    arrowPadding = 4,
+  } = input;
+
+  const preferred = parsePlacement(input.placement);
+  // Collision handling needs both a viewport to collide with and an anchor
+  // that has actually been laid out. A zero-sized anchor — an element still
+  // in `display: none`, or any element in a headless DOM — would otherwise
+  // report itself as overflowing every edge and flip for no reason. Falling
+  // through to the preferred placement is both correct and predictable.
+  const anchored = anchor.width > 0 || anchor.height > 0;
+  const measurable = anchored && viewport.width > 0 && viewport.height > 0;
+
+  let side = preferred.side;
+  let align = preferred.align;
+  let flipped = false;
+
+  if (measurable && flip) {
+    const available = spaceOn(side, anchor, viewport, padding);
+    const needed = mainSize(side, floating, offset);
+    if (available < needed) {
+      const opposite = OPPOSITE[side];
+      const oppositeAvailable = spaceOn(opposite, anchor, viewport, padding);
+      // Only flip when the far side is genuinely roomier; otherwise a panel
+      // that fits nowhere would jump sides for no benefit.
+      if (oppositeAvailable > available) {
+        side = opposite;
+        flipped = true;
+      }
+    }
+  }
+
+  const vertical = isVertical(side);
+  const floatingCross = vertical ? floating.width : floating.height;
+  const viewportCrossStart = vertical ? viewport.x : viewport.y;
+  const viewportCrossEnd = vertical
+    ? rectRight(viewport)
+    : rectBottom(viewport);
+
+  // Cross-axis flip: a `-start` panel hanging off the right edge is usually
+  // better served by `-end`, which is cheaper than shifting it far off-anchor.
+  if (measurable && flip && align !== 'center') {
+    const current = crossAxis(side, align, anchor, floating);
+    const overflows =
+      current < viewportCrossStart + padding ||
+      current + floatingCross > viewportCrossEnd - padding;
+    if (overflows) {
+      const swapped: Align = align === 'start' ? 'end' : 'start';
+      const candidate = crossAxis(side, swapped, anchor, floating);
+      const candidateFits =
+        candidate >= viewportCrossStart + padding &&
+        candidate + floatingCross <= viewportCrossEnd - padding;
+      if (candidateFits) align = swapped;
+    }
+  }
+
+  const main = mainAxis(side, anchor, floating, offset);
+  const crossIdeal = crossAxis(side, align, anchor, floating);
+  let cross = crossIdeal;
+
+  if (measurable && shift) {
+    const min = viewportCrossStart + padding;
+    const max = viewportCrossEnd - padding - floatingCross;
+    // When the element is wider than the viewport, `max` falls below `min`;
+    // pinning to `min` keeps the leading edge visible instead of the trailing.
+    cross = max < min ? min : Math.min(Math.max(cross, min), max);
+  }
+
+  const shifted = cross - crossIdeal;
+
+  let arrow: number | null = null;
+  if (arrowSize > 0) {
+    const anchorCrossStart = vertical ? anchor.x : anchor.y;
+    const anchorCrossSize = vertical ? anchor.width : anchor.height;
+    // Point at the anchor's midpoint, expressed relative to the panel's own
+    // leading edge, then keep it clear of the rounded corners.
+    const target = anchorCrossStart + anchorCrossSize / 2 - cross - arrowSize / 2;
+    const min = arrowPadding;
+    const max = floatingCross - arrowSize - arrowPadding;
+    arrow = max < min ? min : Math.min(Math.max(target, min), max);
+  }
+
+  return {
+    x: vertical ? cross : main,
+    y: vertical ? main : cross,
+    placement: formatPlacement(side, align),
+    side,
+    align,
+    flipped,
+    shifted,
+    arrow,
+    measured: anchored,
+  };
+}
+
+/** Options accepted by the DOM-facing positioning helpers. */
+export interface PositionOptions
+  extends Omit<ResolvePositionInput, 'anchor' | 'floating' | 'viewport'> {
+  /**
+   * Element the arrow is rendered as. Its cross-axis size is measured and the
+   * resolved offset is written back onto it.
+   */
+  arrowElement?: HTMLElement | null | undefined;
+  /**
+   * Coordinate space the returned `x`/`y` are expressed in.
+   *
+   * - `'absolute'` (default) — relative to `offsetParent`, matching a panel
+   *   absolutely positioned inside its `position: relative` host.
+   * - `'fixed'` — raw viewport coordinates.
+   */
+  strategy?: 'absolute' | 'fixed';
+}
+
+function toRect(rect: DOMRect | Rect): Rect {
+  return {
+    x: rect.x,
+    y: rect.y,
+    width: rect.width,
+    height: rect.height,
+  };
+}
+
+/** Reads an element's viewport rect, tolerating environments without layout. */
+function measure(el: Element): Rect {
+  const fn = (el as Element & { getBoundingClientRect?: () => DOMRect })
+    .getBoundingClientRect;
+  if (typeof fn !== 'function') return { x: 0, y: 0, width: 0, height: 0 };
+  try {
+    return toRect(fn.call(el));
+  } catch {
+    return { x: 0, y: 0, width: 0, height: 0 };
+  }
+}
+
+/** The visible viewport rect, or a zero rect when there is no window. */
+function viewportRect(el: Element): Rect {
+  const view = el.ownerDocument?.defaultView;
+  if (!view) return { x: 0, y: 0, width: 0, height: 0 };
+  return {
+    x: 0,
+    y: 0,
+    width: view.innerWidth || 0,
+    height: view.innerHeight || 0,
+  };
+}
+
+/**
+ * Measures anchor and floating element, then resolves a placement for them.
+ * Coordinates follow {@link PositionOptions.strategy}.
+ */
+export function computePosition(
+  anchor: Element,
+  floating: HTMLElement,
+  options: PositionOptions = {}
+): PositionResult {
+  const { arrowElement, strategy = 'absolute', ...rest } = options;
+  const anchorRect = measure(anchor);
+  const floatingRect = measure(floating);
+  const arrowRect = arrowElement ? measure(arrowElement) : null;
+  const { side } = parsePlacement(rest.placement);
+
+  const resolved = resolvePosition({
+    ...rest,
+    anchor: anchorRect,
+    floating: floatingRect,
+    viewport: viewportRect(floating),
+    ...(arrowRect
+      ? {
+          arrowSize: isVertical(side) ? arrowRect.width : arrowRect.height,
+        }
+      : {}),
+  });
+
+  if (strategy === 'fixed') return resolved;
+
+  // Absolute coordinates are relative to the offset parent's padding box; the
+  // panel's own rect already accounts for borders, so the parent rect is the
+  // only correction needed.
+  const parent = floating.offsetParent ?? floating.parentElement;
+  if (!parent) return resolved;
+  const parentRect = measure(parent);
+  return {
+    ...resolved,
+    x: resolved.x - parentRect.x,
+    y: resolved.y - parentRect.y,
+  };
+}
+
+/**
+ * Resolves a placement and writes it to the floating element's inline styles,
+ * mirroring the outcome onto `data-placement` (and `data-side`) so CSS can key
+ * transitions and arrow rotation off the *effective* placement rather than the
+ * requested one.
+ */
+export function positionElement(
+  anchor: Element,
+  floating: HTMLElement,
+  options: PositionOptions = {}
+): PositionResult {
+  const result = computePosition(anchor, floating, options);
+
+  // Without a laid-out anchor the coordinates are meaningless. Publishing the
+  // requested placement and leaving the stylesheet's static rules untouched
+  // degrades to the pre-engine behaviour instead of pinning the panel to 0,0.
+  if (!result.measured) {
+    floating.setAttribute('data-placement', result.placement);
+    floating.setAttribute('data-side', result.side);
+    return result;
+  }
+
+  floating.style.position = options.strategy === 'fixed' ? 'fixed' : 'absolute';
+  floating.style.left = `${Math.round(result.x)}px`;
+  floating.style.top = `${Math.round(result.y)}px`;
+  // The static-CSS placement rules used `right`/`bottom` for some sides; clear
+  // them so a stale value cannot fight the computed offsets.
+  floating.style.right = 'auto';
+  floating.style.bottom = 'auto';
+  floating.style.transform = 'none';
+  floating.setAttribute('data-placement', result.placement);
+  floating.setAttribute('data-side', result.side);
+
+  const arrowEl = options.arrowElement;
+  if (arrowEl && result.arrow !== null) {
+    const vertical = result.side === 'top' || result.side === 'bottom';
+    if (vertical) {
+      arrowEl.style.left = `${Math.round(result.arrow)}px`;
+      arrowEl.style.top = '';
+    } else {
+      arrowEl.style.top = `${Math.round(result.arrow)}px`;
+      arrowEl.style.left = '';
+    }
+  }
+
+  return result;
+}
+
+/** Collects scrollable ancestors so the panel can follow them. */
+function scrollAncestors(el: Element): EventTarget[] {
+  const targets: EventTarget[] = [];
+  let node: Node | null = el.parentNode;
+  while (node) {
+    if (node instanceof ShadowRoot) {
+      node = node.host;
+      continue;
+    }
+    if (node instanceof Element) {
+      targets.push(node);
+      node = node.parentNode;
+      continue;
+    }
+    break;
+  }
+  const view = el.ownerDocument?.defaultView;
+  if (view) targets.push(view);
+  return targets;
+}
+
+/**
+ * Keeps a floating element positioned while it is visible.
+ *
+ * Repositions immediately, then again on scroll of any ancestor, on window
+ * resize, and — where supported — whenever the anchor or the panel changes
+ * size. Returns a disposer; register it on the component scope so an element
+ * disconnected while open cannot strand listeners on `window`.
+ */
+export function autoPosition(
+  anchor: Element,
+  floating: HTMLElement,
+  options: PositionOptions = {}
+): Disposer {
+  let frame: number | null = null;
+  let disposed = false;
+
+  const apply = () => {
+    if (disposed || !floating.isConnected) return;
+    positionElement(anchor, floating, options);
+  };
+
+  // Scroll fires far more often than layout needs updating; coalescing to one
+  // frame keeps a long scroll from thrashing measurement and style writes.
+  const schedule = () => {
+    if (disposed || frame !== null) return;
+    const view = floating.ownerDocument?.defaultView;
+    if (!view?.requestAnimationFrame) {
+      apply();
+      return;
+    }
+    frame = view.requestAnimationFrame(() => {
+      frame = null;
+      apply();
+    });
+  };
+
+  apply();
+
+  const targets = scrollAncestors(anchor);
+  for (const target of targets) {
+    target.addEventListener('scroll', schedule, { passive: true });
+  }
+  const view = floating.ownerDocument?.defaultView;
+  view?.addEventListener('resize', schedule, { passive: true });
+
+  let observer: ResizeObserver | null = null;
+  const ResizeObserverCtor = (
+    view as unknown as { ResizeObserver?: typeof ResizeObserver } | undefined
+  )?.ResizeObserver;
+  if (ResizeObserverCtor) {
+    observer = new ResizeObserverCtor(schedule);
+    observer.observe(anchor);
+    observer.observe(floating);
+  }
+
+  return () => {
+    if (disposed) return;
+    disposed = true;
+    if (frame !== null) view?.cancelAnimationFrame?.(frame);
+    frame = null;
+    for (const target of targets) {
+      target.removeEventListener('scroll', schedule);
+    }
+    view?.removeEventListener('resize', schedule);
+    observer?.disconnect();
+    observer = null;
+  };
+}
diff --git a/src/utils/validation.ts b/src/utils/validation.ts
new file mode 100644
index 0000000..dc048a4
--- /dev/null
+++ b/src/utils/validation.ts
@@ -0,0 +1,424 @@
+/**
+ * Constraint validation for @bquery/ui form controls.
+ *
+ * The library's form controls submit through a hidden-input proxy (see
+ * `form.ts`), and hidden inputs are *barred from constraint validation* by the
+ * HTML spec. That means `required`, `minlength`, `pattern` and friends render
+ * as attributes but the browser never enforces them, and a `<form>` full of
+ * `bq-*` controls submits regardless of what the user typed.
+ *
+ * This module closes that gap by reimplementing the parts of the Constraint
+ * Validation API that apply to text-like values, and by intercepting form
+ * submission for the controls that opted in.
+ *
+ * The rule evaluation in {@link validateValue} is a pure function, so the
+ * semantics — which are fiddly, and where deviating from the platform would be
+ * a bug — are testable without a DOM.
+ */
+import { t } from '../i18n/index.js';
+import type { ComponentScope } from './component.js';
+
+/**
+ * The subset of `ValidityState` this module can determine.
+ *
+ * `badInput` and `stepMismatch` for date-like types are deliberately absent:
+ * they depend on a native control's parsing, which a proxied value has no
+ * access to.
+ */
+export interface ValidityFlags {
+  /** A required field was left empty. */
+  valueMissing: boolean;
+  /** The value does not match the declared `type`. */
+  typeMismatch: boolean;
+  /** The value does not match the declared `pattern`. */
+  patternMismatch: boolean;
+  /** Shorter than `minlength`. */
+  tooShort: boolean;
+  /** Longer than `maxlength`. */
+  tooLong: boolean;
+  /** Numerically below `min`. */
+  rangeUnderflow: boolean;
+  /** Numerically above `max`. */
+  rangeOverflow: boolean;
+  /** Not on the `step` grid. */
+  stepMismatch: boolean;
+  /** A message was installed via `setCustomValidity()`. */
+  customError: boolean;
+  /** True when every other flag is false. */
+  valid: boolean;
+}
+
+/** Declarative constraints, mirroring the equivalent HTML attributes. */
+export interface ValidationRules {
+  required?: boolean;
+  minLength?: number | undefined;
+  maxLength?: number | undefined;
+  min?: number | undefined;
+  max?: number | undefined;
+  step?: number | undefined;
+  pattern?: string | undefined;
+  /** `email`, `url` and `number` are enforced; anything else is treated as text. */
+  type?: string | undefined;
+  /** Message installed by `setCustomValidity()`. */
+  customError?: string | undefined;
+}
+
+const VALID: ValidityFlags = {
+  valueMissing: false,
+  typeMismatch: false,
+  patternMismatch: false,
+  tooShort: false,
+  tooLong: false,
+  rangeUnderflow: false,
+  rangeOverflow: false,
+  stepMismatch: false,
+  customError: false,
+  valid: true,
+};
+
+// Deliberately permissive, matching the HTML spec's definition of a valid
+// email address rather than trying to be cleverer than the platform.
+const EMAIL_RE = /^[^\s@]+@[^\s@.]+(\.[^\s@.]+)+$/;
+
+function isValidUrl(value: string): boolean {
+  try {
+    const url = new URL(value);
+    return Boolean(url.protocol);
+  } catch {
+    return false;
+  }
+}
+
+/** Floating-point-safe step check. */
+function offGrid(value: number, min: number, step: number): boolean {
+  if (!Number.isFinite(step) || step <= 0) return false;
+  const offset = (value - min) / step;
+  const nearest = Math.round(offset);
+  // 1e-9 absorbs the representation error of decimal steps like 0.1, which
+  // would otherwise report a mismatch for values the user typed exactly.
+  return Math.abs(offset - nearest) > 1e-9;
+}
+
+/**
+ * Evaluates a value against a set of constraints.
+ *
+ * Follows the platform's ordering rules: an empty value only ever triggers
+ * `valueMissing`, because the browser does not apply format or range
+ * constraints to a field the user has not filled in.
+ */
+export function validateValue(
+  value: string,
+  rules: ValidationRules = {}
+): ValidityFlags {
+  const flags: ValidityFlags = { ...VALID };
+  const customError = Boolean(rules.customError);
+  const trimmed = value.trim();
+
+  if (rules.required && trimmed === '') {
+    return { ...flags, valueMissing: true, customError, valid: false };
+  }
+
+  // An empty optional field is valid regardless of the other constraints —
+  // this is what lets `minlength` coexist with an optional input.
+  if (trimmed === '') {
+    return { ...flags, customError, valid: !customError };
+  }
+
+  if (rules.type === 'email') flags.typeMismatch = !EMAIL_RE.test(value);
+  else if (rules.type === 'url') flags.typeMismatch = !isValidUrl(value);
+  else if (rules.type === 'number')
+    flags.typeMismatch = !Number.isFinite(Number(value));
+
+  if (rules.pattern) {
+    try {
+      // Anchored, as the platform does for the `pattern` attribute.
+      flags.patternMismatch = !new RegExp(`^(?:${rules.pattern})$`, 'v').test(
+        value
+      );
+    } catch {
+      try {
+        flags.patternMismatch = !new RegExp(`^(?:${rules.pattern})$`).test(
+          value
+        );
+      } catch {
+        // An unparseable pattern is ignored rather than failing the field,
+        // matching how browsers treat an invalid `pattern` attribute.
+        flags.patternMismatch = false;
+      }
+    }
+  }
+
+  if (typeof rules.minLength === 'number' && value.length < rules.minLength) {
+    flags.tooShort = true;
+  }
+  if (typeof rules.maxLength === 'number' && value.length > rules.maxLength) {
+    flags.tooLong = true;
+  }
+
+  const numeric = Number(value);
+  if (!flags.typeMismatch && Number.isFinite(numeric)) {
+    if (typeof rules.min === 'number' && numeric < rules.min) {
+      flags.rangeUnderflow = true;
+    }
+    if (typeof rules.max === 'number' && numeric > rules.max) {
+      flags.rangeOverflow = true;
+    }
+    if (typeof rules.step === 'number') {
+      flags.stepMismatch = offGrid(numeric, rules.min ?? 0, rules.step);
+    }
+  }
+
+  flags.customError = customError;
+  flags.valid =
+    !flags.valueMissing &&
+    !flags.typeMismatch &&
+    !flags.patternMismatch &&
+    !flags.tooShort &&
+    !flags.tooLong &&
+    !flags.rangeUnderflow &&
+    !flags.rangeOverflow &&
+    !flags.stepMismatch &&
+    !flags.customError;
+
+  return flags;
+}
+
+/**
+ * Picks the localized message for a set of flags.
+ *
+ * A custom message always wins — it is the author speaking about their own
+ * field, which is more useful than a generic constraint message.
+ */
+export function validationMessageFor(
+  flags: ValidityFlags,
+  rules: ValidationRules = {}
+): string {
+  if (flags.valid) return '';
+  if (flags.customError && rules.customError) return rules.customError;
+  if (flags.valueMissing) return t('validation.valueMissing');
+  if (flags.typeMismatch) {
+    if (rules.type === 'email') return t('validation.typeMismatchEmail');
+    if (rules.type === 'url') return t('validation.typeMismatchUrl');
+    if (rules.type === 'number') return t('validation.typeMismatchNumber');
+  }
+  if (flags.tooShort)
+    return t('validation.tooShort', { min: rules.minLength ?? 0 });
+  if (flags.tooLong)
+    return t('validation.tooLong', { max: rules.maxLength ?? 0 });
+  if (flags.rangeUnderflow)
+    return t('validation.rangeUnderflow', { min: rules.min ?? 0 });
+  if (flags.rangeOverflow)
+    return t('validation.rangeOverflow', { max: rules.max ?? 0 });
+  if (flags.stepMismatch) return t('validation.stepMismatch');
+  if (flags.patternMismatch) return t('validation.patternMismatch');
+  return t('validation.invalid');
+}
+
+// ─── Host binding ────────────────────────────────────────────────────────────
+
+/** The validation surface added to a form control's host element. */
+export interface ValidatableElement extends HTMLElement {
+  /** Current validity flags. */
+  readonly validity: ValidityFlags;
+  /** Message for the current validity, or `''` when valid. */
+  readonly validationMessage: string;
+  /** True when the control satisfies its constraints. Fires `bq-invalid` when it does not. */
+  checkValidity(): boolean;
+  /** Like `checkValidity()`, but also surfaces the message to the user. */
+  reportValidity(): boolean;
+  /** Installs (or clears, with `''`) an author-defined error. */
+  setCustomValidity(message: string): void;
+}
+
+/** Options for {@link bindValidation}. */
+export interface ValidationBindingOptions {
+  /** Reads the value to validate. */
+  value: () => string;
+  /**
+   * Reads the constraints. Called on every check so attribute changes take
+   * effect without rebinding.
+   */
+  rules?: () => ValidationRules;
+  /**
+   * Displays a message on the control. Defaults to setting the `error`
+   * attribute, which every form control in this library already renders.
+   */
+  show?: (message: string) => void;
+}
+
+/** Registry of controls per form, so submission can validate them as a group. */
+const formRegistry = new WeakMap<HTMLFormElement, Set<ValidatableElement>>();
+const formListeners = new WeakSet<HTMLFormElement>();
+
+function readAttributeRules(el: HTMLElement): ValidationRules {
+  const num = (name: string): number | undefined => {
+    const raw = el.getAttribute(name);
+    if (raw === null || raw.trim() === '') return undefined;
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) ? parsed : undefined;
+  };
+  const rules: ValidationRules = { required: el.hasAttribute('required') };
+  const minLength = num('minlength');
+  if (minLength !== undefined) rules.minLength = minLength;
+  const maxLength = num('maxlength');
+  if (maxLength !== undefined) rules.maxLength = maxLength;
+  const min = num('min');
+  if (min !== undefined) rules.min = min;
+  const max = num('max');
+  if (max !== undefined) rules.max = max;
+  const step = num('step');
+  if (step !== undefined) rules.step = step;
+  const pattern = el.getAttribute('pattern');
+  if (pattern) rules.pattern = pattern;
+  const type = el.getAttribute('type');
+  if (type) rules.type = type;
+  return rules;
+}
+
+/**
+ * Validates every registered control in a form, blocking submission and
+ * focusing the first offender when one fails.
+ */
+function attachFormGuard(form: HTMLFormElement, scope: ComponentScope): void {
+  if (formListeners.has(form)) return;
+  formListeners.add(form);
+  // Capture phase, so the guard runs before author-supplied submit handlers
+  // and a rejected submission never reaches application code.
+  scope.on(
+    form,
+    'submit',
+    (event) => {
+      if (form.hasAttribute('novalidate')) return;
+      const controls = formRegistry.get(form);
+      if (!controls || controls.size === 0) return;
+      let firstInvalid: ValidatableElement | null = null;
+      for (const control of controls) {
+        if (!control.isConnected) continue;
+        if (!control.reportValidity() && !firstInvalid) firstInvalid = control;
+      }
+      if (!firstInvalid) return;
+      event.preventDefault();
+      event.stopPropagation();
+      firstInvalid.focus();
+    },
+    true
+  );
+  scope.add(() => formListeners.delete(form));
+}
+
+/**
+ * Gives a component the Constraint Validation surface and enrols it in its
+ * form's submit guard.
+ *
+ * ```ts
+ * connected() {
+ *   const self = host(this);
+ *   const scope = bind(self);
+ *   bindValidation(self, scope, { value: () => self.getAttribute('value') ?? '' });
+ * }
+ * ```
+ */
+export function bindValidation(
+  el: HTMLElement,
+  scope: ComponentScope,
+  options: ValidationBindingOptions
+): ValidatableElement {
+  const target = el as ValidatableElement;
+  let customError = '';
+
+  const readRules = (): ValidationRules => {
+    const base = options.rules?.() ?? readAttributeRules(el);
+    return customError ? { ...base, customError } : base;
+  };
+
+  const show =
+    options.show ??
+    ((message: string) => {
+      if (message) el.setAttribute('error', message);
+      else el.removeAttribute('error');
+    });
+
+  const evaluate = (): ValidityFlags =>
+    validateValue(options.value(), readRules());
+
+  Object.defineProperties(target, {
+    validity: {
+      get: evaluate,
+      configurable: true,
+      enumerable: false,
+    },
+    validationMessage: {
+      get: () => validationMessageFor(evaluate(), readRules()),
+      configurable: true,
+      enumerable: false,
+    },
+  });
+
+  target.checkValidity = function checkValidity(): boolean {
+    const flags = evaluate();
+    el.setAttribute('aria-invalid', flags.valid ? 'false' : 'true');
+    if (flags.valid) return true;
+    // Cancelable, mirroring the platform's `invalid` event: cancelling it
+    // suppresses the default reporting in `reportValidity()`.
+    el.dispatchEvent(
+      new CustomEvent('bq-invalid', {
+        detail: {
+          validity: flags,
+          message: validationMessageFor(flags, readRules()),
+        },
+        bubbles: true,
+        composed: true,
+        cancelable: true,
+      })
+    );
+    return false;
+  };
+
+  target.reportValidity = function reportValidity(): boolean {
+    const flags = evaluate();
+    el.setAttribute('aria-invalid', flags.valid ? 'false' : 'true');
+    if (flags.valid) {
+      show('');
+      return true;
+    }
+    const message = validationMessageFor(flags, readRules());
+    const notCancelled = el.dispatchEvent(
+      new CustomEvent('bq-invalid', {
+        detail: { validity: flags, message },
+        bubbles: true,
+        composed: true,
+        cancelable: true,
+      })
+    );
+    if (notCancelled) show(message);
+    return false;
+  };
+
+  target.setCustomValidity = function setCustomValidity(
+    message: string
+  ): void {
+    customError = message ?? '';
+  };
+
+  const form = el.closest('form');
+  if (form) {
+    let controls = formRegistry.get(form);
+    if (!controls) {
+      controls = new Set();
+      formRegistry.set(form, controls);
+    }
+    controls.add(target);
+    attachFormGuard(form, scope);
+    scope.add(() => {
+      formRegistry.get(form)?.delete(target);
+    });
+  }
+
+  scope.add(() => {
+    delete (target as Partial<ValidatableElement>).checkValidity;
+    delete (target as Partial<ValidatableElement>).reportValidity;
+    delete (target as Partial<ValidatableElement>).setCustomValidity;
+  });
+
+  return target;
+}
diff --git a/tests/combobox.test.ts b/tests/combobox.test.ts
new file mode 100644
index 0000000..95ad36e
--- /dev/null
+++ b/tests/combobox.test.ts
@@ -0,0 +1,469 @@
+// DOM environment is provided by tests/setup.ts (preloaded via bunfig.toml)
+import { afterEach, beforeAll, describe, expect, it } from 'bun:test';
+import {
+  filterOptions,
+  nextEnabledIndex,
+  parseValues,
+  readOptions,
+  type ComboboxOption,
+} from '../src/components/combobox/BqCombobox.js';
+import { waitForFrame } from './helpers.ts';
+
+const win = (globalThis as unknown as Record<string, unknown>)[
+  'window'
+] as Window & typeof globalThis;
+const doc = win.document as unknown as Document;
+
+const option = (
+  value: string,
+  label = value,
+  disabled = false,
+  group = ''
+): ComboboxOption => ({ value, label, disabled, group });
+
+describe('parseValues', () => {
+  it('splits and trims a comma-separated value', () => {
+    expect(parseValues(' a , b ,c ')).toEqual(['a', 'b', 'c']);
+  });
+
+  it('drops empty segments', () => {
+    expect(parseValues('a,,b,')).toEqual(['a', 'b']);
+    expect(parseValues('')).toEqual([]);
+  });
+});
+
+describe('filterOptions', () => {
+  const options = [
+    option('apple', 'Apple'),
+    option('apricot', 'Apricot'),
+    option('banana', 'Banana'),
+    option('jose', 'José'),
+  ];
+
+  it('returns everything for an empty query', () => {
+    expect(filterOptions(options, '')).toHaveLength(4);
+    expect(filterOptions(options, '   ')).toHaveLength(4);
+  });
+
+  it('matches anywhere in contains mode', () => {
+    expect(filterOptions(options, 'an').map((o) => o.value)).toEqual([
+      'banana',
+    ]);
+  });
+
+  it('matches only the beginning in starts-with mode', () => {
+    expect(
+      filterOptions(options, 'ap', 'starts-with').map((o) => o.value)
+    ).toEqual(['apple', 'apricot']);
+    expect(filterOptions(options, 'na', 'starts-with')).toHaveLength(0);
+  });
+
+  it('ignores case', () => {
+    expect(filterOptions(options, 'APPLE')).toHaveLength(1);
+  });
+
+  it('ignores diacritics so plain ASCII finds accented labels', () => {
+    expect(filterOptions(options, 'jose').map((o) => o.value)).toEqual([
+      'jose',
+    ]);
+    expect(filterOptions(options, 'josé').map((o) => o.value)).toEqual([
+      'jose',
+    ]);
+  });
+});
+
+describe('nextEnabledIndex', () => {
+  const options = [
+    option('a'),
+    option('b', 'b', true),
+    option('c'),
+    option('d', 'd', true),
+  ];
+
+  it('steps forward past disabled entries', () => {
+    expect(nextEnabledIndex(options, 0, 1)).toBe(2);
+  });
+
+  it('wraps around the end', () => {
+    expect(nextEnabledIndex(options, 2, 1)).toBe(0);
+  });
+
+  it('steps backward past disabled entries', () => {
+    expect(nextEnabledIndex(options, 2, -1)).toBe(0);
+  });
+
+  it('returns -1 when nothing can be activated', () => {
+    expect(nextEnabledIndex([option('x', 'x', true)], -1, 1)).toBe(-1);
+    expect(nextEnabledIndex([], -1, 1)).toBe(-1);
+  });
+});
+
+describe('readOptions', () => {
+  afterEach(() => {
+    doc.body.innerHTML = '';
+  });
+
+  it('reads value, label and disabled from option children', () => {
+    const wrap = doc.createElement('div');
+    wrap.innerHTML =
+      '<option value="a">Alpha</option><option disabled>Beta</option>';
+    const options = readOptions(wrap);
+
+    expect(options[0]).toEqual({
+      value: 'a',
+      label: 'Alpha',
+      disabled: false,
+      group: '',
+    });
+    // Without an explicit value the label doubles as the value.
+    expect(options[1]?.value).toBe('Beta');
+    expect(options[1]?.disabled).toBe(true);
+  });
+
+  it('carries the optgroup label onto its options', () => {
+    const wrap = doc.createElement('div');
+    wrap.innerHTML =
+      '<optgroup label="Fruit"><option value="a">Apple</option></optgroup>';
+    expect(readOptions(wrap)[0]?.group).toBe('Fruit');
+  });
+});
+
+describe('bq-combobox', () => {
+  beforeAll(async () => {
+    await import('../src/components/combobox/index.js');
+  });
+
+  afterEach(() => {
+    doc.body.innerHTML = '';
+  });
+
+  const create = (attrs: Record<string, string> = {}): HTMLElement => {
+    const el = doc.createElement('bq-combobox');
+    for (const [k, v] of Object.entries(attrs)) el.setAttribute(k, v);
+    el.innerHTML = `
+      <option value="apple">Apple</option>
+      <option value="apricot">Apricot</option>
+      <option value="banana" disabled>Banana</option>
+      <option value="cherry">Cherry</option>`;
+    doc.body.appendChild(el);
+    return el;
+  };
+
+  const input = (el: HTMLElement): HTMLInputElement =>
+    el.shadowRoot?.querySelector('input') as HTMLInputElement;
+
+  const options = (el: HTMLElement): HTMLElement[] =>
+    Array.from(el.shadowRoot?.querySelectorAll('.option') ?? []);
+
+  const press = (el: HTMLElement, key: string) =>
+    input(el).dispatchEvent(
+      new win.KeyboardEvent('keydown', {
+        key,
+        bubbles: true,
+        composed: true,
+        cancelable: true,
+      })
+    );
+
+  it('registers as a custom element', () => {
+    expect(win.customElements.get('bq-combobox')).toBeDefined();
+  });
+
+  it('exposes the ARIA combobox wiring', async () => {
+    const el = create({ label: 'Fruit' });
+    await waitForFrame();
+
+    const field = input(el);
+    const listbox = el.shadowRoot?.querySelector('[role="listbox"]');
+    expect(field.getAttribute('role')).toBe('combobox');
+    expect(field.getAttribute('aria-expanded')).toBe('false');
+    expect(field.getAttribute('aria-controls')).toBe(listbox?.id);
+    expect(field.getAttribute('aria-autocomplete')).toBe('list');
+  });
+
+  it('mirrors light-DOM options into the listbox', async () => {
+    const el = create();
+    await waitForFrame();
+    expect(options(el).map((o) => o.getAttribute('data-value'))).toEqual([
+      'apple',
+      'apricot',
+      'banana',
+      'cherry',
+    ]);
+  });
+
+  it('opens on ArrowDown and activates the first enabled option', async () => {
+    const el = create();
+    await waitForFrame();
+
+    press(el, 'ArrowDown');
+    await waitForFrame();
+
+    expect(input(el).getAttribute('aria-expanded')).toBe('true');
+    expect(options(el)[0]?.getAttribute('data-active')).toBe('true');
+  });
+
+  it('skips disabled options when arrowing', async () => {
+    const el = create();
+    await waitForFrame();
+
+    press(el, 'ArrowDown');
+    await waitForFrame();
+    press(el, 'ArrowDown');
+    await waitForFrame();
+    press(el, 'ArrowDown');
+    await waitForFrame();
+
+    // apple → apricot → (banana disabled) → cherry
+    expect(options(el)[3]?.getAttribute('data-active')).toBe('true');
+  });
+
+  it('points aria-activedescendant at the active option', async () => {
+    const el = create();
+    await waitForFrame();
+    press(el, 'ArrowDown');
+    await waitForFrame();
+
+    expect(input(el).getAttribute('aria-activedescendant')).toBe(
+      options(el)[0]?.id
+    );
+  });
+
+  it('filters as the user types', async () => {
+    const el = create();
+    await waitForFrame();
+
+    const field = input(el);
+    field.value = 'ap';
+    field.dispatchEvent(new win.Event('input', { bubbles: true, composed: true }));
+    await waitForFrame();
+
+    expect(options(el).map((o) => o.getAttribute('data-value'))).toEqual([
+      'apple',
+      'apricot',
+    ]);
+  });
+
+  it('shows an empty message when nothing matches', async () => {
+    const el = create();
+    await waitForFrame();
+
+    const field = input(el);
+    field.value = 'zzz';
+    field.dispatchEvent(new win.Event('input', { bubbles: true, composed: true }));
+    await waitForFrame();
+
+    expect(options(el)).toHaveLength(0);
+    expect(el.shadowRoot?.querySelector('.empty')?.textContent?.trim()).toBe(
+      'No matches found'
+    );
+  });
+
+  it('selects with Enter, closes, and emits bq-change', async () => {
+    const el = create();
+    await waitForFrame();
+
+    let detail: { value: string; values: string[] } | null = null;
+    el.addEventListener('bq-change', (event) => {
+      detail = (event as CustomEvent<{ value: string; values: string[] }>)
+        .detail;
+    });
+
+    press(el, 'ArrowDown');
+    await waitForFrame();
+    press(el, 'Enter');
+    await waitForFrame();
+
+    expect(el.getAttribute('value')).toBe('apple');
+    expect(detail).toEqual({ value: 'apple', values: ['apple'] });
+    expect(input(el).getAttribute('aria-expanded')).toBe('false');
+    // The field shows the human-readable label, not the raw key.
+    expect(input(el).value).toBe('Apple');
+  });
+
+  it('lets Enter through to the form when the list is closed', async () => {
+    const el = create();
+    await waitForFrame();
+
+    const notPrevented = press(el, 'Enter');
+    expect(notPrevented).toBe(true);
+  });
+
+  it('closes on Escape without changing the value', async () => {
+    const el = create({ value: 'apple' });
+    await waitForFrame();
+
+    press(el, 'ArrowDown');
+    await waitForFrame();
+    press(el, 'Escape');
+    await waitForFrame();
+
+    expect(input(el).getAttribute('aria-expanded')).toBe('false');
+    expect(el.getAttribute('value')).toBe('apple');
+  });
+
+  it('accumulates values and stays open in multiple mode', async () => {
+    const el = create({ multiple: '' });
+    await waitForFrame();
+
+    press(el, 'ArrowDown');
+    await waitForFrame();
+    press(el, 'Enter');
+    await waitForFrame();
+
+    expect(el.getAttribute('value')).toBe('apple');
+    expect(input(el).getAttribute('aria-expanded')).toBe('true');
+
+    // The active index survives the selection, so one step lands on apricot.
+    press(el, 'ArrowDown');
+    await waitForFrame();
+    press(el, 'Enter');
+    await waitForFrame();
+
+    expect(el.getAttribute('value')).toBe('apple,apricot');
+  });
+
+  it('deselects an already-selected value in multiple mode', async () => {
+    const el = create({ multiple: '', value: 'apple' });
+    await waitForFrame();
+
+    press(el, 'ArrowDown');
+    await waitForFrame();
+    press(el, 'Enter');
+    await waitForFrame();
+
+    expect(el.getAttribute('value')).toBe('');
+  });
+
+  it('renders a token per selected value in multiple mode', async () => {
+    const el = create({ multiple: '', value: 'apple,cherry' });
+    await waitForFrame();
+
+    const tokens = Array.from(el.shadowRoot?.querySelectorAll('.token') ?? []);
+    expect(tokens.map((token) => token.textContent?.replace('×', '').trim())).toEqual([
+      'Apple',
+      'Cherry',
+    ]);
+  });
+
+  it('removes the last token on Backspace with an empty query', async () => {
+    const el = create({ multiple: '', value: 'apple,cherry' });
+    await waitForFrame();
+
+    input(el).value = '';
+    press(el, 'Backspace');
+    await waitForFrame();
+
+    expect(el.getAttribute('value')).toBe('apple');
+  });
+
+  it('leaves tokens alone when the query is not empty', async () => {
+    const el = create({ multiple: '', value: 'apple,cherry' });
+    await waitForFrame();
+
+    input(el).value = 'ch';
+    press(el, 'Backspace');
+    await waitForFrame();
+
+    expect(el.getAttribute('value')).toBe('apple,cherry');
+  });
+
+  it('marks selected options with aria-selected', async () => {
+    const el = create({ value: 'apricot' });
+    await waitForFrame();
+    press(el, 'ArrowDown');
+    await waitForFrame();
+
+    const selected = options(el).filter(
+      (o) => o.getAttribute('aria-selected') === 'true'
+    );
+    expect(selected.map((o) => o.getAttribute('data-value'))).toEqual([
+      'apricot',
+    ]);
+  });
+
+  it('picks up options added after connection', async () => {
+    const el = create();
+    await waitForFrame();
+
+    const extra = doc.createElement('option');
+    extra.setAttribute('value', 'damson');
+    extra.textContent = 'Damson';
+    el.appendChild(extra);
+    await waitForFrame();
+    await waitForFrame();
+
+    expect(options(el).map((o) => o.getAttribute('data-value'))).toContain(
+      'damson'
+    );
+  });
+
+  it('does not open while disabled', async () => {
+    const el = create({ disabled: '' });
+    await waitForFrame();
+
+    press(el, 'ArrowDown');
+    await waitForFrame();
+
+    expect(input(el).getAttribute('aria-expanded')).toBe('false');
+  });
+
+  it('shows every option when no-filter is set', async () => {
+    const el = create({ 'no-filter': '' });
+    await waitForFrame();
+
+    const field = input(el);
+    field.value = 'zzz';
+    field.dispatchEvent(new win.Event('input', { bubbles: true, composed: true }));
+    await waitForFrame();
+
+    expect(options(el)).toHaveLength(4);
+  });
+
+  it('participates in forms through a hidden proxy input', async () => {
+    const form = doc.createElement('form');
+    const el = doc.createElement('bq-combobox');
+    el.setAttribute('name', 'fruit');
+    el.setAttribute('value', 'apple');
+    el.innerHTML = '<option value="apple">Apple</option>';
+    form.appendChild(el);
+    doc.body.appendChild(form);
+    await waitForFrame();
+
+    const proxy = form.querySelector(
+      'input[data-bq-form-proxy]'
+    ) as HTMLInputElement;
+    expect(proxy).toBeTruthy();
+    expect(proxy.name).toBe('fruit');
+    expect(proxy.value).toBe('apple');
+  });
+
+  it('enforces required through the validation surface', async () => {
+    const el = create({ required: '' }) as HTMLElement & {
+      checkValidity(): boolean;
+    };
+    await waitForFrame();
+
+    expect(el.checkValidity()).toBe(false);
+
+    el.setAttribute('value', 'apple');
+    await waitForFrame();
+    expect(el.checkValidity()).toBe(true);
+  });
+
+  it('leaves no document listeners behind after removal', async () => {
+    const el = create();
+    await waitForFrame();
+    press(el, 'ArrowDown');
+    await waitForFrame();
+
+    el.remove();
+    await waitForFrame();
+
+    // A stranded outside-click listener would throw when the shadow root is
+    // gone; dispatching here proves the scope unwound it.
+    expect(() =>
+      doc.dispatchEvent(new win.Event('mousedown', { bubbles: true }))
+    ).not.toThrow();
+  });
+});
diff --git a/tests/focus-preservation.test.ts b/tests/focus-preservation.test.ts
new file mode 100644
index 0000000..896b3ef
--- /dev/null
+++ b/tests/focus-preservation.test.ts
@@ -0,0 +1,169 @@
+// DOM environment is provided by tests/setup.ts (preloaded via bunfig.toml)
+import { afterEach, beforeAll, describe, expect, it } from 'bun:test';
+import { captureFocus, restoreFocus } from '../src/utils/focus.js';
+import { waitForFrame } from './helpers.ts';
+
+const win = (globalThis as unknown as Record<string, unknown>)[
+  'window'
+] as Window & typeof globalThis;
+const doc = win.document as unknown as Document;
+
+describe('captureFocus / restoreFocus', () => {
+  afterEach(() => {
+    doc.body.innerHTML = '';
+  });
+
+  const makeRoot = (markup: string): ShadowRoot => {
+    const host = doc.createElement('div');
+    doc.body.appendChild(host);
+    const root = host.attachShadow({ mode: 'open' });
+    root.innerHTML = markup;
+    return root;
+  };
+
+  it('returns null when nothing inside is focused', () => {
+    const root = makeRoot('<input part="input" />');
+    expect(captureFocus(root)).toBeNull();
+  });
+
+  it('identifies the focused element by its part', () => {
+    const root = makeRoot('<input part="input" class="x" />');
+    const input = root.querySelector('input') as HTMLInputElement;
+    input.focus();
+
+    const snapshot = captureFocus(root);
+    expect(snapshot?.selector).toBe('[part~="input"]');
+  });
+
+  it('falls back to id, then to tag and classes', () => {
+    const byId = makeRoot('<input id="field" />');
+    (byId.querySelector('input') as HTMLInputElement).focus();
+    expect(captureFocus(byId)?.selector).toBe('[id="field"]');
+
+    const byClass = makeRoot('<textarea class="body tall"></textarea>');
+    (byClass.querySelector('textarea') as HTMLTextAreaElement).focus();
+    expect(captureFocus(byClass)?.selector).toBe('textarea.body.tall');
+  });
+
+  it('restores focus and the caret onto the replacement node', () => {
+    const root = makeRoot('<input part="input" value="hello" />');
+    const input = root.querySelector('input') as HTMLInputElement;
+    input.focus();
+    input.setSelectionRange(3, 3);
+
+    const snapshot = captureFocus(root);
+    // Stand in for a re-render: the old node is gone, a new one takes over.
+    root.innerHTML = '<input part="input" value="hello" />';
+    expect(root.activeElement).toBeFalsy();
+
+    expect(restoreFocus(root, snapshot)).toBe(true);
+    const next = root.querySelector('input') as HTMLInputElement;
+    expect(root.activeElement).toBe(next);
+    expect(next.selectionStart).toBe(3);
+  });
+
+  it('does not steal focus when the tree already has some', () => {
+    const root = makeRoot('<input part="input" /><input part="other" />');
+    const first = root.querySelector('[part~="input"]') as HTMLInputElement;
+    first.focus();
+    const snapshot = captureFocus(root);
+
+    const other = root.querySelector('[part~="other"]') as HTMLInputElement;
+    other.focus();
+
+    expect(restoreFocus(root, snapshot)).toBe(false);
+    expect(root.activeElement).toBe(other);
+  });
+
+  it('is a no-op when the element no longer exists', () => {
+    const root = makeRoot('<input part="input" />');
+    (root.querySelector('input') as HTMLInputElement).focus();
+    const snapshot = captureFocus(root);
+
+    root.innerHTML = '<span>gone</span>';
+    expect(restoreFocus(root, snapshot)).toBe(false);
+  });
+
+  it('tolerates a null root or snapshot', () => {
+    expect(restoreFocus(null, null)).toBe(false);
+    expect(captureFocus(null)).toBeNull();
+  });
+});
+
+describe('form controls survive a re-render while focused', () => {
+  beforeAll(async () => {
+    await import('../src/components/input/index.js');
+    await import('../src/components/textarea/index.js');
+  });
+
+  afterEach(() => {
+    doc.body.innerHTML = '';
+  });
+
+  it('keeps focus in bq-input when the value attribute changes', async () => {
+    const el = doc.createElement('bq-input');
+    doc.body.appendChild(el);
+    await waitForFrame();
+
+    const input = el.shadowRoot?.querySelector('input') as HTMLInputElement;
+    input.focus();
+    expect(el.shadowRoot?.activeElement).toBe(input);
+
+    // Reflecting a keystroke re-renders the shadow tree, replacing the node
+    // the user is typing into.
+    el.setAttribute('value', 'abc');
+    await waitForFrame();
+
+    const next = el.shadowRoot?.querySelector('input') as HTMLInputElement;
+    expect(next).not.toBe(input);
+    expect(el.shadowRoot?.activeElement).toBe(next);
+  });
+
+  it('keeps the caret position across the re-render', async () => {
+    const el = doc.createElement('bq-input');
+    el.setAttribute('value', 'hello world');
+    doc.body.appendChild(el);
+    await waitForFrame();
+
+    const input = el.shadowRoot?.querySelector('input') as HTMLInputElement;
+    input.focus();
+    input.setSelectionRange(5, 5);
+
+    el.setAttribute('value', 'hello brave world');
+    await waitForFrame();
+
+    const next = el.shadowRoot?.querySelector('input') as HTMLInputElement;
+    expect(next.selectionStart).toBe(5);
+  });
+
+  it('keeps focus in bq-textarea when the value attribute changes', async () => {
+    const el = doc.createElement('bq-textarea');
+    doc.body.appendChild(el);
+    await waitForFrame();
+
+    const ta = el.shadowRoot?.querySelector('textarea') as HTMLTextAreaElement;
+    ta.focus();
+
+    el.setAttribute('value', 'typed');
+    await waitForFrame();
+
+    const next = el.shadowRoot?.querySelector(
+      'textarea'
+    ) as HTMLTextAreaElement;
+    expect(el.shadowRoot?.activeElement).toBe(next);
+  });
+
+  it('leaves focus alone when the control was not focused', async () => {
+    const outside = doc.createElement('button');
+    doc.body.appendChild(outside);
+    const el = doc.createElement('bq-input');
+    doc.body.appendChild(el);
+    await waitForFrame();
+
+    outside.focus();
+    el.setAttribute('value', 'changed');
+    await waitForFrame();
+
+    expect(el.shadowRoot?.activeElement).toBeFalsy();
+  });
+});
diff --git a/tests/position.test.ts b/tests/position.test.ts
new file mode 100644
index 0000000..1274c64
--- /dev/null
+++ b/tests/position.test.ts
@@ -0,0 +1,408 @@
+// DOM environment is provided by tests/setup.ts (preloaded via bunfig.toml)
+import { afterEach, describe, expect, it } from 'bun:test';
+import {
+  autoPosition,
+  formatPlacement,
+  parsePlacement,
+  positionElement,
+  resolvePosition,
+  type Rect,
+} from '../src/utils/position.js';
+
+const win = (globalThis as unknown as Record<string, unknown>)[
+  'window'
+] as Window & typeof globalThis;
+const doc = win.document as unknown as Document;
+
+const viewport: Rect = { x: 0, y: 0, width: 1000, height: 800 };
+const panel: Rect = { x: 0, y: 0, width: 200, height: 100 };
+
+/** Anchor centred in the viewport — collides with nothing. */
+const centered: Rect = { x: 400, y: 350, width: 100, height: 40 };
+
+describe('parsePlacement', () => {
+  it('splits a side-align placement', () => {
+    expect(parsePlacement('bottom-start')).toEqual({
+      side: 'bottom',
+      align: 'start',
+    });
+  });
+
+  it('defaults a bare side to center alignment', () => {
+    expect(parsePlacement('left')).toEqual({ side: 'left', align: 'center' });
+  });
+
+  it('falls back to bottom-center for unusable input', () => {
+    expect(parsePlacement('sideways')).toEqual({
+      side: 'bottom',
+      align: 'center',
+    });
+    expect(parsePlacement(undefined)).toEqual({
+      side: 'bottom',
+      align: 'center',
+    });
+    expect(parsePlacement('top-diagonal')).toEqual({
+      side: 'top',
+      align: 'center',
+    });
+  });
+
+  it('round-trips through formatPlacement', () => {
+    expect(formatPlacement('top', 'center')).toBe('top');
+    expect(formatPlacement('top', 'end')).toBe('top-end');
+  });
+});
+
+describe('resolvePosition — placement geometry', () => {
+  it('places a bottom-centered panel below and centered on the anchor', () => {
+    const r = resolvePosition({
+      anchor: centered,
+      floating: panel,
+      viewport,
+      placement: 'bottom',
+      offset: 8,
+    });
+    expect(r.side).toBe('bottom');
+    expect(r.y).toBe(centered.y + centered.height + 8);
+    // Anchor centre is 450; panel is 200 wide, so its left edge sits at 350.
+    expect(r.x).toBe(350);
+    expect(r.flipped).toBe(false);
+    expect(r.shifted).toBe(0);
+  });
+
+  it('places a top panel above the anchor', () => {
+    const r = resolvePosition({
+      anchor: centered,
+      floating: panel,
+      viewport,
+      placement: 'top',
+      offset: 8,
+    });
+    expect(r.y).toBe(centered.y - panel.height - 8);
+  });
+
+  it('honours start and end alignment on the cross axis', () => {
+    const start = resolvePosition({
+      anchor: centered,
+      floating: panel,
+      viewport,
+      placement: 'bottom-start',
+    });
+    expect(start.x).toBe(centered.x);
+
+    const end = resolvePosition({
+      anchor: centered,
+      floating: panel,
+      viewport,
+      placement: 'bottom-end',
+    });
+    expect(end.x).toBe(centered.x + centered.width - panel.width);
+  });
+
+  it('places left and right panels on the horizontal axis', () => {
+    const left = resolvePosition({
+      anchor: centered,
+      floating: panel,
+      viewport,
+      placement: 'left',
+      offset: 8,
+    });
+    expect(left.x).toBe(centered.x - panel.width - 8);
+
+    const right = resolvePosition({
+      anchor: centered,
+      floating: panel,
+      viewport,
+      placement: 'right',
+      offset: 8,
+    });
+    expect(right.x).toBe(centered.x + centered.width + 8);
+  });
+});
+
+describe('resolvePosition — flip', () => {
+  it('flips a bottom panel to top when it would run past the bottom edge', () => {
+    const nearBottom: Rect = { x: 400, y: 760, width: 100, height: 30 };
+    const r = resolvePosition({
+      anchor: nearBottom,
+      floating: panel,
+      viewport,
+      placement: 'bottom',
+    });
+    expect(r.side).toBe('top');
+    expect(r.flipped).toBe(true);
+    expect(r.y).toBe(nearBottom.y - panel.height - 8);
+  });
+
+  it('flips a top panel to bottom when it would run past the top edge', () => {
+    const nearTop: Rect = { x: 400, y: 10, width: 100, height: 30 };
+    const r = resolvePosition({
+      anchor: nearTop,
+      floating: panel,
+      viewport,
+      placement: 'top',
+    });
+    expect(r.side).toBe('bottom');
+    expect(r.flipped).toBe(true);
+  });
+
+  it('stays put when the opposite side is no roomier', () => {
+    // An anchor spanning almost the whole viewport leaves equally little room
+    // above and below. The panel fits on neither side, so flipping would only
+    // make the placement jitter without buying any space.
+    const tallAnchor: Rect = { x: 400, y: 5, width: 100, height: 790 };
+    const r = resolvePosition({
+      anchor: tallAnchor,
+      floating: panel,
+      viewport,
+      placement: 'bottom',
+    });
+    expect(r.side).toBe('bottom');
+    expect(r.flipped).toBe(false);
+  });
+
+  it('picks the roomier side when neither side fits outright', () => {
+    // Panel taller than either gap: bottom has 352px, top has 392px, so the
+    // engine still takes the better of two bad options.
+    const tall: Rect = { x: 0, y: 0, width: 200, height: 900 };
+    const middle: Rect = { x: 400, y: 400, width: 100, height: 40 };
+    const r = resolvePosition({
+      anchor: middle,
+      floating: tall,
+      viewport,
+      placement: 'bottom',
+    });
+    expect(r.side).toBe('top');
+    expect(r.flipped).toBe(true);
+  });
+
+  it('does not flip when flip is disabled', () => {
+    const nearBottom: Rect = { x: 400, y: 760, width: 100, height: 30 };
+    const r = resolvePosition({
+      anchor: nearBottom,
+      floating: panel,
+      viewport,
+      placement: 'bottom',
+      flip: false,
+    });
+    expect(r.side).toBe('bottom');
+    expect(r.flipped).toBe(false);
+  });
+
+  it('flips alignment when a -start panel overflows the trailing edge', () => {
+    const nearRight: Rect = { x: 900, y: 300, width: 80, height: 30 };
+    const r = resolvePosition({
+      anchor: nearRight,
+      floating: panel,
+      viewport,
+      placement: 'bottom-start',
+    });
+    expect(r.align).toBe('end');
+    expect(r.placement).toBe('bottom-end');
+  });
+});
+
+describe('resolvePosition — shift', () => {
+  it('slides a panel back inside the left viewport edge', () => {
+    const nearLeft: Rect = { x: 4, y: 300, width: 40, height: 30 };
+    const r = resolvePosition({
+      anchor: nearLeft,
+      floating: panel,
+      viewport,
+      placement: 'bottom',
+      padding: 8,
+    });
+    expect(r.x).toBe(8);
+    expect(r.shifted).toBeGreaterThan(0);
+  });
+
+  it('slides a panel back inside the right viewport edge', () => {
+    const nearRight: Rect = { x: 960, y: 300, width: 40, height: 30 };
+    const r = resolvePosition({
+      anchor: nearRight,
+      floating: panel,
+      viewport,
+      placement: 'bottom',
+      padding: 8,
+    });
+    expect(r.x).toBe(viewport.width - 8 - panel.width);
+    expect(r.shifted).toBeLessThan(0);
+  });
+
+  it('pins the leading edge when the panel is wider than the viewport', () => {
+    const huge: Rect = { x: 0, y: 0, width: 1200, height: 100 };
+    const r = resolvePosition({
+      anchor: centered,
+      floating: huge,
+      viewport,
+      placement: 'bottom',
+      padding: 8,
+    });
+    expect(r.x).toBe(8);
+  });
+
+  it('does not shift when shift is disabled', () => {
+    const nearLeft: Rect = { x: 4, y: 300, width: 40, height: 30 };
+    const r = resolvePosition({
+      anchor: nearLeft,
+      floating: panel,
+      viewport,
+      placement: 'bottom',
+      shift: false,
+    });
+    expect(r.shifted).toBe(0);
+    expect(r.x).toBeLessThan(0);
+  });
+});
+
+describe('resolvePosition — arrow', () => {
+  it('reports no arrow offset when no arrow size is given', () => {
+    const r = resolvePosition({
+      anchor: centered,
+      floating: panel,
+      viewport,
+      placement: 'bottom',
+    });
+    expect(r.arrow).toBeNull();
+  });
+
+  it('centres the arrow on the anchor', () => {
+    const r = resolvePosition({
+      anchor: centered,
+      floating: panel,
+      viewport,
+      placement: 'bottom',
+      arrowSize: 10,
+    });
+    // Anchor centre 450, panel left edge 350, arrow half-width 5.
+    expect(r.arrow).toBe(95);
+  });
+
+  it('keeps pointing at the anchor after the panel is shifted', () => {
+    const nearLeft: Rect = { x: 4, y: 300, width: 40, height: 30 };
+    const r = resolvePosition({
+      anchor: nearLeft,
+      floating: panel,
+      viewport,
+      placement: 'bottom',
+      arrowSize: 10,
+      padding: 8,
+    });
+    // Panel pinned to x=8; anchor centre is 24, so the arrow sits at 24-8-5.
+    expect(r.arrow).toBe(11);
+  });
+
+  it('clamps the arrow inside the panel corners', () => {
+    const farLeft: Rect = { x: 0, y: 300, width: 4, height: 30 };
+    const r = resolvePosition({
+      anchor: farLeft,
+      floating: panel,
+      viewport,
+      placement: 'bottom',
+      arrowSize: 10,
+      arrowPadding: 6,
+      padding: 8,
+    });
+    expect(r.arrow).toBe(6);
+  });
+});
+
+describe('resolvePosition — degenerate input', () => {
+  it('keeps the preferred placement when the anchor has no extent', () => {
+    const r = resolvePosition({
+      anchor: { x: 0, y: 0, width: 0, height: 0 },
+      floating: panel,
+      viewport,
+      placement: 'top-start',
+    });
+    expect(r.placement).toBe('top-start');
+    expect(r.flipped).toBe(false);
+    expect(r.shifted).toBe(0);
+    expect(r.measured).toBe(false);
+  });
+
+  it('keeps the preferred placement when the viewport has no extent', () => {
+    const r = resolvePosition({
+      anchor: centered,
+      floating: panel,
+      viewport: { x: 0, y: 0, width: 0, height: 0 },
+      placement: 'right-end',
+    });
+    expect(r.placement).toBe('right-end');
+    expect(r.flipped).toBe(false);
+  });
+
+  it('marks a laid-out anchor as measured', () => {
+    const r = resolvePosition({
+      anchor: centered,
+      floating: panel,
+      viewport,
+      placement: 'bottom',
+    });
+    expect(r.measured).toBe(true);
+  });
+});
+
+describe('positionElement — DOM writes', () => {
+  afterEach(() => {
+    doc.body.innerHTML = '';
+  });
+
+  it('publishes the placement without touching styles for an unmeasured anchor', () => {
+    // happy-dom reports zero-sized rects, which is exactly the "no layout"
+    // case the engine must not act on.
+    const anchor = doc.createElement('div');
+    const panel = doc.createElement('div');
+    anchor.appendChild(panel);
+    doc.body.appendChild(anchor);
+
+    const result = positionElement(anchor, panel, { placement: 'top-start' });
+
+    expect(result.measured).toBe(false);
+    expect(panel.getAttribute('data-placement')).toBe('top-start');
+    expect(panel.getAttribute('data-side')).toBe('top');
+    // The static CSS fallback must survive untouched.
+    expect(panel.style.left).toBe('');
+    expect(panel.style.top).toBe('');
+  });
+});
+
+describe('autoPosition — teardown', () => {
+  afterEach(() => {
+    doc.body.innerHTML = '';
+  });
+
+  it('removes every listener it registered when disposed', () => {
+    const anchor = doc.createElement('div');
+    const panel = doc.createElement('div');
+    anchor.appendChild(panel);
+    doc.body.appendChild(anchor);
+
+    const added: string[] = [];
+    const removed: string[] = [];
+    const originalAdd = win.addEventListener.bind(win);
+    const originalRemove = win.removeEventListener.bind(win);
+    win.addEventListener = ((type: string, ...rest: unknown[]) => {
+      added.push(type);
+      return (originalAdd as (...a: unknown[]) => unknown)(type, ...rest);
+    }) as typeof win.addEventListener;
+    win.removeEventListener = ((type: string, ...rest: unknown[]) => {
+      removed.push(type);
+      return (originalRemove as (...a: unknown[]) => unknown)(type, ...rest);
+    }) as typeof win.removeEventListener;
+
+    try {
+      const stop = autoPosition(anchor, panel, { placement: 'bottom' });
+      expect(added).toContain('resize');
+      expect(added).toContain('scroll');
+      stop();
+      expect(removed).toContain('resize');
+      expect(removed).toContain('scroll');
+      // Disposing twice must stay harmless.
+      expect(() => stop()).not.toThrow();
+    } finally {
+      win.addEventListener = originalAdd as typeof win.addEventListener;
+      win.removeEventListener = originalRemove as typeof win.removeEventListener;
+    }
+  });
+});
diff --git a/tests/segmented-control.test.ts b/tests/segmented-control.test.ts
index 7c21d09..ebd102f 100644
--- a/tests/segmented-control.test.ts
+++ b/tests/segmented-control.test.ts
@@ -98,20 +98,46 @@ describe('BqSegmentedControl', () => {
     expect(detailValue).toBe('board');
   });
 
-  it('should not register a host keydown listener', async () => {
-    let hostKeydownRegistrations = 0;
-    createControl(({ el: control }) => {
-      const originalHostAddEventListener =
-        control.addEventListener.bind(control);
-      control.addEventListener = ((type, listener, options) => {
-        if (type === 'keydown') hostKeydownRegistrations += 1;
-        return originalHostAddEventListener(type, listener, options);
-      }) as HTMLElement['addEventListener'];
+  // Keyboard handling used to be bound to every individual segment button,
+  // which meant a button removed from the light DOM kept its listener. The
+  // handler resolves its button from the event target anyway, so one
+  // delegated listener on the host does the same job without the leak. What
+  // must hold either way is that a keypress is handled exactly once — see
+  // the ArrowRight test below, which is the regression guard for the
+  // double-handling bug that the two-path implementation originally caused.
+  it('should not bind keydown listeners to individual segment buttons', async () => {
+    const perButtonRegistrations: string[] = [];
+    const { overview, board } = createControl(({ overview: a, board: b }) => {
+      for (const button of [a, b]) {
+        const original = button.addEventListener.bind(button);
+        button.addEventListener = ((type, listener, options) => {
+          if (type === 'keydown') perButtonRegistrations.push(type);
+          return original(type, listener, options);
+        }) as HTMLElement['addEventListener'];
+      }
     });
 
     await waitForFrame();
 
-    expect(hostKeydownRegistrations).toBe(0);
+    expect(perButtonRegistrations).toEqual([]);
+
+    // Delegation still has to reach a button that was never present when the
+    // component connected.
+    const extra = doc.createElement('button');
+    extra.setAttribute('value', 'timeline');
+    extra.textContent = 'Timeline';
+    board.after(extra);
+    await waitForFrame();
+
+    extra.dispatchEvent(
+      new win.KeyboardEvent('keydown', {
+        key: 'Home',
+        bubbles: true,
+        cancelable: true,
+      })
+    );
+
+    expect(overview.getAttribute('data-selected')).toBe('true');
   });
 
   it('should still move selection when a segment receives ArrowRight', async () => {
diff --git a/tests/tag-input.test.ts b/tests/tag-input.test.ts
new file mode 100644
index 0000000..921db8a
--- /dev/null
+++ b/tests/tag-input.test.ts
@@ -0,0 +1,314 @@
+// DOM environment is provided by tests/setup.ts (preloaded via bunfig.toml)
+import { afterEach, beforeAll, describe, expect, it } from 'bun:test';
+import { addTag, parseTags } from '../src/components/tag-input/BqTagInput.js';
+import { waitForFrame } from './helpers.ts';
+
+const win = (globalThis as unknown as Record<string, unknown>)[
+  'window'
+] as Window & typeof globalThis;
+const doc = win.document as unknown as Document;
+
+describe('parseTags', () => {
+  it('splits, trims and drops empties', () => {
+    expect(parseTags(' a , b ,, c ')).toEqual(['a', 'b', 'c']);
+    expect(parseTags('')).toEqual([]);
+  });
+
+  it('honours a custom separator', () => {
+    expect(parseTags('a|b|c', '|')).toEqual(['a', 'b', 'c']);
+  });
+});
+
+describe('addTag', () => {
+  it('appends a trimmed tag', () => {
+    expect(addTag(['a'], '  b  ')).toEqual(['a', 'b']);
+  });
+
+  it('rejects blank input', () => {
+    expect(addTag(['a'], '   ')).toBeNull();
+  });
+
+  it('rejects duplicates by default', () => {
+    expect(addTag(['a'], 'a')).toBeNull();
+  });
+
+  it('allows duplicates when asked', () => {
+    expect(addTag(['a'], 'a', { allowDuplicates: true })).toEqual(['a', 'a']);
+  });
+
+  it('rejects once the maximum is reached', () => {
+    expect(addTag(['a', 'b'], 'c', { max: 2 })).toBeNull();
+    expect(addTag(['a'], 'b', { max: 2 })).toEqual(['a', 'b']);
+  });
+
+  it('treats max 0 as unlimited', () => {
+    expect(addTag(['a', 'b', 'c'], 'd', { max: 0 })).toHaveLength(4);
+  });
+
+  it('does not mutate the input array', () => {
+    const tags = ['a'];
+    addTag(tags, 'b');
+    expect(tags).toEqual(['a']);
+  });
+});
+
+describe('bq-tag-input', () => {
+  beforeAll(async () => {
+    await import('../src/components/tag-input/index.js');
+  });
+
+  afterEach(() => {
+    doc.body.innerHTML = '';
+  });
+
+  const create = (attrs: Record<string, string> = {}): HTMLElement => {
+    const el = doc.createElement('bq-tag-input');
+    for (const [k, v] of Object.entries(attrs)) el.setAttribute(k, v);
+    doc.body.appendChild(el);
+    return el;
+  };
+
+  const input = (el: HTMLElement): HTMLInputElement =>
+    el.shadowRoot?.querySelector('input') as HTMLInputElement;
+
+  const tags = (el: HTMLElement): string[] =>
+    Array.from(el.shadowRoot?.querySelectorAll('.tag') ?? []).map((tag) =>
+      tag.textContent?.replace('×', '').trim() ?? ''
+    );
+
+  const type = (el: HTMLElement, text: string) => {
+    const field = input(el);
+    field.value = text;
+    field.dispatchEvent(
+      new win.Event('input', { bubbles: true, composed: true })
+    );
+  };
+
+  const press = (el: HTMLElement, key: string) =>
+    input(el).dispatchEvent(
+      new win.KeyboardEvent('keydown', {
+        key,
+        bubbles: true,
+        composed: true,
+        cancelable: true,
+      })
+    );
+
+  it('registers as a custom element', () => {
+    expect(win.customElements.get('bq-tag-input')).toBeDefined();
+  });
+
+  it('renders existing tags from the value', async () => {
+    const el = create({ value: 'red,green' });
+    await waitForFrame();
+    expect(tags(el)).toEqual(['red', 'green']);
+  });
+
+  it('commits a tag on Enter and clears the draft', async () => {
+    const el = create();
+    await waitForFrame();
+
+    let added = '';
+    el.addEventListener('bq-add', (event) => {
+      added = (event as CustomEvent<{ tag: string }>).detail.tag;
+    });
+
+    type(el, 'alpha');
+    press(el, 'Enter');
+    await waitForFrame();
+
+    expect(el.getAttribute('value')).toBe('alpha');
+    expect(added).toBe('alpha');
+    expect(input(el).value).toBe('');
+  });
+
+  it('lets Enter through when the draft is empty', async () => {
+    const el = create();
+    await waitForFrame();
+    expect(press(el, 'Enter')).toBe(true);
+  });
+
+  it('splits on a delimiter typed mid-string', async () => {
+    const el = create();
+    await waitForFrame();
+
+    type(el, 'a,b,c');
+    await waitForFrame();
+
+    // Trailing segment stays in the field as the in-progress draft.
+    expect(el.getAttribute('value')).toBe('a,b');
+    expect(input(el).value).toBe('c');
+  });
+
+  it('supports custom delimiters', async () => {
+    const el = create({ delimiters: ';' });
+    await waitForFrame();
+
+    type(el, 'x;y');
+    await waitForFrame();
+
+    expect(el.getAttribute('value')).toBe('x');
+  });
+
+  it('removes the last tag on Backspace with an empty draft', async () => {
+    const el = create({ value: 'a,b' });
+    await waitForFrame();
+
+    let removed = '';
+    el.addEventListener('bq-remove', (event) => {
+      removed = (event as CustomEvent<{ tag: string }>).detail.tag;
+    });
+
+    input(el).value = '';
+    press(el, 'Backspace');
+    await waitForFrame();
+
+    expect(el.getAttribute('value')).toBe('a');
+    expect(removed).toBe('b');
+  });
+
+  it('leaves tags alone when Backspace has a draft to delete', async () => {
+    const el = create({ value: 'a,b' });
+    await waitForFrame();
+
+    input(el).value = 'draft';
+    press(el, 'Backspace');
+    await waitForFrame();
+
+    expect(el.getAttribute('value')).toBe('a,b');
+  });
+
+  it('removes a tag through its remove button', async () => {
+    const el = create({ value: 'a,b,c' });
+    await waitForFrame();
+
+    const button = el.shadowRoot?.querySelectorAll(
+      '.tag button'
+    )[1] as HTMLElement;
+    button.click();
+    await waitForFrame();
+
+    expect(el.getAttribute('value')).toBe('a,c');
+  });
+
+  it('names each remove button after its tag', async () => {
+    const el = create({ value: 'urgent' });
+    await waitForFrame();
+
+    const button = el.shadowRoot?.querySelector('.tag button');
+    expect(button?.getAttribute('aria-label')).toBe('Remove urgent');
+  });
+
+  it('rejects duplicates unless allowed', async () => {
+    const el = create({ value: 'a' });
+    await waitForFrame();
+
+    type(el, 'a');
+    press(el, 'Enter');
+    await waitForFrame();
+    expect(el.getAttribute('value')).toBe('a');
+
+    el.setAttribute('allow-duplicates', '');
+    type(el, 'a');
+    press(el, 'Enter');
+    await waitForFrame();
+    expect(el.getAttribute('value')).toBe('a,a');
+  });
+
+  it('stops accepting input at the maximum', async () => {
+    const el = create({ value: 'a,b', max: '2' });
+    await waitForFrame();
+
+    expect(input(el).disabled).toBe(true);
+    expect(el.shadowRoot?.querySelector('.count')?.textContent).toBe('2/2');
+  });
+
+  it('clears the draft on Escape', async () => {
+    const el = create();
+    await waitForFrame();
+
+    type(el, 'half-typed');
+    press(el, 'Escape');
+    await waitForFrame();
+
+    expect(input(el).value).toBe('');
+    expect(el.getAttribute('value')).toBe('');
+  });
+
+  it('commits a pending draft on blur rather than discarding it', async () => {
+    const el = create();
+    await waitForFrame();
+
+    type(el, 'pending');
+    input(el).dispatchEvent(
+      new win.Event('focusout', { bubbles: true, composed: true })
+    );
+    await waitForFrame();
+
+    expect(el.getAttribute('value')).toBe('pending');
+  });
+
+  it('emits bq-change with the parsed tags', async () => {
+    const el = create();
+    await waitForFrame();
+
+    let detail: { value: string; tags: string[] } | null = null;
+    el.addEventListener('bq-change', (event) => {
+      detail = (event as CustomEvent<{ value: string; tags: string[] }>).detail;
+    });
+
+    type(el, 'one');
+    press(el, 'Enter');
+    await waitForFrame();
+
+    expect(detail).toEqual({ value: 'one', tags: ['one'] });
+  });
+
+  it('ignores interaction while disabled', async () => {
+    const el = create({ disabled: '', value: 'a' });
+    await waitForFrame();
+
+    press(el, 'Backspace');
+    await waitForFrame();
+
+    expect(el.getAttribute('value')).toBe('a');
+  });
+
+  it('participates in forms and enforces required', async () => {
+    const form = doc.createElement('form');
+    const el = doc.createElement('bq-tag-input') as HTMLElement & {
+      checkValidity(): boolean;
+    };
+    el.setAttribute('name', 'labels');
+    el.setAttribute('required', '');
+    form.appendChild(el);
+    doc.body.appendChild(form);
+    await waitForFrame();
+
+    expect(el.checkValidity()).toBe(false);
+
+    el.setAttribute('value', 'bug');
+    await waitForFrame();
+
+    const proxy = form.querySelector(
+      'input[data-bq-form-proxy]'
+    ) as HTMLInputElement;
+    expect(proxy.name).toBe('labels');
+    expect(proxy.value).toBe('bug');
+    expect(el.checkValidity()).toBe(true);
+  });
+
+  it('keeps focus in the field while typing', async () => {
+    const el = create();
+    await waitForFrame();
+
+    const field = input(el);
+    field.focus();
+    type(el, 'abc');
+    await waitForFrame();
+
+    expect(el.shadowRoot?.activeElement).toBe(
+      el.shadowRoot?.querySelector('input') as Element
+    );
+  });
+});
diff --git a/tests/validation.test.ts b/tests/validation.test.ts
new file mode 100644
index 0000000..ea68abe
--- /dev/null
+++ b/tests/validation.test.ts
@@ -0,0 +1,391 @@
+// DOM environment is provided by tests/setup.ts (preloaded via bunfig.toml)
+import { afterEach, beforeAll, describe, expect, it } from 'bun:test';
+import { resetLocale, setLocale } from '../src/i18n/index.js';
+import {
+  validateValue,
+  validationMessageFor,
+} from '../src/utils/validation.js';
+import { waitForFrame } from './helpers.ts';
+
+const win = (globalThis as unknown as Record<string, unknown>)[
+  'window'
+] as Window & typeof globalThis;
+const doc = win.document as unknown as Document;
+
+describe('validateValue — required', () => {
+  it('flags an empty required value', () => {
+    const flags = validateValue('', { required: true });
+    expect(flags.valueMissing).toBe(true);
+    expect(flags.valid).toBe(false);
+  });
+
+  it('treats whitespace-only input as missing', () => {
+    expect(validateValue('   ', { required: true }).valueMissing).toBe(true);
+  });
+
+  it('accepts a filled required value', () => {
+    expect(validateValue('hi', { required: true }).valid).toBe(true);
+  });
+
+  it('reports only valueMissing for an empty required field', () => {
+    // The platform does not apply format constraints to a field the user has
+    // not filled in; only the "fill this in" message should surface.
+    const flags = validateValue('', {
+      required: true,
+      minLength: 5,
+      type: 'email',
+    });
+    expect(flags.valueMissing).toBe(true);
+    expect(flags.tooShort).toBe(false);
+    expect(flags.typeMismatch).toBe(false);
+  });
+
+  it('leaves an empty optional field valid despite other constraints', () => {
+    const flags = validateValue('', { minLength: 5, type: 'email' });
+    expect(flags.valid).toBe(true);
+  });
+});
+
+describe('validateValue — type', () => {
+  it('validates email addresses', () => {
+    expect(validateValue('user@example.com', { type: 'email' }).valid).toBe(
+      true
+    );
+    expect(validateValue('user@sub.example.co', { type: 'email' }).valid).toBe(
+      true
+    );
+    expect(validateValue('nope', { type: 'email' }).typeMismatch).toBe(true);
+    expect(validateValue('a@b', { type: 'email' }).typeMismatch).toBe(true);
+    expect(validateValue('a b@c.de', { type: 'email' }).typeMismatch).toBe(
+      true
+    );
+  });
+
+  it('validates URLs', () => {
+    expect(validateValue('https://example.com', { type: 'url' }).valid).toBe(
+      true
+    );
+    expect(validateValue('example.com', { type: 'url' }).typeMismatch).toBe(
+      true
+    );
+  });
+
+  it('validates numbers', () => {
+    expect(validateValue('42', { type: 'number' }).valid).toBe(true);
+    expect(validateValue('4x2', { type: 'number' }).typeMismatch).toBe(true);
+  });
+
+  it('ignores unknown types', () => {
+    expect(validateValue('anything', { type: 'text' }).valid).toBe(true);
+  });
+});
+
+describe('validateValue — length and range', () => {
+  it('enforces minLength and maxLength', () => {
+    expect(validateValue('ab', { minLength: 3 }).tooShort).toBe(true);
+    expect(validateValue('abc', { minLength: 3 }).valid).toBe(true);
+    expect(validateValue('abcd', { maxLength: 3 }).tooLong).toBe(true);
+  });
+
+  it('enforces min and max', () => {
+    expect(validateValue('4', { min: 5 }).rangeUnderflow).toBe(true);
+    expect(validateValue('5', { min: 5 }).valid).toBe(true);
+    expect(validateValue('11', { max: 10 }).rangeOverflow).toBe(true);
+  });
+
+  it('enforces step relative to min', () => {
+    expect(validateValue('4', { min: 0, step: 2 }).stepMismatch).toBe(false);
+    expect(validateValue('5', { min: 0, step: 2 }).stepMismatch).toBe(true);
+    expect(validateValue('7', { min: 1, step: 2 }).stepMismatch).toBe(false);
+  });
+
+  it('tolerates decimal steps without floating-point false positives', () => {
+    // 0.3 / 0.1 is 2.9999999999999996 in IEEE 754; a naive modulo would
+    // report this exact, user-typed value as off-grid.
+    expect(validateValue('0.3', { min: 0, step: 0.1 }).stepMismatch).toBe(
+      false
+    );
+  });
+
+  it('ignores a non-positive step', () => {
+    expect(validateValue('5', { min: 0, step: 0 }).stepMismatch).toBe(false);
+  });
+});
+
+describe('validateValue — pattern', () => {
+  it('anchors the pattern', () => {
+    // Unanchored, "abc123" would match /[a-z]+/ — the platform requires the
+    // whole value to match.
+    expect(validateValue('abc123', { pattern: '[a-z]+' }).patternMismatch).toBe(
+      true
+    );
+    expect(validateValue('abc', { pattern: '[a-z]+' }).patternMismatch).toBe(
+      false
+    );
+  });
+
+  it('ignores an unparseable pattern instead of failing the field', () => {
+    expect(validateValue('abc', { pattern: '([' }).valid).toBe(true);
+  });
+});
+
+describe('validateValue — custom errors', () => {
+  it('invalidates a field carrying a custom error', () => {
+    const flags = validateValue('fine', { customError: 'Already taken' });
+    expect(flags.customError).toBe(true);
+    expect(flags.valid).toBe(false);
+  });
+
+  it('keeps the custom error on an empty optional field', () => {
+    const flags = validateValue('', { customError: 'Nope' });
+    expect(flags.valid).toBe(false);
+  });
+});
+
+describe('validationMessageFor', () => {
+  afterEach(() => resetLocale());
+
+  it('returns an empty message for a valid field', () => {
+    expect(validationMessageFor(validateValue('ok', {}), {})).toBe('');
+  });
+
+  it('prefers the custom error over constraint messages', () => {
+    const rules = { required: true, customError: 'Already taken' };
+    expect(validationMessageFor(validateValue('', rules), rules)).toBe(
+      'Already taken'
+    );
+  });
+
+  it('interpolates the offending bound', () => {
+    const rules = { minLength: 8 };
+    expect(validationMessageFor(validateValue('short', rules), rules)).toBe(
+      'Please use at least 8 characters.'
+    );
+  });
+
+  it('is localizable', () => {
+    setLocale({ validation: { valueMissing: 'Bitte ausfüllen.' } });
+    const rules = { required: true };
+    expect(validationMessageFor(validateValue('', rules), rules)).toBe(
+      'Bitte ausfüllen.'
+    );
+  });
+
+  it('picks a type-specific message', () => {
+    const rules = { type: 'email' };
+    expect(validationMessageFor(validateValue('nope', rules), rules)).toBe(
+      'Please enter a valid email address.'
+    );
+  });
+});
+
+describe('bindValidation — on components', () => {
+  beforeAll(async () => {
+    await import('../src/components/input/index.js');
+    await import('../src/components/select/index.js');
+  });
+
+  afterEach(() => {
+    doc.body.innerHTML = '';
+    resetLocale();
+  });
+
+  type Validatable = HTMLElement & {
+    checkValidity(): boolean;
+    reportValidity(): boolean;
+    setCustomValidity(message: string): void;
+    readonly validity: { valid: boolean; valueMissing: boolean };
+    readonly validationMessage: string;
+  };
+
+  const makeInput = (attrs: Record<string, string>): Validatable => {
+    const el = doc.createElement('bq-input') as Validatable;
+    for (const [k, v] of Object.entries(attrs)) el.setAttribute(k, v);
+    doc.body.appendChild(el);
+    return el;
+  };
+
+  it('exposes the constraint validation surface on the host', async () => {
+    const el = makeInput({ required: '', value: '' });
+    await waitForFrame();
+
+    expect(typeof el.checkValidity).toBe('function');
+    expect(typeof el.reportValidity).toBe('function');
+    expect(typeof el.setCustomValidity).toBe('function');
+    expect(el.validity.valueMissing).toBe(true);
+    expect(el.validationMessage).toBe('Please fill out this field.');
+  });
+
+  it('reflects validity through aria-invalid', async () => {
+    const el = makeInput({ required: '', value: '' });
+    await waitForFrame();
+
+    expect(el.checkValidity()).toBe(false);
+    expect(el.getAttribute('aria-invalid')).toBe('true');
+
+    el.setAttribute('value', 'filled');
+    await waitForFrame();
+
+    expect(el.checkValidity()).toBe(true);
+    expect(el.getAttribute('aria-invalid')).toBe('false');
+  });
+
+  it('surfaces the message only on reportValidity', async () => {
+    const el = makeInput({ required: '', value: '' });
+    await waitForFrame();
+
+    el.checkValidity();
+    expect(el.hasAttribute('error')).toBe(false);
+
+    el.reportValidity();
+    expect(el.getAttribute('error')).toBe('Please fill out this field.');
+  });
+
+  it('clears the reported message once the field becomes valid', async () => {
+    const el = makeInput({ required: '', value: '' });
+    await waitForFrame();
+    el.reportValidity();
+    expect(el.hasAttribute('error')).toBe(true);
+
+    el.setAttribute('value', 'filled');
+    await waitForFrame();
+    expect(el.reportValidity()).toBe(true);
+    expect(el.hasAttribute('error')).toBe(false);
+  });
+
+  it('emits a cancelable bq-invalid event that suppresses reporting', async () => {
+    const el = makeInput({ required: '', value: '' });
+    await waitForFrame();
+
+    let seen = '';
+    el.addEventListener('bq-invalid', (event) => {
+      seen = (event as CustomEvent<{ message: string }>).detail.message;
+      event.preventDefault();
+    });
+
+    expect(el.reportValidity()).toBe(false);
+    expect(seen).toBe('Please fill out this field.');
+    // Cancelled: the component must not paint its own error message.
+    expect(el.hasAttribute('error')).toBe(false);
+  });
+
+  it('honours setCustomValidity and clears it with an empty string', async () => {
+    const el = makeInput({ value: 'taken' });
+    await waitForFrame();
+
+    el.setCustomValidity('Already taken');
+    expect(el.checkValidity()).toBe(false);
+    expect(el.validationMessage).toBe('Already taken');
+
+    el.setCustomValidity('');
+    expect(el.checkValidity()).toBe(true);
+  });
+
+  it('reads constraints from attributes at check time', async () => {
+    const el = makeInput({ value: 'ab' });
+    await waitForFrame();
+    expect(el.checkValidity()).toBe(true);
+
+    el.setAttribute('minlength', '5');
+    expect(el.checkValidity()).toBe(false);
+  });
+});
+
+describe('bindValidation — form submission guard', () => {
+  beforeAll(async () => {
+    await import('../src/components/input/index.js');
+  });
+
+  afterEach(() => {
+    doc.body.innerHTML = '';
+  });
+
+  const submitForm = (form: HTMLFormElement): boolean =>
+    form.dispatchEvent(
+      new win.Event('submit', { bubbles: true, cancelable: true })
+    );
+
+  it('blocks submission while a control is invalid', async () => {
+    const form = doc.createElement('form');
+    const el = doc.createElement('bq-input');
+    el.setAttribute('required', '');
+    el.setAttribute('name', 'email');
+    form.appendChild(el);
+    doc.body.appendChild(form);
+    await waitForFrame();
+
+    let submitted = false;
+    form.addEventListener('submit', () => {
+      submitted = true;
+    });
+
+    const notPrevented = submitForm(form);
+
+    expect(notPrevented).toBe(false);
+    // The guard runs in the capture phase, so application handlers never fire.
+    expect(submitted).toBe(false);
+    expect(el.getAttribute('error')).toBe('Please fill out this field.');
+  });
+
+  it('allows submission once every control is valid', async () => {
+    const form = doc.createElement('form');
+    const el = doc.createElement('bq-input');
+    el.setAttribute('required', '');
+    el.setAttribute('value', 'someone@example.com');
+    form.appendChild(el);
+    doc.body.appendChild(form);
+    await waitForFrame();
+
+    let submitted = false;
+    form.addEventListener('submit', (event) => {
+      submitted = true;
+      event.preventDefault();
+    });
+
+    submitForm(form);
+    expect(submitted).toBe(true);
+  });
+
+  it('respects novalidate on the form', async () => {
+    const form = doc.createElement('form');
+    form.setAttribute('novalidate', '');
+    const el = doc.createElement('bq-input');
+    el.setAttribute('required', '');
+    form.appendChild(el);
+    doc.body.appendChild(form);
+    await waitForFrame();
+
+    let submitted = false;
+    form.addEventListener('submit', (event) => {
+      submitted = true;
+      event.preventDefault();
+    });
+
+    submitForm(form);
+    expect(submitted).toBe(true);
+  });
+
+  it('stops guarding a control that was removed from the form', async () => {
+    const form = doc.createElement('form');
+    const good = doc.createElement('bq-input');
+    good.setAttribute('value', 'fine');
+    const bad = doc.createElement('bq-input');
+    bad.setAttribute('required', '');
+    form.append(good, bad);
+    doc.body.appendChild(form);
+    await waitForFrame();
+
+    expect(submitForm(form)).toBe(false);
+
+    bad.remove();
+    await waitForFrame();
+
+    let submitted = false;
+    form.addEventListener('submit', (event) => {
+      submitted = true;
+      event.preventDefault();
+    });
+    submitForm(form);
+    expect(submitted).toBe(true);
+  });
+});

From aae4e67141d759a8f246d913099f49dd063a3c2d Mon Sep 17 00:00:00 2001
From: Jonas Pfalzgraf <jolun.swtor@gmail.com>
Date: Fri, 31 Jul 2026 14:44:42 +0000
Subject: [PATCH 3/5] improve

---
 AGENT.md                                      |  76 +-
 README.md                                     |  37 +-
 docs/.vitepress/config.ts                     |   6 +
 docs/components/button.md                     |   2 +
 docs/components/copy-button.md                |  75 ++
 docs/components/date-picker.md                | 122 +++
 docs/components/icon.md                       | 109 +++
 docs/components/index.md                      |  16 +-
 docs/components/input.md                      |   1 +
 docs/components/meter.md                      |  81 ++
 docs/components/pin-input.md                  | 106 +++
 docs/components/radio.md                      |   4 +
 docs/components/switch.md                     |  13 +-
 docs/components/tree.md                       | 105 +++
 docs/guide/dark-mode.md                       | 100 ++-
 docs/guide/migration-from-1-1-0.md            |   2 +-
 docs/guide/theming.md                         | 118 ++-
 src/components/accordion/BqAccordion.ts       |  17 +-
 src/components/alert/BqAlert.ts               |  93 ++-
 src/components/avatar-group/BqAvatarGroup.ts  |  12 +-
 src/components/avatar/BqAvatar.ts             |   3 +-
 src/components/badge/BqBadge.ts               |   3 +-
 src/components/banner/BqBanner.ts             |  14 +-
 src/components/breadcrumbs/BqBreadcrumbs.ts   |   8 +-
 src/components/button-group/BqButtonGroup.ts  |   2 +-
 src/components/button/BqButton.ts             |  86 +-
 src/components/card/BqCard.ts                 |   6 +-
 src/components/checkbox/BqCheckbox.ts         | 161 +++-
 src/components/chip/BqChip.ts                 |  21 +-
 src/components/combobox/BqCombobox.ts         |  58 +-
 src/components/copy-button/BqCopyButton.ts    | 212 +++++
 src/components/copy-button/index.ts           |   1 +
 src/components/date-picker/BqDatePicker.ts    | 767 ++++++++++++++++++
 src/components/date-picker/index.ts           |   1 +
 src/components/dialog/BqDialog.ts             |  16 +-
 src/components/divider/BqDivider.ts           |   3 +-
 src/components/drawer/BqDrawer.ts             |  16 +-
 .../dropdown-menu/BqDropdownMenu.ts           |  10 +-
 src/components/empty-state/BqEmptyState.ts    |  25 +-
 src/components/file-upload/BqFileUpload.ts    |  10 +-
 src/components/icon-button/BqIconButton.ts    |   4 +-
 src/components/icon/BqIcon.ts                 |  87 ++
 src/components/icon/index.ts                  |   1 +
 src/components/index.ts                       |   6 +
 src/components/input/BqInput.ts               | 148 +++-
 src/components/meter/BqMeter.ts               | 198 +++++
 src/components/meter/index.ts                 |   1 +
 src/components/number-input/BqNumberInput.ts  |  18 +-
 src/components/pagination/BqPagination.ts     |  37 +-
 src/components/pin-input/BqPinInput.ts        | 367 +++++++++
 src/components/pin-input/index.ts             |   1 +
 src/components/popover/BqPopover.ts           |  12 +-
 src/components/progress/BqProgress.ts         |   3 +-
 src/components/radio/BqRadio.ts               | 162 +++-
 src/components/rating/BqRating.ts             |  10 +-
 .../segmented-control/BqSegmentedControl.ts   |   4 +-
 src/components/select/BqSelect.ts             |  55 +-
 src/components/skeleton/BqSkeleton.ts         |   3 +-
 src/components/slider/BqSlider.ts             | 101 ++-
 src/components/spinner/BqSpinner.ts           |   3 +-
 src/components/stat-card/BqStatCard.ts        |   6 +-
 src/components/stepper/BqStepper.ts           |  14 +-
 src/components/switch/BqSwitch.ts             | 185 +++--
 src/components/table/BqTable.ts               |  63 +-
 src/components/tabs/BqTabs.ts                 |  19 +-
 src/components/tag-input/BqTagInput.ts        |  46 +-
 src/components/textarea/BqTextarea.ts         |  34 +-
 src/components/timeline/BqTimeline.ts         |   2 +-
 src/components/toast/BqToast.ts               |  62 +-
 src/components/tooltip/BqTooltip.ts           |   5 +-
 src/components/tree/BqTree.ts                 | 484 +++++++++++
 src/components/tree/index.ts                  |   1 +
 src/i18n/en.ts                                |  19 +
 src/index.ts                                  |  12 +
 src/theme/dark.ts                             |  64 +-
 src/theme/default.ts                          |  44 +-
 src/theme/index.ts                            | 101 +--
 src/theme/root.ts                             |  71 ++
 src/theme/scheme.ts                           | 242 ++++++
 src/tokens/index.ts                           |  41 +-
 src/utils/focus.ts                            | 154 +++-
 src/utils/icons.ts                            | 230 ++++++
 src/utils/index.ts                            |  23 +-
 src/utils/styles.ts                           | 108 ++-
 stories/copy-button.stories.ts                |  49 ++
 stories/date-picker.stories.ts                |  59 ++
 stories/icon.stories.ts                       |  61 ++
 stories/meter.stories.ts                      |  60 ++
 stories/pin-input.stories.ts                  |  59 ++
 stories/tree.stories.ts                       |  58 ++
 tests/checkbox-radio-switch.test.ts           |  45 +
 tests/combobox.test.ts                        |  38 +
 tests/component-css.test.ts                   | 108 +++
 tests/date-picker.test.ts                     | 357 ++++++++
 tests/icons.test.ts                           | 154 ++++
 tests/input-enhancements.test.ts              |   4 +-
 tests/meter-copy-button.test.ts               | 270 ++++++
 tests/new-components.test.ts                  |   4 +-
 tests/pin-input.test.ts                       | 194 +++++
 tests/sanitizer-allowlist.test.ts             | 122 +++
 tests/slider-pagination.test.ts               |  28 +
 tests/styles.test.ts                          |  28 +-
 tests/tag-input.test.ts                       |   3 +-
 tests/theme-scheme.test.ts                    | 129 +++
 tests/tree.test.ts                            | 255 ++++++
 105 files changed, 7221 insertions(+), 633 deletions(-)
 create mode 100644 docs/components/copy-button.md
 create mode 100644 docs/components/date-picker.md
 create mode 100644 docs/components/icon.md
 create mode 100644 docs/components/meter.md
 create mode 100644 docs/components/pin-input.md
 create mode 100644 docs/components/tree.md
 create mode 100644 src/components/copy-button/BqCopyButton.ts
 create mode 100644 src/components/copy-button/index.ts
 create mode 100644 src/components/date-picker/BqDatePicker.ts
 create mode 100644 src/components/date-picker/index.ts
 create mode 100644 src/components/icon/BqIcon.ts
 create mode 100644 src/components/icon/index.ts
 create mode 100644 src/components/meter/BqMeter.ts
 create mode 100644 src/components/meter/index.ts
 create mode 100644 src/components/pin-input/BqPinInput.ts
 create mode 100644 src/components/pin-input/index.ts
 create mode 100644 src/components/tree/BqTree.ts
 create mode 100644 src/components/tree/index.ts
 create mode 100644 src/theme/root.ts
 create mode 100644 src/theme/scheme.ts
 create mode 100644 src/utils/icons.ts
 create mode 100644 stories/copy-button.stories.ts
 create mode 100644 stories/date-picker.stories.ts
 create mode 100644 stories/icon.stories.ts
 create mode 100644 stories/meter.stories.ts
 create mode 100644 stories/pin-input.stories.ts
 create mode 100644 stories/tree.stories.ts
 create mode 100644 tests/component-css.test.ts
 create mode 100644 tests/date-picker.test.ts
 create mode 100644 tests/icons.test.ts
 create mode 100644 tests/meter-copy-button.test.ts
 create mode 100644 tests/pin-input.test.ts
 create mode 100644 tests/sanitizer-allowlist.test.ts
 create mode 100644 tests/theme-scheme.test.ts
 create mode 100644 tests/tree.test.ts

diff --git a/AGENT.md b/AGENT.md
index 4128e35..cd2c51a 100644
--- a/AGENT.md
+++ b/AGENT.md
@@ -31,15 +31,30 @@ interpolate the shared fragments from `src/utils/styles.ts`:
 
 ```ts
 import { component, css, html } from '@bquery/bquery/component';
-import { baseStyles, reset, srOnly } from '../../utils/styles.js';
+import { baseStyles, fieldStyles, focusRing, reset, srOnly } from '../../utils/styles.js';
 
 styles: css`
   ${baseStyles}
   ${reset}
+  ${focusRing}
   :host { display: block; }
 `
 ```
 
+The fragments, and when to reach for each:
+
+| Fragment       | Provides                                                            |
+| -------------- | ------------------------------------------------------------------- |
+| `baseStyles`   | Tokens + both colour schemes. Every component.                       |
+| `reset`        | `box-sizing`, `[hidden]`, and the reduced-motion opt-out.            |
+| `focusRing`    | The standard ring on the usual focusable elements, at zero specificity. |
+| `fieldStyles`  | `.field` / `.label` / `.hint` / `.error-msg` / `.required-mark` for form controls. |
+| `srOnly`       | `.sr-only`.                                                          |
+
+**A backtick inside a CSS comment terminates the template literal.** Two
+components have been broken this way; write ``accent-color`` without the
+backticks inside `css` blocks.
+
 This matters for more than tidiness. A `css` payload is handed to
 `adoptedStyleSheets`, so the stylesheet is constructed **once per component and
 shared by every instance**, and re-renders no longer rewrite it. A plain string
@@ -75,12 +90,67 @@ asserts that the overlay components leave no document listeners behind.
 Use `store(owner, init)` when a value created in `connected()` has to stay
 reachable from `updated()`.
 
+### Icons
+
+`svg` is on the sanitizer's *forbidden* list, which `sanitize.allowTags` cannot
+re-open — a component can never emit inline SVG. Icons therefore live in the
+stylesheet, as `mask-image` data URIs painted with `currentColor`:
+
+```ts
+import { iconCss } from '../../utils/icons.js';
+
+styles: css`
+  ${baseStyles}
+  ${iconCss('chevron-down', 'x')}
+`,
+// render: <span class="icon" data-icon="x" aria-hidden="true"></span>
+```
+
+Name only the icons the component draws; `iconCss` emits one rule each, and the
+full set is far too heavy to embed everywhere (`bq-icon` is the exception).
+`iconMask(name)` returns just the mask declarations, for a `::before`/`::after`
+on an element the component already renders.
+
+`iconCss` defines a global `.icon` box inside the shadow root. A component that
+already uses `.icon` for something else — a slot wrapper, say — must rename it,
+or the wrapper inherits the mask box. `bq-banner` and `bq-file-upload` hit this.
+
 ### Sanitizer allowlist
 
 Rendered markup is sanitized. The framework's base allowlist covers `part`,
 `aria-*`, `data-*` and the usual form attributes, but not everything — `accept`,
-`datetime` and `inputmode` each needed an explicit `sanitize.allowAttributes`
-entry. If an attribute silently disappears from rendered output, this is why.
+`datetime`, `inputmode`, `scope`, `colspan`, `spellcheck` and `style` each
+needed an explicit `sanitize.allowAttributes` entry. If an attribute silently
+disappears from rendered output, this is why.
+
+`tests/sanitizer-allowlist.test.ts` parses every render template and fails on an
+attribute the sanitizer would drop, so this can no longer ship unnoticed.
+
+### Focus across re-renders
+
+Rendering assigns `shadowRoot.innerHTML`, so every render destroys the node the
+user is in. Any component with a focusable element inside its shadow root wants
+the packaged treatment:
+
+```ts
+connected()    { trackFocus(host(this), bind(this)); },
+beforeUpdate() { markFocus(this); },
+updated()      { restorePreservedFocus(this); },
+```
+
+`trackFocus` records the focus position from a handful of events in the
+**capture** phase, so the snapshot is taken before the component's own handler
+runs. `beforeUpdate` covers attribute-driven renders, which no event precedes.
+`setState` renders skip `beforeUpdate` entirely, which is why the event-driven
+half is needed at all.
+
+### Theming across the shadow boundary
+
+Semantic tokens resolve through a scheme channel — `--bq-bg-base:
+var(--bq-scheme-bg-base, #fff)` — so a document-level `data-theme` can reach
+into shadow roots. Do not "simplify" that away: a plain `:host` definition
+cannot be overridden by an ancestor, and `:host-context()` only exists in
+Chromium. See `src/theme/scheme.ts`.
 
 ### Shadow-DOM state and re-renders
 
diff --git a/README.md b/README.md
index 6acb8d0..fa3c903 100644
--- a/README.md
+++ b/README.md
@@ -19,7 +19,8 @@ It is designed to give teams the kind of component coverage, polish, accessibili
 - **Reusable UI components** spanning actions, forms, navigation, data display, overlays, and feedback
 - **Framework-agnostic** usage in plain HTML, React, Vue, Angular, Svelte, and other Custom Element-capable runtimes
 - **Accessible by default** with keyboard support, ARIA roles, focus management, and screen reader announcements
-- **Themeable via design tokens** and CSS custom properties
+- **Themeable via design tokens** and CSS custom properties, switchable from the document in every browser
+- **A built-in icon set** rendered as CSS masks, so glyphs inherit text colour and stay crisp at any size
 - **Tree-shakeable ESM exports** with per-component imports
 - **Browser-ready UMD and IIFE bundles** for direct CDN delivery
 - **Built-in dark mode, i18n, and event-driven APIs**
@@ -30,12 +31,12 @@ The current library covers the core component categories developers expect from
 
 | Category         | Components                                                                                                            |
 | ---------------- | --------------------------------------------------------------------------------------------------------------------- |
-| **Actions**      | Button, Icon Button, Button Group                                                                                     |
-| **Forms**        | Input, Number Input, Textarea, Select, Segmented Control, Checkbox, Radio, Switch, Slider, Chip, Rating, File Upload   |
-| **Navigation**   | Tabs, Accordion, Breadcrumbs, Pagination, Stepper                                                                     |
-| **Data Display** | Card, Badge, Avatar, Avatar Group, Table, Divider, Empty State, Stat Card, Timeline, Kbd                               |
-| **Feedback**     | Alert, Banner, Progress, Spinner, Skeleton, Tooltip, Toast                                                            |
-| **Overlays**     | Dialog, Drawer, Dropdown Menu, Popover                                                                                |
+| **Actions**      | Button, Icon Button, Button Group, Copy Button                                                                                              |
+| **Forms**        | Input, Number Input, Textarea, Select, Combobox, Tag Input, Pin Input, Date Picker, Segmented Control, Checkbox, Radio, Switch, Slider, Chip, Rating, File Upload |
+| **Navigation**   | Tabs, Accordion, Breadcrumbs, Pagination, Stepper, Tree                                                                                     |
+| **Data Display** | Card, Badge, Avatar, Avatar Group, Table, Divider, Empty State, Stat Card, Timeline, Kbd, Icon, Meter                                       |
+| **Feedback**     | Alert, Banner, Progress, Spinner, Skeleton, Tooltip, Toast                                                                                  |
+| **Overlays**     | Dialog, Drawer, Dropdown Menu, Popover                                                                                                      |
 
 For the full catalog and feature coverage, see [`docs/components/index.md`](./docs/components/index.md).
 
@@ -80,13 +81,14 @@ For ESM-based app builds, prefer importing `@bquery/ui` from your bundler or oth
 
 ## Current release snapshot
 
-The current release (`1.10.0`) emphasizes:
+The current release (`1.15.0`) emphasizes:
 
-- **Import-based registration as the canonical integration path.** Import `@bquery/ui` once to register all components, or import `@bquery/ui/components/<name>` to register only the wrappers you need.
-- **A clearer shared package surface.** `@bquery/ui/tokens`, `@bquery/ui/theme`, `@bquery/ui/i18n`, `@bquery/ui/utils`, and `@bquery/ui/register` are all explicit entry points.
-- **Broader accessibility and localization coverage.** Recent releases improved accordion semantics, live form-field counters, localized table states, chip keyboard behavior, and reduced-motion-aware overlay transitions.
-- **A larger production-ready catalog.** The package now spans 31 web components across actions, forms, navigation, data display, feedback, and overlays, including `bq-dropdown-menu`, `bq-stat-card`, and the imperative toast API.
-- **Aligned docs and browser bundles.** Version-pinned CDN snippets, migration guidance, and Storybook/VitePress references now target `1.10.0`.
+- **A built-in icon set.** Interface glyphs are rendered as CSS masks rather than text characters, so they inherit `currentColor`, scale with `font-size`, and look the same on every platform. Available as `<bq-icon>` and to your own components through `iconCss()`.
+- **Dark mode that works in every browser.** The scheme now travels through an inherited custom-property channel instead of `:host-context()`, which exists only in Chromium — and which, sitting in a selector list, previously took the whole dark theme down with it in Firefox and Safari. `data-theme` also works on any subtree, not just the root.
+- **A deeper token layer.** Semantic surfaces (`--bq-surface-raised`, `--bq-surface-overlay`), translucent interaction states, per-intent focus rings, a shared control-height scale, and dark-mode elevation.
+- **Focus that survives a re-render.** Rendering replaces the shadow tree; text fields, calendars and tree views now keep focus and the caret across the renders their own interactions cause.
+- **A larger production-ready catalog.** The package spans 49 web components across actions, forms, navigation, data display, feedback, and overlays — including `bq-date-picker`, `bq-tree`, `bq-pin-input`, `bq-meter`, `bq-copy-button`, and `bq-icon`.
+- **Aligned docs and browser bundles.** Version-pinned CDN snippets, migration guidance, and Storybook/VitePress references target `1.15.0`.
 
 ## Tree-Shakeable Usage
 
@@ -153,9 +155,16 @@ For migration guidance from older registration patterns, see [`docs/guide/migrat
 ### Theming
 
 - CSS custom properties for colors, spacing, typography, radius, shadows, motion, and z-index
-- Light and dark themes
+- Semantic surface, interaction, and focus-ring tokens on top of the raw palette
+- Light and dark themes, switchable per document *or* per subtree with `data-theme`
 - `::part()` support for targeted customization
 
+### Icons
+
+- A built-in set of interface glyphs, available as `<bq-icon name="…">`
+- Rendered through CSS masks, so an icon inherits `currentColor` and scales with `font-size`
+- `iconCss()` lets your own components pull in only the glyphs they draw
+
 ### Internationalization
 
 - User-facing strings run through the library i18n system
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index f70ad01..b120d38 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -64,17 +64,22 @@ export default defineConfig({
           { text: 'Card', link: '/components/card' },
           { text: 'Checkbox', link: '/components/checkbox' },
           { text: 'Chip', link: '/components/chip' },
+          { text: 'Copy Button', link: '/components/copy-button' },
+          { text: 'Date Picker', link: '/components/date-picker' },
           { text: 'Dialog', link: '/components/dialog' },
           { text: 'Divider', link: '/components/divider' },
           { text: 'Drawer', link: '/components/drawer' },
           { text: 'Dropdown Menu', link: '/components/dropdown-menu' },
           { text: 'Empty State', link: '/components/empty-state' },
           { text: 'File Upload', link: '/components/file-upload' },
+          { text: 'Icon', link: '/components/icon' },
           { text: 'Icon Button', link: '/components/icon-button' },
           { text: 'Input', link: '/components/input' },
           { text: 'Kbd', link: '/components/kbd' },
+          { text: 'Meter', link: '/components/meter' },
           { text: 'Number Input', link: '/components/number-input' },
           { text: 'Pagination', link: '/components/pagination' },
+          { text: 'Pin Input', link: '/components/pin-input' },
           { text: 'Popover', link: '/components/popover' },
           { text: 'Progress', link: '/components/progress' },
           { text: 'Radio', link: '/components/radio' },
@@ -93,6 +98,7 @@ export default defineConfig({
           { text: 'Timeline', link: '/components/timeline' },
           { text: 'Toast', link: '/components/toast' },
           { text: 'Tooltip', link: '/components/tooltip' },
+          { text: 'Tree', link: '/components/tree' },
         ],
       },
     ],
diff --git a/docs/components/button.md b/docs/components/button.md
index fe648eb..e88147d 100644
--- a/docs/components/button.md
+++ b/docs/components/button.md
@@ -79,6 +79,8 @@ If you need an icon-only action, prefer [`bq-icon-button`](/components/icon-butt
 | `href` | `string` | — | Renders as `<a>` when set |
 | `target` | `string` | — | Link target (used with `href`) |
 | `label` | `string` | — | Optional accessible label override, especially useful for icon-only usage |
+| `full-width` | `boolean` | `false` | Stretch to the width of the container |
+| `pill` | `boolean` | `false` | Fully rounded ends |
 
 ## Events
 
diff --git a/docs/components/copy-button.md b/docs/components/copy-button.md
new file mode 100644
index 0000000..7ab5bcf
--- /dev/null
+++ b/docs/components/copy-button.md
@@ -0,0 +1,75 @@
+# Copy Button
+
+`bq-copy-button` copies text to the clipboard and confirms that it did.
+
+The confirmation is the point: without it a copy button is indistinguishable
+from a dead one. The icon and the accessible name both switch to the confirmed
+state for a moment, then switch back.
+
+## Basic Usage
+
+```html
+<bq-copy-button value="npm install @bquery/ui"></bq-copy-button>
+```
+
+## Copying another element
+
+For the common "copy the code in that block" case, point `from` at a selector.
+It is resolved against the containing document or shadow root:
+
+```html
+<code id="install">npm install @bquery/ui</code>
+<bq-copy-button from="#install"></bq-copy-button>
+```
+
+## Variants
+
+```html
+<bq-copy-button value="x" variant="ghost"></bq-copy-button>
+<bq-copy-button value="x" variant="outline"></bq-copy-button>
+<bq-copy-button value="x" variant="solid"></bq-copy-button>
+```
+
+## Events
+
+```js
+document.querySelector('bq-copy-button').addEventListener('bq-copy', (e) => {
+  console.log(e.detail.value, e.detail.ok);
+});
+```
+
+`ok` is `false` when the clipboard write was refused — for instance in a
+browser that blocks it outside a user gesture. The button stays in its idle
+state in that case rather than claiming success.
+
+## Properties
+
+| Property       | Type      | Default   | Description                                    |
+| -------------- | --------- | --------- | ---------------------------------------------- |
+| `value`        | `string`  | `''`      | Text to copy                                   |
+| `from`         | `string`  | `''`      | Selector whose text content is copied instead  |
+| `label`        | `string`  | `''`      | Accessible name in the idle state              |
+| `copied-label` | `string`  | `''`      | Accessible name after a successful copy        |
+| `timeout`      | `number`  | `2000`    | How long the confirmed state lasts, in ms      |
+| `disabled`     | `boolean` | `false`   |                                                |
+| `variant`      | `string`  | `'ghost'` | `ghost` \| `outline` \| `solid`                |
+| `size`         | `string`  | `'md'`    | `sm` \| `md` \| `lg`                           |
+
+## Events
+
+| Event     | Detail                             | Description              |
+| --------- | ---------------------------------- | ------------------------ |
+| `bq-copy` | `{ value: string, ok: boolean }`   | A copy was attempted     |
+
+## CSS Parts
+
+| Part     | Description       |
+| -------- | ----------------- |
+| `button` | The button element |
+
+## Accessibility
+
+- The button is named by `label`, and the name changes to `copied-label` while
+  the confirmed state is showing.
+- A polite live region announces the confirmation, so the feedback is not
+  colour- and icon-only.
diff --git a/docs/components/date-picker.md b/docs/components/date-picker.md
new file mode 100644
index 0000000..7ad5f32
--- /dev/null
+++ b/docs/components/date-picker.md
@@ -0,0 +1,122 @@
+# Date Picker
+
+`bq-date-picker` is a text field with a calendar popup.
+
+## Basic Usage
+
+```html
+<bq-date-picker label="Due date" value="2026-03-15"></bq-date-picker>
+```
+
+`value` is always ISO `YYYY-MM-DD`, in and out, so the attribute means the same
+thing in every locale. What the user sees is formatted with
+`Intl.DateTimeFormat`.
+
+## Localisation
+
+The `locale` prop drives the displayed date, the month name and the weekday
+headers. `first-day-of-week` decides which column the week starts in — `1` for
+Monday (the default), `0` for Sunday.
+
+```html
+<bq-date-picker locale="de-DE" label="Fälligkeitsdatum"></bq-date-picker>
+<bq-date-picker locale="en-US" first-day-of-week="0"></bq-date-picker>
+```
+
+## Range
+
+```html
+<bq-date-picker min="2026-03-10" max="2026-03-24"></bq-date-picker>
+```
+
+Days outside the range are disabled, the month arrows stop at the boundary, and
+a date typed into the field outside the range is rejected.
+
+## Keyboard
+
+| Key                              | Action                          |
+| -------------------------------- | ------------------------------- |
+| <kbd>Alt</kbd> + <kbd>↓</kbd>    | Open the calendar               |
+| <kbd>←</kbd> / <kbd>→</kbd>      | Previous / next day             |
+| <kbd>↑</kbd> / <kbd>↓</kbd>      | Previous / next week            |
+| <kbd>PageUp</kbd> / <kbd>PageDown</kbd> | Previous / next month    |
+| <kbd>Shift</kbd> + <kbd>PageUp</kbd> / <kbd>PageDown</kbd> | Previous / next year |
+| <kbd>Home</kbd> / <kbd>End</kbd> | Start / end of the week         |
+| <kbd>Enter</kbd> / <kbd>Space</kbd> | Select the focused day       |
+| <kbd>Escape</kbd>                | Close and return to the field   |
+
+## Typing a date
+
+The field accepts an ISO date typed directly. Anything it cannot parse — or a
+date outside `min`/`max` — is rejected by repainting the last good value, so
+the component never stores something other than what is shown.
+
+## Forms
+
+The ISO value is mirrored into a hidden input, so the picker submits with a
+plain `<form>` and participates in constraint validation:
+
+```html
+<form>
+  <bq-date-picker name="due" label="Due date" required></bq-date-picker>
+  <bq-button type="submit">Save</bq-button>
+</form>
+```
+
+## Time zones
+
+All date arithmetic runs in UTC. A calendar built from local-time `Date`
+objects lands on the wrong day twice a year — on a spring-forward morning the
+missing hour makes "add one day" produce the same date again — and a calendar
+date has no time zone to begin with.
+
+## Properties
+
+| Property            | Type      | Default | Description                                |
+| ------------------- | --------- | ------- | ------------------------------------------ |
+| `label`             | `string`  | `''`    | Field label                                |
+| `value`             | `string`  | `''`    | Selected date as `YYYY-MM-DD`              |
+| `name`              | `string`  | `''`    | Form field name                            |
+| `min`               | `string`  | `''`    | Earliest selectable date                   |
+| `max`               | `string`  | `''`    | Latest selectable date                     |
+| `locale`            | `string`  | `''`    | BCP-47 tag; defaults to the environment    |
+| `first-day-of-week` | `number`  | `1`     | `0` (Sunday) … `6`                         |
+| `placeholder`       | `string`  | `''`    |                                            |
+| `clearable`         | `boolean` | `false` | Show a button that clears the date         |
+| `disabled`          | `boolean` | `false` |                                            |
+| `readonly`          | `boolean` | `false` |                                            |
+| `required`          | `boolean` | `false` |                                            |
+| `error`             | `string`  | `''`    | Error message; non-empty = error state     |
+| `hint`              | `string`  | `''`    | Helper text                                |
+| `size`              | `string`  | `'md'`  | `sm` \| `md` \| `lg`                       |
+
+## Events
+
+| Event       | Detail              | Description             |
+| ----------- | ------------------- | ----------------------- |
+| `bq-change` | `{ value: string }` | A date was selected     |
+| `bq-open`   | —                   | The calendar opened     |
+| `bq-close`  | —                   | The calendar closed     |
+
+## CSS Parts
+
+| Part      | Description               |
+| --------- | ------------------------- |
+| `field`   | The outer wrapper         |
+| `label`   | The label element         |
+| `control` | The input shell           |
+| `input`   | The text field            |
+| `trigger` | The calendar button       |
+| `clear`   | The clear button          |
+| `panel`   | The popup                 |
+| `grid`    | The month grid            |
+| `day`     | A single day button       |
+
+## Accessibility
+
+- The field is `aria-haspopup="dialog"` with `aria-expanded`; the popup is a
+  labelled dialog containing a `role="grid"` calendar.
+- Each day button is named with its full localised date, so a screen reader
+  reads "Sunday, March 15, 2026" rather than "15".
+- One day is in the tab order at a time and the arrow keys move it, matching
+  the ARIA date-picker pattern.
diff --git a/docs/components/icon.md b/docs/components/icon.md
new file mode 100644
index 0000000..9e417ca
--- /dev/null
+++ b/docs/components/icon.md
@@ -0,0 +1,109 @@
+# Icon
+
+`bq-icon` renders one glyph from the built-in icon set.
+
+Icons are drawn as CSS masks filled with `currentColor`, so they inherit the
+surrounding text colour and scale with `font-size` — and they stay a single
+crisp path at any zoom level or pixel density.
+
+> Inline `<svg>` cannot be used inside a component's rendered markup: the
+> framework sanitizer removes `svg` and no `allowTags` entry can re-open it.
+> That is why the set is delivered as masks rather than as markup.
+
+## Basic Usage
+
+```html
+<bq-icon name="check"></bq-icon>
+<bq-icon name="trash" size="1.5rem"></bq-icon>
+```
+
+## Colour and size
+
+An icon takes its colour from the text around it and its size from the font
+size, so it drops into a sentence, a button or a heading without configuration.
+
+```html
+<span style="color: #dc2626; font-size: 1.25rem">
+  <bq-icon name="alert-triangle"></bq-icon> Deletion is permanent
+</span>
+```
+
+Override the size explicitly with the `size` prop or the `--bq-icon-size`
+custom property:
+
+```html
+<bq-icon name="star" size="2rem"></bq-icon>
+<bq-icon name="star" style="--bq-icon-size: 2rem"></bq-icon>
+```
+
+## Accessibility
+
+An icon is decorative by default and carries `aria-hidden`. Pass `label` only
+when the icon *is* the content — an icon-only control with no other text:
+
+```html
+<!-- Decorative: the button already says what it does -->
+<bq-button><bq-icon slot="prefix-icon" name="download"></bq-icon> Download</bq-button>
+
+<!-- Meaningful: nothing else names the control -->
+<bq-icon name="trash" label="Delete"></bq-icon>
+```
+
+## Using icons inside your own components
+
+`iconCss()` returns a stylesheet fragment containing only the icons you name,
+so an unused icon costs nothing:
+
+```ts
+import { css } from '@bquery/bquery/component';
+import { iconCss } from '@bquery/ui/utils';
+import { baseStyles } from '@bquery/ui/utils';
+
+styles: css`
+  ${baseStyles}
+  ${iconCss('chevron-down', 'x')}
+`,
+// …then render <span class="icon" data-icon="x" aria-hidden="true"></span>
+```
+
+To decorate an element you already render, `iconMask()` returns the mask
+declarations on their own, for use in any rule including `::before`/`::after`.
+
+## Properties
+
+| Property | Type     | Default | Description                                      |
+| -------- | -------- | ------- | ------------------------------------------------ |
+| `name`   | `string` | `''`    | Icon name; an unknown name renders nothing       |
+| `size`   | `string` | `''`    | Any CSS length; defaults to `1em`                |
+| `label`  | `string` | `''`    | Accessible name. Omit for decorative icons.      |
+
+## CSS Custom Properties
+
+| Property          | Description                     |
+| ----------------- | ------------------------------- |
+| `--bq-icon-size`  | Alternative to the `size` prop  |
+
+## CSS Parts
+
+| Part   | Description        |
+| ------ | ------------------ |
+| `icon` | The glyph element  |
+
+## Available icons
+
+Status: `check` `check-circle` `x` `x-circle` `info` `alert-circle`
+`alert-triangle` `help-circle` `circle` `dot`
+
+Direction: `chevron-up` `chevron-down` `chevron-left` `chevron-right`
+`chevrons-left` `chevrons-right` `chevrons-up-down` `arrow-up` `arrow-down`
+`arrow-left` `arrow-right` `external-link`
+
+Actions: `plus` `minus` `search` `menu` `more-horizontal` `more-vertical`
+`trash` `copy` `edit` `download` `upload` `refresh` `filter` `settings`
+
+Objects: `eye` `eye-off` `lock` `calendar` `clock` `star` `star-filled`
+`heart` `user` `users` `mail` `link` `image` `file` `folder` `home` `sun`
+`moon` `loader`
+
+The full list is also available programmatically as `iconNames` from
+`@bquery/ui/utils`.
diff --git a/docs/components/index.md b/docs/components/index.md
index 3d14130..df7be95 100644
--- a/docs/components/index.md
+++ b/docs/components/index.md
@@ -8,10 +8,10 @@ This catalog gives you a complete overview of the currently available building b
 
 | Category | Components |
 | --- | --- |
-| **Actions** | `bq-button`, `bq-icon-button`, `bq-button-group` |
-| **Forms** | `bq-input`, `bq-number-input`, `bq-textarea`, `bq-select`, `bq-segmented-control`, `bq-checkbox`, `bq-radio`, `bq-switch`, `bq-slider`, `bq-chip`, `bq-rating`, `bq-file-upload` |
-| **Navigation & Disclosure** | `bq-tabs`, `bq-accordion`, `bq-breadcrumbs`, `bq-pagination`, `bq-stepper` |
-| **Data Display** | `bq-card`, `bq-badge`, `bq-avatar`, `bq-avatar-group`, `bq-table`, `bq-divider`, `bq-empty-state`, `bq-stat-card`, `bq-timeline`, `bq-kbd` |
+| **Actions** | `bq-button`, `bq-icon-button`, `bq-button-group`, `bq-copy-button` |
+| **Forms** | `bq-input`, `bq-number-input`, `bq-textarea`, `bq-select`, `bq-combobox`, `bq-tag-input`, `bq-pin-input`, `bq-date-picker`, `bq-segmented-control`, `bq-checkbox`, `bq-radio`, `bq-switch`, `bq-slider`, `bq-chip`, `bq-rating`, `bq-file-upload` |
+| **Navigation & Disclosure** | `bq-tabs`, `bq-accordion`, `bq-breadcrumbs`, `bq-pagination`, `bq-stepper`, `bq-tree` |
+| **Data Display** | `bq-card`, `bq-badge`, `bq-avatar`, `bq-avatar-group`, `bq-table`, `bq-divider`, `bq-empty-state`, `bq-stat-card`, `bq-timeline`, `bq-kbd`, `bq-icon`, `bq-meter` |
 | **Feedback & Loading** | `bq-alert`, `bq-banner`, `bq-progress`, `bq-spinner`, `bq-skeleton`, `bq-tooltip`, `bq-toast` |
 | **Overlays** | `bq-dialog`, `bq-drawer`, `bq-dropdown-menu`, `bq-popover` |
 
@@ -33,6 +33,7 @@ Across the component library you will find the same professional capabilities th
 | `bq-button` | Primary and secondary actions | Variants, sizes, loading state, link rendering, icon slots, accessible label override |
 | `bq-icon-button` | Compact icon-only actions | Accessible label or title fallback, multiple variants, loading state, link rendering |
 | `bq-button-group` | Joining related actions into one control | Attached mode with shared borders, orientation, shared size forwarding, group semantics |
+| `bq-copy-button` | Copying a snippet or token to the clipboard | Confirmed state with icon swap, copy-from-selector, legacy clipboard fallback |
 
 ## Forms
 
@@ -50,6 +51,10 @@ Across the component library you will find the same professional capabilities th
 | `bq-chip` | Compact selectable tags | Selection state, removable chips, contextual variants |
 | `bq-rating` | Star ratings and scores | Radio-group semantics, keyboard support, read-only and clearable modes, form participation |
 | `bq-file-upload` | File selection and drag-and-drop | Type and size filtering, selected-file list, rejection events, keyboard-reachable drop zone |
+| `bq-combobox` | Filtering a long list of options | ARIA 1.2 combobox pattern, single and multiple selection, diacritic-insensitive matching |
+| `bq-tag-input` | Free-form tag and keyword entry | Delimiter splitting, paste handling, per-tag removal, limit enforcement |
+| `bq-pin-input` | One-time codes and PINs | Per-cell entry, paste distribution, `one-time-code` autofill, completion event |
+| `bq-date-picker` | Choosing a calendar date | Locale-aware calendar, UTC date maths, min/max range, full keyboard grid |
 
 ## Navigation & Disclosure
 
@@ -60,6 +65,7 @@ Across the component library you will find the same professional capabilities th
 | `bq-breadcrumbs` | Hierarchical navigation | Automatic separators, semantic navigation markup |
 | `bq-pagination` | Paging through result sets | Previous/next controls, ellipsis logic, sibling page calculation |
 | `bq-stepper` | Multi-step flows and wizards | Horizontal/vertical layouts, clickable steps, per-step status announcements |
+| `bq-tree` | Hierarchical browsing and pickers | ARIA tree pattern, roving tab stop, typeahead, single or multiple selection |
 
 ## Data Display
 
@@ -75,6 +81,8 @@ Across the component library you will find the same professional capabilities th
 | `bq-stat-card` | Dashboard metrics and KPI summaries | Compact metric layout, trend pill, loading skeleton, icon slot |
 | `bq-timeline` | Activity feeds and audit trails | Ordered-list semantics, event variants, machine-readable timestamps, custom markers |
 | `bq-kbd` | Keyboard shortcuts | Combination parsing, symbol substitution, sizes and variants |
+| `bq-icon` | Interface glyphs | Mask-rendered set that inherits text colour and size, decorative by default |
+| `bq-meter` | Levels and gauges that are not progress | Native `<meter>` band semantics, graded colouring, custom value text |
 
 ## Feedback & Loading
 
diff --git a/docs/components/input.md b/docs/components/input.md
index 432c79e..53a2180 100644
--- a/docs/components/input.md
+++ b/docs/components/input.md
@@ -106,6 +106,7 @@ The counter:
 | `hint` | `string` | — | Hint / helper text |
 | `maxlength` | `string` | — | Maximum character count |
 | `show-counter` | `boolean` | `false` | Show character counter (requires `maxlength`) |
+| `clearable` | `boolean` | `false` | Show a button that clears the value |
 
 ## Events
 
diff --git a/docs/components/meter.md b/docs/components/meter.md
new file mode 100644
index 0000000..e164a25
--- /dev/null
+++ b/docs/components/meter.md
@@ -0,0 +1,81 @@
+# Meter
+
+`bq-meter` shows a scalar measurement inside a known range — disk usage,
+password strength, a budget, a rating average.
+
+## Meter or progress?
+
+They look alike and mean different things. A **progress bar** runs from nothing
+to done and only ever moves forward; it answers *how far along is this task*. A
+**meter** shows a level that can sit anywhere and move in either direction; it
+answers *is this reading healthy*. Use `bq-progress` for the former.
+
+## Basic Usage
+
+```html
+<bq-meter label="Storage used" value="64" show-value></bq-meter>
+```
+
+## Bands
+
+`low`, `high` and `optimum` follow the semantics of the native `<meter>`
+element. The bands split the range in three; `optimum` says which part is
+good, and the bar colours itself accordingly.
+
+Lower is better — disk usage:
+
+```html
+<bq-meter label="Disk" value="94" low="40" high="80" optimum="0" show-value></bq-meter>
+```
+
+Higher is better — battery:
+
+```html
+<bq-meter label="Battery" value="12" low="20" high="80" optimum="100" show-value></bq-meter>
+```
+
+Without any bands the meter stays in the accent colour, which is the right
+default when the value has no good or bad end.
+
+## Custom value text
+
+```html
+<bq-meter label="Storage" value="72" value-text="72 GB of 100 GB" show-value></bq-meter>
+```
+
+`value-text` is what both the label and `aria-valuetext` use, so the spoken and
+the visible reading stay in step.
+
+## Properties
+
+| Property     | Type      | Default | Description                                |
+| ------------ | --------- | ------- | ------------------------------------------ |
+| `value`      | `number`  | `0`     | Current reading; clamped into the range    |
+| `min`        | `number`  | `0`     | Range start                                |
+| `max`        | `number`  | `100`   | Range end                                  |
+| `low`        | `number`  | —       | Upper bound of the low band                |
+| `high`       | `number`  | —       | Lower bound of the high band               |
+| `optimum`    | `number`  | —       | Where in the range is best                 |
+| `label`      | `string`  | `''`    | Visible label and accessible name          |
+| `value-text` | `string`  | `''`    | Overrides the rendered and spoken reading  |
+| `show-value` | `boolean` | `false` | Show the reading next to the label         |
+| `size`       | `string`  | `'md'`  | `sm` \| `md` \| `lg`                       |
+
+## CSS Parts
+
+| Part    | Description        |
+| ------- | ------------------ |
+| `field` | The outer wrapper  |
+| `label` | The label element  |
+| `value` | The reading        |
+| `track` | The bar background |
+| `bar`   | The filled portion |
+
+## Accessibility
+
+- The track carries `role="meter"` with `aria-valuenow`, `aria-valuemin`,
+  `aria-valuemax` and `aria-valuetext`.
+- Colour is never the only signal: pair a graded meter with `show-value` or a
+  `value-text` that states the reading.
+- Under Windows high-contrast the bar falls back to the system highlight
+  colour and the track gains a border.
diff --git a/docs/components/pin-input.md b/docs/components/pin-input.md
new file mode 100644
index 0000000..8ec7b5b
--- /dev/null
+++ b/docs/components/pin-input.md
@@ -0,0 +1,106 @@
+# Pin Input
+
+`bq-pin-input` collects a short code — a one-time password, a PIN, an invite
+code — in a row of single-character cells.
+
+## Basic Usage
+
+```html
+<bq-pin-input label="Verification code" length="6"></bq-pin-input>
+```
+
+## Behaviour
+
+- Typing a character fills the current cell and moves to the next one.
+- Backspace clears the current cell; on an empty cell it steps back and clears
+  the previous one, so holding it deletes the whole code.
+- Pasting spreads the code across the cells from wherever the caret is,
+  overwriting rather than inserting.
+- Arrow keys, `Home` and `End` move between cells.
+- Clicking a partly filled row lands on the first empty cell.
+
+The first cell carries `autocomplete="one-time-code"`, so iOS and Android
+offer a code arriving by SMS.
+
+## Character types
+
+```html
+<bq-pin-input type="numeric" length="6"></bq-pin-input>
+<bq-pin-input type="alphanumeric" length="5"></bq-pin-input>
+<bq-pin-input type="text" length="4"></bq-pin-input>
+```
+
+Characters outside the chosen type are rejected as they are typed, so a
+numeric field never shows a stray letter.
+
+## Masked
+
+```html
+<bq-pin-input label="PIN" length="4" mask></bq-pin-input>
+```
+
+## Events
+
+```js
+const pin = document.querySelector('bq-pin-input');
+
+pin.addEventListener('bq-complete', (e) => {
+  // Fires once the last cell is filled
+  verify(e.detail.value);
+});
+```
+
+## Forms
+
+The component mirrors its value into a hidden input, so it submits with a
+plain `<form>` and participates in constraint validation:
+
+```html
+<form>
+  <bq-pin-input name="code" length="6" required></bq-pin-input>
+  <bq-button type="submit">Verify</bq-button>
+</form>
+```
+
+## Properties
+
+| Property     | Type      | Default     | Description                            |
+| ------------ | --------- | ----------- | -------------------------------------- |
+| `length`     | `number`  | `6`         | Number of cells                        |
+| `value`      | `string`  | `''`        | Current code                           |
+| `name`       | `string`  | `''`        | Form field name                        |
+| `type`       | `string`  | `'numeric'` | `numeric` \| `alphanumeric` \| `text`  |
+| `mask`       | `boolean` | `false`     | Obscure the characters                 |
+| `disabled`   | `boolean` | `false`     |                                        |
+| `readonly`   | `boolean` | `false`     |                                        |
+| `required`   | `boolean` | `false`     |                                        |
+| `label`      | `string`  | `''`        | Visible label                          |
+| `hint`       | `string`  | `''`        | Helper text                            |
+| `error`      | `string`  | `''`        | Error message; non-empty = error state |
+| `size`       | `string`  | `'md'`      | `sm` \| `md` \| `lg`                   |
+
+## Events
+
+| Event         | Detail                | Description                     |
+| ------------- | --------------------- | ------------------------------- |
+| `bq-input`    | `{ value: string }`   | The code changed                |
+| `bq-change`   | `{ value: string }`   | The code changed                |
+| `bq-complete` | `{ value: string }`   | Every cell is now filled        |
+
+## CSS Parts
+
+| Part    | Description            |
+| ------- | ---------------------- |
+| `field` | The outer wrapper      |
+| `label` | The label element      |
+| `cells` | The row of cells       |
+| `cell`  | A single cell          |
+| `hint`  | The hint text          |
+| `error` | The error message      |
+
+## Accessibility
+
+- The cells sit in a labelled `role="group"`, and each one is named
+  "Digit *n* of *m*".
+- A polite live region announces how many characters have been entered, so a
+  screen-reader user knows the code is progressing.
diff --git a/docs/components/radio.md b/docs/components/radio.md
index edb36a0..235b865 100644
--- a/docs/components/radio.md
+++ b/docs/components/radio.md
@@ -74,5 +74,9 @@ The component creates a hidden input proxy for native `<form>` submission. The p
 ## Accessibility
 
 - Each radio renders a native `<input type="radio">` inside the shadow DOM for full keyboard support.
+- Radios sharing a `name` behave as one group. Because each radio lives in its
+  own shadow root, the platform's "one checked per name" rule cannot see the
+  siblings, so the component clears them itself — scoped to the nearest `<form>`
+  so two unrelated groups on one page do not interfere.
 - The label is associated with the input via a wrapping `<label>` element.
 - Use the `required` prop to mark mandatory radio fields; the required indicator is rendered visually and conveyed through the native `required` attribute on the internal radio input.
diff --git a/docs/components/switch.md b/docs/components/switch.md
index 1e7245c..787ff80 100644
--- a/docs/components/switch.md
+++ b/docs/components/switch.md
@@ -33,11 +33,14 @@ The `bq-switch` component is a toggle switch form control.
 
 | Property   | Type      | Default | Description              |
 | ---------- | --------- | ------- | ------------------------ |
-| `label`    | `string`  | —       | Visible label text       |
-| `name`     | `string`  | —       | Form field name          |
-| `checked`  | `boolean` | `false` | Whether the switch is on |
-| `disabled` | `boolean` | `false` | Disables the switch      |
-| `size`     | `string`  | `'md'`  | `sm` \| `md` \| `lg`     |
+| `label`    | `string`  | —       | Visible label text                     |
+| `name`     | `string`  | —       | Form field name                        |
+| `value`    | `string`  | `'on'`  | Value submitted when the switch is on  |
+| `checked`  | `boolean` | `false` | Whether the switch is on               |
+| `disabled` | `boolean` | `false` | Disables the switch                    |
+| `required` | `boolean` | `false` | Must be on for the form to submit      |
+| `hint`     | `string`  | —       | Helper text below the switch           |
+| `size`     | `string`  | `'md'`  | `sm` \| `md` \| `lg`                   |
 
 ## Events
 
diff --git a/docs/components/tree.md b/docs/components/tree.md
new file mode 100644
index 0000000..5a42c2a
--- /dev/null
+++ b/docs/components/tree.md
@@ -0,0 +1,105 @@
+# Tree
+
+`bq-tree` renders hierarchical data — a file browser, a category picker, an
+org chart — with the full ARIA tree keyboard pattern.
+
+That pattern is the reason the component exists. A tree is not a nested list of
+buttons: the whole widget is a single tab stop, and the arrow keys move a
+*roving* focus through the nodes that are currently visible.
+
+## Basic Usage
+
+```html
+<bq-tree
+  label="Project files"
+  expanded="src"
+  items='[
+    {"id":"src","label":"src","icon":"folder","children":[
+      {"id":"index","label":"index.ts","icon":"file"}
+    ]},
+    {"id":"readme","label":"README.md","icon":"file"}
+  ]'
+></bq-tree>
+```
+
+Nodes are supplied as JSON, matching `bq-table`. Each node takes:
+
+| Field      | Type         | Description                                     |
+| ---------- | ------------ | ----------------------------------------------- |
+| `id`       | `string`     | Unique identifier; used by `expanded`/`selected` |
+| `label`    | `string`     | Visible text                                    |
+| `children` | `TreeNode[]` | Child nodes; presence makes the node a branch    |
+| `disabled` | `boolean`    | Not selectable, skipped by the arrow keys        |
+| `icon`     | `string`     | Icon name drawn before the label                |
+
+## Keyboard
+
+| Key                 | Action                                              |
+| ------------------- | --------------------------------------------------- |
+| <kbd>↓</kbd> / <kbd>↑</kbd> | Move to the next / previous visible node    |
+| <kbd>→</kbd>        | Open a closed branch, or move into an open one      |
+| <kbd>←</kbd>        | Close an open branch, or move to the parent         |
+| <kbd>Home</kbd> / <kbd>End</kbd> | Jump to the first / last visible node   |
+| <kbd>Enter</kbd> / <kbd>Space</kbd> | Select the focused node              |
+| <kbd>*</kbd>        | Open every branch at the current level              |
+| any letter          | Jump to the next node starting with it              |
+
+## Controlled state
+
+`expanded` and `selected` are comma-separated id lists, and both are reflected
+back onto the element — so a tree can be driven entirely from attributes:
+
+```js
+const tree = document.querySelector('bq-tree');
+
+tree.addEventListener('bq-select', (e) => {
+  console.log(e.detail.id, e.detail.node);
+});
+
+tree.addEventListener('bq-expand', (e) => {
+  console.log(e.detail.id, e.detail.expanded);
+});
+
+tree.setAttribute('expanded', 'src,components');
+```
+
+## Multiple selection
+
+```html
+<bq-tree multiple selected="a,b" items="…"></bq-tree>
+```
+
+## Properties
+
+| Property   | Type      | Default | Description                          |
+| ---------- | --------- | ------- | ------------------------------------ |
+| `items`    | `string`  | `'[]'`  | JSON array of nodes                  |
+| `expanded` | `string`  | `''`    | Comma-separated ids of open branches |
+| `selected` | `string`  | `''`    | Comma-separated ids of selected nodes |
+| `label`    | `string`  | `''`    | Accessible name for the tree         |
+| `multiple` | `boolean` | `false` | Allow more than one selected node    |
+| `disabled` | `boolean` | `false` |                                      |
+
+## Events
+
+| Event       | Detail                                          |
+| ----------- | ----------------------------------------------- |
+| `bq-select` | `{ id: string, ids: string[], node: TreeNode }` |
+| `bq-expand` | `{ id: string, expanded: boolean }`             |
+
+## CSS Parts
+
+| Part     | Description                    |
+| -------- | ------------------------------ |
+| `tree`   | The root list                  |
+| `node`   | A single node row              |
+| `twisty` | The expand/collapse arrow      |
+| `label`  | A node's text                  |
+
+## Accessibility
+
+- The root is `role="tree"`; nodes are `role="treeitem"` with `aria-level`,
+  `aria-selected` and — on branches only — `aria-expanded`.
+- Exactly one node is in the tab order at a time, and the arrow keys move it.
+- Clicking the arrow opens a branch without selecting it; clicking the row
+  does both.
diff --git a/docs/guide/dark-mode.md b/docs/guide/dark-mode.md
index b678553..3f2fddc 100644
--- a/docs/guide/dark-mode.md
+++ b/docs/guide/dark-mode.md
@@ -1,44 +1,100 @@
 # Dark Mode
 
-`@bquery/ui` supports dark mode via the `data-theme="dark"` attribute on the `<html>` element (or any ancestor).
+`@bquery/ui` switches colour scheme with the `data-theme` attribute. Put it on
+`<html>` for the whole page, or on any element to theme just that subtree.
 
-## Automatic (OS preference)
+```html
+<html data-theme="dark">
+  <!-- every bq-* element below uses dark tokens -->
+</html>
+```
 
-```typescript
-import { setColorScheme } from '@bquery/ui/theme';
+`data-theme` takes three values:
 
-setColorScheme('auto'); // follows prefers-color-scheme
-```
+| Value    | Meaning                                        |
+| -------- | ---------------------------------------------- |
+| `dark`   | Dark, regardless of the operating system        |
+| `light`  | Light, regardless of the operating system       |
+| `auto`   | Follows `prefers-color-scheme`, live            |
 
-## Manual Toggle
+## From JavaScript
 
 ```typescript
-import { setColorScheme } from '@bquery/ui/theme';
+import { setColorScheme, getResolvedColorScheme } from '@bquery/ui/theme';
 
-// Force dark
-setColorScheme('dark');
+setColorScheme('auto');   // follow the OS
+setColorScheme('dark');   // pin dark
+setColorScheme('light');  // pin light
 
-// Force light
-setColorScheme('light');
+getResolvedColorScheme(); // 'light' | 'dark' — what is actually showing
 ```
 
-## HTML Attribute
+`auto` is resolved in CSS with a `prefers-color-scheme` media query, so a
+system-level switch repaints the page immediately with no JavaScript listening
+for the change — and there is no `matchMedia` subscription to leak.
+
+## Theming part of a page
 
-You can also set it directly without JavaScript:
+Because the scheme is inherited, a themed island needs no API at all:
 
 ```html
-<html data-theme="dark">
-  <!-- All bq-* components will use dark tokens -->
-</html>
+<body data-theme="light">
+  <aside data-theme="dark">
+    <bq-button>Dark sidebar</bq-button>
+  </aside>
+</body>
+```
+
+## Native controls follow too
+
+Each scheme also sets the CSS `color-scheme` property, so scrollbars, the
+native date and colour pickers, and form-control defaults inside your page
+match the theme instead of staying stubbornly light.
+
+## How it works
+
+A component defines its tokens on its own `:host`, and a value set on an
+element always beats one inherited from an ancestor — which is why setting
+`--bq-bg-base` on `<html>` cannot re-theme a component on its own.
+
+So components resolve every semantic token through a *scheme channel*:
+
+```css
+:host {
+  --bq-bg-base: var(--bq-scheme-bg-base, #ffffff);
+}
 ```
 
-## Custom Dark Tokens
+`--bq-scheme-bg-base` is never defined on the host, so it resolves the ordinary
+way — by inheritance from the document. A small stylesheet, installed
+automatically the first time any component module is imported, defines the
+channel for each `data-theme` value.
+
+That stylesheet is plain CSS with no exotic selectors. The previous approach
+relied on `:host-context()`, which exists only in Chromium; worse, it appeared
+in a selector list alongside `:host([data-theme="dark"])`, and one unknown
+selector invalidates the entire list — so Firefox and Safari dropped the whole
+dark theme. The channel works in every browser.
 
-Override dark mode tokens with CSS:
+If you need to install the stylesheet into another document — an iframe or a
+popup window — call it yourself:
+
+```typescript
+import { installThemeStyles } from '@bquery/ui/theme';
+
+installThemeStyles(iframe.contentDocument);
+```
+
+## Custom dark tokens
+
+Override any token for one scheme by writing the rule against the attribute:
 
 ```css
-[data-theme="dark"] {
-  --bq-color-primary-600: #3b82f6;  /* slightly lighter in dark */
-  --bq-bg-base: #0f172a;
+[data-theme='dark'] {
+  --bq-color-primary-600: #818cf8;
+  --bq-surface-overlay: #111827;
 }
 ```
+
+To override a token in *both* schemes, set it on `:root` instead — see
+[Theming](/guide/theming).
diff --git a/docs/guide/migration-from-1-1-0.md b/docs/guide/migration-from-1-1-0.md
index d1141c4..7d1cd5b 100644
--- a/docs/guide/migration-from-1-1-0.md
+++ b/docs/guide/migration-from-1-1-0.md
@@ -1,6 +1,6 @@
 # Migration from 1.1.0
 
-Moving from `1.1.0` to the current `@bquery/ui` line (`1.10.0`) is mostly about aligning with the modern import model, the explicit package entry points, and the expanded accessibility/i18n defaults.
+Moving from `1.1.0` to the current `@bquery/ui` line (`1.15.0`) is mostly about aligning with the modern import model, the explicit package entry points, and the expanded accessibility/i18n defaults.
 
 ## Summary
 
diff --git a/docs/guide/theming.md b/docs/guide/theming.md
index 5506bf5..0f39145 100644
--- a/docs/guide/theming.md
+++ b/docs/guide/theming.md
@@ -1,8 +1,21 @@
 # Theming
 
-`@bquery/ui` uses CSS custom properties (variables) for all design tokens. You can override any token at any scope.
+`@bquery/ui` uses CSS custom properties for all design tokens. You can override
+any token at any scope.
 
-## Global Token Override
+Tokens come in two layers, and knowing which one you are reaching for saves a
+lot of guesswork:
+
+- **Primitives** — the raw palette and scales: `--bq-color-primary-600`,
+  `--bq-space-4`, `--bq-radius-lg`. These are the same in light and dark.
+- **Semantics** — what a primitive is being used *for*: `--bq-bg-base`,
+  `--bq-text-muted`, `--bq-surface-overlay`, `--bq-focus-ring`. These change
+  with the colour scheme.
+
+Retheme with the primitives; reach for the semantics when you want a surface or
+a piece of text to behave differently from the rest.
+
+## Global token override
 
 ```css
 :root {
@@ -13,6 +26,25 @@
 }
 ```
 
+## Scoped override
+
+Custom properties inherit through shadow boundaries, so scoping a theme to part
+of the page needs nothing special:
+
+```css
+.checkout {
+  --bq-color-primary-600: #059669;
+}
+```
+
+## Per-component override
+
+Every component also honours tokens set on the element itself:
+
+```html
+<bq-button style="--bq-radius-lg: 9999px">Pill</bq-button>
+```
+
 ## Using `applyThemeTokens`
 
 ```typescript
@@ -22,11 +54,51 @@ applyThemeTokens({
   '--bq-color-primary-600': '#7c3aed',
   '--bq-color-primary-700': '#6d28d9',
 });
+
+// Or scoped to one element:
+applyThemeTokens({ '--bq-radius-lg': '1rem' }, document.querySelector('.card-grid'));
 ```
 
-## Available Tokens
+Values set this way land in the element's inline style, so they outrank the
+theme in both schemes. To override only one scheme, write a rule against
+`[data-theme="dark"]` instead — see [Dark Mode](/guide/dark-mode).
+
+## Semantic tokens
+
+| Token                   | Used for                                              |
+| ----------------------- | ----------------------------------------------------- |
+| `--bq-bg-base`          | The page-level background a component sits on         |
+| `--bq-bg-subtle`        | Quiet fills: table headers, inset panels              |
+| `--bq-bg-muted`         | Stronger fills: disabled controls, hovered rows       |
+| `--bq-bg-hover`         | Translucent hover wash; tints whatever is beneath it  |
+| `--bq-bg-active`        | Translucent pressed wash                              |
+| `--bq-bg-selected`      | Selected rows and options                             |
+| `--bq-surface-raised`   | Cards — above the page                                |
+| `--bq-surface-overlay`  | Menus, popovers, dialogs, toasts — above everything   |
+| `--bq-surface-sunken`   | Wells and recessed areas                              |
+| `--bq-text-base`        | Body text                                             |
+| `--bq-text-muted`       | Secondary text, hints                                 |
+| `--bq-text-subtle`      | Placeholders, disabled text                           |
+| `--bq-text-inverse`     | Text on `--bq-bg-inverse`                             |
+| `--bq-border-base`      | Dividers and quiet outlines                           |
+| `--bq-border-emphasis`  | Control borders                                       |
+| `--bq-border-strong`    | Borders that need to read at a glance                 |
+| `--bq-border-focus`     | The border colour a focused control takes             |
+| `--bq-focus-ring`       | The focus ring `box-shadow`                           |
+| `--bq-overlay-backdrop` | Dialog and drawer scrims                              |
+
+The surfaces are a stack — sunken, base, raised, overlay. In light mode they
+are told apart by shadow; in dark mode shadows are invisible, so each level is
+a slightly different lightness. That is why an overlay has its own token rather
+than reusing `--bq-bg-base`.
+
+## Primitive tokens
 
 ### Colors
+
+Each of `primary`, `secondary`, `danger`, `success`, `warning` and `info` ships
+a full 50–900 ramp.
+
 | Token | Default |
 |-------|---------|
 | `--bq-color-primary-600` | `#2563eb` |
@@ -35,21 +107,59 @@ applyThemeTokens({
 | `--bq-color-warning-600` | `#d97706` |
 
 ### Typography
+
 | Token | Default |
 |-------|---------|
 | `--bq-font-family-sans` | `'Inter', system-ui, ...` |
+| `--bq-font-family-mono` | `'JetBrains Mono', ...` |
 | `--bq-font-size-md` | `1rem` |
 | `--bq-font-weight-semibold` | `600` |
+| `--bq-line-height-normal` | `1.5` |
+| `--bq-letter-spacing-wide` | `0.04em` |
+
+### Spacing & radius
 
-### Spacing & Radius
 | Token | Default |
 |-------|---------|
 | `--bq-space-4` | `1rem` |
 | `--bq-radius-lg` | `0.5rem` |
 | `--bq-radius-full` | `9999px` |
 
+### Control metrics
+
+One height scale for everything that sits on a form row, so a button, an input
+and a select line up on the same baseline.
+
+| Token | Default |
+|-------|---------|
+| `--bq-control-height-sm` | `2rem` |
+| `--bq-control-height-md` | `2.5rem` |
+| `--bq-control-height-lg` | `3rem` |
+| `--bq-control-padding-md` | `0.875rem` |
+| `--bq-border-width-control` | `1.5px` |
+
+### Elevation
+
+| Token | Used for |
+|-------|----------|
+| `--bq-shadow-xs` | Buttons at rest |
+| `--bq-shadow-sm` | Cards |
+| `--bq-shadow-md` | Raised panels |
+| `--bq-shadow-lg` | Menus, popovers, toasts |
+| `--bq-shadow-xl` | Dialogs, drawers |
+
+The dark theme replaces these with much stronger values: a shadow tuned for
+white paper is invisible on a dark surface.
+
 ### Motion
+
 | Token | Default |
 |-------|---------|
+| `--bq-duration-instant` | `75ms` |
 | `--bq-duration-fast` | `150ms` |
+| `--bq-duration-normal` | `200ms` |
 | `--bq-easing-standard` | `cubic-bezier(0.4, 0, 0.2, 1)` |
+| `--bq-easing-emphasized` | `cubic-bezier(0.2, 0, 0, 1)` |
+
+Every component honours `prefers-reduced-motion: reduce` by collapsing
+durations, so you do not have to opt out per component.
diff --git a/src/components/accordion/BqAccordion.ts b/src/components/accordion/BqAccordion.ts
index 2c6c9c2..5d1933a 100644
--- a/src/components/accordion/BqAccordion.ts
+++ b/src/components/accordion/BqAccordion.ts
@@ -14,7 +14,8 @@ import { escapeHtml } from '@bquery/bquery/security';
 import type { Disposer } from '../../utils/component.js';
 import { bind, release } from '../../utils/component.js';
 import { getAnimationTimeoutMs, uniqueId } from '../../utils/dom.js';
-import { baseStyles } from '../../utils/styles.js';
+import { iconCss } from '../../utils/icons.js';
+import { baseStyles, focusRing, reset } from '../../utils/styles.js';
 
 type BqAccordionProps = {
   label: string;
@@ -38,7 +39,9 @@ const definition: ComponentDefinition<BqAccordionProps, BqAccordionState> = {
   },
   styles: css`
     ${baseStyles}
-    *, *::before, *::after { box-sizing: border-box; }
+    ${reset}
+    ${focusRing}
+    ${iconCss('chevron-down')}
     :host { display: block; }
     :host([variant="bordered"]) .accordion { border: 1.5px solid var(--bq-border-base,#e2e8f0); border-radius: var(--bq-radius-lg); }
     :host([variant="flush"]) .accordion { border-bottom: 1px solid var(--bq-border-base,#e2e8f0); }
@@ -48,13 +51,13 @@ const definition: ComponentDefinition<BqAccordionProps, BqAccordionState> = {
       width: 100%; padding: var(--bq-space-4,1rem); background: none; border: none;
       cursor: pointer; color: var(--bq-text-base,#0f172a);
       font-size: var(--bq-font-size-md,1rem); font-weight: var(--bq-font-weight-semibold,600);
-      font-family: inherit; text-align: left;
+      font-family: inherit; text-align: start;
       transition: background var(--bq-duration-fast) var(--bq-easing-standard);
     }
     .trigger:hover:not([disabled]) { background: var(--bq-bg-subtle,#f8fafc); }
     .trigger[disabled] { opacity: 0.5; cursor: not-allowed; }
-    .trigger:focus-visible { outline: 2px solid transparent; box-shadow: var(--bq-focus-ring); }
-    .icon { flex-shrink: 0; font-size: 1rem; color: var(--bq-text-muted,#475569); transition: transform var(--bq-duration-fast) var(--bq-easing-standard); }
+    .trigger:focus-visible { outline: 2px solid transparent; box-shadow: var(--bq-focus-ring); border-radius: var(--bq-radius-md,0.375rem); }
+    .icon { color: var(--bq-text-muted,#475569); --bq-icon-size: 1.25rem; transition: transform var(--bq-duration-normal) var(--bq-easing-standard); }
     :host([open]:not([data-closing])) .icon { transform: rotate(180deg); }
     .panel { display: grid; grid-template-rows: 0fr; overflow: hidden; }
     .panel-inner { overflow: hidden; min-height: 0; padding: 0 var(--bq-space-4,1rem) var(--bq-space-4,1rem); color: var(--bq-text-muted,#475569); font-size: var(--bq-font-size-sm,0.875rem); line-height: var(--bq-line-height-relaxed,1.625); }
@@ -64,8 +67,6 @@ const definition: ComponentDefinition<BqAccordionProps, BqAccordionState> = {
     @keyframes panel-close { from { grid-template-rows: 1fr; } to { grid-template-rows: 0fr; } }
     @media (prefers-reduced-motion: reduce) {
       .panel { animation: none !important; }
-      .icon { transition: none; }
-      .trigger { transition: none; }
     }
   `,
   connected() {
@@ -212,7 +213,7 @@ const definition: ComponentDefinition<BqAccordionProps, BqAccordionState> = {
           ${props.disabled ? 'aria-disabled="true"' : ''}
         >
           <span part="label">${escapeHtml(props.label)}</span>
-          <span class="icon" aria-hidden="true">&#9662;</span>
+          <span class="icon" data-icon="chevron-down" part="icon" aria-hidden="true"></span>
         </button>
         <div
           part="panel"
diff --git a/src/components/alert/BqAlert.ts b/src/components/alert/BqAlert.ts
index 0cb75e4..879d066 100644
--- a/src/components/alert/BqAlert.ts
+++ b/src/components/alert/BqAlert.ts
@@ -11,45 +11,86 @@ import { component, css, html } from '@bquery/bquery/component';
 import type { ComponentDefinition } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { bind, host, release } from '../../utils/component.js';
-import { baseStyles } from '../../utils/styles.js';
+import { iconCss, isIconName, type IconName } from '../../utils/icons.js';
+import { baseStyles, focusRing, reset } from '../../utils/styles.js';
 import { t } from '../../i18n/index.js';
 
 type BqAlertProps = { variant: string; title: string; dismissible: boolean };
 
+/** Status glyph per variant. Falls back to `info` for an unknown variant. */
+const VARIANT_ICON: Record<string, IconName> = {
+  info: 'info',
+  success: 'check-circle',
+  warning: 'alert-triangle',
+  danger: 'alert-circle',
+};
+
 const definition: ComponentDefinition<BqAlertProps> = {
   props: {
-    variant:    { type: String, default: 'info' },
-    title:      { type: String, default: '' },
-    dismissible:{ type: Boolean, default: false },
+    variant: { type: String, default: 'info' },
+    title: { type: String, default: '' },
+    dismissible: { type: Boolean, default: false },
   },
   styles: css`
     ${baseStyles}
-    *, *::before, *::after { box-sizing: border-box; }
+    ${reset}
+    ${focusRing}
+    ${iconCss('info', 'check-circle', 'alert-triangle', 'alert-circle', 'x')}
     :host { display: block; }
-    :host([hidden]) { display: none; }
     .alert {
       display: flex; align-items: flex-start; gap: 0.75rem;
-      padding: var(--bq-space-4,1rem); border-radius: var(--bq-radius-lg,0.5rem);
-      border: 1.5px solid transparent; font-family: var(--bq-font-family-sans);
+      padding: var(--bq-space-4,1rem);
+      border-radius: var(--bq-radius-lg,0.5rem);
+      border: 1px solid transparent;
+      font-family: var(--bq-font-family-sans);
+      /* A tinted panel plus a single saturated edge on the leading side reads
+         as a status band without the heavy full outline it used to have. */
+      border-inline-start-width: 3px;
+    }
+    .alert[data-variant="info"]    { background: var(--bq-color-info-50,#eff6ff);    border-color: var(--bq-color-info-200,#bfdbfe);    border-inline-start-color: var(--bq-color-info-500,#3b82f6);    color: var(--bq-color-info-800,#1e40af); }
+    .alert[data-variant="success"] { background: var(--bq-color-success-50,#f0fdf4); border-color: var(--bq-color-success-200,#bbf7d0); border-inline-start-color: var(--bq-color-success-500,#22c55e); color: var(--bq-color-success-800,#166534); }
+    .alert[data-variant="warning"] { background: var(--bq-color-warning-50,#fffbeb); border-color: var(--bq-color-warning-200,#fde68a); border-inline-start-color: var(--bq-color-warning-500,#f59e0b); color: var(--bq-color-warning-800,#92400e); }
+    .alert[data-variant="danger"]  { background: var(--bq-color-danger-50,#fef2f2);  border-color: var(--bq-color-danger-200,#fecaca);  border-inline-start-color: var(--bq-color-danger-500,#ef4444);  color: var(--bq-color-danger-800,#991b1b); }
+
+    /* Dark mode cannot use the 50-step tints — they are near-white. A
+       translucent wash of the accent over the page keeps the same hue
+       relationship at the right lightness. */
+    :host([data-theme="dark"]) .alert[data-variant="info"],
+    :host([data-theme="dark"]) .alert[data-variant="success"],
+    :host([data-theme="dark"]) .alert[data-variant="warning"],
+    :host([data-theme="dark"]) .alert[data-variant="danger"] { background: var(--bq-bg-subtle,#1e293b); }
+    :host([data-theme="dark"]) .alert[data-variant="info"]    { border-color: var(--bq-color-info-800,#1e40af);    color: var(--bq-color-info-200,#bfdbfe); }
+    :host([data-theme="dark"]) .alert[data-variant="success"] { border-color: var(--bq-color-success-800,#166534); color: var(--bq-color-success-200,#bbf7d0); }
+    :host([data-theme="dark"]) .alert[data-variant="warning"] { border-color: var(--bq-color-warning-800,#92400e); color: var(--bq-color-warning-200,#fde68a); }
+    :host([data-theme="dark"]) .alert[data-variant="danger"]  { border-color: var(--bq-color-danger-800,#991b1b);  color: var(--bq-color-danger-200,#fecaca); }
+
+    .status-icon { --bq-icon-size: 1.25rem; margin-block-start: 0.0625rem; }
+    .content { flex: 1; min-inline-size: 0; }
+    .alert-title {
+      font-weight: var(--bq-font-weight-semibold,600);
+      font-size: var(--bq-font-size-sm,0.875rem);
+      margin-block-end: 0.25rem;
+    }
+    .body { font-size: var(--bq-font-size-sm,0.875rem); line-height: var(--bq-line-height-normal,1.5); }
+    .close {
+      flex: none; display: inline-flex; align-items: center; justify-content: center;
+      inline-size: 1.5rem; block-size: 1.5rem;
+      background: none; border: none; cursor: pointer; color: inherit;
+      border-radius: var(--bq-radius-md,0.375rem); opacity: 0.65;
+      --bq-icon-size: 1rem;
+      transition: opacity var(--bq-duration-fast) var(--bq-easing-standard),
+                  background-color var(--bq-duration-fast) var(--bq-easing-standard);
     }
-    .alert[data-variant="info"]    { background: var(--bq-color-info-50,#eff6ff);    border-color: var(--bq-color-info-500,#3b82f6);    color: var(--bq-color-info-700,#1d4ed8); }
-    .alert[data-variant="success"] { background: var(--bq-color-success-50,#f0fdf4); border-color: var(--bq-color-success-500,#22c55e); color: var(--bq-color-success-700,#15803d); }
-    .alert[data-variant="warning"] { background: var(--bq-color-warning-50,#fffbeb); border-color: var(--bq-color-warning-500,#f59e0b); color: var(--bq-color-warning-700,#b45309); }
-    .alert[data-variant="danger"]  { background: var(--bq-color-danger-50,#fef2f2);  border-color: var(--bq-color-danger-500,#ef4444);  color: var(--bq-color-danger-700,#b91c1c); }
-    .icon { font-size: 1.1em; flex-shrink: 0; margin-top: 0.1em; }
-    .content { flex: 1; min-width: 0; }
-    .alert-title { font-weight: var(--bq-font-weight-semibold,600); font-size: var(--bq-font-size-sm,0.875rem); margin-bottom: 0.25rem; }
-    .body { font-size: var(--bq-font-size-sm,0.875rem); }
-    .close { flex-shrink: 0; display: inline-flex; align-items: center; justify-content: center; background: none; border: none; cursor: pointer; color: inherit; padding: 0.25rem; border-radius: var(--bq-radius-md,0.375rem); opacity: 0.7; font-size: 0.875rem; }
-    .close:hover { opacity: 1; background: rgba(0,0,0,0.08); }
-    .close:focus-visible { outline: 2px solid transparent; box-shadow: var(--bq-focus-ring); }
+    .close:hover { opacity: 1; background: var(--bq-bg-hover,rgba(15,23,42,0.06)); }
   `,
   connected() {
     const self = host(this);
     bind(self).on(self.shadowRoot, 'click', (e) => {
       if ((e.target as Element).closest('.close')) {
         self.setAttribute('hidden', '');
-        self.dispatchEvent(new CustomEvent('bq-close', { bubbles: true, composed: true }));
+        self.dispatchEvent(
+          new CustomEvent('bq-close', { bubbles: true, composed: true })
+        );
       }
     });
   },
@@ -57,18 +98,18 @@ const definition: ComponentDefinition<BqAlertProps> = {
     release(this);
   },
   render({ props }) {
-    const icons: Record<string, string> = { info: 'ℹ', success: '✓', warning: '⚠', danger: '✕' };
-    const icon = icons[props.variant] ?? 'ℹ';
+    const name = VARIANT_ICON[props.variant];
+    const icon = name && isIconName(name) ? name : 'info';
     const isAlert = props.variant === 'warning' || props.variant === 'danger';
     return html`
       <div part="alert" class="alert" data-variant="${escapeHtml(props.variant)}"
         role="${isAlert ? 'alert' : 'status'}" aria-live="${isAlert ? 'assertive' : 'polite'}">
-        <span class="icon" aria-hidden="true">${icon}</span>
+        <span class="icon status-icon" part="icon" data-icon="${icon}" aria-hidden="true"></span>
         <div class="content">
-          ${props.title ? `<div class="alert-title">${escapeHtml(props.title)}</div>` : ''}
-          <div class="body"><slot></slot></div>
+          ${props.title ? `<div class="alert-title" part="title">${escapeHtml(props.title)}</div>` : ''}
+          <div class="body" part="body"><slot></slot></div>
         </div>
-        ${props.dismissible ? `<button type="button" class="close" aria-label="${t('common.close')}">✕</button>` : ''}
+        ${props.dismissible ? `<button type="button" class="close" part="close" aria-label="${escapeHtml(t('common.close'))}"><span class="icon" data-icon="x" aria-hidden="true"></span></button>` : ''}
       </div>
     `;
   },
diff --git a/src/components/avatar-group/BqAvatarGroup.ts b/src/components/avatar-group/BqAvatarGroup.ts
index 2663534..924b74d 100644
--- a/src/components/avatar-group/BqAvatarGroup.ts
+++ b/src/components/avatar-group/BqAvatarGroup.ts
@@ -72,9 +72,9 @@ const definition: ComponentDefinition<BqAvatarGroupProps> = {
     ${reset}
     :host { display: inline-flex; }
     .group { display: inline-flex; align-items: center; }
-    .group[data-spacing="tight"]  ::slotted(*:not(:first-child)) { margin-left: -0.75rem; }
-    .group[data-spacing="normal"] ::slotted(*:not(:first-child)) { margin-left: -0.5rem; }
-    .group[data-spacing="loose"]  ::slotted(*:not(:first-child)) { margin-left: -0.25rem; }
+    .group[data-spacing="tight"]  ::slotted(*:not(:first-child)) { margin-inline-start: -0.75rem; }
+    .group[data-spacing="normal"] ::slotted(*:not(:first-child)) { margin-inline-start: -0.5rem; }
+    .group[data-spacing="loose"]  ::slotted(*:not(:first-child)) { margin-inline-start: -0.25rem; }
     ::slotted(*) {
       border-radius: var(--bq-radius-full,9999px);
       box-shadow: 0 0 0 2px var(--bq-bg-base,#fff);
@@ -91,9 +91,9 @@ const definition: ComponentDefinition<BqAvatarGroupProps> = {
       box-shadow: 0 0 0 2px var(--bq-bg-base,#fff);
     }
     .overflow[hidden] { display: none; }
-    .group[data-spacing="tight"]  .overflow { margin-left: -0.75rem; }
-    .group[data-spacing="normal"] .overflow { margin-left: -0.5rem; }
-    .group[data-spacing="loose"]  .overflow { margin-left: -0.25rem; }
+    .group[data-spacing="tight"]  .overflow { margin-inline-start: -0.75rem; }
+    .group[data-spacing="normal"] .overflow { margin-inline-start: -0.5rem; }
+    .group[data-spacing="loose"]  .overflow { margin-inline-start: -0.25rem; }
     .overflow[data-size="xs"] { width: 1.5rem;  height: 1.5rem;  font-size: 0.625rem; }
     .overflow[data-size="sm"] { width: 2rem;    height: 2rem;    font-size: 0.6875rem; }
     .overflow[data-size="md"] { width: 2.5rem;  height: 2.5rem;  font-size: 0.75rem; }
diff --git a/src/components/avatar/BqAvatar.ts b/src/components/avatar/BqAvatar.ts
index e69d9ea..09dce4f 100644
--- a/src/components/avatar/BqAvatar.ts
+++ b/src/components/avatar/BqAvatar.ts
@@ -11,7 +11,7 @@
 import type { ComponentDefinition } from '@bquery/bquery/component';
 import { component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
-import { baseStyles } from '../../utils/styles.js';
+import { baseStyles, reset } from '../../utils/styles.js';
 
 type BqAvatarProps = {
   src: string;
@@ -79,6 +79,7 @@ const definition: ComponentDefinition<BqAvatarProps> = {
   },
   styles: css`
     ${baseStyles}
+    ${reset}
     :host { display: inline-block; position: relative; }
     .avatar {
       overflow: hidden; display: flex; align-items: center; justify-content: center;
diff --git a/src/components/badge/BqBadge.ts b/src/components/badge/BqBadge.ts
index a4de6ca..f87df2a 100644
--- a/src/components/badge/BqBadge.ts
+++ b/src/components/badge/BqBadge.ts
@@ -9,7 +9,7 @@
 import { component, css, html } from '@bquery/bquery/component';
 import type { ComponentDefinition } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
-import { baseStyles } from '../../utils/styles.js';
+import { baseStyles, reset } from '../../utils/styles.js';
 
 type BqBadgeProps = { variant: string; size: string; pill: boolean };
 
@@ -21,6 +21,7 @@ const definition: ComponentDefinition<BqBadgeProps> = {
   },
   styles: css`
     ${baseStyles}
+    ${reset}
     :host { display: inline-flex; }
     .badge {
       display: inline-flex; align-items: center; gap: 0.25rem;
diff --git a/src/components/banner/BqBanner.ts b/src/components/banner/BqBanner.ts
index df9df60..22eb677 100644
--- a/src/components/banner/BqBanner.ts
+++ b/src/components/banner/BqBanner.ts
@@ -15,7 +15,8 @@ import type { ComponentDefinition } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { t } from '../../i18n/index.js';
 import { bind, host, release } from '../../utils/component.js';
-import { baseStyles, reset, srOnly } from '../../utils/styles.js';
+import { iconCss } from '../../utils/icons.js';
+import { baseStyles, focusRing, reset, srOnly } from '../../utils/styles.js';
 
 type BqBannerProps = {
   variant: string;
@@ -40,6 +41,8 @@ const definition: ComponentDefinition<BqBannerProps> = {
   },
   styles: css`
     ${baseStyles}
+    ${focusRing}
+    ${iconCss('x')}
     ${reset}
     ${srOnly}
     :host { display: block; }
@@ -54,7 +57,7 @@ const definition: ComponentDefinition<BqBannerProps> = {
     }
     .content { flex: 1 1 auto; min-width: 0; }
     .actions { display: flex; align-items: center; gap: 0.5rem; flex: 0 0 auto; }
-    .icon { display: inline-flex; flex: 0 0 auto; }
+    .banner-icon { display: inline-flex; flex: 0 0 auto; }
     .dismiss {
       display: inline-flex; align-items: center; justify-content: center;
       width: 1.75rem; height: 1.75rem; flex: 0 0 auto;
@@ -63,7 +66,8 @@ const definition: ComponentDefinition<BqBannerProps> = {
       font-size: 1rem; line-height: 1;
       transition: background-color var(--bq-duration-fast) var(--bq-easing-standard);
     }
-    .dismiss:hover { background: rgba(0,0,0,0.08); }
+    .dismiss:hover { background: var(--bq-bg-hover,rgba(15,23,42,0.08)); }
+    .dismiss { --bq-icon-size: 1rem; }
     .dismiss:focus-visible { outline: 2px solid transparent; box-shadow: var(--bq-focus-ring); }
     .banner[data-variant="info"]    { background: var(--bq-color-info-100,#dbeafe);    color: var(--bq-color-info-700,#1d4ed8);    border-bottom-color: var(--bq-color-info-200,#bfdbfe); }
     .banner[data-variant="success"] { background: var(--bq-color-success-100,#dcfce7); color: var(--bq-color-success-700,#15803d); border-bottom-color: var(--bq-color-success-200,#bbf7d0); }
@@ -107,12 +111,12 @@ const definition: ComponentDefinition<BqBannerProps> = {
         aria-live="${live}"
         ${label ? `aria-label="${escapeHtml(label)}"` : ''}
       >
-        <span class="icon" part="icon"><slot name="icon"></slot></span>
+        <span class="banner-icon" part="icon"><slot name="icon"></slot></span>
         <div class="content" part="content"><slot></slot></div>
         <div class="actions" part="actions"><slot name="actions"></slot></div>
         ${
           props.dismissible
-            ? `<button type="button" part="dismiss" class="dismiss" aria-label="${escapeHtml(dismissLabel)}">&times;</button>`
+            ? `<button type="button" part="dismiss" class="dismiss" aria-label="${escapeHtml(dismissLabel)}"><span class="icon" data-icon="x" aria-hidden="true"></span></button>`
             : ''
         }
       </div>
diff --git a/src/components/breadcrumbs/BqBreadcrumbs.ts b/src/components/breadcrumbs/BqBreadcrumbs.ts
index 4698ad7..0be2e32 100644
--- a/src/components/breadcrumbs/BqBreadcrumbs.ts
+++ b/src/components/breadcrumbs/BqBreadcrumbs.ts
@@ -10,7 +10,7 @@ import type { ComponentDefinition } from '@bquery/bquery/component';
 import { component, css, html } from '@bquery/bquery/component';
 import { t } from '../../i18n/index.js';
 import { bind, host, release, store } from '../../utils/component.js';
-import { baseStyles } from '../../utils/styles.js';
+import { baseStyles, reset } from '../../utils/styles.js';
 
 type BqBreadcrumbsProps = { separator: string };
 
@@ -34,19 +34,19 @@ const definition: ComponentDefinition<BqBreadcrumbsProps> = {
   },
   styles: css`
     ${baseStyles}
-    *, *::before, *::after { box-sizing: border-box; }
+    ${reset}
     :host { display: block; }
     .breadcrumbs { display: flex; align-items: center; flex-wrap: wrap; list-style: none; margin: 0; padding: 0; font-family: var(--bq-font-family-sans); font-size: var(--bq-font-size-sm,0.875rem); gap: 0; }
     ::slotted(*) { display: inline-flex; align-items: center; }
     ::slotted(*:not(:first-child))::before {
       content: var(--bq-breadcrumb-separator, "/");
       color: var(--bq-text-subtle,#94a3b8);
-      margin: 0 var(--bq-space-2,0.5rem);
+      margin-inline: var(--bq-space-2,0.5rem);
       user-select: none;
       pointer-events: none;
       speak: never;
     }
-    ::slotted(a) { color: var(--bq-text-muted,#475569); text-decoration: none; transition: color var(--bq-duration-fast); }
+    ::slotted(a) { color: var(--bq-text-muted,#475569); text-decoration: none; border-radius: var(--bq-radius-sm,0.25rem); transition: color var(--bq-duration-fast); }
     ::slotted(a:hover) { color: var(--bq-color-primary-600,#2563eb); text-decoration: underline; }
     ::slotted([aria-current="page"]) { color: var(--bq-text-base,#0f172a); font-weight: var(--bq-font-weight-medium,500); pointer-events: none; }
     @media (prefers-reduced-motion: reduce) {
diff --git a/src/components/button-group/BqButtonGroup.ts b/src/components/button-group/BqButtonGroup.ts
index aaffb9c..718c093 100644
--- a/src/components/button-group/BqButtonGroup.ts
+++ b/src/components/button-group/BqButtonGroup.ts
@@ -50,7 +50,7 @@ const definition: ComponentDefinition<BqButtonGroupProps> = {
     :host([attached]) .group[data-orientation="vertical"] ::slotted(*:last-child) {
       --bq-radius-lg: 0 0 0.5rem 0.5rem; --bq-radius-md: 0 0 0.375rem 0.375rem;
     }
-    :host([attached]) .group[data-orientation="horizontal"] ::slotted(*:not(:first-child)) { margin-left: -1.5px; }
+    :host([attached]) .group[data-orientation="horizontal"] ::slotted(*:not(:first-child)) { margin-inline-start: -1.5px; }
     :host([attached]) .group[data-orientation="vertical"] ::slotted(*:not(:first-child)) { margin-top: -1.5px; }
     /* Keep the focused button's ring above its neighbours' borders. */
     ::slotted(*:focus-within) { position: relative; z-index: 1; }
diff --git a/src/components/button/BqButton.ts b/src/components/button/BqButton.ts
index bb24cf5..c268ac1 100644
--- a/src/components/button/BqButton.ts
+++ b/src/components/button/BqButton.ts
@@ -3,6 +3,8 @@
  * @element bq-button
  * @prop {string}  variant  - primary | secondary | outline | ghost | danger
  * @prop {string}  size     - sm | md | lg | xl
+ * @prop {boolean} full-width - Stretch to the width of the container
+ * @prop {boolean} pill     - Fully rounded ends
  * @prop {boolean} disabled
  * @prop {boolean} loading
  * @prop {string}  type     - button | submit | reset
@@ -20,11 +22,13 @@ import { escapeHtml } from '@bquery/bquery/security';
 import { t } from '../../i18n/index.js';
 import { uniqueId } from '../../utils/dom.js';
 import { bind, host, release } from '../../utils/component.js';
-import { baseStyles } from '../../utils/styles.js';
+import { baseStyles, reset, srOnly } from '../../utils/styles.js';
 
 type BqButtonProps = {
   variant: string;
   size: string;
+  'full-width': boolean;
+  pill: boolean;
   disabled: boolean;
   loading: boolean;
   type: string;
@@ -38,6 +42,8 @@ const definition: ComponentDefinition<BqButtonProps, BqButtonState> = {
   props: {
     variant: { type: String, default: 'primary' },
     size:    { type: String, default: 'md' },
+    'full-width': { type: Boolean, default: false },
+    pill:    { type: Boolean, default: false },
     disabled:{ type: Boolean, default: false },
     loading: { type: Boolean, default: false },
     type:    { type: String, default: 'button' },
@@ -50,13 +56,16 @@ const definition: ComponentDefinition<BqButtonProps, BqButtonState> = {
   },
   styles: css`
     ${baseStyles}
-    *, *::before, *::after { box-sizing: border-box; }
+    ${reset}
+    ${srOnly}
     :host { display: inline-block; }
-    :host([hidden]) { display: none; }
+    :host([full-width]) { display: block; }
 
     .btn {
       display: inline-flex; align-items: center; justify-content: center;
-      gap: 0.5rem; border: 1.5px solid transparent;
+      gap: 0.5rem;
+      inline-size: 100%;
+      border: var(--bq-border-width-control, 1.5px) solid transparent;
       border-radius: var(--bq-radius-lg, 0.5rem);
       font-family: var(--bq-font-family-sans);
       font-weight: var(--bq-font-weight-semibold, 600);
@@ -64,36 +73,63 @@ const definition: ComponentDefinition<BqButtonProps, BqButtonState> = {
       transition: background-color var(--bq-duration-fast) var(--bq-easing-standard),
                   border-color var(--bq-duration-fast) var(--bq-easing-standard),
                   box-shadow var(--bq-duration-fast) var(--bq-easing-standard),
+                  transform var(--bq-duration-instant) var(--bq-easing-standard),
                   opacity var(--bq-duration-fast) var(--bq-easing-standard);
       white-space: nowrap; user-select: none; -webkit-user-select: none;
-      position: relative; overflow: hidden;
+      -webkit-tap-highlight-color: transparent;
+      position: relative;
     }
-    /* Sizes */
-    .btn[data-size="sm"] { font-size: 0.875rem; padding: 0.375rem 0.75rem; min-height: 2rem; }
-    .btn[data-size="md"] { font-size: 1rem; padding: 0.5rem 1rem; min-height: 2.5rem; }
-    .btn[data-size="lg"] { font-size: 1.125rem; padding: 0.625rem 1.25rem; min-height: 3rem; }
-    .btn[data-size="xl"] { font-size: 1.25rem; padding: 0.75rem 1.5rem; min-height: 3.5rem; }
+    /* Sizes track the shared control scale, so a button and an input placed
+       side by side share a baseline. */
+    .btn[data-size="sm"] { font-size: var(--bq-font-size-sm, 0.875rem); padding-inline: var(--bq-control-padding-sm, 0.75rem); min-block-size: var(--bq-control-height-sm, 2rem); }
+    .btn[data-size="md"] { font-size: var(--bq-font-size-md, 1rem); padding-inline: var(--bq-control-padding-lg, 1rem); min-block-size: var(--bq-control-height-md, 2.5rem); }
+    .btn[data-size="lg"] { font-size: var(--bq-font-size-lg, 1.125rem); padding-inline: 1.25rem; min-block-size: var(--bq-control-height-lg, 3rem); }
+    .btn[data-size="xl"] { font-size: var(--bq-font-size-xl, 1.25rem); padding-inline: 1.5rem; min-block-size: var(--bq-control-height-xl, 3.5rem); }
+    :host([pill]) .btn { border-radius: var(--bq-radius-full, 9999px); }
+
     /* Variants */
-    .btn[data-variant="primary"] { background-color: var(--bq-color-primary-600,#2563eb); color: #fff; border-color: var(--bq-color-primary-600,#2563eb); }
+    .btn[data-variant="primary"] {
+      background-color: var(--bq-color-primary-600,#2563eb);
+      color: var(--bq-text-on-primary,#fff);
+      border-color: var(--bq-color-primary-600,#2563eb);
+      box-shadow: var(--bq-shadow-xs);
+    }
     .btn[data-variant="primary"]:hover:not(:disabled):not([aria-disabled="true"]) { background-color: var(--bq-color-primary-700,#1d4ed8); border-color: var(--bq-color-primary-700,#1d4ed8); }
-    .btn[data-variant="secondary"] { background-color: var(--bq-color-secondary-100,#f1f5f9); color: var(--bq-color-secondary-700,#334155); border-color: var(--bq-color-secondary-200,#e2e8f0); }
-    .btn[data-variant="secondary"]:hover:not(:disabled):not([aria-disabled="true"]) { background-color: var(--bq-color-secondary-200,#e2e8f0); }
+    .btn[data-variant="secondary"] { background-color: var(--bq-bg-muted,#f1f5f9); color: var(--bq-text-base,#0f172a); border-color: var(--bq-border-base,#e2e8f0); }
+    .btn[data-variant="secondary"]:hover:not(:disabled):not([aria-disabled="true"]) { background-color: var(--bq-bg-emphasis,#e2e8f0); border-color: var(--bq-border-emphasis,#cbd5e1); }
     .btn[data-variant="outline"] { background-color: transparent; color: var(--bq-color-primary-600,#2563eb); border-color: var(--bq-color-primary-600,#2563eb); }
     .btn[data-variant="outline"]:hover:not(:disabled):not([aria-disabled="true"]) { background-color: var(--bq-color-primary-50,#eff6ff); }
-    .btn[data-variant="ghost"] { background-color: transparent; color: var(--bq-color-secondary-700,#334155); border-color: transparent; }
-    .btn[data-variant="ghost"]:hover:not(:disabled):not([aria-disabled="true"]) { background-color: var(--bq-color-secondary-100,#f1f5f9); }
-    .btn[data-variant="danger"] { background-color: var(--bq-color-danger-600,#dc2626); color: #fff; border-color: var(--bq-color-danger-600,#dc2626); }
-    .btn[data-variant="danger"]:hover:not(:disabled):not([aria-disabled="true"]) { background-color: var(--bq-color-danger-700,#b91c1c); }
-    /* States */
-    .btn:focus-visible { outline: 2px solid transparent; box-shadow: var(--bq-focus-ring); }
+    .btn[data-variant="ghost"] { background-color: transparent; color: var(--bq-text-base,#0f172a); border-color: transparent; }
+    .btn[data-variant="ghost"]:hover:not(:disabled):not([aria-disabled="true"]) { background-color: var(--bq-bg-hover,rgba(15,23,42,0.06)); }
+    .btn[data-variant="danger"] {
+      background-color: var(--bq-color-danger-600,#dc2626);
+      color: var(--bq-text-on-danger,#fff);
+      border-color: var(--bq-color-danger-600,#dc2626);
+      box-shadow: var(--bq-shadow-xs);
+    }
+    .btn[data-variant="danger"]:hover:not(:disabled):not([aria-disabled="true"]) { background-color: var(--bq-color-danger-700,#b91c1c); border-color: var(--bq-color-danger-700,#b91c1c); }
+
+    /* States. The 1px nudge is what makes a click feel like a press; without
+       it a button that triggers async work reads as unresponsive. */
+    .btn:active:not(:disabled):not([aria-disabled="true"]) { transform: translateY(1px); }
+    .btn:focus-visible { outline: 2px solid transparent; outline-offset: 2px; box-shadow: var(--bq-focus-ring); }
     .btn[data-variant="danger"]:focus-visible { box-shadow: var(--bq-focus-ring-danger); }
-    .btn:disabled, .btn[aria-disabled="true"] { opacity: 0.5; cursor: not-allowed; }
-    /* Loading spinner */
-    .spinner { width: 1em; height: 1em; border: 2px solid currentColor; border-top-color: transparent; border-radius: 50%; animation: spin 0.7s linear infinite; }
-    .sr-only { position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0,0,0,0); white-space: nowrap; border: 0; }
+    .btn:disabled, .btn[aria-disabled="true"] { opacity: 0.55; cursor: not-allowed; box-shadow: none; }
+
+    /* The label is dimmed rather than removed while loading, so the button
+       keeps its width and the row does not reflow mid-request. */
+    :host([loading]) .btn { cursor: progress; }
+    .spinner {
+      inline-size: 1em; block-size: 1em; flex: none;
+      border: 2px solid currentColor; border-block-start-color: transparent;
+      border-radius: var(--bq-radius-full,9999px);
+      animation: spin 0.7s linear infinite;
+    }
     @keyframes spin { to { transform: rotate(360deg); } }
-    @media (prefers-reduced-motion: reduce) {
-      .btn, .spinner { transition: none; animation: none; }
+
+    @media (forced-colors: active) {
+      .btn { border-color: ButtonText; }
+      .btn:focus-visible { outline: 2px solid Highlight; }
     }
   `,
   connected() {
diff --git a/src/components/card/BqCard.ts b/src/components/card/BqCard.ts
index b933629..de9e867 100644
--- a/src/components/card/BqCard.ts
+++ b/src/components/card/BqCard.ts
@@ -11,7 +11,7 @@
 import type { ComponentDefinition } from '@bquery/bquery/component';
 import { component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
-import { baseStyles } from '../../utils/styles.js';
+import { baseStyles, reset } from '../../utils/styles.js';
 
 type BqCardProps = { title: string; elevated: boolean; padding: string };
 
@@ -23,10 +23,10 @@ const definition: ComponentDefinition<BqCardProps> = {
   },
   styles: css`
     ${baseStyles}
-    *, *::before, *::after { box-sizing: border-box; }
+    ${reset}
     :host { display: block; }
     .card {
-      background: var(--bq-bg-base,#fff);
+      background: var(--bq-surface-raised,#fff);
       border-radius: var(--bq-radius-xl,0.75rem);
       border: 1px solid var(--bq-border-base,#e2e8f0);
       overflow: hidden; font-family: var(--bq-font-family-sans);
diff --git a/src/components/checkbox/BqCheckbox.ts b/src/components/checkbox/BqCheckbox.ts
index 046c7e3..4cfc1dc 100644
--- a/src/components/checkbox/BqCheckbox.ts
+++ b/src/components/checkbox/BqCheckbox.ts
@@ -1,5 +1,13 @@
 /**
  * Checkbox form control.
+ *
+ * The native `<input type="checkbox">` is kept — it carries the semantics,
+ * the form behaviour and the keyboard handling — but rendered transparently
+ * on top of a drawn box, because `accent-color` is the only thing a real
+ * checkbox lets you style. Everything else (radius, border weight, the
+ * check mark itself, the focus ring, the indeterminate dash) is the platform's
+ * to decide, and every platform decides differently.
+ *
  * @element bq-checkbox
  * @prop {string}  label         - Visible label
  * @prop {string}  name          - Input name
@@ -16,7 +24,9 @@ import { bool, component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { bindFormProxy, syncFormProxy } from '../../utils/form.js';
 import { bind, host, release } from '../../utils/component.js';
-import { baseStyles } from '../../utils/styles.js';
+import { uniqueId } from '../../utils/dom.js';
+import { iconMask } from '../../utils/icons.js';
+import { baseStyles, fieldStyles, reset } from '../../utils/styles.js';
 
 type BqCheckboxProps = {
   label: string;
@@ -29,7 +39,9 @@ type BqCheckboxProps = {
   hint: string;
 };
 
-const definition: ComponentDefinition<BqCheckboxProps> = {
+type BqCheckboxState = { uid: string };
+
+const definition: ComponentDefinition<BqCheckboxProps, BqCheckboxState> = {
   props: {
     label: { type: String, default: '' },
     name: { type: String, default: '' },
@@ -40,28 +52,107 @@ const definition: ComponentDefinition<BqCheckboxProps> = {
     required: { type: Boolean, default: false },
     hint: { type: String, default: '' },
   },
+  state: { uid: '' },
   styles: css`
     ${baseStyles}
-    *, *::before, *::after { box-sizing: border-box; }
+    ${reset}
+    ${fieldStyles}
     :host { display: block; }
-    .wrapper { display: flex; flex-direction: column; gap: 0.25rem; }
-    .control { display: flex; align-items: flex-start; gap: 0.625rem; cursor: pointer; }
-    :host([disabled]) .control { opacity: 0.5; cursor: not-allowed; pointer-events: none; }
-    input[type="checkbox"] {
-      width: 1.125rem; height: 1.125rem; flex-shrink: 0;
-      border: 2px solid var(--bq-border-emphasis,#cbd5e1);
-      border-radius: var(--bq-radius-sm,0.25rem);
-      background: var(--bq-bg-base,#fff); cursor: pointer;
-      accent-color: var(--bq-color-primary-600,#2563eb);
-      margin-top: 0.125rem;
+    .field { gap: 0.25rem; }
+    .control {
+      display: flex;
+      align-items: flex-start;
+      gap: 0.625rem;
+      cursor: pointer;
+      font-family: var(--bq-font-family-sans);
+    }
+    :host([disabled]) .control { opacity: 0.55; cursor: not-allowed; }
+
+    /* The box and the real input share one grid cell: the input stays on top
+       so pointer and assistive technology still hit the actual control. */
+    .box-wrap {
+      position: relative;
+      display: inline-grid;
+      place-items: center;
+      flex: none;
+      margin-block-start: 0.125rem;
+    }
+    input {
+      position: absolute;
+      inset: 0;
+      inline-size: 100%;
+      block-size: 100%;
+      margin: 0;
+      opacity: 0;
+      cursor: inherit;
+    }
+    .box {
+      inline-size: 1.125rem;
+      block-size: 1.125rem;
+      display: grid;
+      place-items: center;
+      border: var(--bq-border-width-control, 1.5px) solid var(--bq-border-strong, #94a3b8);
+      border-radius: var(--bq-radius-sm, 0.25rem);
+      background: var(--bq-bg-base, #fff);
+      transition:
+        background-color var(--bq-duration-fast) var(--bq-easing-standard),
+        border-color var(--bq-duration-fast) var(--bq-easing-standard),
+        box-shadow var(--bq-duration-fast) var(--bq-easing-standard);
+    }
+    .box::after {
+      content: '';
+      inline-size: 0.875rem;
+      block-size: 0.875rem;
+      background-color: var(--bq-text-on-primary, #fff);
+      -webkit-mask-repeat: no-repeat;
+      mask-repeat: no-repeat;
+      -webkit-mask-position: center;
+      mask-position: center;
+      -webkit-mask-size: contain;
+      mask-size: contain;
+      ${iconMask('check')}
+      transform: scale(0.6);
+      opacity: 0;
+      transition:
+        transform var(--bq-duration-fast) var(--bq-easing-spring),
+        opacity var(--bq-duration-instant) var(--bq-easing-standard);
+    }
+    .control:hover input:not(:disabled) ~ .box { border-color: var(--bq-color-primary-500, #3b82f6); }
+    input:checked ~ .box,
+    input:indeterminate ~ .box {
+      background: var(--bq-color-primary-600, #2563eb);
+      border-color: var(--bq-color-primary-600, #2563eb);
+    }
+    input:checked ~ .box::after,
+    input:indeterminate ~ .box::after { transform: scale(1); opacity: 1; }
+    /* Indeterminate outranks checked: the dash is the state the user sees. */
+    input:indeterminate ~ .box::after { ${iconMask('minus')} }
+    input:focus-visible ~ .box {
+      border-color: var(--bq-border-focus, #2563eb);
+      box-shadow: var(--bq-focus-ring);
+    }
+    input:disabled ~ .box { background: var(--bq-bg-muted, #f1f5f9); }
+    input:checked:disabled ~ .box { background: var(--bq-border-strong, #94a3b8); border-color: var(--bq-border-strong, #94a3b8); }
+
+    .label-text {
+      font-size: var(--bq-font-size-sm, 0.875rem);
+      color: var(--bq-text-base, #0f172a);
+      line-height: var(--bq-line-height-normal, 1.5);
+    }
+    .hint { padding-inline-start: 1.75rem; }
+
+    @media (forced-colors: active) {
+      .box { forced-color-adjust: none; background: Canvas; border-color: CanvasText; }
+      input:checked ~ .box,
+      input:indeterminate ~ .box { background: Highlight; border-color: Highlight; }
+      .box::after { background-color: HighlightText; }
+      input:focus-visible ~ .box { outline: 2px solid CanvasText; outline-offset: 2px; }
     }
-    input[type="checkbox"]:focus-visible { outline: 2px solid transparent; box-shadow: var(--bq-focus-ring); }
-    .label-text { font-size: var(--bq-font-size-sm,0.875rem); color: var(--bq-text-base,#0f172a); font-family: var(--bq-font-family-sans); line-height: 1.5; }
-    .hint { font-size: var(--bq-font-size-sm,0.875rem); color: var(--bq-text-muted,#475569); font-family: var(--bq-font-family-sans); padding-inline-start: 1.75rem; }
   `,
   connected() {
-    const self = host(this);
+    const self = host<BqCheckboxState>(this);
     const scope = bind(self);
+    if (!self.getState<string>('uid')) self.setState('uid', uniqueId('bq-cb'));
 
     // Form proxy for native <form> participation
     const readValue = () =>
@@ -73,6 +164,9 @@ const definition: ComponentDefinition<BqCheckboxProps> = {
       if (input?.type !== 'checkbox') return;
       if (input.checked) self.setAttribute('checked', '');
       else self.removeAttribute('checked');
+      // Any deliberate toggle resolves the mixed state, exactly as a native
+      // tri-state checkbox behaves.
+      self.removeAttribute('indeterminate');
       proxy.setValue(input.checked ? self.getAttribute('value') || 'on' : '');
       self.dispatchEvent(
         new CustomEvent('bq-change', {
@@ -99,29 +193,36 @@ const definition: ComponentDefinition<BqCheckboxProps> = {
     if (input) input.indeterminate = this.hasAttribute('indeterminate');
     syncFormProxy(this);
   },
-  render({ props }) {
+  render({ props, state }) {
+    const uid = state.uid || 'bq-cb';
+    const hintId = `${uid}-hint`;
     return html`
-      <div class="wrapper" part="wrapper">
+      <div class="field" part="wrapper">
         <label class="control" part="control">
-          <input
-            type="checkbox"
-            part="input"
-            name="${escapeHtml(props.name)}"
-            value="${escapeHtml(props.value)}"
-            ${bool('checked', props.checked)}
-            ${bool('disabled', props.disabled)}
-            ${bool('required', props.required)}
-          />
+          <span class="box-wrap">
+            <input
+              type="checkbox"
+              part="input"
+              name="${escapeHtml(props.name)}"
+              value="${escapeHtml(props.value)}"
+              ${bool('checked', props.checked)}
+              ${bool('disabled', props.disabled)}
+              ${bool('required', props.required)}
+              ${props.indeterminate ? 'aria-checked="mixed"' : ''}
+              ${props.hint ? `aria-describedby="${escapeHtml(hintId)}"` : ''}
+            />
+            <span class="box" part="box" aria-hidden="true"></span>
+          </span>
           ${props.label
             ? `<span class="label-text" part="label">${escapeHtml(props.label)}${props.required ? '<span class="required-mark" aria-hidden="true"> *</span>' : ''}</span>`
             : ''}
         </label>
         ${props.hint
-          ? `<span class="hint" part="hint">${escapeHtml(props.hint)}</span>`
+          ? `<span class="hint" id="${escapeHtml(hintId)}" part="hint">${escapeHtml(props.hint)}</span>`
           : ''}
       </div>
     `;
   },
 };
 
-component<BqCheckboxProps>('bq-checkbox', definition);
+component<BqCheckboxProps, BqCheckboxState>('bq-checkbox', definition);
diff --git a/src/components/chip/BqChip.ts b/src/components/chip/BqChip.ts
index b5eb42d..40afa76 100644
--- a/src/components/chip/BqChip.ts
+++ b/src/components/chip/BqChip.ts
@@ -15,7 +15,8 @@ import { component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { t } from '../../i18n/index.js';
 import { bind, host, release } from '../../utils/component.js';
-import { baseStyles } from '../../utils/styles.js';
+import { iconCss } from '../../utils/icons.js';
+import { baseStyles, focusRing, reset } from '../../utils/styles.js';
 
 type BqChipProps = {
   variant: string;
@@ -35,14 +36,18 @@ const definition: ComponentDefinition<BqChipProps> = {
   },
   styles: css`
     ${baseStyles}
-    *, *::before, *::after { box-sizing: border-box; }
+    ${reset}
+    ${focusRing}
+    ${iconCss('x')}
     :host { display: inline-flex; }
     .chip {
       display: inline-flex; align-items: center; gap: 0.375rem;
       border-radius: var(--bq-radius-full,9999px); font-family: var(--bq-font-family-sans);
       font-weight: var(--bq-font-weight-medium,500); white-space: nowrap; cursor: pointer;
       border: 1.5px solid transparent;
-      transition: all var(--bq-duration-fast) var(--bq-easing-standard);
+      transition: color var(--bq-duration-fast) var(--bq-easing-standard),
+                  background-color var(--bq-duration-fast) var(--bq-easing-standard),
+                  border-color var(--bq-duration-fast) var(--bq-easing-standard);
     }
     .chip[data-size="sm"] { font-size: 0.75rem; padding: 0.25rem 0.625rem; }
     .chip[data-size="md"] { font-size: 0.875rem; padding: 0.375rem 0.75rem; }
@@ -58,9 +63,13 @@ const definition: ComponentDefinition<BqChipProps> = {
     .remove-btn {
       display: inline-flex; align-items: center; justify-content: center;
       background: none; border: none; cursor: pointer; color: inherit;
-      padding: 0; width: 1rem; height: 1rem; border-radius: 50%; font-size: 0.75rem; opacity: 0.7;
+      padding: 0; inline-size: 1rem; block-size: 1rem;
+      border-radius: var(--bq-radius-full,9999px); opacity: 0.6;
+      --bq-icon-size: 0.75rem;
+      transition: opacity var(--bq-duration-fast) var(--bq-easing-standard),
+                  background-color var(--bq-duration-fast) var(--bq-easing-standard);
     }
-    .remove-btn:hover { opacity: 1; }
+    .remove-btn:hover { opacity: 1; background: var(--bq-bg-hover,rgba(15,23,42,0.1)); }
     .remove-btn:focus-visible { outline: 2px solid transparent; box-shadow: var(--bq-focus-ring); }
     @media (prefers-reduced-motion: reduce) {
       .chip { transition: none; }
@@ -131,7 +140,7 @@ const definition: ComponentDefinition<BqChipProps> = {
       >
         <slot></slot>
         ${props.removable
-          ? `<button type="button" class="remove-btn" aria-label="${t('chip.remove')}">✕</button>`
+          ? `<button type="button" class="remove-btn" aria-label="${t('chip.remove')}"><span class="icon" data-icon="x" aria-hidden="true"></span></button>`
           : ''}
       </span>
     `;
diff --git a/src/components/combobox/BqCombobox.ts b/src/components/combobox/BqCombobox.ts
index a5d9ef3..85100db 100644
--- a/src/components/combobox/BqCombobox.ts
+++ b/src/components/combobox/BqCombobox.ts
@@ -37,11 +37,15 @@ import { t } from '../../i18n/index.js';
 import { bind, host, release, store } from '../../utils/component.js';
 import type { Disposer } from '../../utils/component.js';
 import { uniqueId } from '../../utils/dom.js';
-import { captureFocus, restoreFocus } from '../../utils/focus.js';
-import type { FocusSnapshot } from '../../utils/focus.js';
+import {
+  markFocus,
+  restorePreservedFocus,
+  trackFocus,
+} from '../../utils/focus.js';
 import { bindFormProxy, syncFormProxy } from '../../utils/form.js';
 import { autoPosition } from '../../utils/position.js';
-import { baseStyles, reset, srOnly } from '../../utils/styles.js';
+import { iconCss, iconMask } from '../../utils/icons.js';
+import { baseStyles, focusRing, reset, srOnly } from '../../utils/styles.js';
 import { bindValidation } from '../../utils/validation.js';
 
 type BqComboboxProps = {
@@ -84,7 +88,6 @@ export interface ComboboxOption {
 
 const comboboxStore = (owner: object) =>
   store<{
-    snapshot?: FocusSnapshot | null;
     syncPosition?: () => void;
     syncOptions?: () => void;
     stopPosition?: Disposer | null;
@@ -201,10 +204,13 @@ const definition: ComponentDefinition<BqComboboxProps, BqComboboxState> = {
     size: { type: String, default: 'md' },
   },
   state: { uid: '', open: false, query: '', activeIndex: -1, options: [] },
+  sanitize: { allowAttributes: ['spellcheck'] },
   styles: css`
     ${baseStyles}
     ${reset}
     ${srOnly}
+    ${focusRing}
+    ${iconCss('x', 'chevron-down')}
     :host { display: block; position: relative; }
     .field { display: flex; flex-direction: column; gap: 0.375rem; }
     .label {
@@ -248,11 +254,15 @@ const definition: ComponentDefinition<BqComboboxProps, BqComboboxState> = {
       font-family: var(--bq-font-family-sans);
     }
     .token button {
+      display: inline-flex; align-items: center; justify-content: center;
       border: none; background: none; cursor: pointer; line-height: 1;
-      color: var(--bq-text-muted,#475569); padding: 0 0.125rem;
-      border-radius: var(--bq-radius-sm,0.25rem);
+      color: var(--bq-text-muted,#475569); padding: 0.125rem;
+      border-radius: var(--bq-radius-full,9999px);
+      --bq-icon-size: 0.75rem;
+      transition: color var(--bq-duration-fast) var(--bq-easing-standard),
+                  background-color var(--bq-duration-fast) var(--bq-easing-standard);
     }
-    .token button:hover { color: var(--bq-color-danger-600,#dc2626); }
+    .token button:hover { color: var(--bq-color-danger-600,#dc2626); background: var(--bq-bg-hover,rgba(15,23,42,0.06)); }
     .token button:focus-visible { outline: 2px solid transparent; box-shadow: var(--bq-focus-ring); }
 
     .actions { display: inline-flex; align-items: center; gap: 0.125rem; margin-inline-start: auto; }
@@ -262,7 +272,10 @@ const definition: ComponentDefinition<BqComboboxProps, BqComboboxState> = {
       color: var(--bq-text-muted,#475569); cursor: pointer; line-height: 1;
       border-radius: var(--bq-radius-sm,0.25rem); font-size: 0.75rem;
     }
+    .action { --bq-icon-size: 1rem; }
     .action:hover { background: var(--bq-bg-muted,#f1f5f9); color: var(--bq-text-base,#0f172a); }
+    :host([data-open]) .toggle .icon { transform: rotate(180deg); }
+    .toggle .icon { transition: transform var(--bq-duration-normal) var(--bq-easing-standard); }
     .action:focus-visible { outline: 2px solid transparent; box-shadow: var(--bq-focus-ring); }
 
     .listbox {
@@ -270,9 +283,9 @@ const definition: ComponentDefinition<BqComboboxProps, BqComboboxState> = {
       inset-inline-start: 0; min-width: 100%;
       max-height: 16rem; overflow-y: auto;
       margin-top: 0.25rem;
-      background: var(--bq-bg-base,#fff);
+      background: var(--bq-surface-overlay,#fff);
       border: 1px solid var(--bq-border-base,#e2e8f0);
-      border-radius: var(--bq-radius-lg,0.5rem);
+      border-radius: var(--bq-radius-xl,0.75rem);
       box-shadow: var(--bq-shadow-lg);
       padding: 0.25rem 0;
       font-family: var(--bq-font-family-sans);
@@ -288,7 +301,15 @@ const definition: ComponentDefinition<BqComboboxProps, BqComboboxState> = {
     }
     .option[data-active="true"] { background: var(--bq-bg-muted,#f1f5f9); }
     .option[aria-selected="true"] { font-weight: var(--bq-font-weight-semibold,600); }
-    .option[aria-selected="true"]::after { content: "✓"; margin-inline-start: auto; color: var(--bq-color-primary-600,#2563eb); }
+    .option[aria-selected="true"]::after {
+      content: ''; margin-inline-start: auto; flex: none;
+      inline-size: 1rem; block-size: 1rem;
+      background-color: var(--bq-color-primary-600,#2563eb);
+      -webkit-mask-repeat: no-repeat; mask-repeat: no-repeat;
+      -webkit-mask-position: center; mask-position: center;
+      -webkit-mask-size: contain; mask-size: contain;
+      ${iconMask('check')}
+    }
     .option[aria-disabled="true"] { opacity: 0.5; cursor: not-allowed; }
 
     .group-label {
@@ -424,6 +445,12 @@ const definition: ComponentDefinition<BqComboboxProps, BqComboboxState> = {
     };
     local.syncPosition = syncPosition;
 
+    // Every handler below writes state, and every state write replaces the
+    // shadow tree — including the field the user is typing in. `trackFocus`
+    // records the caret from the same events in the capture phase, and
+    // `updated()` puts it back.
+    trackFocus(self, scope);
+
     // ── Input ────────────────────────────────────────────────────────────
     scope.on(self.shadowRoot, 'input', (event) => {
       const input = event.target as HTMLInputElement | null;
@@ -594,15 +621,14 @@ const definition: ComponentDefinition<BqComboboxProps, BqComboboxState> = {
     }
   },
   beforeUpdate() {
-    comboboxStore(this).snapshot = captureFocus(this.shadowRoot);
+    markFocus(this);
   },
   disconnected() {
     release(this);
   },
   updated() {
     const local = comboboxStore(this);
-    restoreFocus(this.shadowRoot, local.snapshot);
-    local.snapshot = null;
+    restorePreservedFocus(this);
     local.syncOptions?.();
     local.syncPosition?.();
     syncFormProxy(this);
@@ -643,7 +669,7 @@ const definition: ComponentDefinition<BqComboboxProps, BqComboboxState> = {
                   data-value="${escapeHtml(value)}"
                   tabindex="-1"
                   aria-label="${escapeHtml(t('combobox.removeOption', { label }))}"
-                >&times;</button></span>`;
+                ><span class="icon" data-icon="x" aria-hidden="true"></span></button></span>`;
             })
             .join('')
         : '';
@@ -703,10 +729,10 @@ const definition: ComponentDefinition<BqComboboxProps, BqComboboxState> = {
           <span class="actions">
             ${
               props.clearable && values.length > 0
-                ? `<button type="button" class="action clear" part="clear" tabindex="-1" aria-label="${escapeHtml(t('combobox.clear'))}">&times;</button>`
+                ? `<button type="button" class="action clear" part="clear" tabindex="-1" aria-label="${escapeHtml(t('combobox.clear'))}"><span class="icon" data-icon="x" aria-hidden="true"></span></button>`
                 : ''
             }
-            <button type="button" class="action toggle" part="toggle" tabindex="-1" aria-label="${escapeHtml(t('combobox.toggle'))}">&#9660;</button>
+            <button type="button" class="action toggle" part="toggle" tabindex="-1" aria-label="${escapeHtml(t('combobox.toggle'))}"><span class="icon" data-icon="chevron-down" aria-hidden="true"></span></button>
           </span>
         </div>
         <div
diff --git a/src/components/copy-button/BqCopyButton.ts b/src/components/copy-button/BqCopyButton.ts
new file mode 100644
index 0000000..de0345c
--- /dev/null
+++ b/src/components/copy-button/BqCopyButton.ts
@@ -0,0 +1,212 @@
+/**
+ * Copy-to-clipboard button.
+ *
+ * Copying is only half the job — without feedback the user cannot tell a
+ * successful copy from a dead button, so the icon and the accessible name both
+ * switch to the confirmed state for a moment and then switch back.
+ *
+ * The text can come from the `value` prop or, for the common "copy the code in
+ * that block" case, from `from` — a selector resolved against the containing
+ * document or shadow root.
+ *
+ * @element bq-copy-button
+ * @prop {string}  value     - Text to copy
+ * @prop {string}  from      - Selector whose text content is copied instead
+ * @prop {string}  label     - Accessible name in the idle state
+ * @prop {string}  copied-label - Accessible name after a successful copy
+ * @prop {number}  timeout   - How long the confirmed state lasts, in ms
+ * @prop {boolean} disabled
+ * @prop {string}  variant   - ghost | outline | solid
+ * @prop {string}  size      - sm | md | lg
+ * @fires bq-copy - { value: string, ok: boolean }
+ */
+import type { ComponentDefinition } from '@bquery/bquery/component';
+import { component, css, html } from '@bquery/bquery/component';
+import { escapeHtml } from '@bquery/bquery/security';
+import { t } from '../../i18n/index.js';
+import { bind, host, release, store } from '../../utils/component.js';
+import type { Disposer } from '../../utils/component.js';
+import { iconCss } from '../../utils/icons.js';
+import { baseStyles, focusRing, reset, srOnly } from '../../utils/styles.js';
+
+type BqCopyButtonProps = {
+  value: string;
+  from: string;
+  label: string;
+  'copied-label': string;
+  timeout: number;
+  disabled: boolean;
+  variant: string;
+  size: string;
+};
+
+type BqCopyButtonState = { copied: boolean };
+
+const copyStore = (owner: object) =>
+  store<{ resetTimer?: Disposer | null }>(owner, () => ({}));
+
+/**
+ * Writes text to the clipboard.
+ *
+ * The async Clipboard API needs a secure context, so the deprecated
+ * `execCommand` path stays as a fallback — a copy button on plain HTTP is
+ * still expected to work, and there is no other way to do it.
+ */
+export async function writeClipboard(text: string): Promise<boolean> {
+  if (!text) return false;
+  try {
+    if (typeof navigator !== 'undefined' && navigator.clipboard?.writeText) {
+      await navigator.clipboard.writeText(text);
+      return true;
+    }
+  } catch {
+    /* Blocked or unavailable — try the legacy path below. */
+  }
+
+  if (typeof document === 'undefined') return false;
+  try {
+    const scratch = document.createElement('textarea');
+    scratch.value = text;
+    scratch.setAttribute('readonly', '');
+    // Off-screen rather than hidden: `display: none` makes it unselectable,
+    // and an unselectable node cannot be copied from.
+    scratch.style.cssText = 'position:fixed;top:-9999px;opacity:0;';
+    document.body.appendChild(scratch);
+    scratch.select();
+    const ok = document.execCommand?.('copy') ?? false;
+    scratch.remove();
+    return ok;
+  } catch {
+    return false;
+  }
+}
+
+const definition: ComponentDefinition<BqCopyButtonProps, BqCopyButtonState> = {
+  props: {
+    value: { type: String, default: '' },
+    from: { type: String, default: '' },
+    label: { type: String, default: '' },
+    'copied-label': { type: String, default: '' },
+    timeout: { type: Number, default: 2000 },
+    disabled: { type: Boolean, default: false },
+    variant: { type: String, default: 'ghost' },
+    size: { type: String, default: 'md' },
+  },
+  state: { copied: false },
+  styles: css`
+    ${baseStyles}
+    ${reset}
+    ${srOnly}
+    ${focusRing}
+    ${iconCss('copy', 'check')}
+    :host { display: inline-flex; }
+    .btn {
+      display: inline-flex; align-items: center; justify-content: center;
+      gap: 0.375rem;
+      inline-size: var(--bq-copy-size, 2.25rem);
+      block-size: var(--bq-copy-size, 2.25rem);
+      padding: 0;
+      border: var(--bq-border-width-control, 1.5px) solid transparent;
+      border-radius: var(--bq-radius-md, 0.375rem);
+      background: transparent;
+      color: var(--bq-text-muted, #475569);
+      cursor: pointer;
+      font-family: var(--bq-font-family-sans);
+      --bq-icon-size: 1.125rem;
+      transition:
+        background-color var(--bq-duration-fast) var(--bq-easing-standard),
+        border-color var(--bq-duration-fast) var(--bq-easing-standard),
+        color var(--bq-duration-fast) var(--bq-easing-standard);
+    }
+    :host([size='sm']) .btn { --bq-copy-size: 1.75rem; --bq-icon-size: 0.875rem; }
+    :host([size='lg']) .btn { --bq-copy-size: 2.75rem; --bq-icon-size: 1.25rem; }
+    .btn:hover:not(:disabled) { background: var(--bq-bg-hover, rgba(15,23,42,0.06)); color: var(--bq-text-base, #0f172a); }
+    :host([variant='outline']) .btn { border-color: var(--bq-border-emphasis, #cbd5e1); }
+    :host([variant='solid']) .btn {
+      background: var(--bq-bg-muted, #f1f5f9);
+      border-color: var(--bq-border-base, #e2e8f0);
+    }
+    .btn:disabled { opacity: 0.5; cursor: not-allowed; }
+    /* Confirmation reads as a state change, not a colour flash: the icon
+       swaps and settles into the success hue. */
+    .btn[data-copied='true'] { color: var(--bq-color-success-600, #16a34a); }
+    .icon { transition: transform var(--bq-duration-fast) var(--bq-easing-spring); }
+    .btn[data-copied='true'] .icon { transform: scale(1.1); }
+  `,
+  connected() {
+    const self = host<BqCopyButtonState>(this);
+    const scope = bind(self);
+    const local = copyStore(self);
+
+    /** Resolves the text to copy, preferring an explicit `value`. */
+    const resolveText = (): string => {
+      const explicit = self.getAttribute('value');
+      if (explicit) return explicit;
+      const selector = self.getAttribute('from');
+      if (!selector) return self.textContent?.trim() ?? '';
+      const root = self.getRootNode() as Document | ShadowRoot;
+      try {
+        const target =
+          root.querySelector(selector) ?? document.querySelector(selector);
+        return target?.textContent?.trim() ?? '';
+      } catch {
+        return '';
+      }
+    };
+
+    scope.on(self.shadowRoot, 'click', (event) => {
+      if (!(event.target as Element)?.closest('.btn')) return;
+      if (self.hasAttribute('disabled')) return;
+      const text = resolveText();
+      void writeClipboard(text).then((ok) => {
+        if (!self.isConnected) return;
+        self.dispatchEvent(
+          new CustomEvent('bq-copy', {
+            detail: { value: text, ok },
+            bubbles: true,
+            composed: true,
+          })
+        );
+        if (!ok) return;
+        self.setState('copied', true);
+        // Restarting the timer on every copy means a second click extends the
+        // confirmation instead of cutting the first one short.
+        local.resetTimer?.();
+        const ms = Number(self.getAttribute('timeout') ?? 2000);
+        local.resetTimer = scope.timeout(
+          () => {
+            local.resetTimer = null;
+            if (self.isConnected) self.setState('copied', false);
+          },
+          Number.isFinite(ms) && ms > 0 ? ms : 2000
+        );
+      });
+    });
+  },
+  disconnected() {
+    release(this);
+  },
+  render({ props, state }) {
+    const copied = state.copied === true;
+    const idleLabel = props.label.trim() || t('copyButton.copy');
+    const doneLabel = props['copied-label'].trim() || t('copyButton.copied');
+    const label = copied ? doneLabel : idleLabel;
+    return html`
+      <button
+        type="button"
+        class="btn"
+        part="button"
+        data-copied="${copied ? 'true' : 'false'}"
+        aria-label="${escapeHtml(label)}"
+        ${props.disabled ? 'disabled aria-disabled="true"' : ''}
+      >
+        <span class="icon" data-icon="${copied ? 'check' : 'copy'}" aria-hidden="true"></span>
+      </button>
+      <span class="sr-only" role="status" aria-live="polite"
+        >${copied ? escapeHtml(doneLabel) : ''}</span
+      >
+    `;
+  },
+};
+
+component<BqCopyButtonProps, BqCopyButtonState>('bq-copy-button', definition);
diff --git a/src/components/copy-button/index.ts b/src/components/copy-button/index.ts
new file mode 100644
index 0000000..eb9869e
--- /dev/null
+++ b/src/components/copy-button/index.ts
@@ -0,0 +1 @@
+export * as __bqComponentEntry from './BqCopyButton.js';
diff --git a/src/components/date-picker/BqDatePicker.ts b/src/components/date-picker/BqDatePicker.ts
new file mode 100644
index 0000000..b8aedd2
--- /dev/null
+++ b/src/components/date-picker/BqDatePicker.ts
@@ -0,0 +1,767 @@
+/**
+ * Date picker — a text field with a calendar popup.
+ *
+ * Values are ISO `YYYY-MM-DD` on the way in and out, so the attribute means
+ * the same thing everywhere; what the user sees is formatted with
+ * `Intl.DateTimeFormat` for the requested locale, as are the month and weekday
+ * names and the first day of the week.
+ *
+ * All the date arithmetic runs in UTC. A calendar built from local-time `Date`
+ * objects lands on the wrong day twice a year — the hour that does not exist
+ * on a spring-forward morning makes "add one day" produce the same date again —
+ * and a date has no time zone to begin with.
+ *
+ * @element bq-date-picker
+ * @prop {string}  label
+ * @prop {string}  value       - Selected date as `YYYY-MM-DD`
+ * @prop {string}  name        - Form field name
+ * @prop {string}  min         - Earliest selectable date
+ * @prop {string}  max         - Latest selectable date
+ * @prop {string}  locale      - BCP-47 tag; defaults to the document language
+ * @prop {number}  first-day-of-week - 0 (Sunday) … 6
+ * @prop {string}  placeholder
+ * @prop {boolean} clearable
+ * @prop {boolean} disabled
+ * @prop {boolean} readonly
+ * @prop {boolean} required
+ * @prop {string}  error
+ * @prop {string}  hint
+ * @prop {string}  size        - sm | md | lg
+ * @fires bq-change - { value: string }
+ * @fires bq-open
+ * @fires bq-close
+ */
+import type { ComponentDefinition } from '@bquery/bquery/component';
+import { component, css, html } from '@bquery/bquery/component';
+import { escapeHtml } from '@bquery/bquery/security';
+import { t } from '../../i18n/index.js';
+import { bind, host, release, store } from '../../utils/component.js';
+import type { Disposer } from '../../utils/component.js';
+import { uniqueId } from '../../utils/dom.js';
+import { markFocus, restorePreservedFocus } from '../../utils/focus.js';
+import { bindFormProxy, syncFormProxy } from '../../utils/form.js';
+import { iconCss } from '../../utils/icons.js';
+import { autoPosition } from '../../utils/position.js';
+import {
+  baseStyles,
+  fieldStyles,
+  focusRing,
+  reset,
+  srOnly,
+} from '../../utils/styles.js';
+import { bindValidation } from '../../utils/validation.js';
+
+type BqDatePickerProps = {
+  label: string;
+  value: string;
+  name: string;
+  min: string;
+  max: string;
+  locale: string;
+  'first-day-of-week': number;
+  placeholder: string;
+  clearable: boolean;
+  disabled: boolean;
+  readonly: boolean;
+  required: boolean;
+  error: string;
+  hint: string;
+  size: string;
+};
+
+type BqDatePickerState = {
+  uid: string;
+  open: boolean;
+  /** The day the keyboard is on, as ISO. Drives the roving tab stop. */
+  cursor: string;
+};
+
+const MS_PER_DAY = 86_400_000;
+
+const pickerStore = (owner: object) =>
+  store<{ syncPosition?: () => void; stopPosition?: Disposer | null }>(
+    owner,
+    () => ({})
+  );
+
+/** Parses `YYYY-MM-DD` into a UTC timestamp, or `null` if it is not a real date. */
+export function parseISODate(value: string): Date | null {
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value.trim());
+  if (!match) return null;
+  const [, y, m, d] = match;
+  const year = Number(y);
+  const month = Number(m);
+  const day = Number(d);
+  if (month < 1 || month > 12 || day < 1 || day > 31) return null;
+  const date = new Date(Date.UTC(year, month - 1, day));
+  // Rejects 2024-02-31 and friends, which `Date.UTC` silently rolls over.
+  if (date.getUTCMonth() !== month - 1 || date.getUTCDate() !== day) return null;
+  return date;
+}
+
+/** Formats a UTC date back to `YYYY-MM-DD`. */
+export function formatISODate(date: Date): string {
+  const y = String(date.getUTCFullYear()).padStart(4, '0');
+  const m = String(date.getUTCMonth() + 1).padStart(2, '0');
+  const d = String(date.getUTCDate()).padStart(2, '0');
+  return `${y}-${m}-${d}`;
+}
+
+/** Adds whole days. */
+export function addDays(date: Date, days: number): Date {
+  return new Date(date.getTime() + days * MS_PER_DAY);
+}
+
+/**
+ * Adds whole months, clamping the day to the length of the target month.
+ *
+ * Without the clamp, stepping from 31 January lands in March, so paging
+ * through a calendar would skip February entirely.
+ */
+export function addMonths(date: Date, months: number): Date {
+  const year = date.getUTCFullYear();
+  const month = date.getUTCMonth() + months;
+  const day = date.getUTCDate();
+  const lastDay = new Date(Date.UTC(year, month + 1, 0)).getUTCDate();
+  return new Date(Date.UTC(year, month, Math.min(day, lastDay)));
+}
+
+/** Whether two dates fall on the same UTC day. */
+export function isSameDay(a: Date | null, b: Date | null): boolean {
+  if (!a || !b) return false;
+  return formatISODate(a) === formatISODate(b);
+}
+
+/**
+ * Builds the six-week grid a month is drawn on.
+ *
+ * Always six rows, always starting on `firstDayOfWeek`: a grid that changes
+ * height between months makes the popup jump as the user pages through it,
+ * and the leading and trailing days are what keep the columns aligned.
+ */
+export function buildMonthGrid(
+  year: number,
+  month: number,
+  firstDayOfWeek = 1
+): Date[] {
+  const first = new Date(Date.UTC(year, month, 1));
+  const offset = (first.getUTCDay() - firstDayOfWeek + 7) % 7;
+  const start = addDays(first, -offset);
+  return Array.from({ length: 42 }, (_, i) => addDays(start, i));
+}
+
+/** Clamps a date into the `[min, max]` window, ignoring absent bounds. */
+export function clampDate(
+  date: Date,
+  min: Date | null,
+  max: Date | null
+): Date {
+  if (min && date.getTime() < min.getTime()) return min;
+  if (max && date.getTime() > max.getTime()) return max;
+  return date;
+}
+
+function isOutOfRange(date: Date, min: Date | null, max: Date | null): boolean {
+  if (min && date.getTime() < min.getTime()) return true;
+  if (max && date.getTime() > max.getTime()) return true;
+  return false;
+}
+
+/**
+ * Weekday and month names for a locale.
+ *
+ * Cached because a `DateTimeFormat` is expensive to construct and a calendar
+ * re-renders on every arrow key.
+ */
+const formatterCache = new Map<string, Intl.DateTimeFormat>();
+function formatter(locale: string, options: Intl.DateTimeFormatOptions) {
+  const key = `${locale}|${JSON.stringify(options)}`;
+  const cached = formatterCache.get(key);
+  if (cached) return cached;
+  let created: Intl.DateTimeFormat;
+  try {
+    created = new Intl.DateTimeFormat(locale || undefined, {
+      timeZone: 'UTC',
+      ...options,
+    });
+  } catch {
+    created = new Intl.DateTimeFormat(undefined, {
+      timeZone: 'UTC',
+      ...options,
+    });
+  }
+  formatterCache.set(key, created);
+  return created;
+}
+
+/** Short weekday headers, rotated to start on `firstDayOfWeek`. */
+export function weekdayNames(locale: string, firstDayOfWeek: number): string[] {
+  const fmt = formatter(locale, { weekday: 'short' });
+  // 1970-01-04 was a Sunday, which makes the index arithmetic trivial.
+  return Array.from({ length: 7 }, (_, i) =>
+    fmt.format(new Date(Date.UTC(1970, 0, 4 + ((firstDayOfWeek + i) % 7))))
+  );
+}
+
+const definition: ComponentDefinition<BqDatePickerProps, BqDatePickerState> = {
+  props: {
+    label: { type: String, default: '' },
+    value: { type: String, default: '' },
+    name: { type: String, default: '' },
+    min: { type: String, default: '' },
+    max: { type: String, default: '' },
+    locale: { type: String, default: '' },
+    'first-day-of-week': { type: Number, default: 1 },
+    placeholder: { type: String, default: '' },
+    clearable: { type: Boolean, default: false },
+    disabled: { type: Boolean, default: false },
+    readonly: { type: Boolean, default: false },
+    required: { type: Boolean, default: false },
+    error: { type: String, default: '' },
+    hint: { type: String, default: '' },
+    size: { type: String, default: 'md' },
+  },
+  state: { uid: '', open: false, cursor: '' },
+  sanitize: { allowAttributes: ['scope'] },
+  styles: css`
+    ${baseStyles}
+    ${reset}
+    ${fieldStyles}
+    ${srOnly}
+    ${focusRing}
+    ${iconCss('calendar', 'chevron-left', 'chevron-right', 'x')}
+    :host { display: block; position: relative; }
+
+    .control {
+      display: flex; align-items: center;
+      border: var(--bq-border-width-control,1.5px) solid var(--bq-border-emphasis,#cbd5e1);
+      border-radius: var(--bq-radius-lg,0.5rem);
+      background: var(--bq-bg-base,#fff);
+      overflow: hidden;
+      transition: border-color var(--bq-duration-fast) var(--bq-easing-standard),
+                  box-shadow var(--bq-duration-fast) var(--bq-easing-standard);
+    }
+    .control:hover { border-color: var(--bq-border-strong,#94a3b8); }
+    .control:focus-within { border-color: var(--bq-border-focus,#2563eb); box-shadow: var(--bq-focus-ring); }
+    :host([error]:not([error=""])) .control { border-color: var(--bq-color-danger-500,#ef4444); }
+    :host([error]:not([error=""])) .control:focus-within { box-shadow: var(--bq-focus-ring-danger); }
+    :host([disabled]) .control { opacity: 0.55; background: var(--bq-bg-muted,#f1f5f9); }
+
+    input {
+      flex: 1; min-inline-size: 0;
+      border: none; outline: none; background: transparent;
+      color: var(--bq-text-base,#0f172a);
+      font-family: var(--bq-font-family-sans);
+    }
+    :host([size="sm"]) input { font-size: var(--bq-font-size-sm,0.875rem); padding: 0.375rem var(--bq-control-padding-sm,0.75rem); min-block-size: var(--bq-control-height-sm,2rem); }
+    :host([size="md"]) input, :host(:not([size])) input { font-size: var(--bq-font-size-md,1rem); padding: 0.5rem var(--bq-control-padding-md,0.875rem); min-block-size: var(--bq-control-height-md,2.5rem); }
+    :host([size="lg"]) input { font-size: var(--bq-font-size-lg,1.125rem); padding: 0.625rem var(--bq-control-padding-lg,1rem); min-block-size: var(--bq-control-height-lg,3rem); }
+    input::placeholder { color: var(--bq-text-subtle,#94a3b8); }
+
+    .affix-btn {
+      display: inline-flex; align-items: center; justify-content: center;
+      align-self: stretch; padding-inline: 0.5rem;
+      background: none; border: none; cursor: pointer;
+      color: var(--bq-text-muted,#475569);
+      --bq-icon-size: 1.125rem;
+      transition: color var(--bq-duration-fast) var(--bq-easing-standard),
+                  background-color var(--bq-duration-fast) var(--bq-easing-standard);
+    }
+    .affix-btn:hover { color: var(--bq-text-base,#0f172a); background: var(--bq-bg-hover,rgba(15,23,42,0.04)); }
+    .affix-btn:disabled { cursor: not-allowed; opacity: 0.5; }
+
+    .panel {
+      position: absolute; z-index: var(--bq-z-dropdown,100);
+      inset-inline-start: 0; margin-block-start: 0.25rem;
+      background: var(--bq-surface-overlay,#fff);
+      border: 1px solid var(--bq-border-base,#e2e8f0);
+      border-radius: var(--bq-radius-xl,0.75rem);
+      box-shadow: var(--bq-shadow-lg);
+      padding: 0.75rem;
+      font-family: var(--bq-font-family-sans);
+      inline-size: max-content;
+    }
+    :host(:not([data-open])) .panel { display: none; }
+
+    .panel-head {
+      display: flex; align-items: center; justify-content: space-between;
+      gap: 0.5rem; margin-block-end: 0.5rem;
+    }
+    .month-label {
+      font-size: var(--bq-font-size-sm,0.875rem);
+      font-weight: var(--bq-font-weight-semibold,600);
+      color: var(--bq-text-base,#0f172a);
+    }
+    .nav-btn {
+      display: inline-flex; align-items: center; justify-content: center;
+      inline-size: 1.75rem; block-size: 1.75rem;
+      border: none; border-radius: var(--bq-radius-md,0.375rem);
+      background: none; cursor: pointer;
+      color: var(--bq-text-muted,#475569);
+      --bq-icon-size: 1rem;
+      transition: background-color var(--bq-duration-fast) var(--bq-easing-standard);
+    }
+    .nav-btn:hover:not(:disabled) { background: var(--bq-bg-hover,rgba(15,23,42,0.06)); color: var(--bq-text-base,#0f172a); }
+    .nav-btn:disabled { opacity: 0.4; cursor: not-allowed; }
+
+    .grid { border-collapse: collapse; }
+    .grid th {
+      inline-size: 2rem; padding-block-end: 0.25rem;
+      font-size: var(--bq-font-size-xs,0.75rem);
+      font-weight: var(--bq-font-weight-medium,500);
+      color: var(--bq-text-subtle,#94a3b8);
+      text-transform: uppercase;
+      letter-spacing: var(--bq-letter-spacing-wide,0.04em);
+    }
+    .grid td { padding: 1px; }
+    .day {
+      inline-size: 2rem; block-size: 2rem;
+      display: grid; place-items: center;
+      border: none; border-radius: var(--bq-radius-md,0.375rem);
+      background: none; cursor: pointer;
+      font-family: inherit;
+      font-size: var(--bq-font-size-sm,0.875rem);
+      font-variant-numeric: tabular-nums;
+      color: var(--bq-text-base,#0f172a);
+      transition: background-color var(--bq-duration-fast) var(--bq-easing-standard),
+                  color var(--bq-duration-fast) var(--bq-easing-standard);
+    }
+    .day:hover:not(:disabled) { background: var(--bq-bg-hover,rgba(15,23,42,0.06)); }
+    /* Days spilling in from the neighbouring months stay visible but recede,
+       so the six-row grid keeps its shape without pulling the eye. */
+    .day[data-outside="true"] { color: var(--bq-text-subtle,#94a3b8); }
+    .day[data-today="true"] { font-weight: var(--bq-font-weight-semibold,600); box-shadow: inset 0 0 0 1px var(--bq-border-strong,#94a3b8); }
+    .day[aria-selected="true"] {
+      background: var(--bq-color-primary-600,#2563eb);
+      color: var(--bq-text-on-primary,#fff);
+      box-shadow: none;
+    }
+    .day:disabled { opacity: 0.35; cursor: not-allowed; }
+
+    .panel-foot { display: flex; justify-content: flex-end; margin-block-start: 0.5rem; }
+    .today-btn {
+      border: none; background: none; cursor: pointer;
+      font-family: inherit; font-size: var(--bq-font-size-sm,0.875rem);
+      color: var(--bq-color-primary-600,#2563eb);
+      padding: 0.25rem 0.5rem; border-radius: var(--bq-radius-md,0.375rem);
+    }
+    .today-btn:hover { background: var(--bq-bg-hover,rgba(15,23,42,0.06)); }
+  `,
+  connected() {
+    const self = host<BqDatePickerState>(this);
+    const scope = bind(self);
+    const local = pickerStore(self);
+    if (!self.getState<string>('uid')) self.setState('uid', uniqueId('bq-dp'));
+
+    const readValue = () => self.getAttribute('value') ?? '';
+    const minDate = () => parseISODate(self.getAttribute('min') ?? '');
+    const maxDate = () => parseISODate(self.getAttribute('max') ?? '');
+    const isInteractive = () =>
+      !self.hasAttribute('disabled') && !self.hasAttribute('readonly');
+
+    bindFormProxy(self, scope, { value: readValue });
+    bindValidation(self, scope, { value: readValue });
+
+    /** The day the keyboard is on: the cursor, else the value, else today. */
+    const cursorDate = (): Date => {
+      const explicit = parseISODate(self.getState<string>('cursor') ?? '');
+      if (explicit) return explicit;
+      const selected = parseISODate(readValue());
+      if (selected) return selected;
+      const now = new Date();
+      return new Date(
+        Date.UTC(now.getFullYear(), now.getMonth(), now.getDate())
+      );
+    };
+
+    const setCursor = (date: Date) => {
+      markFocus(self);
+      self.setState('cursor', formatISODate(clampDate(date, minDate(), maxDate())));
+    };
+
+    const open = () => {
+      if (!isInteractive() || self.getState<boolean>('open')) return;
+      markFocus(self);
+      self.setState('cursor', formatISODate(cursorDate()));
+      self.setState('open', true);
+      self.setAttribute('data-open', '');
+      self.dispatchEvent(
+        new CustomEvent('bq-open', { bubbles: true, composed: true })
+      );
+    };
+
+    const close = ({ restore = false } = {}) => {
+      if (!self.getState<boolean>('open')) return;
+      markFocus(self);
+      self.setState('open', false);
+      self.removeAttribute('data-open');
+      self.dispatchEvent(
+        new CustomEvent('bq-close', { bubbles: true, composed: true })
+      );
+      if (!restore) return;
+      const field = self.shadowRoot?.querySelector(
+        'input'
+      ) as HTMLInputElement | null;
+      field?.focus();
+    };
+
+    const commit = (iso: string) => {
+      if (self.getAttribute('value') === iso) return;
+      self.setAttribute('value', iso);
+      self.dispatchEvent(
+        new CustomEvent('bq-change', {
+          detail: { value: iso },
+          bubbles: true,
+          composed: true,
+        })
+      );
+    };
+
+    const select = (date: Date) => {
+      if (isOutOfRange(date, minDate(), maxDate())) return;
+      commit(formatISODate(date));
+      close({ restore: true });
+    };
+
+    // ── Positioning ──────────────────────────────────────────────────────
+    const syncPosition = () => {
+      local.stopPosition?.();
+      local.stopPosition = null;
+      if (!self.getState<boolean>('open')) return;
+      const panel = self.shadowRoot?.querySelector(
+        '.panel'
+      ) as HTMLElement | null;
+      if (!panel) return;
+      local.stopPosition = scope.add(
+        autoPosition(self, panel, { placement: 'bottom-start', offset: 4 })
+      );
+    };
+    local.syncPosition = syncPosition;
+
+    // ── Text entry ───────────────────────────────────────────────────────
+    scope.on(self.shadowRoot, 'change', (event) => {
+      const input = event.target as HTMLInputElement | null;
+      if (input?.tagName !== 'INPUT') return;
+      const typed = input.value.trim();
+      if (!typed) {
+        commit('');
+        return;
+      }
+      const parsed = parseISODate(typed);
+      // Anything the field cannot parse is rejected by repainting the last
+      // good value, rather than by silently storing something else.
+      if (!parsed || isOutOfRange(parsed, minDate(), maxDate())) {
+        input.value = displayValue();
+        return;
+      }
+      commit(formatISODate(parsed));
+    });
+
+    const displayValue = (): string => {
+      const date = parseISODate(readValue());
+      if (!date) return '';
+      return formatter(self.getAttribute('locale') ?? '', {
+        dateStyle: 'medium',
+      }).format(date);
+    };
+
+    scope.on(self.shadowRoot, 'click', (event) => {
+      const target = event.target as Element;
+      if (target.closest('.calendar-btn')) {
+        if (self.getState<boolean>('open')) close({ restore: true });
+        else open();
+        return;
+      }
+      if (target.closest('.clear-btn')) {
+        commit('');
+        return;
+      }
+      if (!isInteractive()) return;
+      const nav = target.closest('.nav-btn') as HTMLElement | null;
+      if (nav) {
+        setCursor(
+          addMonths(cursorDate(), nav.getAttribute('data-dir') === 'next' ? 1 : -1)
+        );
+        return;
+      }
+      if (target.closest('.today-btn')) {
+        const now = new Date();
+        select(
+          new Date(Date.UTC(now.getFullYear(), now.getMonth(), now.getDate()))
+        );
+        return;
+      }
+      const day = target.closest('.day') as HTMLElement | null;
+      if (day && !day.hasAttribute('disabled')) {
+        const parsed = parseISODate(day.getAttribute('data-date') ?? '');
+        if (parsed) select(parsed);
+      }
+    });
+
+    scope.on(self.shadowRoot, 'keydown', (event) => {
+      const ke = event as KeyboardEvent;
+      if (!isInteractive()) return;
+      const isOpen = self.getState<boolean>('open') === true;
+      const onField = (ke.target as Element)?.tagName === 'INPUT';
+
+      if (!isOpen) {
+        if (onField && (ke.key === 'ArrowDown' || ke.key === 'Enter') && ke.altKey) {
+          ke.preventDefault();
+          open();
+        }
+        return;
+      }
+
+      switch (ke.key) {
+        case 'Escape':
+          ke.preventDefault();
+          close({ restore: true });
+          return;
+        case 'ArrowLeft':
+          if (onField) return;
+          ke.preventDefault();
+          setCursor(addDays(cursorDate(), -1));
+          return;
+        case 'ArrowRight':
+          if (onField) return;
+          ke.preventDefault();
+          setCursor(addDays(cursorDate(), 1));
+          return;
+        case 'ArrowUp':
+          if (onField) return;
+          ke.preventDefault();
+          setCursor(addDays(cursorDate(), -7));
+          return;
+        case 'ArrowDown':
+          if (onField) return;
+          ke.preventDefault();
+          setCursor(addDays(cursorDate(), 7));
+          return;
+        case 'PageUp':
+          ke.preventDefault();
+          setCursor(addMonths(cursorDate(), ke.shiftKey ? -12 : -1));
+          return;
+        case 'Home': {
+          if (onField) return;
+          ke.preventDefault();
+          const first = Number(self.getAttribute('first-day-of-week') ?? 1);
+          const current = cursorDate();
+          const offset = (current.getUTCDay() - first + 7) % 7;
+          setCursor(addDays(current, -offset));
+          return;
+        }
+        case 'End': {
+          if (onField) return;
+          ke.preventDefault();
+          const first = Number(self.getAttribute('first-day-of-week') ?? 1);
+          const current = cursorDate();
+          const offset = (current.getUTCDay() - first + 7) % 7;
+          setCursor(addDays(current, 6 - offset));
+          return;
+        }
+        case 'PageDown':
+          ke.preventDefault();
+          setCursor(addMonths(cursorDate(), ke.shiftKey ? 12 : 1));
+          return;
+        case 'Enter':
+        case ' ':
+          if (onField) return;
+          ke.preventDefault();
+          select(cursorDate());
+          return;
+      }
+    });
+
+    // Registered once and gated on `open`, so the listener count does not
+    // depend on how often the calendar is toggled.
+    scope.on(document, 'mousedown', (event) => {
+      if (!self.getState<boolean>('open')) return;
+      if (self.contains(event.target as Node)) return;
+      close();
+    });
+    scope.on(self.shadowRoot, 'focusout', (event) => {
+      if (!self.getState<boolean>('open')) return;
+      const next = (event as FocusEvent).relatedTarget as Node | null;
+      if (next && self.shadowRoot?.contains(next)) return;
+      if (next && self.contains(next)) return;
+      if (next) close();
+    });
+  },
+  disconnected() {
+    release(this);
+  },
+  beforeUpdate() {
+    markFocus(this);
+  },
+  updated() {
+    const local = pickerStore(this);
+    restorePreservedFocus(this);
+    local.syncPosition?.();
+    syncFormProxy(this);
+
+    // Arrow keys move a roving tab stop through the grid, and the render that
+    // moved it destroyed the button that had focus.
+    const root = this.shadowRoot;
+    const cursor = root?.querySelector(
+      '.day[tabindex="0"]'
+    ) as HTMLElement | null;
+    if (cursor && this.hasAttribute('data-open') && !root?.activeElement) {
+      cursor.focus();
+    }
+  },
+  render({ props, state }) {
+    const uid = state.uid || 'bq-dp';
+    const isOpen = state.open === true;
+    const locale = props.locale;
+    const min = parseISODate(props.min);
+    const max = parseISODate(props.max);
+    const selected = parseISODate(props.value);
+    const cursor =
+      parseISODate(state.cursor ?? '') ??
+      selected ??
+      (() => {
+        const now = new Date();
+        return new Date(
+          Date.UTC(now.getFullYear(), now.getMonth(), now.getDate())
+        );
+      })();
+    const now = new Date();
+    const today = new Date(
+      Date.UTC(now.getFullYear(), now.getMonth(), now.getDate())
+    );
+
+    const firstDay = Number.isFinite(props['first-day-of-week'])
+      ? ((props['first-day-of-week'] % 7) + 7) % 7
+      : 1;
+    const grid = buildMonthGrid(
+      cursor.getUTCFullYear(),
+      cursor.getUTCMonth(),
+      firstDay
+    );
+    const monthLabel = formatter(locale, {
+      month: 'long',
+      year: 'numeric',
+    }).format(cursor);
+    const dayFormatter = formatter(locale, { dateStyle: 'full' });
+
+    const hasError = Boolean(props.error);
+    const hasHint = Boolean(props.hint) && !hasError;
+    const describedBy: string[] = [];
+    if (hasError) describedBy.push(`${uid}-err`);
+    if (hasHint) describedBy.push(`${uid}-hint`);
+
+    const display = selected
+      ? formatter(locale, { dateStyle: 'medium' }).format(selected)
+      : '';
+
+    const headers = weekdayNames(locale, firstDay)
+      .map(
+        (name) =>
+          `<th scope="col">${escapeHtml(name)}</th>`
+      )
+      .join('');
+
+    let cells = '';
+    for (let week = 0; week < 6; week += 1) {
+      const days = grid
+        .slice(week * 7, week * 7 + 7)
+        .map((date) => {
+          const iso = formatISODate(date);
+          const outside = date.getUTCMonth() !== cursor.getUTCMonth();
+          const disabled = isOutOfRange(date, min, max);
+          const isCursor = isSameDay(date, cursor);
+          return `<td role="gridcell" aria-selected="${isSameDay(date, selected) ? 'true' : 'false'}">
+            <button
+              type="button"
+              class="day"
+              part="day"
+              data-date="${escapeHtml(iso)}"
+              data-outside="${outside ? 'true' : 'false'}"
+              data-today="${isSameDay(date, today) ? 'true' : 'false'}"
+              aria-selected="${isSameDay(date, selected) ? 'true' : 'false'}"
+              aria-label="${escapeHtml(dayFormatter.format(date))}"
+              tabindex="${isCursor ? '0' : '-1'}"
+              ${disabled ? 'disabled' : ''}
+            >${date.getUTCDate()}</button>
+          </td>`;
+        })
+        .join('');
+      cells += `<tr role="row">${days}</tr>`;
+    }
+
+    const prevDisabled = Boolean(
+      min && addMonths(cursor, -1).getUTCFullYear() * 100 +
+        addMonths(cursor, -1).getUTCMonth() <
+        min.getUTCFullYear() * 100 + min.getUTCMonth()
+    );
+    const nextDisabled = Boolean(
+      max && addMonths(cursor, 1).getUTCFullYear() * 100 +
+        addMonths(cursor, 1).getUTCMonth() >
+        max.getUTCFullYear() * 100 + max.getUTCMonth()
+    );
+
+    return html`
+      <div class="field" part="field">
+        ${
+          props.label
+            ? `<label class="label" part="label" for="${escapeHtml(`${uid}-input`)}">${escapeHtml(props.label)}${props.required ? '<span class="required-mark" aria-hidden="true"> *</span>' : ''}</label>`
+            : ''
+        }
+        <div class="control" part="control">
+          <input
+            id="${escapeHtml(`${uid}-input`)}"
+            part="input"
+            type="text"
+            autocomplete="off"
+            value="${escapeHtml(display)}"
+            placeholder="${escapeHtml(props.placeholder || t('datePicker.placeholder'))}"
+            aria-haspopup="dialog"
+            aria-expanded="${isOpen ? 'true' : 'false'}"
+            aria-invalid="${hasError ? 'true' : 'false'}"
+            ${props.required ? 'aria-required="true"' : ''}
+            ${describedBy.length > 0 ? `aria-describedby="${escapeHtml(describedBy.join(' '))}"` : ''}
+            ${props.disabled ? 'disabled' : ''}
+            ${props.readonly ? 'readonly' : ''}
+          />
+          ${
+            props.clearable && display && !props.disabled && !props.readonly
+              ? `<button type="button" class="affix-btn clear-btn" part="clear" tabindex="-1" aria-label="${escapeHtml(t('datePicker.clear'))}"><span class="icon" data-icon="x" aria-hidden="true"></span></button>`
+              : ''
+          }
+          <button
+            type="button"
+            class="affix-btn calendar-btn"
+            part="trigger"
+            aria-label="${escapeHtml(t('datePicker.open'))}"
+            aria-expanded="${isOpen ? 'true' : 'false'}"
+            ${props.disabled || props.readonly ? 'disabled' : ''}
+          ><span class="icon" data-icon="calendar" aria-hidden="true"></span></button>
+        </div>
+
+        <div class="panel" part="panel" role="dialog" aria-modal="false" aria-label="${escapeHtml(monthLabel)}">
+          <div class="panel-head">
+            <button type="button" class="nav-btn" part="prev" data-dir="prev" aria-label="${escapeHtml(t('datePicker.prevMonth'))}" ${prevDisabled ? 'disabled' : ''}>
+              <span class="icon" data-icon="chevron-left" aria-hidden="true"></span>
+            </button>
+            <span class="month-label" part="month" aria-live="polite">${escapeHtml(monthLabel)}</span>
+            <button type="button" class="nav-btn" part="next" data-dir="next" aria-label="${escapeHtml(t('datePicker.nextMonth'))}" ${nextDisabled ? 'disabled' : ''}>
+              <span class="icon" data-icon="chevron-right" aria-hidden="true"></span>
+            </button>
+          </div>
+          <table class="grid" part="grid" role="grid" aria-label="${escapeHtml(monthLabel)}">
+            <thead><tr role="row">${headers}</tr></thead>
+            <tbody>${cells}</tbody>
+          </table>
+          <div class="panel-foot">
+            <button type="button" class="today-btn" part="today">${escapeHtml(t('datePicker.today'))}</button>
+          </div>
+        </div>
+
+        ${hasHint ? `<span class="hint" id="${uid}-hint" part="hint">${escapeHtml(props.hint)}</span>` : ''}
+        ${hasError ? `<span class="error-msg" id="${uid}-err" role="alert" part="error">${escapeHtml(props.error)}</span>` : ''}
+      </div>
+    `;
+  },
+};
+
+component<BqDatePickerProps, BqDatePickerState>('bq-date-picker', definition);
diff --git a/src/components/date-picker/index.ts b/src/components/date-picker/index.ts
new file mode 100644
index 0000000..9b31dab
--- /dev/null
+++ b/src/components/date-picker/index.ts
@@ -0,0 +1 @@
+export * as __bqComponentEntry from './BqDatePicker.js';
diff --git a/src/components/dialog/BqDialog.ts b/src/components/dialog/BqDialog.ts
index 91d1c59..d74a18d 100644
--- a/src/components/dialog/BqDialog.ts
+++ b/src/components/dialog/BqDialog.ts
@@ -21,7 +21,8 @@ import {
   uniqueId,
   updateOverlayFocus,
 } from '../../utils/dom.js';
-import { baseStyles } from '../../utils/styles.js';
+import { iconCss } from '../../utils/icons.js';
+import { baseStyles, focusRing, reset } from '../../utils/styles.js';
 
 type BqDialogProps = {
   open: boolean;
@@ -44,19 +45,21 @@ const definition: ComponentDefinition<BqDialogProps, BqDialogState> = {
   },
   styles: css`
     ${baseStyles}
-    *, *::before, *::after { box-sizing: border-box; }
+    ${reset}
+    ${focusRing}
+    ${iconCss('x')}
     :host { display: block; }
     :host(:not([open])) .overlay { display: none; }
     .overlay {
       position: fixed; inset: 0; z-index: var(--bq-z-modal,400);
-      background: rgba(0,0,0,0.5);
+      background: var(--bq-overlay-backdrop,rgba(15,23,42,0.5));
       display: flex; align-items: center; justify-content: center;
       padding: var(--bq-space-4,1rem);
       animation: fadeIn var(--bq-duration-normal,200ms) var(--bq-easing-decelerate);
     }
     @keyframes fadeIn { from { opacity: 0; } to { opacity: 1; } }
     .dialog {
-      background: var(--bq-bg-base,#fff); border-radius: var(--bq-radius-xl,0.75rem);
+      background: var(--bq-surface-overlay,#fff); border-radius: var(--bq-radius-2xl,1rem);
       box-shadow: var(--bq-shadow-xl); width: 100%;
       max-height: calc(100vh - 4rem); display: flex; flex-direction: column;
       animation: scaleIn var(--bq-duration-normal,200ms) var(--bq-easing-spring);
@@ -75,7 +78,8 @@ const definition: ComponentDefinition<BqDialogProps, BqDialogState> = {
     .header { display: flex; align-items: center; justify-content: space-between; padding: var(--bq-space-5,1.25rem) var(--bq-space-6,1.5rem); border-bottom: 1px solid var(--bq-border-base,#e2e8f0); flex-shrink: 0; }
     .header-title { font-size: var(--bq-font-size-lg,1.125rem); font-weight: var(--bq-font-weight-semibold,600); color: var(--bq-text-base,#0f172a); margin: 0; flex: 1; }
     .close-btn { display: inline-flex; align-items: center; justify-content: center; width: 2rem; height: 2rem; background: none; border: none; cursor: pointer; color: var(--bq-text-muted,#475569); border-radius: var(--bq-radius-md,0.375rem); font-size: 1rem; flex-shrink: 0; transition: background var(--bq-duration-fast); }
-    .close-btn:hover { background: var(--bq-bg-muted,#f1f5f9); }
+    .close-btn:hover { background: var(--bq-bg-muted,#f1f5f9); color: var(--bq-text-base,#0f172a); }
+    .close-btn .icon, .close-btn { --bq-icon-size: 1.125rem; }
     .close-btn:focus-visible { outline: 2px solid transparent; box-shadow: var(--bq-focus-ring); }
     .body { padding: var(--bq-space-6,1.5rem); overflow-y: auto; flex: 1; color: var(--bq-text-muted,#475569); font-size: var(--bq-font-size-md,1rem); line-height: var(--bq-line-height-relaxed,1.625); }
     .footer { padding: var(--bq-space-4,1rem) var(--bq-space-6,1.5rem); border-top: 1px solid var(--bq-border-base,#e2e8f0); display: flex; align-items: center; justify-content: flex-end; gap: var(--bq-space-3,0.75rem); flex-shrink: 0; background: var(--bq-bg-subtle,#f8fafc); }
@@ -133,7 +137,7 @@ const definition: ComponentDefinition<BqDialogProps, BqDialogState> = {
               ${escapeHtml(props.title)}
             </h2>
             ${props.dismissible
-              ? `<button class="close-btn" type="button" aria-label="${t('dialog.close')}" part="close">&#10005;</button>`
+              ? `<button class="close-btn" type="button" aria-label="${t('dialog.close')}" part="close"><span class="icon" data-icon="x" aria-hidden="true"></span></button>`
               : ''}
           </div>
           <div class="body" part="body"><slot></slot></div>
diff --git a/src/components/divider/BqDivider.ts b/src/components/divider/BqDivider.ts
index a6375c3..cb8858e 100644
--- a/src/components/divider/BqDivider.ts
+++ b/src/components/divider/BqDivider.ts
@@ -8,7 +8,7 @@
 import type { ComponentDefinition } from '@bquery/bquery/component';
 import { component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
-import { baseStyles } from '../../utils/styles.js';
+import { baseStyles, reset } from '../../utils/styles.js';
 
 type BqDividerProps = { orientation: string; variant: string; label: string };
 
@@ -20,6 +20,7 @@ const definition: ComponentDefinition<BqDividerProps> = {
   },
   styles: css`
     ${baseStyles}
+    ${reset}
     :host { display: block; }
     .divider {
       display: flex; align-items: center; gap: 0.75rem;
diff --git a/src/components/drawer/BqDrawer.ts b/src/components/drawer/BqDrawer.ts
index cc33b68..9c5a09e 100644
--- a/src/components/drawer/BqDrawer.ts
+++ b/src/components/drawer/BqDrawer.ts
@@ -21,7 +21,8 @@ import {
   uniqueId,
   updateOverlayFocus,
 } from '../../utils/dom.js';
-import { baseStyles } from '../../utils/styles.js';
+import { iconCss } from '../../utils/icons.js';
+import { baseStyles, focusRing, reset } from '../../utils/styles.js';
 
 type BqDrawerProps = {
   open: boolean;
@@ -44,18 +45,20 @@ const definition: ComponentDefinition<BqDrawerProps, BqDrawerState> = {
   },
   styles: css`
     ${baseStyles}
-    *, *::before, *::after { box-sizing: border-box; }
+    ${reset}
+    ${focusRing}
+    ${iconCss('x')}
     :host { display: block; }
     :host(:not([open])) .backdrop { display: none; }
     .backdrop {
       position: fixed; inset: 0; z-index: var(--bq-z-overlay,300);
-      background: rgba(0,0,0,0.5);
+      background: var(--bq-overlay-backdrop,rgba(15,23,42,0.5));
       animation: fadeIn var(--bq-duration-normal) var(--bq-easing-decelerate);
     }
     @keyframes fadeIn { from { opacity: 0; } to { opacity: 1; } }
     .drawer {
       position: fixed; z-index: calc(var(--bq-z-overlay,300) + 1);
-      background: var(--bq-bg-base,#fff); box-shadow: var(--bq-shadow-xl);
+      background: var(--bq-surface-overlay,#fff); box-shadow: var(--bq-shadow-xl);
       display: flex; flex-direction: column;
       font-family: var(--bq-font-family-sans);
     }
@@ -87,7 +90,8 @@ const definition: ComponentDefinition<BqDrawerProps, BqDrawerState> = {
     .header { display: flex; align-items: center; justify-content: space-between; padding: var(--bq-space-5,1.25rem) var(--bq-space-6,1.5rem); border-bottom: 1px solid var(--bq-border-base,#e2e8f0); flex-shrink: 0; }
     .title { font-size: var(--bq-font-size-lg,1.125rem); font-weight: var(--bq-font-weight-semibold,600); color: var(--bq-text-base,#0f172a); margin: 0; flex: 1; }
     .close-btn { display: inline-flex; align-items: center; justify-content: center; width: 2rem; height: 2rem; background: none; border: none; cursor: pointer; color: var(--bq-text-muted,#475569); border-radius: var(--bq-radius-md,0.375rem); font-size: 1rem; transition: background var(--bq-duration-fast); }
-    .close-btn:hover { background: var(--bq-bg-muted,#f1f5f9); }
+    .close-btn:hover { background: var(--bq-bg-muted,#f1f5f9); color: var(--bq-text-base,#0f172a); }
+    .close-btn { --bq-icon-size: 1.125rem; }
     .close-btn:focus-visible { outline: 2px solid transparent; box-shadow: var(--bq-focus-ring); }
     .body { padding: var(--bq-space-6,1.5rem); overflow-y: auto; flex: 1; }
     .footer { padding: var(--bq-space-4,1rem) var(--bq-space-6,1.5rem); border-top: 1px solid var(--bq-border-base,#e2e8f0); display: flex; gap: var(--bq-space-3,0.75rem); justify-content: flex-end; flex-shrink: 0; background: var(--bq-bg-subtle,#f8fafc); }
@@ -151,7 +155,7 @@ const definition: ComponentDefinition<BqDrawerProps, BqDrawerState> = {
               aria-label="${t('drawer.close')}"
               part="close"
             >
-              &#10005;
+              <span class="icon" data-icon="x" aria-hidden="true"></span>
             </button>
           </div>
           <div class="body" part="body"><slot></slot></div>
diff --git a/src/components/dropdown-menu/BqDropdownMenu.ts b/src/components/dropdown-menu/BqDropdownMenu.ts
index ed44fbe..614a6a4 100644
--- a/src/components/dropdown-menu/BqDropdownMenu.ts
+++ b/src/components/dropdown-menu/BqDropdownMenu.ts
@@ -18,7 +18,7 @@ import type { Disposer } from '../../utils/component.js';
 import { bind, host, release, store } from '../../utils/component.js';
 import { getAnimationTimeoutMs, uniqueId } from '../../utils/dom.js';
 import { autoPosition } from '../../utils/position.js';
-import { baseStyles } from '../../utils/styles.js';
+import { baseStyles, reset } from '../../utils/styles.js';
 
 type BqDropdownMenuProps = {
   label: string;
@@ -51,14 +51,14 @@ const definition: ComponentDefinition<
   },
   styles: css`
     ${baseStyles}
-    *, *::before, *::after { box-sizing: border-box; }
+    ${reset}
     :host { display: inline-block; position: relative; }
     .trigger-wrap { display: inline-flex; }
     .menu {
       display: none; position: absolute; z-index: var(--bq-z-dropdown,100);
       min-width: 10rem; max-height: 20rem; overflow-y: auto;
-      background: var(--bq-bg-base,#fff); border: 1px solid var(--bq-border-base,#e2e8f0);
-      border-radius: var(--bq-radius-lg,0.5rem); box-shadow: var(--bq-shadow-lg);
+      background: var(--bq-surface-overlay,#fff); border: 1px solid var(--bq-border-base,#e2e8f0);
+      border-radius: var(--bq-radius-xl,0.75rem); box-shadow: var(--bq-shadow-lg);
       padding: var(--bq-space-1,0.25rem) 0; font-family: var(--bq-font-family-sans);
       animation: menuFadeIn var(--bq-duration-fast,150ms) var(--bq-easing-decelerate);
     }
@@ -76,7 +76,7 @@ const definition: ComponentDefinition<
       display: flex; align-items: center; gap: 0.5rem; width: 100%;
       padding: 0.5rem 0.875rem; border: none; background: none;
       color: var(--bq-text-base,#0f172a); font-size: var(--bq-font-size-sm,0.875rem);
-      font-family: var(--bq-font-family-sans); text-align: left; cursor: pointer;
+      font-family: var(--bq-font-family-sans); text-align: start; cursor: pointer;
       text-decoration: none; white-space: nowrap;
       transition: background var(--bq-duration-fast) var(--bq-easing-standard);
     }
diff --git a/src/components/empty-state/BqEmptyState.ts b/src/components/empty-state/BqEmptyState.ts
index 789494f..128ced8 100644
--- a/src/components/empty-state/BqEmptyState.ts
+++ b/src/components/empty-state/BqEmptyState.ts
@@ -3,14 +3,15 @@
  * @element bq-empty-state
  * @prop {string} title       - Main heading
  * @prop {string} description - Descriptive text
- * @prop {string} icon        - Icon character/emoji
+ * @prop {string} icon        - Icon character/emoji, for the simplest case
+ * @slot icon - Illustration or `bq-icon` shown above the title
  * @slot - Additional content (e.g. action button)
  */
 import { component, css, html } from '@bquery/bquery/component';
 import type { ComponentDefinition } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { t } from '../../i18n/index.js';
-import { baseStyles } from '../../utils/styles.js';
+import { baseStyles, reset } from '../../utils/styles.js';
 
 type BqEmptyStateProps = { title: string; description: string; icon: string };
 
@@ -22,16 +23,24 @@ const definition: ComponentDefinition<BqEmptyStateProps> = {
   },
   styles: css`
     ${baseStyles}
-    *, *::before, *::after { box-sizing: border-box; }
+    ${reset}
     :host { display: block; }
     .empty {
       display: flex; flex-direction: column; align-items: center; justify-content: center;
       text-align: center; padding: var(--bq-space-12,3rem) var(--bq-space-6,1.5rem);
       font-family: var(--bq-font-family-sans);
     }
-    .icon { font-size: 3rem; line-height: 1; margin-bottom: var(--bq-space-4,1rem); color: var(--bq-text-subtle,#94a3b8); }
-    .title { font-size: var(--bq-font-size-xl,1.25rem); font-weight: var(--bq-font-weight-semibold,600); color: var(--bq-text-base,#0f172a); margin: 0 0 0.5rem; }
-    .description { font-size: var(--bq-font-size-md,1rem); color: var(--bq-text-muted,#475569); margin: 0 0 var(--bq-space-6,1.5rem); max-width: 28rem; }
+    .icon {
+      display: flex; align-items: center; justify-content: center;
+      font-size: 3rem; line-height: 1;
+      margin-block-end: var(--bq-space-4,1rem);
+      color: var(--bq-text-subtle,#94a3b8);
+      --bq-icon-size: 3rem;
+    }
+    /* An empty slot must not reserve the icon's margin. */
+    .icon:empty { display: none; }
+    .title { font-size: var(--bq-font-size-xl,1.25rem); font-weight: var(--bq-font-weight-semibold,600); letter-spacing: var(--bq-letter-spacing-tight,-0.015em); color: var(--bq-text-base,#0f172a); margin: 0 0 0.5rem; }
+    .description { font-size: var(--bq-font-size-md,1rem); line-height: var(--bq-line-height-relaxed,1.625); color: var(--bq-text-muted,#475569); margin: 0 0 var(--bq-space-6,1.5rem); max-inline-size: 28rem; }
     .actions { display: flex; gap: var(--bq-space-3,0.75rem); flex-wrap: wrap; justify-content: center; }
   `,
   render({ props }) {
@@ -39,7 +48,9 @@ const definition: ComponentDefinition<BqEmptyStateProps> = {
     const description = props.description.trim() || t('emptyState.description');
     return html`
       <div part="empty-state" class="empty" role="status" aria-live="polite">
-        ${props.icon ? `<span class="icon" part="icon" aria-hidden="true">${escapeHtml(props.icon)}</span>` : ''}
+        <span class="icon" part="icon" aria-hidden="true"
+          ><slot name="icon">${props.icon ? escapeHtml(props.icon) : ''}</slot
+        ></span>
         ${title ? `<h3 class="title" part="title">${escapeHtml(title)}</h3>` : ''}
         ${description ? `<p class="description" part="description">${escapeHtml(description)}</p>` : ''}
         <div class="actions" part="actions"><slot></slot></div>
diff --git a/src/components/file-upload/BqFileUpload.ts b/src/components/file-upload/BqFileUpload.ts
index af91024..b730b1a 100644
--- a/src/components/file-upload/BqFileUpload.ts
+++ b/src/components/file-upload/BqFileUpload.ts
@@ -19,7 +19,8 @@ import { escapeHtml } from '@bquery/bquery/security';
 import { t } from '../../i18n/index.js';
 import { bind, host, release, store } from '../../utils/component.js';
 import { uniqueId } from '../../utils/dom.js';
-import { baseStyles, reset, srOnly } from '../../utils/styles.js';
+import { iconCss } from '../../utils/icons.js';
+import { baseStyles, focusRing, reset, srOnly } from '../../utils/styles.js';
 
 type BqFileUploadProps = {
   accept: string;
@@ -89,6 +90,8 @@ const definition: ComponentDefinition<BqFileUploadProps, BqFileUploadState> = {
     ${baseStyles}
     ${reset}
     ${srOnly}
+    ${focusRing}
+    ${iconCss('upload')}
     :host { display: block; }
     .field { font-family: var(--bq-font-family-sans); }
     .label {
@@ -116,7 +119,8 @@ const definition: ComponentDefinition<BqFileUploadProps, BqFileUploadState> = {
     :host([data-dragging]) .zone { border-color: var(--bq-color-primary-600,#2563eb); background: var(--bq-color-primary-50,#eff6ff); }
     :host([error]) .zone { border-color: var(--bq-color-danger-600,#dc2626); }
     .browse { color: var(--bq-color-primary-600,#2563eb); font-weight: var(--bq-font-weight-semibold,600); }
-    .icon { display: inline-flex; font-size: 1.5rem; }
+    .dropzone-icon { display: inline-flex; color: var(--bq-text-subtle,#94a3b8); }
+    .dropzone-icon .icon { --bq-icon-size: 2rem; }
 
     input[type="file"] {
       position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px;
@@ -348,7 +352,7 @@ const definition: ComponentDefinition<BqFileUploadProps, BqFileUploadState> = {
           ${props.error ? 'aria-invalid="true"' : ''}
           ${describedBy ? `aria-describedby="${escapeHtml(describedBy)}"` : ''}
         >
-          <span class="icon" part="icon"><slot name="icon"></slot></span>
+          <span class="dropzone-icon" part="icon"><slot name="icon"><span class="icon" data-icon="upload" aria-hidden="true"></span></slot></span>
           <span
             >${escapeHtml(t('fileUpload.hint'))}
             <span class="browse">${escapeHtml(t('fileUpload.browse'))}</span></span
diff --git a/src/components/icon-button/BqIconButton.ts b/src/components/icon-button/BqIconButton.ts
index 5433c46..cf4b07c 100644
--- a/src/components/icon-button/BqIconButton.ts
+++ b/src/components/icon-button/BqIconButton.ts
@@ -17,7 +17,7 @@ import { escapeHtml } from '@bquery/bquery/security';
 import { t } from '../../i18n/index.js';
 import { bind, host, release } from '../../utils/component.js';
 import { uniqueId } from '../../utils/dom.js';
-import { baseStyles } from '../../utils/styles.js';
+import { baseStyles, reset } from '../../utils/styles.js';
 
 type BqIconButtonProps = {
   variant: string; size: string; disabled: boolean; loading: boolean;
@@ -40,7 +40,7 @@ const definition: ComponentDefinition<BqIconButtonProps, BqIconButtonState> = {
   },
   styles: css`
     ${baseStyles}
-    *, *::before, *::after { box-sizing: border-box; }
+    ${reset}
     :host { display: inline-block; }
     .btn {
       display: inline-flex; align-items: center; justify-content: center;
diff --git a/src/components/icon/BqIcon.ts b/src/components/icon/BqIcon.ts
new file mode 100644
index 0000000..3f0114a
--- /dev/null
+++ b/src/components/icon/BqIcon.ts
@@ -0,0 +1,87 @@
+/**
+ * Icon component — renders one glyph from the built-in set.
+ *
+ * The icon is drawn as a CSS mask filled with `currentColor`, so it inherits
+ * the surrounding text colour and scales with `font-size` by default. That
+ * also means it is a single path at any zoom or pixel density, unlike the
+ * text glyphs (`✓`, `×`, `▾`) this library used before, whose weight and
+ * baseline were up to whichever font the platform happened to pick.
+ *
+ * ```html
+ * <bq-icon name="check"></bq-icon>
+ * <bq-icon name="trash" size="1.5rem" label="Delete"></bq-icon>
+ * ```
+ *
+ * Decorative by default (`aria-hidden`). Pass `label` when the icon *is* the
+ * content — an icon-only button with no other text — and it becomes an
+ * `img`-role element with an accessible name instead.
+ *
+ * @element bq-icon
+ * @prop {string} name  - Icon name; see `iconNames`
+ * @prop {string} size  - Any CSS length; defaults to `1em`
+ * @prop {string} label - Accessible name. Omit for decorative icons.
+ * @cssprop --bq-icon-size - Alternative to the `size` prop
+ */
+import type { ComponentDefinition } from '@bquery/bquery/component';
+import { component, css, html } from '@bquery/bquery/component';
+import { escapeHtml } from '@bquery/bquery/security';
+import { allIconCss, isIconName } from '../../utils/icons.js';
+import { baseStyles, reset } from '../../utils/styles.js';
+
+type BqIconProps = { name: string; size: string; label: string };
+
+/**
+ * Rejects anything that is not a plain CSS length or keyword.
+ *
+ * `size` lands in an inline style, so it is the one prop that could otherwise
+ * carry `)` or `;` out of an attribute value and into the rest of the
+ * declaration block.
+ */
+function safeSize(value: string): string {
+  const trimmed = value.trim();
+  return /^[0-9a-zA-Z.%\-\s]*$/.test(trimmed) ? trimmed : '';
+}
+
+const definition: ComponentDefinition<BqIconProps> = {
+  props: {
+    name: { type: String, default: '' },
+    size: { type: String, default: '' },
+    label: { type: String, default: '' },
+  },
+  sanitize: { allowAttributes: ['style'] },
+  styles: css`
+    ${baseStyles}
+    ${reset}
+    ${allIconCss()}
+    :host {
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      /* Nudges the glyph onto the text baseline it sits next to; without it an
+         icon in a sentence rides slightly high. */
+      vertical-align: -0.125em;
+    }
+    .icon { display: block; }
+  `,
+  render({ props }) {
+    const name = isIconName(props.name) ? props.name : '';
+    if (!name) return html`<span></span>`;
+    const size = safeSize(props.size);
+    const label = props.label.trim();
+    return html`
+      <span
+        class="icon"
+        part="icon"
+        data-icon="${escapeHtml(name)}"
+        ${size ? `style="--bq-icon-size: ${escapeHtml(size)}"` : ''}
+        ${
+          label
+            ? `role="img" aria-label="${escapeHtml(label)}"`
+            : 'aria-hidden="true"'
+        }
+      ></span>
+    `;
+  },
+};
+
+component<BqIconProps>('bq-icon', definition);
diff --git a/src/components/icon/index.ts b/src/components/icon/index.ts
new file mode 100644
index 0000000..9274e63
--- /dev/null
+++ b/src/components/icon/index.ts
@@ -0,0 +1 @@
+export * as __bqComponentEntry from './BqIcon.js';
diff --git a/src/components/index.ts b/src/components/index.ts
index df1843b..e6ad428 100644
--- a/src/components/index.ts
+++ b/src/components/index.ts
@@ -14,17 +14,22 @@ import './card/BqCard.js';
 import './checkbox/BqCheckbox.js';
 import './chip/BqChip.js';
 import './combobox/BqCombobox.js';
+import './copy-button/BqCopyButton.js';
+import './date-picker/BqDatePicker.js';
 import './dialog/BqDialog.js';
 import './divider/BqDivider.js';
 import './dropdown-menu/BqDropdownMenu.js';
 import './drawer/BqDrawer.js';
 import './empty-state/BqEmptyState.js';
 import './file-upload/BqFileUpload.js';
+import './icon/BqIcon.js';
 import './icon-button/BqIconButton.js';
 import './input/BqInput.js';
 import './kbd/BqKbd.js';
+import './meter/BqMeter.js';
 import './number-input/BqNumberInput.js';
 import './pagination/BqPagination.js';
+import './pin-input/BqPinInput.js';
 import './popover/BqPopover.js';
 import './progress/BqProgress.js';
 import './radio/BqRadio.js';
@@ -43,6 +48,7 @@ import './tabs/BqTabs.js';
 import './textarea/BqTextarea.js';
 import './timeline/BqTimeline.js';
 import './toast/index.js';
+import './tree/BqTree.js';
 import './tooltip/BqTooltip.js';
 
 export * from './toast/index.js';
diff --git a/src/components/input/BqInput.ts b/src/components/input/BqInput.ts
index 580e4dc..fe4f072 100644
--- a/src/components/input/BqInput.ts
+++ b/src/components/input/BqInput.ts
@@ -27,10 +27,20 @@ import { escapeHtml } from '@bquery/bquery/security';
 import { t } from '../../i18n/index.js';
 import { uniqueId } from '../../utils/dom.js';
 import { bindFormProxy, syncFormProxy } from '../../utils/form.js';
-import { bind, release, store } from '../../utils/component.js';
-import { captureFocus, restoreFocus, type FocusSnapshot } from '../../utils/focus.js';
+import { bind, release } from '../../utils/component.js';
+import {
+  markFocus,
+  restorePreservedFocus,
+  trackFocus,
+} from '../../utils/focus.js';
+import { iconCss } from '../../utils/icons.js';
 import { bindValidation } from '../../utils/validation.js';
-import { baseStyles } from '../../utils/styles.js';
+import {
+  baseStyles,
+  fieldStyles,
+  focusRing,
+  reset,
+} from '../../utils/styles.js';
 
 type BqInputProps = {
   label: string;
@@ -46,6 +56,7 @@ type BqInputProps = {
   hint: string;
   maxlength: string;
   'show-counter': boolean;
+  clearable: boolean;
 };
 type BqInputState = { uid: string; passwordVisible: boolean };
 type BqInputEl = HTMLElement & {
@@ -53,14 +64,6 @@ type BqInputEl = HTMLElement & {
   getState<T>(k: string): T;
 };
 
-/**
- * Holds the pre-render focus snapshot. Rendering replaces the whole shadow
- * tree, so without this the field the user is typing in is destroyed on
- * every keystroke that reflects a value to an attribute.
- */
-const inputFocusStore = (owner: object) =>
-  store<{ snapshot?: FocusSnapshot | null }>(owner, () => ({}));
-
 const definition: ComponentDefinition<BqInputProps, BqInputState> = {
   props: {
     label: { type: String, default: '' },
@@ -76,6 +79,7 @@ const definition: ComponentDefinition<BqInputProps, BqInputState> = {
     hint: { type: String, default: '' },
     maxlength: { type: String, default: '' },
     'show-counter': { type: Boolean, default: false },
+    clearable: { type: Boolean, default: false },
   },
   state: {
     uid: '',
@@ -83,54 +87,70 @@ const definition: ComponentDefinition<BqInputProps, BqInputState> = {
   },
   styles: css`
     ${baseStyles}
-    *, *::before, *::after { box-sizing: border-box; }
+    ${reset}
+    ${fieldStyles}
+    ${focusRing}
+    ${iconCss('eye', 'eye-off', 'x')}
     :host { display: block; }
-    .field { display: flex; flex-direction: column; gap: 0.375rem; }
-    .label { display: flex; align-items: center; gap: 0.25rem; font-size: var(--bq-font-size-sm,0.875rem); font-weight: var(--bq-font-weight-medium,500); color: var(--bq-text-base,#0f172a); font-family: var(--bq-font-family-sans); }
-    .required-mark { color: var(--bq-color-danger-600,#dc2626); }
     .input-wrap {
       display: flex; align-items: center;
-      border: 1.5px solid var(--bq-border-emphasis,#cbd5e1);
+      border: var(--bq-border-width-control,1.5px) solid var(--bq-border-emphasis,#cbd5e1);
       border-radius: var(--bq-radius-lg,0.5rem);
       background: var(--bq-bg-base,#fff);
-      transition: border-color var(--bq-duration-fast) var(--bq-easing-standard), box-shadow var(--bq-duration-fast) var(--bq-easing-standard);
+      transition: border-color var(--bq-duration-fast) var(--bq-easing-standard),
+                  box-shadow var(--bq-duration-fast) var(--bq-easing-standard);
       overflow: hidden;
     }
+    .input-wrap:hover { border-color: var(--bq-border-strong,#94a3b8); }
     .input-wrap:focus-within { border-color: var(--bq-border-focus,#2563eb); box-shadow: var(--bq-focus-ring); }
     :host([error]:not([error=""])) .input-wrap { border-color: var(--bq-color-danger-500,#ef4444); }
     :host([error]:not([error=""])) .input-wrap:focus-within { border-color: var(--bq-color-danger-500,#ef4444); box-shadow: var(--bq-focus-ring-danger); }
-    :host([disabled]) .input-wrap { opacity: 0.5; cursor: not-allowed; background: var(--bq-bg-muted,#f1f5f9); }
-    .slot-wrap { display: flex; align-items: center; padding: 0 0.5rem; color: var(--bq-text-muted,#475569); }
+    :host([disabled]) .input-wrap { opacity: 0.55; cursor: not-allowed; background: var(--bq-bg-muted,#f1f5f9); }
+    :host([disabled]) .input-wrap:hover { border-color: var(--bq-border-emphasis,#cbd5e1); }
+    :host([readonly]) .input-wrap { background: var(--bq-bg-subtle,#f8fafc); }
+
+    /* Spacing lives on the slotted content, not on the wrapper: a wrapper with
+       padding reserves it even when nothing is slotted, which left every field
+       without a prefix looking lopsided next to one that had it. */
+    .slot-wrap { display: flex; align-items: center; color: var(--bq-text-muted,#475569); }
+    .slot-wrap ::slotted(*) { margin-inline: 0.5rem; }
+
     input {
       flex: 1; border: none; outline: none; background: transparent;
-      color: var(--bq-text-base,#0f172a); font-family: var(--bq-font-family-sans); width: 100%;
+      color: var(--bq-text-base,#0f172a);
+      font-family: var(--bq-font-family-sans);
+      inline-size: 100%; min-inline-size: 0;
     }
-    :host([size="sm"]) input { font-size: 0.875rem; padding: 0.375rem 0.75rem; min-height: 2rem; }
-    :host([size="md"]) input, :host(:not([size])) input { font-size: 1rem; padding: 0.5rem 0.875rem; min-height: 2.5rem; }
-    :host([size="lg"]) input { font-size: 1.125rem; padding: 0.625rem 1rem; min-height: 3rem; }
+    :host([size="sm"]) input { font-size: var(--bq-font-size-sm,0.875rem); padding: 0.375rem var(--bq-control-padding-sm,0.75rem); min-block-size: var(--bq-control-height-sm,2rem); }
+    :host([size="md"]) input, :host(:not([size])) input { font-size: var(--bq-font-size-md,1rem); padding: 0.5rem var(--bq-control-padding-md,0.875rem); min-block-size: var(--bq-control-height-md,2.5rem); }
+    :host([size="lg"]) input { font-size: var(--bq-font-size-lg,1.125rem); padding: 0.625rem var(--bq-control-padding-lg,1rem); min-block-size: var(--bq-control-height-lg,3rem); }
     input::placeholder { color: var(--bq-text-subtle,#94a3b8); }
     input:disabled { cursor: not-allowed; }
-    .hint { font-size: var(--bq-font-size-sm,0.875rem); color: var(--bq-text-muted,#475569); font-family: var(--bq-font-family-sans); }
-    .error-msg { font-size: var(--bq-font-size-sm,0.875rem); color: var(--bq-color-danger-600,#dc2626); font-family: var(--bq-font-family-sans); }
+    /* The browser's own search affordance duplicates the clear button. */
+    input[type="search"]::-webkit-search-cancel-button { -webkit-appearance: none; appearance: none; }
+
     .footer { display: flex; align-items: center; justify-content: space-between; gap: 0.5rem; }
-    .counter { font-size: var(--bq-font-size-sm,0.875rem); color: var(--bq-text-muted,#475569); font-family: var(--bq-font-family-sans); margin-left: auto; }
+    .counter {
+      font-size: var(--bq-font-size-sm,0.875rem);
+      color: var(--bq-text-muted,#475569);
+      font-family: var(--bq-font-family-sans);
+      margin-inline-start: auto;
+      font-variant-numeric: tabular-nums;
+    }
     .counter[data-over="true"] { color: var(--bq-color-danger-600,#dc2626); }
-    .password-toggle {
+
+    .affix-btn {
       display: inline-flex; align-items: center; justify-content: center;
       background: none; border: none; cursor: pointer;
-      padding: 0 0.5rem; margin-inline-start: 0.25rem;
-      border-inline-start: 1px solid var(--bq-border-base,#e2e8f0);
-      color: var(--bq-text-muted,#475569); font-size: 0.875rem; line-height: 1;
-      align-self: stretch;
-      transition: color var(--bq-duration-fast) var(--bq-easing-standard), background var(--bq-duration-fast) var(--bq-easing-standard);
-    }
-    .password-toggle:hover { color: var(--bq-text-base,#0f172a); background: var(--bq-bg-subtle,#f8fafc); }
-    .password-toggle:disabled { cursor: not-allowed; opacity: 0.5; }
-    .password-toggle:focus-visible { outline: 2px solid transparent; box-shadow: var(--bq-focus-ring); border-radius: var(--bq-radius-sm,0.25rem); }
-    .pw-icon { font-size: 1.125rem; line-height: 1; }
-    @media (prefers-reduced-motion: reduce) {
-      input, .input-wrap, .password-toggle { transition: none; }
+      padding-inline: 0.5rem; align-self: stretch;
+      color: var(--bq-text-muted,#475569);
+      --bq-icon-size: 1.125rem;
+      transition: color var(--bq-duration-fast) var(--bq-easing-standard),
+                  background-color var(--bq-duration-fast) var(--bq-easing-standard);
     }
+    .affix-btn:hover { color: var(--bq-text-base,#0f172a); background: var(--bq-bg-hover,rgba(15,23,42,0.04)); }
+    .affix-btn:disabled { cursor: not-allowed; opacity: 0.5; }
+    .password-toggle { border-inline-start: 1px solid var(--bq-border-base,#e2e8f0); }
   `,
   connected() {
     const self = this as unknown as BqInputEl;
@@ -200,22 +220,52 @@ const definition: ComponentDefinition<BqInputProps, BqInputState> = {
         self.setState('passwordVisible', !current);
       }
     };
+    // Toggling the password eye or clearing the field writes state, which
+    // re-renders and would otherwise drop the caret on the floor.
+    trackFocus(self, scope);
+
+    const clear = (e: Event) => {
+      if (self.hasAttribute('disabled') || self.hasAttribute('readonly')) return;
+      if (!(e.target as Element)?.closest('.clear-btn')) return;
+      self.setAttribute('value', '');
+      proxy.setValue('');
+      const field = self.shadowRoot?.querySelector(
+        'input'
+      ) as HTMLInputElement | null;
+      if (field) field.value = '';
+      field?.focus();
+      self.dispatchEvent(
+        new CustomEvent('bq-input', {
+          detail: { value: '' },
+          bubbles: true,
+          composed: true,
+        })
+      );
+      self.dispatchEvent(
+        new CustomEvent('bq-change', {
+          detail: { value: '' },
+          bubbles: true,
+          composed: true,
+        })
+      );
+    };
+
     const shadow = self.shadowRoot;
     scope.on(shadow, 'input', ih);
     scope.on(shadow, 'change', ch);
     scope.on(shadow, 'focusin', fh);
     scope.on(shadow, 'focusout', bh);
     scope.on(shadow, 'click', pwToggle);
+    scope.on(shadow, 'click', clear);
   },
   disconnected() {
     release(this);
   },
   beforeUpdate() {
-    inputFocusStore(this).snapshot = captureFocus(this.shadowRoot);
+    markFocus(this);
   },
   updated() {
-    restoreFocus(this.shadowRoot, inputFocusStore(this).snapshot);
-    inputFocusStore(this).snapshot = null;
+    restorePreservedFocus(this);
     const self = this as unknown as BqInputEl;
     if (
       this.getAttribute('type') !== 'password' &&
@@ -236,6 +286,11 @@ const definition: ComponentDefinition<BqInputProps, BqInputState> = {
     const charCount = props.value.length;
     const isOver = showCounter && charCount > maxLen;
     const hasFooter = hasError || Boolean(props.hint) || showCounter;
+    const showClear =
+      props.clearable &&
+      props.value.length > 0 &&
+      !props.disabled &&
+      !props.readonly;
     const describedByParts: string[] = [];
     if (hasError) describedByParts.push(`${uid}-err`);
     else if (props.hint) describedByParts.push(`${uid}-hint`);
@@ -268,9 +323,14 @@ const definition: ComponentDefinition<BqInputProps, BqInputState> = {
             ${describedBy ? `aria-describedby="${describedBy}"` : ''}
             ${hasError ? `aria-errormessage="${uid}-err"` : ''}
           />
+          ${
+            showClear
+              ? `<button type="button" class="affix-btn clear-btn" part="clear" aria-label="${escapeHtml(t('input.clearValue'))}" tabindex="-1"><span class="icon" data-icon="x" aria-hidden="true"></span></button>`
+              : ''
+          }
           ${isPassword
-            ? `<button type="button" class="password-toggle" part="password-toggle" aria-label="${escapeHtml(state.passwordVisible ? t('input.hidePassword') : t('input.showPassword'))}" aria-pressed="${state.passwordVisible ? 'true' : 'false'}" ${props.disabled || props.readonly ? 'disabled aria-disabled="true"' : ''}>
-                <span class="pw-icon" aria-hidden="true">${state.passwordVisible ? '&#9673;' : '&#9678;'}</span>
+            ? `<button type="button" class="affix-btn password-toggle" part="password-toggle" aria-label="${escapeHtml(state.passwordVisible ? t('input.hidePassword') : t('input.showPassword'))}" aria-pressed="${state.passwordVisible ? 'true' : 'false'}" ${props.disabled || props.readonly ? 'disabled aria-disabled="true"' : ''}>
+                <span class="icon" data-icon="${state.passwordVisible ? 'eye-off' : 'eye'}" aria-hidden="true"></span>
               </button>`
             : ''}
           <span class="slot-wrap" part="suffix"
diff --git a/src/components/meter/BqMeter.ts b/src/components/meter/BqMeter.ts
new file mode 100644
index 0000000..6b2d8c2
--- /dev/null
+++ b/src/components/meter/BqMeter.ts
@@ -0,0 +1,198 @@
+/**
+ * Meter — a scalar measurement inside a known range.
+ *
+ * Not a progress bar, and the distinction is not pedantic: progress runs from
+ * nothing to done and only ever goes up, while a meter shows a *level* — disk
+ * usage, password strength, a budget — which can sit anywhere and where the
+ * interesting question is whether the value is in a good part of the range.
+ *
+ * That is what `low`, `high` and `optimum` encode, following the semantics of
+ * the native `<meter>` element: the bar colours itself green, amber or red
+ * depending on which band the value falls in and which end is preferable.
+ *
+ * @element bq-meter
+ * @prop {number}  value
+ * @prop {number}  min
+ * @prop {number}  max
+ * @prop {number}  low      - Upper bound of the "low" band
+ * @prop {number}  high     - Lower bound of the "high" band
+ * @prop {number}  optimum  - Where in the range is best
+ * @prop {string}  label
+ * @prop {string}  value-text - Overrides the rendered value, e.g. "72 GB of 100 GB"
+ * @prop {boolean} show-value
+ * @prop {string}  size     - sm | md | lg
+ */
+import type { ComponentDefinition } from '@bquery/bquery/component';
+import { component, css, html } from '@bquery/bquery/component';
+import { escapeHtml } from '@bquery/bquery/security';
+import { baseStyles, fieldStyles, reset } from '../../utils/styles.js';
+
+type BqMeterProps = {
+  value: number;
+  min: number;
+  max: number;
+  low: number;
+  high: number;
+  optimum: number;
+  label: string;
+  'value-text': string;
+  'show-value': boolean;
+  size: string;
+};
+
+/** Which band a meter reading falls into, relative to the preferred end. */
+export type MeterLevel = 'optimum' | 'suboptimum' | 'poor';
+
+/**
+ * Classifies a value the way the HTML `<meter>` element does.
+ *
+ * The bands themselves say nothing about good or bad — `optimum` does. A disk
+ * gauge wants a low reading, a battery wants a high one, and the same `low`
+ * and `high` bounds serve both depending on where the optimum sits.
+ */
+export function meterLevel(
+  value: number,
+  min: number,
+  max: number,
+  low: number,
+  high: number,
+  optimum: number
+): MeterLevel {
+  const inLow = value < low;
+  const inHigh = value > high;
+
+  if (optimum < low) {
+    // Lower is better.
+    if (inLow) return 'optimum';
+    return inHigh ? 'poor' : 'suboptimum';
+  }
+  if (optimum > high) {
+    // Higher is better.
+    if (inHigh) return 'optimum';
+    return inLow ? 'poor' : 'suboptimum';
+  }
+  // The middle band is preferred; both extremes are equally wrong.
+  if (!inLow && !inHigh) return 'optimum';
+  return 'suboptimum';
+}
+
+/** Clamps a value into `[min, max]`, tolerating a reversed or degenerate range. */
+function clamp(value: number, min: number, max: number): number {
+  if (!Number.isFinite(value)) return min;
+  if (max <= min) return min;
+  return Math.min(max, Math.max(min, value));
+}
+
+const definition: ComponentDefinition<BqMeterProps> = {
+  props: {
+    value: { type: Number, default: 0 },
+    min: { type: Number, default: 0 },
+    max: { type: Number, default: 100 },
+    low: { type: Number, default: Number.NaN },
+    high: { type: Number, default: Number.NaN },
+    optimum: { type: Number, default: Number.NaN },
+    label: { type: String, default: '' },
+    'value-text': { type: String, default: '' },
+    'show-value': { type: Boolean, default: false },
+    size: { type: String, default: 'md' },
+  },
+  sanitize: { allowAttributes: ['style'] },
+  styles: css`
+    ${baseStyles}
+    ${reset}
+    ${fieldStyles}
+    :host { display: block; }
+    .field { gap: 0.375rem; }
+    .head {
+      display: flex; align-items: baseline; justify-content: space-between;
+      gap: 0.75rem;
+    }
+    .value {
+      font-size: var(--bq-font-size-sm, 0.875rem);
+      font-weight: var(--bq-font-weight-medium, 500);
+      color: var(--bq-text-muted, #475569);
+      font-variant-numeric: tabular-nums;
+    }
+    .track {
+      position: relative;
+      block-size: var(--bq-meter-height, 0.5rem);
+      inline-size: 100%;
+      background: var(--bq-bg-muted, #f1f5f9);
+      border-radius: var(--bq-radius-full, 9999px);
+      overflow: hidden;
+    }
+    :host([size='sm']) .track { --bq-meter-height: 0.25rem; }
+    :host([size='lg']) .track { --bq-meter-height: 0.75rem; }
+    .bar {
+      block-size: 100%;
+      border-radius: inherit;
+      background: var(--bq-color-primary-600, #2563eb);
+      transition: inline-size var(--bq-duration-slow) var(--bq-easing-decelerate),
+                  background-color var(--bq-duration-normal) var(--bq-easing-standard);
+    }
+    .bar[data-level='optimum'] { background: var(--bq-color-success-600, #16a34a); }
+    .bar[data-level='suboptimum'] { background: var(--bq-color-warning-500, #f59e0b); }
+    .bar[data-level='poor'] { background: var(--bq-color-danger-600, #dc2626); }
+
+    @media (forced-colors: active) {
+      .track { border: 1px solid CanvasText; }
+      .bar { background: Highlight !important; }
+    }
+  `,
+  render({ props }) {
+    const min = Number.isFinite(props.min) ? props.min : 0;
+    const max = Number.isFinite(props.max) ? props.max : 100;
+    const value = clamp(props.value, min, max);
+    const span = max - min;
+    const ratio = span > 0 ? (value - min) / span : 0;
+    const percent = Math.round(ratio * 1000) / 10;
+
+    // Bands are optional; a meter with none is a plain gauge in the accent
+    // colour, which is the right default for "just show me the level".
+    const graded =
+      Number.isFinite(props.low) ||
+      Number.isFinite(props.high) ||
+      Number.isFinite(props.optimum);
+    const low = Number.isFinite(props.low) ? props.low : min;
+    const high = Number.isFinite(props.high) ? props.high : max;
+    const optimum = Number.isFinite(props.optimum) ? props.optimum : max;
+    const level = graded
+      ? meterLevel(value, min, max, low, high, optimum)
+      : '';
+
+    const valueText =
+      props['value-text'].trim() || `${value}${span > 0 ? ` / ${max}` : ''}`;
+
+    return html`
+      <div class="field" part="field">
+        ${
+          props.label || props['show-value']
+            ? `<div class="head">
+                ${props.label ? `<span class="label" part="label">${escapeHtml(props.label)}</span>` : '<span></span>'}
+                ${props['show-value'] ? `<span class="value" part="value">${escapeHtml(valueText)}</span>` : ''}
+              </div>`
+            : ''
+        }
+        <div
+          class="track"
+          part="track"
+          role="meter"
+          aria-valuenow="${escapeHtml(String(value))}"
+          aria-valuemin="${escapeHtml(String(min))}"
+          aria-valuemax="${escapeHtml(String(max))}"
+          aria-valuetext="${escapeHtml(valueText)}"
+          ${props.label ? `aria-label="${escapeHtml(props.label)}"` : ''}
+        >
+          <div
+            class="bar"
+            part="bar"
+            ${level ? `data-level="${level}"` : ''}
+            style="inline-size: ${percent}%"
+          ></div>
+        </div>
+      </div>
+    `;
+  },
+};
+
+component<BqMeterProps>('bq-meter', definition);
diff --git a/src/components/meter/index.ts b/src/components/meter/index.ts
new file mode 100644
index 0000000..fdf6295
--- /dev/null
+++ b/src/components/meter/index.ts
@@ -0,0 +1 @@
+export * as __bqComponentEntry from './BqMeter.js';
diff --git a/src/components/number-input/BqNumberInput.ts b/src/components/number-input/BqNumberInput.ts
index 7370286..97ab52e 100644
--- a/src/components/number-input/BqNumberInput.ts
+++ b/src/components/number-input/BqNumberInput.ts
@@ -28,7 +28,8 @@ import { bind, host, release, store } from '../../utils/component.js';
 import { uniqueId } from '../../utils/dom.js';
 import { createFormProxy, type FormProxy } from '../../utils/form.js';
 import { bindValidation } from '../../utils/validation.js';
-import { baseStyles, reset, srOnly } from '../../utils/styles.js';
+import { iconCss } from '../../utils/icons.js';
+import { baseStyles, focusRing, reset, srOnly } from '../../utils/styles.js';
 
 type BqNumberInputProps = {
   value: number;
@@ -106,6 +107,8 @@ const definition: ComponentDefinition<BqNumberInputProps, BqNumberInputState> =
     ${baseStyles}
     ${reset}
     ${srOnly}
+    ${focusRing}
+    ${iconCss('plus', 'minus')}
     :host { display: block; }
     .field { font-family: var(--bq-font-family-sans); }
     .label {
@@ -115,7 +118,7 @@ const definition: ComponentDefinition<BqNumberInputProps, BqNumberInputState> =
       color: var(--bq-text-base,#0f172a);
       margin-bottom: 0.375rem;
     }
-    .required { color: var(--bq-color-danger-600,#dc2626); margin-left: 0.125rem; }
+    .required { color: var(--bq-color-danger-600,#dc2626); margin-inline-start: 0.125rem; }
     .control {
       display: flex; align-items: stretch;
       border: 1.5px solid var(--bq-border-emphasis,#cbd5e1);
@@ -134,7 +137,7 @@ const definition: ComponentDefinition<BqNumberInputProps, BqNumberInputState> =
       flex: 1 1 auto; min-width: 0; width: 100%;
       border: none; outline: none; background: transparent;
       font-family: inherit; color: var(--bq-text-base,#0f172a);
-      text-align: var(--bq-number-input-align, left);
+      text-align: var(--bq-number-input-align, start);
       /* The custom stepper replaces the native one. */
       -moz-appearance: textfield; appearance: textfield;
     }
@@ -156,8 +159,9 @@ const definition: ComponentDefinition<BqNumberInputProps, BqNumberInputState> =
     .step:hover:not(:disabled) { background: var(--bq-bg-emphasis,#e2e8f0); color: var(--bq-text-base,#0f172a); }
     .step:disabled { opacity: 0.4; cursor: not-allowed; }
     .step:focus-visible { outline: 2px solid transparent; box-shadow: var(--bq-focus-ring); z-index: 1; }
-    .step[data-action="decrement"] { border-right: 1px solid var(--bq-border-base,#e2e8f0); }
-    .step[data-action="increment"] { border-left: 1px solid var(--bq-border-base,#e2e8f0); }
+    .step { --bq-icon-size: 1rem; }
+    .step[data-action="decrement"] { border-inline-end: 1px solid var(--bq-border-base,#e2e8f0); }
+    .step[data-action="increment"] { border-inline-start: 1px solid var(--bq-border-base,#e2e8f0); }
 
     .affix { display: inline-flex; align-items: center; padding: 0 0.5rem; color: var(--bq-text-subtle,#94a3b8); }
     .message { font-size: var(--bq-font-size-xs,0.75rem); margin-top: 0.375rem; }
@@ -307,7 +311,7 @@ const definition: ComponentDefinition<BqNumberInputProps, BqNumberInputState> =
             aria-label="${escapeHtml(t('numberInput.decrement'))}"
             ${bool('disabled', locked || atMin)}
             tabindex="-1"
-          >&minus;</button>
+          ><span class="icon" data-icon="minus" aria-hidden="true"></span></button>
           <span class="affix"><slot name="prefix"></slot></span>
           <input
             id="${escapeHtml(inputId)}"
@@ -334,7 +338,7 @@ const definition: ComponentDefinition<BqNumberInputProps, BqNumberInputState> =
             aria-label="${escapeHtml(t('numberInput.increment'))}"
             ${bool('disabled', locked || atMax)}
             tabindex="-1"
-          >&plus;</button>
+          ><span class="icon" data-icon="plus" aria-hidden="true"></span></button>
         </div>
         ${
           props.error
diff --git a/src/components/pagination/BqPagination.ts b/src/components/pagination/BqPagination.ts
index d5667f4..c50ddc4 100644
--- a/src/components/pagination/BqPagination.ts
+++ b/src/components/pagination/BqPagination.ts
@@ -12,7 +12,8 @@ import type { ComponentDefinition } from '@bquery/bquery/component';
 import { bool, component, css, html } from '@bquery/bquery/component';
 import { t } from '../../i18n/index.js';
 import { bind, host, release } from '../../utils/component.js';
-import { baseStyles } from '../../utils/styles.js';
+import { iconCss } from '../../utils/icons.js';
+import { baseStyles, focusRing, reset } from '../../utils/styles.js';
 
 type BqPaginationProps = {
   page: number;
@@ -53,7 +54,9 @@ const definition: ComponentDefinition<BqPaginationProps> = {
   },
   styles: css`
     ${baseStyles}
-    *, *::before, *::after { box-sizing: border-box; }
+    ${reset}
+    ${focusRing}
+    ${iconCss('chevron-left', 'chevron-right', 'chevrons-left', 'chevrons-right', 'more-horizontal')}
     :host { display: block; }
     .pagination { display: flex; align-items: center; gap: 0.25rem; flex-wrap: wrap; font-family: var(--bq-font-family-sans); }
     :host([disabled]) .pagination { opacity: 0.5; pointer-events: none; }
@@ -65,15 +68,21 @@ const definition: ComponentDefinition<BqPaginationProps> = {
       background: var(--bq-bg-base,#fff); color: var(--bq-text-base,#0f172a);
       font-size: var(--bq-font-size-sm,0.875rem); font-weight: var(--bq-font-weight-medium,500);
       cursor: pointer; font-family: inherit;
-      transition: all var(--bq-duration-fast) var(--bq-easing-standard);
+      transition: color var(--bq-duration-fast) var(--bq-easing-standard),
+                  background-color var(--bq-duration-fast) var(--bq-easing-standard),
+                  border-color var(--bq-duration-fast) var(--bq-easing-standard),
+                  transform var(--bq-duration-instant) var(--bq-easing-standard);
     }
-    .page-btn:hover:not(:disabled):not([data-current="true"]) { background: var(--bq-bg-muted,#f1f5f9); border-color: var(--bq-color-primary-300,#93c5fd); }
-    .page-btn[data-current="true"] { background: var(--bq-color-primary-600,#2563eb); border-color: var(--bq-color-primary-600,#2563eb); color: #fff; }
+    .page-btn:hover:not(:disabled):not([data-current="true"]) { background: var(--bq-bg-muted,#f1f5f9); border-color: var(--bq-border-strong,#94a3b8); }
+    .page-btn:active:not(:disabled) { transform: translateY(1px); }
+    .page-btn[data-current="true"] { background: var(--bq-color-primary-600,#2563eb); border-color: var(--bq-color-primary-600,#2563eb); color: var(--bq-text-on-primary,#fff); }
     .page-btn:disabled { opacity: 0.45; cursor: not-allowed; }
-    .page-btn:focus-visible { outline: 2px solid transparent; box-shadow: var(--bq-focus-ring); }
-    .ellipsis { display: inline-flex; align-items: center; justify-content: center; min-width: 2.25rem; height: 2.25rem; color: var(--bq-text-subtle,#94a3b8); font-size: var(--bq-font-size-sm,0.875rem); }
-    @media (prefers-reduced-motion: reduce) {
-      .page-btn { transition: none; }
+    .page-btn .icon { --bq-icon-size: 1.125rem; }
+    .ellipsis {
+      display: inline-flex; align-items: center; justify-content: center;
+      min-inline-size: 2.25rem; block-size: 2.25rem;
+      color: var(--bq-text-subtle,#94a3b8);
+      --bq-icon-size: 1.125rem;
     }
   `,
   connected() {
@@ -111,7 +120,7 @@ const definition: ComponentDefinition<BqPaginationProps> = {
     const pageItems = pages
       .map((p) => {
         if (p === '...')
-          return '<span class="ellipsis" role="separator" aria-hidden="true">&#8230;</span>';
+          return '<span class="ellipsis icon" data-icon="more-horizontal" role="separator" aria-hidden="true"></span>';
         return `<button class="page-btn" data-page="${p}" data-current="${p === page ? 'true' : 'false'}" ${p === page ? 'aria-current="page"' : ''} type="button" aria-label="${t('pagination.page')} ${p}">${p}</button>`;
       })
       .join('');
@@ -125,7 +134,7 @@ const definition: ComponentDefinition<BqPaginationProps> = {
                 ${prevDisabled ? 'disabled' : ''}
                 aria-label="${t('pagination.firstPage')}"
                 type="button"
-              >&#171;</button>`
+              ><span class="icon" data-icon="chevrons-left" aria-hidden="true"></span></button>`
             : ''}
           <button
             class="page-btn"
@@ -134,7 +143,7 @@ const definition: ComponentDefinition<BqPaginationProps> = {
             aria-label="${t('pagination.prev')}"
             type="button"
           >
-            &#8249;
+            <span class="icon" data-icon="chevron-left" aria-hidden="true"></span>
           </button>
           ${pageItems}
           <button
@@ -144,7 +153,7 @@ const definition: ComponentDefinition<BqPaginationProps> = {
             aria-label="${t('pagination.next')}"
             type="button"
           >
-            &#8250;
+            <span class="icon" data-icon="chevron-right" aria-hidden="true"></span>
           </button>
           ${showFirstLast
             ? `<button
@@ -153,7 +162,7 @@ const definition: ComponentDefinition<BqPaginationProps> = {
                 ${nextDisabled ? 'disabled' : ''}
                 aria-label="${t('pagination.lastPage')}"
                 type="button"
-              >&#187;</button>`
+              ><span class="icon" data-icon="chevrons-right" aria-hidden="true"></span></button>`
             : ''}
         </div>
       </nav>
diff --git a/src/components/pin-input/BqPinInput.ts b/src/components/pin-input/BqPinInput.ts
new file mode 100644
index 0000000..9e0e16a
--- /dev/null
+++ b/src/components/pin-input/BqPinInput.ts
@@ -0,0 +1,367 @@
+/**
+ * PIN / one-time-code input — a row of single-character cells.
+ *
+ * A verification code pasted from a text message arrives as one string, and
+ * typed one character at a time. Both have to work: paste distributes across
+ * the cells from wherever the caret is, typing advances, and Backspace in an
+ * empty cell steps back and clears the one before it.
+ *
+ * @element bq-pin-input
+ * @prop {number}  length      - Number of cells
+ * @prop {string}  value       - Current code
+ * @prop {string}  name        - Form field name
+ * @prop {string}  type        - numeric | alphanumeric | text
+ * @prop {boolean} mask        - Obscure the characters, like a password
+ * @prop {boolean} disabled
+ * @prop {boolean} readonly
+ * @prop {boolean} required
+ * @prop {string}  label
+ * @prop {string}  hint
+ * @prop {string}  error
+ * @prop {string}  size        - sm | md | lg
+ * @fires bq-input    - { value: string }
+ * @fires bq-change   - { value: string }
+ * @fires bq-complete - { value: string } once every cell is filled
+ */
+import type { ComponentDefinition } from '@bquery/bquery/component';
+import { bool, component, css, html } from '@bquery/bquery/component';
+import { escapeHtml } from '@bquery/bquery/security';
+import { t } from '../../i18n/index.js';
+import { bind, host, release } from '../../utils/component.js';
+import { uniqueId } from '../../utils/dom.js';
+import { markFocus, restorePreservedFocus } from '../../utils/focus.js';
+import { bindFormProxy, syncFormProxy } from '../../utils/form.js';
+import { baseStyles, fieldStyles, reset, srOnly } from '../../utils/styles.js';
+import { bindValidation } from '../../utils/validation.js';
+
+type BqPinInputProps = {
+  length: number;
+  value: string;
+  name: string;
+  type: string;
+  mask: boolean;
+  disabled: boolean;
+  readonly: boolean;
+  required: boolean;
+  label: string;
+  hint: string;
+  error: string;
+  size: string;
+};
+
+type BqPinInputState = { uid: string };
+
+/** Characters each `type` accepts. Anything else is dropped as it is typed. */
+const PATTERNS: Record<string, RegExp> = {
+  numeric: /[0-9]/,
+  alphanumeric: /[0-9a-zA-Z]/,
+  text: /[^\s]/,
+};
+
+/** Keeps only the characters valid for `type`, capped at `length`. */
+export function sanitizePin(raw: string, type: string, length: number): string {
+  const pattern = PATTERNS[type] ?? PATTERNS['numeric']!;
+  let out = '';
+  for (const ch of raw) {
+    if (pattern.test(ch)) out += ch;
+    if (out.length >= length) break;
+  }
+  return out;
+}
+
+/**
+ * Splices `insert` into `value` at `index`, overwriting the cells it covers.
+ *
+ * Overwriting rather than inserting is what makes a paste land predictably:
+ * dropping six digits onto a half-filled field replaces what was there
+ * instead of pushing it off the end.
+ */
+export function applyPinEdit(
+  value: string,
+  index: number,
+  insert: string,
+  length: number
+): string {
+  const cells = value.padEnd(length, ' ').slice(0, length).split('');
+  for (let i = 0; i < insert.length && index + i < length; i += 1) {
+    cells[index + i] = insert[i] as string;
+  }
+  return cells.join('').replace(/\s+$/, '');
+}
+
+const definition: ComponentDefinition<BqPinInputProps, BqPinInputState> = {
+  props: {
+    length: { type: Number, default: 6 },
+    value: { type: String, default: '' },
+    name: { type: String, default: '' },
+    type: { type: String, default: 'numeric' },
+    mask: { type: Boolean, default: false },
+    disabled: { type: Boolean, default: false },
+    readonly: { type: Boolean, default: false },
+    required: { type: Boolean, default: false },
+    label: { type: String, default: '' },
+    hint: { type: String, default: '' },
+    error: { type: String, default: '' },
+    size: { type: String, default: 'md' },
+  },
+  state: { uid: '' },
+  sanitize: { allowAttributes: ['inputmode', 'autocomplete'] },
+  styles: css`
+    ${baseStyles}
+    ${reset}
+    ${fieldStyles}
+    ${srOnly}
+    :host { display: block; }
+    .cells { display: flex; align-items: center; gap: 0.5rem; }
+    .cell {
+      inline-size: var(--bq-pin-size, 2.75rem);
+      block-size: var(--bq-pin-size, 2.75rem);
+      text-align: center;
+      font-family: var(--bq-font-family-mono);
+      font-size: var(--bq-font-size-lg, 1.125rem);
+      font-weight: var(--bq-font-weight-semibold, 600);
+      color: var(--bq-text-base, #0f172a);
+      background: var(--bq-bg-base, #fff);
+      border: var(--bq-border-width-control, 1.5px) solid var(--bq-border-emphasis, #cbd5e1);
+      border-radius: var(--bq-radius-lg, 0.5rem);
+      outline: none;
+      transition:
+        border-color var(--bq-duration-fast) var(--bq-easing-standard),
+        box-shadow var(--bq-duration-fast) var(--bq-easing-standard);
+    }
+    :host([size='sm']) .cell { --bq-pin-size: 2.25rem; font-size: var(--bq-font-size-md, 1rem); }
+    :host([size='lg']) .cell { --bq-pin-size: 3.25rem; font-size: var(--bq-font-size-xl, 1.25rem); }
+    .cell:hover:not(:disabled) { border-color: var(--bq-border-strong, #94a3b8); }
+    .cell:focus-visible,
+    .cell:focus {
+      border-color: var(--bq-border-focus, #2563eb);
+      box-shadow: var(--bq-focus-ring);
+    }
+    /* A filled cell is worth marking: on a six-cell row it is the only way to
+       see progress at a glance while the caret sits somewhere in the middle. */
+    .cell[data-filled='true'] { border-color: var(--bq-border-strong, #94a3b8); }
+    :host([error]:not([error=''])) .cell { border-color: var(--bq-color-danger-500, #ef4444); }
+    :host([error]:not([error=''])) .cell:focus { box-shadow: var(--bq-focus-ring-danger); }
+    .cell:disabled { opacity: 0.55; cursor: not-allowed; background: var(--bq-bg-muted, #f1f5f9); }
+    .cell:read-only { cursor: default; }
+  `,
+  connected() {
+    const self = host<BqPinInputState>(this);
+    const scope = bind(self);
+    if (!self.getState<string>('uid')) self.setState('uid', uniqueId('bq-pin'));
+
+    const length = () => {
+      const raw = Number(self.getAttribute('length') ?? 6);
+      return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : 6;
+    };
+    const type = () => self.getAttribute('type') ?? 'numeric';
+    const readValue = () => self.getAttribute('value') ?? '';
+    const isInteractive = () =>
+      !self.hasAttribute('disabled') && !self.hasAttribute('readonly');
+
+    const proxy = bindFormProxy(self, scope, { value: readValue });
+    bindValidation(self, scope, { value: readValue });
+
+    const cells = (): HTMLInputElement[] =>
+      Array.from(self.shadowRoot?.querySelectorAll('.cell') ?? []);
+
+    const focusCell = (index: number) => {
+      const list = cells();
+      const clamped = Math.max(0, Math.min(index, list.length - 1));
+      const cell = list[clamped];
+      if (!cell) return;
+      cell.focus();
+      cell.select();
+    };
+
+    /**
+     * Commits a new code and reports it.
+     *
+     * `bq-complete` is separate from `bq-change` on purpose: filling the last
+     * cell is the moment an application wants to submit, and detecting it from
+     * `bq-change` would mean re-deriving the length on every keystroke.
+     */
+    const commit = (next: string, caret: number) => {
+      const previous = readValue();
+      const size = length();
+      self.setAttribute('value', next);
+      proxy.setValue(next);
+      // The attribute write re-renders synchronously, so the cells that exist
+      // after it are the ones to move focus into.
+      focusCell(caret);
+      if (next === previous) return;
+      self.dispatchEvent(
+        new CustomEvent('bq-input', {
+          detail: { value: next },
+          bubbles: true,
+          composed: true,
+        })
+      );
+      self.dispatchEvent(
+        new CustomEvent('bq-change', {
+          detail: { value: next },
+          bubbles: true,
+          composed: true,
+        })
+      );
+      if (next.length === size) {
+        self.dispatchEvent(
+          new CustomEvent('bq-complete', {
+            detail: { value: next },
+            bubbles: true,
+            composed: true,
+          })
+        );
+      }
+    };
+
+    const indexOf = (target: EventTarget | null): number => {
+      const cell = target as HTMLInputElement | null;
+      if (!cell || !cell.classList?.contains('cell')) return -1;
+      return Number(cell.getAttribute('data-index') ?? -1);
+    };
+
+    scope.on(self.shadowRoot, 'input', (event) => {
+      const index = indexOf(event.target);
+      if (index < 0 || !isInteractive()) return;
+      markFocus(self);
+      const cell = event.target as HTMLInputElement;
+      const typed = sanitizePin(cell.value, type(), length());
+      const next = applyPinEdit(readValue(), index, typed, length());
+      // An empty edit means the character was rejected; re-render anyway so
+      // the cell drops what the user typed instead of showing it.
+      commit(next, typed ? index + typed.length : index);
+    });
+
+    scope.on(self.shadowRoot, 'keydown', (event) => {
+      const ke = event as KeyboardEvent;
+      const index = indexOf(ke.target);
+      if (index < 0) return;
+      const value = readValue();
+
+      switch (ke.key) {
+        case 'Backspace': {
+          if (!isInteractive()) return;
+          ke.preventDefault();
+          markFocus(self);
+          // A filled cell clears itself; an empty one steps back and clears
+          // its neighbour, which is what makes holding Backspace feel right.
+          const target = value[index] ? index : index - 1;
+          if (target < 0) return;
+          commit(applyPinEdit(value, target, ' ', length()).trimEnd(), target);
+          return;
+        }
+        case 'Delete': {
+          if (!isInteractive()) return;
+          ke.preventDefault();
+          markFocus(self);
+          commit(applyPinEdit(value, index, ' ', length()).trimEnd(), index);
+          return;
+        }
+        case 'ArrowLeft':
+          ke.preventDefault();
+          focusCell(index - 1);
+          return;
+        case 'ArrowRight':
+          ke.preventDefault();
+          focusCell(index + 1);
+          return;
+        case 'Home':
+          ke.preventDefault();
+          focusCell(0);
+          return;
+        case 'End':
+          ke.preventDefault();
+          focusCell(length() - 1);
+          return;
+      }
+    });
+
+    scope.on(self.shadowRoot, 'paste', (event) => {
+      const index = indexOf(event.target);
+      if (index < 0 || !isInteractive()) return;
+      event.preventDefault();
+      markFocus(self);
+      const clipboard = (event as ClipboardEvent).clipboardData;
+      const pasted = sanitizePin(
+        clipboard?.getData('text') ?? '',
+        type(),
+        length()
+      );
+      if (!pasted) return;
+      const next = applyPinEdit(readValue(), index, pasted, length());
+      commit(next, index + pasted.length);
+    });
+
+    // Clicking anywhere in a partly filled row lands on the first empty cell:
+    // editing the middle of a code is almost never what was meant.
+    scope.on(self.shadowRoot, 'focusin', (event) => {
+      const index = indexOf(event.target);
+      if (index < 0) return;
+      const value = readValue();
+      if (index <= value.length) return;
+      focusCell(value.length);
+    });
+  },
+  disconnected() {
+    release(this);
+  },
+  beforeUpdate() {
+    markFocus(this);
+  },
+  updated() {
+    restorePreservedFocus(this);
+    syncFormProxy(this);
+  },
+  render({ props, state }) {
+    const uid = state.uid || 'bq-pin';
+    const size = Number.isFinite(props.length) && props.length > 0
+      ? Math.floor(props.length)
+      : 6;
+    const value = sanitizePin(props.value, props.type, size);
+    const hasError = Boolean(props.error);
+    const hasHint = Boolean(props.hint) && !hasError;
+    const describedBy: string[] = [];
+    if (hasError) describedBy.push(`${uid}-err`);
+    if (hasHint) describedBy.push(`${uid}-hint`);
+    describedBy.push(`${uid}-progress`);
+
+    const cells = Array.from({ length: size }, (_, index) => {
+      const char = value[index] ?? '';
+      return `<input
+          class="cell"
+          part="cell"
+          data-index="${index}"
+          data-filled="${char ? 'true' : 'false'}"
+          type="${props.mask ? 'password' : 'text'}"
+          inputmode="${props.type === 'numeric' ? 'numeric' : 'text'}"
+          autocomplete="${index === 0 ? 'one-time-code' : 'off'}"
+          maxlength="1"
+          value="${escapeHtml(char)}"
+          aria-label="${escapeHtml(t('pinInput.cell', { index: index + 1, total: size }))}"
+          ${hasError ? 'aria-invalid="true"' : ''}
+          ${describedBy.length > 0 ? `aria-describedby="${escapeHtml(describedBy.join(' '))}"` : ''}
+          ${bool('disabled', props.disabled)}
+          ${bool('readonly', props.readonly)}
+        />`;
+    }).join('');
+
+    return html`
+      <div class="field" part="field" role="group" ${props.label ? `aria-labelledby="${escapeHtml(`${uid}-label`)}"` : ''}>
+        ${
+          props.label
+            ? `<span class="label" id="${escapeHtml(`${uid}-label`)}" part="label">${escapeHtml(props.label)}${props.required ? '<span class="required-mark" aria-hidden="true"> *</span>' : ''}</span>`
+            : ''
+        }
+        <div class="cells" part="cells">${cells}</div>
+        ${hasHint ? `<span class="hint" id="${uid}-hint" part="hint">${escapeHtml(props.hint)}</span>` : ''}
+        ${hasError ? `<span class="error-msg" id="${uid}-err" role="alert" part="error">${escapeHtml(props.error)}</span>` : ''}
+        <span class="sr-only" id="${uid}-progress" role="status" aria-live="polite"
+          >${escapeHtml(t('pinInput.progress', { count: value.length, total: size }))}</span
+        >
+      </div>
+    `;
+  },
+};
+
+component<BqPinInputProps, BqPinInputState>('bq-pin-input', definition);
diff --git a/src/components/pin-input/index.ts b/src/components/pin-input/index.ts
new file mode 100644
index 0000000..cbf5976
--- /dev/null
+++ b/src/components/pin-input/index.ts
@@ -0,0 +1 @@
+export * as __bqComponentEntry from './BqPinInput.js';
diff --git a/src/components/popover/BqPopover.ts b/src/components/popover/BqPopover.ts
index e3d9335..2161227 100644
--- a/src/components/popover/BqPopover.ts
+++ b/src/components/popover/BqPopover.ts
@@ -24,7 +24,8 @@ import type { Disposer } from '../../utils/component.js';
 import { bind, host, release, store } from '../../utils/component.js';
 import { uniqueId } from '../../utils/dom.js';
 import { autoPosition } from '../../utils/position.js';
-import { baseStyles, reset } from '../../utils/styles.js';
+import { iconCss } from '../../utils/icons.js';
+import { baseStyles, focusRing, reset } from '../../utils/styles.js';
 
 type BqPopoverProps = {
   open: boolean;
@@ -51,12 +52,14 @@ const definition: ComponentDefinition<BqPopoverProps, BqPopoverState> = {
   },
   styles: css`
     ${baseStyles}
+    ${focusRing}
+    ${iconCss('x')}
     ${reset}
     :host { display: inline-block; position: relative; }
     .panel {
       position: absolute; z-index: var(--bq-z-popover, 1100);
       min-width: 12rem; max-width: min(20rem, 90vw);
-      background: var(--bq-bg-base,#fff);
+      background: var(--bq-surface-overlay,#fff);
       color: var(--bq-text-base,#0f172a);
       border: 1px solid var(--bq-border-base,#e2e8f0);
       border-radius: var(--bq-radius-lg,0.5rem);
@@ -97,6 +100,7 @@ const definition: ComponentDefinition<BqPopoverProps, BqPopoverState> = {
       cursor: pointer; font-size: 1rem; line-height: 1;
     }
     .close:hover { background: var(--bq-bg-muted,#f1f5f9); color: var(--bq-text-base,#0f172a); }
+    .close { --bq-icon-size: 1rem; }
     .close:focus-visible { outline: 2px solid transparent; box-shadow: var(--bq-focus-ring); }
     .content { padding: 0.75rem 0.875rem; color: var(--bq-text-muted,#475569); }
     .header + .content { padding-top: 0.5rem; }
@@ -104,7 +108,7 @@ const definition: ComponentDefinition<BqPopoverProps, BqPopoverState> = {
 
     .arrow {
       position: absolute; width: 0.5rem; height: 0.5rem;
-      background: var(--bq-bg-base,#fff);
+      background: var(--bq-surface-overlay,#fff);
       border: 1px solid var(--bq-border-base,#e2e8f0);
       transform: rotate(45deg);
     }
@@ -269,7 +273,7 @@ const definition: ComponentDefinition<BqPopoverProps, BqPopoverState> = {
           heading || props.dismissible
             ? `<div class="header" part="header">
                  ${heading ? `<h2 class="heading" part="heading" id="${escapeHtml(headingId)}">${escapeHtml(heading)}</h2>` : '<span class="heading"></span>'}
-                 ${props.dismissible ? `<button type="button" class="close" part="close" aria-label="${escapeHtml(t('popover.close'))}">&times;</button>` : ''}
+                 ${props.dismissible ? `<button type="button" class="close" part="close" aria-label="${escapeHtml(t('popover.close'))}"><span class="icon" data-icon="x" aria-hidden="true"></span></button>` : ''}
                </div>`
             : ''
         }
diff --git a/src/components/progress/BqProgress.ts b/src/components/progress/BqProgress.ts
index 6333183..f8725ca 100644
--- a/src/components/progress/BqProgress.ts
+++ b/src/components/progress/BqProgress.ts
@@ -12,7 +12,7 @@ import type { ComponentDefinition } from '@bquery/bquery/component';
 import { component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { t } from '../../i18n/index.js';
-import { baseStyles } from '../../utils/styles.js';
+import { baseStyles, reset } from '../../utils/styles.js';
 
 type BqProgressProps = {
   value: number;
@@ -37,6 +37,7 @@ const definition: ComponentDefinition<BqProgressProps> = {
   },
   styles: css`
     ${baseStyles}
+    ${reset}
     :host { display: block; }
     .track {
       background: var(--bq-bg-emphasis,#e2e8f0); border-radius: var(--bq-radius-full,9999px);
diff --git a/src/components/radio/BqRadio.ts b/src/components/radio/BqRadio.ts
index 5ea83bb..5dd49bf 100644
--- a/src/components/radio/BqRadio.ts
+++ b/src/components/radio/BqRadio.ts
@@ -1,5 +1,11 @@
 /**
  * Radio button form control.
+ *
+ * Like `bq-checkbox`, the native input stays for semantics and keyboard/group
+ * behaviour and is rendered transparently over a drawn dial — a real radio
+ * exposes nothing but `accent-color`, so its ring weight, size and focus
+ * treatment would otherwise be whatever the operating system feels like.
+ *
  * @element bq-radio
  * @prop {string}  label    - Visible label
  * @prop {string}  name     - Input name (group)
@@ -15,7 +21,8 @@ import { bool, component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { bindFormProxy, syncFormProxy } from '../../utils/form.js';
 import { bind, host, release } from '../../utils/component.js';
-import { baseStyles } from '../../utils/styles.js';
+import { uniqueId } from '../../utils/dom.js';
+import { baseStyles, fieldStyles, reset } from '../../utils/styles.js';
 
 type BqRadioProps = {
   label: string;
@@ -27,7 +34,9 @@ type BqRadioProps = {
   hint: string;
 };
 
-const definition: ComponentDefinition<BqRadioProps> = {
+type BqRadioState = { uid: string };
+
+const definition: ComponentDefinition<BqRadioProps, BqRadioState> = {
   props: {
     label: { type: String, default: '' },
     name: { type: String, default: '' },
@@ -37,27 +46,89 @@ const definition: ComponentDefinition<BqRadioProps> = {
     required: { type: Boolean, default: false },
     hint: { type: String, default: '' },
   },
+  state: { uid: '' },
   styles: css`
     ${baseStyles}
-    *, *::before, *::after { box-sizing: border-box; }
+    ${reset}
+    ${fieldStyles}
     :host { display: block; }
-    .wrapper { display: flex; flex-direction: column; gap: 0.25rem; }
-    .control { display: flex; align-items: flex-start; gap: 0.625rem; cursor: pointer; }
-    :host([disabled]) .control { opacity: 0.5; cursor: not-allowed; pointer-events: none; }
-    input[type="radio"] {
-      width: 1.125rem; height: 1.125rem; flex-shrink: 0;
-      border: 2px solid var(--bq-border-emphasis,#cbd5e1);
-      border-radius: 50%; background: var(--bq-bg-base,#fff);
-      cursor: pointer; accent-color: var(--bq-color-primary-600,#2563eb); margin-top: 0.125rem;
+    .field { gap: 0.25rem; }
+    .control {
+      display: flex;
+      align-items: flex-start;
+      gap: 0.625rem;
+      cursor: pointer;
+      font-family: var(--bq-font-family-sans);
+    }
+    :host([disabled]) .control { opacity: 0.55; cursor: not-allowed; }
+
+    .dial-wrap {
+      position: relative;
+      display: inline-grid;
+      place-items: center;
+      flex: none;
+      margin-block-start: 0.125rem;
+    }
+    input {
+      position: absolute;
+      inset: 0;
+      inline-size: 100%;
+      block-size: 100%;
+      margin: 0;
+      opacity: 0;
+      cursor: inherit;
+    }
+    .dial {
+      inline-size: 1.125rem;
+      block-size: 1.125rem;
+      display: grid;
+      place-items: center;
+      border: var(--bq-border-width-control, 1.5px) solid var(--bq-border-strong, #94a3b8);
+      border-radius: var(--bq-radius-full, 9999px);
+      background: var(--bq-bg-base, #fff);
+      transition:
+        border-color var(--bq-duration-fast) var(--bq-easing-standard),
+        box-shadow var(--bq-duration-fast) var(--bq-easing-standard);
+    }
+    /* The mark is an inner disc rather than a filled circle: a ring reads as
+       "one of several" where a solid blob reads as a checkbox. */
+    .dial::after {
+      content: '';
+      inline-size: 0.625rem;
+      block-size: 0.625rem;
+      border-radius: var(--bq-radius-full, 9999px);
+      background: var(--bq-color-primary-600, #2563eb);
+      transform: scale(0);
+      transition: transform var(--bq-duration-fast) var(--bq-easing-spring);
+    }
+    .control:hover input:not(:disabled) ~ .dial { border-color: var(--bq-color-primary-500, #3b82f6); }
+    input:checked ~ .dial { border-color: var(--bq-color-primary-600, #2563eb); }
+    input:checked ~ .dial::after { transform: scale(1); }
+    input:focus-visible ~ .dial {
+      border-color: var(--bq-border-focus, #2563eb);
+      box-shadow: var(--bq-focus-ring);
+    }
+    input:disabled ~ .dial { background: var(--bq-bg-muted, #f1f5f9); }
+    input:checked:disabled ~ .dial::after { background: var(--bq-border-strong, #94a3b8); }
+
+    .label-text {
+      font-size: var(--bq-font-size-sm, 0.875rem);
+      color: var(--bq-text-base, #0f172a);
+      line-height: var(--bq-line-height-normal, 1.5);
+    }
+    .hint { padding-inline-start: 1.75rem; }
+
+    @media (forced-colors: active) {
+      .dial { forced-color-adjust: none; background: Canvas; border-color: CanvasText; }
+      input:checked ~ .dial { border-color: Highlight; }
+      .dial::after { background: Highlight; }
+      input:focus-visible ~ .dial { outline: 2px solid CanvasText; outline-offset: 2px; }
     }
-    input[type="radio"]:focus-visible { outline: 2px solid transparent; box-shadow: var(--bq-focus-ring); }
-    .label-text { font-size: var(--bq-font-size-sm,0.875rem); color: var(--bq-text-base,#0f172a); font-family: var(--bq-font-family-sans); line-height: 1.5; }
-    .required-mark { color: var(--bq-color-danger-600,#dc2626); }
-    .hint { font-size: var(--bq-font-size-sm,0.875rem); color: var(--bq-text-muted,#475569); font-family: var(--bq-font-family-sans); padding-inline-start: 1.75rem; }
   `,
   connected() {
-    const self = host(this);
+    const self = host<BqRadioState>(this);
     const scope = bind(self);
+    if (!self.getState<string>('uid')) self.setState('uid', uniqueId('bq-rd'));
 
     // Form proxy for native <form> participation
     const proxy = bindFormProxy(self, scope, {
@@ -71,6 +142,9 @@ const definition: ComponentDefinition<BqRadioProps> = {
       if (input.checked) self.setAttribute('checked', '');
       else self.removeAttribute('checked');
       proxy.setValue(input.checked ? (self.getAttribute('value') ?? '') : '');
+      // Each radio lives in its own shadow root, so the platform's "one per
+      // name" rule cannot see the siblings — unchecking them is up to us.
+      if (input.checked) uncheckSiblings(self);
       self.dispatchEvent(
         new CustomEvent('bq-change', {
           detail: {
@@ -90,29 +164,59 @@ const definition: ComponentDefinition<BqRadioProps> = {
   updated() {
     syncFormProxy(this);
   },
-  render({ props }) {
+  render({ props, state }) {
+    const uid = state.uid || 'bq-rd';
+    const hintId = `${uid}-hint`;
     return html`
-      <div class="wrapper" part="wrapper">
+      <div class="field" part="wrapper">
         <label class="control" part="control">
-          <input
-            type="radio"
-            part="input"
-            name="${escapeHtml(props.name)}"
-            value="${escapeHtml(props.value)}"
-            ${bool('checked', props.checked)}
-            ${bool('disabled', props.disabled)}
-            ${bool('required', props.required)}
-          />
+          <span class="dial-wrap">
+            <input
+              type="radio"
+              part="input"
+              name="${escapeHtml(props.name)}"
+              value="${escapeHtml(props.value)}"
+              ${bool('checked', props.checked)}
+              ${bool('disabled', props.disabled)}
+              ${bool('required', props.required)}
+              ${props.hint ? `aria-describedby="${escapeHtml(hintId)}"` : ''}
+            />
+            <span class="dial" part="dial" aria-hidden="true"></span>
+          </span>
           ${props.label
             ? `<span class="label-text" part="label">${escapeHtml(props.label)}${props.required ? '<span class="required-mark" aria-hidden="true"> *</span>' : ''}</span>`
             : ''}
         </label>
         ${props.hint
-          ? `<span class="hint" part="hint">${escapeHtml(props.hint)}</span>`
+          ? `<span class="hint" id="${escapeHtml(hintId)}" part="hint">${escapeHtml(props.hint)}</span>`
           : ''}
       </div>
     `;
   },
 };
 
-component<BqRadioProps>('bq-radio', definition);
+/**
+ * Clears the `checked` attribute from the other `bq-radio` elements sharing a
+ * name, scoped to the nearest form so two unrelated groups on one page do not
+ * clear each other.
+ */
+function uncheckSiblings(el: HTMLElement): void {
+  const name = el.getAttribute('name');
+  if (!name) return;
+  const root =
+    (el.closest('form') as Element | null) ??
+    (el.getRootNode() as Document | ShadowRoot);
+  const selector = `bq-radio[name="${name.replace(/["\\]/g, '\\$&')}"]`;
+  let peers: NodeListOf<Element>;
+  try {
+    peers = root.querySelectorAll(selector);
+  } catch {
+    return;
+  }
+  for (const peer of Array.from(peers)) {
+    if (peer === el) continue;
+    peer.removeAttribute('checked');
+  }
+}
+
+component<BqRadioProps, BqRadioState>('bq-radio', definition);
diff --git a/src/components/rating/BqRating.ts b/src/components/rating/BqRating.ts
index 41c3b83..d2e64bd 100644
--- a/src/components/rating/BqRating.ts
+++ b/src/components/rating/BqRating.ts
@@ -17,6 +17,7 @@ import { escapeHtml } from '@bquery/bquery/security';
 import { t } from '../../i18n/index.js';
 import { bind, host, release, store } from '../../utils/component.js';
 import { createFormProxy, type FormProxy } from '../../utils/form.js';
+import { iconCss } from '../../utils/icons.js';
 import { baseStyles, reset, srOnly } from '../../utils/styles.js';
 
 type BqRatingProps = {
@@ -54,6 +55,7 @@ const definition: ComponentDefinition<BqRatingProps> = {
     ${baseStyles}
     ${reset}
     ${srOnly}
+    ${iconCss('star', 'star-filled')}
     :host { display: inline-flex; }
     .rating {
       display: inline-flex; align-items: center; gap: 0.125rem;
@@ -68,9 +70,9 @@ const definition: ComponentDefinition<BqRatingProps> = {
                   transform var(--bq-duration-fast) var(--bq-easing-standard);
     }
     .star[data-filled="true"] { color: var(--bq-color-warning-500,#f59e0b); }
-    .rating[data-size="sm"] .star { font-size: 1rem; }
-    .rating[data-size="md"] .star { font-size: 1.375rem; }
-    .rating[data-size="lg"] .star { font-size: 1.75rem; }
+    .rating[data-size="sm"] .star { --bq-icon-size: 1rem; }
+    .rating[data-size="md"] .star { --bq-icon-size: 1.375rem; }
+    .rating[data-size="lg"] .star { --bq-icon-size: 1.75rem; }
     .star:focus-visible { outline: 2px solid transparent; box-shadow: var(--bq-focus-ring); border-radius: var(--bq-radius-sm,0.25rem); }
     :host(:not([readonly]):not([disabled])) .star:hover { transform: scale(1.12); }
     :host([readonly]) .star, :host([disabled]) .star { cursor: default; }
@@ -188,7 +190,7 @@ const definition: ComponentDefinition<BqRatingProps> = {
           aria-label="${escapeHtml(t('rating.valueText', { value: index, max }))}"
           tabindex="${interactive && (index === Math.max(1, Math.ceil(value)) || (value === 0 && index === 1)) ? '0' : '-1'}"
           ${interactive ? '' : 'disabled'}
-        >${filled ? '★' : '☆'}</button>
+        ><span class="icon" data-icon="${filled ? 'star-filled' : 'star'}" aria-hidden="true"></span></button>
       `;
     }).join('');
 
diff --git a/src/components/segmented-control/BqSegmentedControl.ts b/src/components/segmented-control/BqSegmentedControl.ts
index 48b6874..eb11b87 100644
--- a/src/components/segmented-control/BqSegmentedControl.ts
+++ b/src/components/segmented-control/BqSegmentedControl.ts
@@ -19,7 +19,7 @@ import { t } from '../../i18n/index.js';
 import { uniqueId } from '../../utils/dom.js';
 import { bindFormProxy, syncFormProxy } from '../../utils/form.js';
 import { bind, release, store } from '../../utils/component.js';
-import { baseStyles } from '../../utils/styles.js';
+import { baseStyles, reset } from '../../utils/styles.js';
 
 type BqSegmentedControlProps = {
   label: string;
@@ -59,7 +59,7 @@ const definition: ComponentDefinition<
   },
   styles: css`
     ${baseStyles}
-    *, *::before, *::after { box-sizing: border-box; }
+    ${reset}
     :host { display: block; }
     .field { display: flex; flex-direction: column; gap: 0.375rem; }
     .label {
diff --git a/src/components/select/BqSelect.ts b/src/components/select/BqSelect.ts
index 247c53b..571a36b 100644
--- a/src/components/select/BqSelect.ts
+++ b/src/components/select/BqSelect.ts
@@ -24,7 +24,13 @@ import {
 } from '../../utils/form.js';
 import { bind, host, release, store } from '../../utils/component.js';
 import { bindValidation } from '../../utils/validation.js';
-import { baseStyles } from '../../utils/styles.js';
+import { iconCss } from '../../utils/icons.js';
+import {
+  baseStyles,
+  fieldStyles,
+  focusRing,
+  reset,
+} from '../../utils/styles.js';
 
 type BqSelectProps = {
   label: string;
@@ -138,33 +144,42 @@ const definition: ComponentDefinition<BqSelectProps, BqSelectState> = {
   },
   styles: css`
     ${baseStyles}
-    *, *::before, *::after { box-sizing: border-box; }
+    ${reset}
+    ${fieldStyles}
+    ${focusRing}
+    ${iconCss('chevron-down')}
     :host { display: block; }
-    .field { display: flex; flex-direction: column; gap: 0.375rem; }
-    .label { font-size: var(--bq-font-size-sm,0.875rem); font-weight: var(--bq-font-weight-medium,500); color: var(--bq-text-base,#0f172a); font-family: var(--bq-font-family-sans); }
-    .required-mark { color: var(--bq-color-danger-600,#dc2626); }
-    .select-wrap { position: relative; }
+    .select-wrap { position: relative; display: flex; }
     select {
-      display: block; width: 100%;
-      border: 1.5px solid var(--bq-border-emphasis,#cbd5e1);
+      display: block; inline-size: 100%;
+      border: var(--bq-border-width-control,1.5px) solid var(--bq-border-emphasis,#cbd5e1);
       border-radius: var(--bq-radius-lg,0.5rem); background: var(--bq-bg-base,#fff);
       color: var(--bq-text-base,#0f172a); font-family: var(--bq-font-family-sans);
       appearance: none; -webkit-appearance: none;
-      padding-right: 2rem; outline: none; cursor: pointer;
-      transition: border-color var(--bq-duration-fast) var(--bq-easing-standard), box-shadow var(--bq-duration-fast) var(--bq-easing-standard);
+      padding-inline-end: 2.25rem; outline: none; cursor: pointer;
+      transition: border-color var(--bq-duration-fast) var(--bq-easing-standard),
+                  background-color var(--bq-duration-fast) var(--bq-easing-standard),
+                  box-shadow var(--bq-duration-fast) var(--bq-easing-standard);
     }
-    :host([size="sm"]) select { font-size: 0.875rem; padding: 0.375rem 2rem 0.375rem 0.75rem; min-height: 2rem; }
-    :host([size="md"]) select, :host(:not([size])) select { font-size: 1rem; padding: 0.5rem 2rem 0.5rem 0.875rem; min-height: 2.5rem; }
-    :host([size="lg"]) select { font-size: 1.125rem; padding: 0.625rem 2rem 0.625rem 1rem; min-height: 3rem; }
+    :host([size="sm"]) select { font-size: var(--bq-font-size-sm,0.875rem); padding-block: 0.375rem; padding-inline-start: var(--bq-control-padding-sm,0.75rem); min-block-size: var(--bq-control-height-sm,2rem); }
+    :host([size="md"]) select, :host(:not([size])) select { font-size: var(--bq-font-size-md,1rem); padding-block: 0.5rem; padding-inline-start: var(--bq-control-padding-md,0.875rem); min-block-size: var(--bq-control-height-md,2.5rem); }
+    :host([size="lg"]) select { font-size: var(--bq-font-size-lg,1.125rem); padding-block: 0.625rem; padding-inline-start: var(--bq-control-padding-lg,1rem); min-block-size: var(--bq-control-height-lg,3rem); }
+    select:hover:not(:disabled) { border-color: var(--bq-border-strong,#94a3b8); }
+    select:focus-visible { border-color: var(--bq-border-focus,#2563eb); box-shadow: var(--bq-focus-ring); }
+    /* Opening a native select fires no focus-visible in every browser, so the
+       ring is also drawn for plain :focus — a select is never focused by a
+       pointer without the list opening. */
     select:focus { border-color: var(--bq-border-focus,#2563eb); box-shadow: var(--bq-focus-ring); }
     :host([error]:not([error=""])) select { border-color: var(--bq-color-danger-500,#ef4444); }
-    :host([disabled]) select { opacity: 0.5; cursor: not-allowed; background: var(--bq-bg-muted,#f1f5f9); }
-    .arrow { position: absolute; right: 0.75rem; top: 50%; transform: translateY(-50%); pointer-events: none; color: var(--bq-text-muted,#475569); font-size: 0.75rem; }
-    .hint { font-size: var(--bq-font-size-sm,0.875rem); color: var(--bq-text-muted,#475569); font-family: var(--bq-font-family-sans); }
-    .error-msg { font-size: var(--bq-font-size-sm,0.875rem); color: var(--bq-color-danger-600,#dc2626); font-family: var(--bq-font-family-sans); }
-    @media (prefers-reduced-motion: reduce) {
-      select { transition: none; }
+    :host([error]:not([error=""])) select:focus { box-shadow: var(--bq-focus-ring-danger); }
+    :host([disabled]) select { opacity: 0.55; cursor: not-allowed; background: var(--bq-bg-muted,#f1f5f9); }
+    .arrow {
+      position: absolute; inset-inline-end: 0.75rem; inset-block-start: 50%;
+      transform: translateY(-50%); pointer-events: none;
+      color: var(--bq-text-muted,#475569);
+      --bq-icon-size: 1.125rem;
     }
+    :host([disabled]) .arrow { opacity: 0.55; }
   `,
   connected() {
     const self = host<BqSelectState>(this);
@@ -266,7 +281,7 @@ const definition: ComponentDefinition<BqSelectProps, BqSelectState> = {
           >
             ${optionsMarkup}
           </select>
-          <span class="arrow" aria-hidden="true">&#9660;</span>
+          <span class="arrow icon" data-icon="chevron-down" part="arrow" aria-hidden="true"></span>
         </div>
         ${hasHint
           ? `<span class="hint" id="${uid}-hint" part="hint">${escapeHtml(props.hint)}</span>`
diff --git a/src/components/skeleton/BqSkeleton.ts b/src/components/skeleton/BqSkeleton.ts
index 2cae3b6..25685e0 100644
--- a/src/components/skeleton/BqSkeleton.ts
+++ b/src/components/skeleton/BqSkeleton.ts
@@ -9,7 +9,7 @@
 import type { ComponentDefinition } from '@bquery/bquery/component';
 import { component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
-import { baseStyles } from '../../utils/styles.js';
+import { baseStyles, reset } from '../../utils/styles.js';
 
 type BqSkeletonProps = {
   variant: string;
@@ -57,6 +57,7 @@ const definition: ComponentDefinition<BqSkeletonProps> = {
   },
   styles: css`
     ${baseStyles}
+    ${reset}
     :host { display: block; }
     .skeleton {
       background: var(--bq-bg-emphasis,#e2e8f0);
diff --git a/src/components/slider/BqSlider.ts b/src/components/slider/BqSlider.ts
index ef39438..55ff92b 100644
--- a/src/components/slider/BqSlider.ts
+++ b/src/components/slider/BqSlider.ts
@@ -17,7 +17,7 @@ import { escapeHtml } from '@bquery/bquery/security';
 import { t } from '../../i18n/index.js';
 import { bindFormProxy, syncFormProxy } from '../../utils/form.js';
 import { bind, host, release } from '../../utils/component.js';
-import { baseStyles } from '../../utils/styles.js';
+import { baseStyles, reset } from '../../utils/styles.js';
 
 type BqSliderProps = {
   value: number;
@@ -34,6 +34,17 @@ function syncInputAccessibility(input: HTMLInputElement, value: number): void {
   input.setAttribute('aria-valuetext', t('slider.valueText', { value }));
 }
 
+/** How much of the track is behind the thumb, as a percentage. */
+export function sliderFill(value: number, min: number, max: number): number {
+  if (!Number.isFinite(value) || max <= min) return 0;
+  const clamped = Math.min(max, Math.max(min, value));
+  return ((clamped - min) / (max - min)) * 100;
+}
+
+function fillPercent(input: HTMLInputElement): number {
+  return sliderFill(Number(input.value), Number(input.min), Number(input.max));
+}
+
 const definition: ComponentDefinition<BqSliderProps> = {
   props: {
     value: { type: Number, default: 50 },
@@ -44,20 +55,96 @@ const definition: ComponentDefinition<BqSliderProps> = {
     disabled: { type: Boolean, default: false },
     'show-value': { type: Boolean, default: false },
   },
+  sanitize: { allowAttributes: ['style'] },
   styles: css`
     ${baseStyles}
-    *, *::before, *::after { box-sizing: border-box; }
+    ${reset}
     :host { display: block; }
     .wrapper { display: flex; flex-direction: column; gap: 0.375rem; font-family: var(--bq-font-family-sans); }
     .header { display: flex; justify-content: space-between; align-items: center; }
     .label-text { font-size: var(--bq-font-size-sm,0.875rem); font-weight: var(--bq-font-weight-medium,500); color: var(--bq-text-base,#0f172a); }
     .value { font-size: var(--bq-font-size-sm,0.875rem); color: var(--bq-text-muted,#475569); }
+    /* accent-color is all a native range exposes, so the track height, the
+       thumb size and the filled portion were whatever the platform decided.
+       The control is drawn here instead — which needs vendor pseudo-elements,
+       and they cannot share a selector list: one unknown selector invalidates
+       the whole rule, so WebKit and Gecko get their own. */
     input[type="range"] {
-      width: 100%; height: 0.375rem; cursor: pointer;
-      accent-color: var(--bq-color-primary-600,#2563eb);
+      --bq-slider-track: 0.375rem;
+      --bq-slider-thumb: 1.125rem;
+      inline-size: 100%;
+      block-size: var(--bq-slider-thumb);
+      margin: 0;
+      cursor: pointer;
+      appearance: none;
+      -webkit-appearance: none;
+      background: transparent;
     }
     input[type="range"]:disabled { opacity: 0.5; cursor: not-allowed; }
-    input[type="range"]:focus-visible { outline: 2px solid transparent; box-shadow: var(--bq-focus-ring); }
+    input[type="range"]:focus { outline: none; }
+
+    /* The filled portion is a gradient stop, because WebKit has no
+       "progress" pseudo-element the way Gecko does. */
+    input[type="range"]::-webkit-slider-runnable-track {
+      block-size: var(--bq-slider-track);
+      border-radius: var(--bq-radius-full,9999px);
+      background: linear-gradient(
+        to right,
+        var(--bq-color-primary-600,#2563eb) 0 var(--bq-slider-fill,0%),
+        var(--bq-bg-emphasis,#e2e8f0) var(--bq-slider-fill,0%) 100%
+      );
+    }
+    :host(:dir(rtl)) input[type="range"]::-webkit-slider-runnable-track {
+      background: linear-gradient(
+        to left,
+        var(--bq-color-primary-600,#2563eb) 0 var(--bq-slider-fill,0%),
+        var(--bq-bg-emphasis,#e2e8f0) var(--bq-slider-fill,0%) 100%
+      );
+    }
+    input[type="range"]::-webkit-slider-thumb {
+      appearance: none;
+      -webkit-appearance: none;
+      inline-size: var(--bq-slider-thumb);
+      block-size: var(--bq-slider-thumb);
+      margin-block-start: calc((var(--bq-slider-track) - var(--bq-slider-thumb)) / 2);
+      border-radius: var(--bq-radius-full,9999px);
+      background: var(--bq-bg-base,#fff);
+      border: 2px solid var(--bq-color-primary-600,#2563eb);
+      box-shadow: var(--bq-shadow-sm);
+      transition: transform var(--bq-duration-fast) var(--bq-easing-standard),
+                  box-shadow var(--bq-duration-fast) var(--bq-easing-standard);
+    }
+    input[type="range"]:hover:not(:disabled)::-webkit-slider-thumb { transform: scale(1.12); }
+    input[type="range"]:active:not(:disabled)::-webkit-slider-thumb { transform: scale(1.05); }
+    input[type="range"]:focus-visible::-webkit-slider-thumb { box-shadow: var(--bq-focus-ring); }
+
+    input[type="range"]::-moz-range-track {
+      block-size: var(--bq-slider-track);
+      border-radius: var(--bq-radius-full,9999px);
+      background: var(--bq-bg-emphasis,#e2e8f0);
+    }
+    input[type="range"]::-moz-range-progress {
+      block-size: var(--bq-slider-track);
+      border-radius: var(--bq-radius-full,9999px);
+      background: var(--bq-color-primary-600,#2563eb);
+    }
+    input[type="range"]::-moz-range-thumb {
+      inline-size: var(--bq-slider-thumb);
+      block-size: var(--bq-slider-thumb);
+      border-radius: var(--bq-radius-full,9999px);
+      background: var(--bq-bg-base,#fff);
+      border: 2px solid var(--bq-color-primary-600,#2563eb);
+      box-shadow: var(--bq-shadow-sm);
+      transition: transform var(--bq-duration-fast) var(--bq-easing-standard),
+                  box-shadow var(--bq-duration-fast) var(--bq-easing-standard);
+    }
+    input[type="range"]:hover:not(:disabled)::-moz-range-thumb { transform: scale(1.12); }
+    input[type="range"]:focus-visible::-moz-range-thumb { box-shadow: var(--bq-focus-ring); }
+
+    @media (forced-colors: active) {
+      input[type="range"]::-webkit-slider-thumb { background: ButtonFace; border-color: ButtonText; }
+      input[type="range"]::-moz-range-thumb { background: ButtonFace; border-color: ButtonText; }
+    }
   `,
   connected() {
     const self = host(this);
@@ -84,6 +171,9 @@ const definition: ComponentDefinition<BqSliderProps> = {
       syncInputAccessibility(input, v);
       const valueSpan = self.shadowRoot?.querySelector('.value');
       if (valueSpan) valueSpan.textContent = String(v);
+      // Dragging deliberately does not re-render, so the filled portion is
+      // repainted straight onto the element instead.
+      input.style.setProperty('--bq-slider-fill', `${fillPercent(input)}%`);
       self.dispatchEvent(
         new CustomEvent('bq-input', {
           detail: { value: v },
@@ -133,6 +223,7 @@ const definition: ComponentDefinition<BqSliderProps> = {
           max="${String(props.max)}"
           value="${String(props.value)}"
           step="${String(props.step)}"
+          style="--bq-slider-fill: ${sliderFill(props.value, props.min, props.max)}%"
           ${bool('disabled', props.disabled)}
           aria-label="${escapeHtml(props.label || t('slider.ariaLabel'))}"
           aria-valuemin="${String(props.min)}"
diff --git a/src/components/spinner/BqSpinner.ts b/src/components/spinner/BqSpinner.ts
index 4650b16..d5770b8 100644
--- a/src/components/spinner/BqSpinner.ts
+++ b/src/components/spinner/BqSpinner.ts
@@ -9,7 +9,7 @@ import type { ComponentDefinition } from '@bquery/bquery/component';
 import { component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { t } from '../../i18n/index.js';
-import { baseStyles } from '../../utils/styles.js';
+import { baseStyles, reset } from '../../utils/styles.js';
 
 type BqSpinnerProps = { size: string; variant: string; label: string };
 
@@ -21,6 +21,7 @@ const definition: ComponentDefinition<BqSpinnerProps> = {
   },
   styles: css`
     ${baseStyles}
+    ${reset}
     :host { display: inline-flex; align-items: center; justify-content: center; }
     .spinner {
       border-radius: 50%; border-style: solid; border-width: 2.5px; border-color: transparent;
diff --git a/src/components/stat-card/BqStatCard.ts b/src/components/stat-card/BqStatCard.ts
index 9d2f5d2..298660d 100644
--- a/src/components/stat-card/BqStatCard.ts
+++ b/src/components/stat-card/BqStatCard.ts
@@ -16,7 +16,7 @@ import { component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { t } from '../../i18n/index.js';
 import { uniqueId } from '../../utils/dom.js';
-import { baseStyles, srOnly } from '../../utils/styles.js';
+import { baseStyles, reset, srOnly } from '../../utils/styles.js';
 
 type BqStatCardProps = {
   label: string;
@@ -53,8 +53,8 @@ const definition: ComponentDefinition<BqStatCardProps, BqStatCardState> = {
   },
   styles: css`
     ${baseStyles}
+    ${reset}
     ${srOnly}
-    *, *::before, *::after { box-sizing: border-box; }
     :host { display: block; }
     .card {
       display: grid;
@@ -63,7 +63,7 @@ const definition: ComponentDefinition<BqStatCardProps, BqStatCardState> = {
       padding: var(--bq-space-6,1.5rem);
       border-radius: var(--bq-radius-xl,0.75rem);
       border: 1px solid var(--bq-border-base,#e2e8f0);
-      background: var(--bq-bg-base,#fff);
+      background: var(--bq-surface-raised,#fff);
       box-shadow: var(--bq-shadow-sm);
       color: var(--bq-text-base,#0f172a);
       font-family: var(--bq-font-family-sans);
diff --git a/src/components/stepper/BqStepper.ts b/src/components/stepper/BqStepper.ts
index 9080e58..ee5634d 100644
--- a/src/components/stepper/BqStepper.ts
+++ b/src/components/stepper/BqStepper.ts
@@ -17,7 +17,8 @@ import type { ComponentDefinition } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { t } from '../../i18n/index.js';
 import { bind, host, release } from '../../utils/component.js';
-import { baseStyles, reset, srOnly } from '../../utils/styles.js';
+import { iconCss } from '../../utils/icons.js';
+import { baseStyles, focusRing, reset, srOnly } from '../../utils/styles.js';
 
 type BqStepperProps = {
   current: number;
@@ -66,6 +67,8 @@ const definition: ComponentDefinition<BqStepperProps, BqStepperState> = {
     ${baseStyles}
     ${reset}
     ${srOnly}
+    ${focusRing}
+    ${iconCss('check')}
     :host { display: block; }
     .stepper { display: flex; font-family: var(--bq-font-family-sans); }
     .stepper[data-orientation="horizontal"] { flex-direction: row; align-items: flex-start; }
@@ -92,7 +95,7 @@ const definition: ComponentDefinition<BqStepperProps, BqStepperState> = {
     .step[data-status="complete"] .marker {
       background: var(--bq-color-primary-600,#2563eb);
       border-color: var(--bq-color-primary-600,#2563eb);
-      color: #fff;
+      color: var(--bq-text-on-primary,#fff);
     }
     .step[data-status="current"] .marker {
       border-color: var(--bq-color-primary-600,#2563eb);
@@ -198,7 +201,10 @@ const definition: ComponentDefinition<BqStepperProps, BqStepperState> = {
               ? 'stepper.current'
               : 'stepper.upcoming'
         );
-        const marker = status === 'complete' ? '✓' : String(index + 1);
+        const marker =
+          status === 'complete'
+            ? '<span class="icon" data-icon="check" aria-hidden="true"></span>'
+            : escapeHtml(String(index + 1));
         return `
           <${tag}
             class="step"
@@ -209,7 +215,7 @@ const definition: ComponentDefinition<BqStepperProps, BqStepperState> = {
             ${clickable && step.disabled ? 'disabled' : ''}
             ${status === 'current' ? 'aria-current="step"' : ''}
           >
-            <span class="marker" part="marker" aria-hidden="true">${escapeHtml(marker)}</span>
+            <span class="marker" part="marker" aria-hidden="true">${marker}</span>
             <span class="body">
               <span class="label" part="label">${escapeHtml(step.label)}</span>
               <span class="sr-only">${escapeHtml(` (${statusLabel})`)}</span>
diff --git a/src/components/switch/BqSwitch.ts b/src/components/switch/BqSwitch.ts
index 61f12da..9951d6a 100644
--- a/src/components/switch/BqSwitch.ts
+++ b/src/components/switch/BqSwitch.ts
@@ -3,75 +3,139 @@
  * @element bq-switch
  * @prop {string}  label   - Visible label
  * @prop {string}  name    - Input name
+ * @prop {string}  value   - Submitted value when on (default `on`)
  * @prop {boolean} checked
  * @prop {boolean} disabled
+ * @prop {boolean} required
  * @prop {string}  size    - sm | md | lg
+ * @prop {string}  hint
  * @fires bq-change - { value: string, checked: boolean }
  */
 import type { ComponentDefinition } from '@bquery/bquery/component';
 import { bool, component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { bindFormProxy, syncFormProxy } from '../../utils/form.js';
+import { t } from '../../i18n/index.js';
 import { bind, host, release } from '../../utils/component.js';
-import { baseStyles } from '../../utils/styles.js';
+import { uniqueId } from '../../utils/dom.js';
+import { baseStyles, fieldStyles, reset } from '../../utils/styles.js';
 
 type BqSwitchProps = {
   label: string;
   name: string;
+  value: string;
   checked: boolean;
   disabled: boolean;
+  required: boolean;
   size: string;
+  hint: string;
 };
 
-const definition: ComponentDefinition<BqSwitchProps> = {
+type BqSwitchState = { uid: string };
+
+const definition: ComponentDefinition<BqSwitchProps, BqSwitchState> = {
   props: {
     label: { type: String, default: '' },
     name: { type: String, default: '' },
+    value: { type: String, default: '' },
     checked: { type: Boolean, default: false },
     disabled: { type: Boolean, default: false },
+    required: { type: Boolean, default: false },
     size: { type: String, default: 'md' },
+    hint: { type: String, default: '' },
   },
+  state: { uid: '' },
   styles: css`
     ${baseStyles}
-    *, *::before, *::after { box-sizing: border-box; }
-    :host { display: inline-flex; }
-    .control { display: inline-flex; align-items: center; gap: 0.625rem; cursor: pointer; font-family: var(--bq-font-family-sans); }
-    :host([disabled]) .control { opacity: 0.5; cursor: not-allowed; pointer-events: none; }
+    ${reset}
+    ${fieldStyles}
+    :host { display: inline-block; }
+    .field { gap: 0.25rem; }
+    .control {
+      display: inline-flex;
+      align-items: center;
+      gap: 0.625rem;
+      cursor: pointer;
+      font-family: var(--bq-font-family-sans);
+    }
+    :host([disabled]) .control { opacity: 0.55; cursor: not-allowed; }
+
+    /* One custom property drives width, height, thumb size and travel, so a
+       new size is one line rather than four coordinated ones. */
     .track {
-      position: relative; display: inline-block; background: var(--bq-border-emphasis,#cbd5e1);
-      border-radius: var(--bq-radius-full,9999px);
-      transition: background var(--bq-duration-fast) var(--bq-easing-standard);
-      flex-shrink: 0;
+      --bq-switch-track-h: 1.375rem;
+      --bq-switch-track-w: 2.5rem;
+      --bq-switch-gap: 2px;
+      position: relative;
+      display: inline-block;
+      flex: none;
+      inline-size: var(--bq-switch-track-w);
+      block-size: var(--bq-switch-track-h);
+      background: var(--bq-border-strong, #94a3b8);
+      border-radius: var(--bq-radius-full, 9999px);
+      transition:
+        background-color var(--bq-duration-normal) var(--bq-easing-standard),
+        box-shadow var(--bq-duration-fast) var(--bq-easing-standard);
+    }
+    .track[data-size='sm'] { --bq-switch-track-h: 1rem; --bq-switch-track-w: 1.75rem; }
+    .track[data-size='lg'] { --bq-switch-track-h: 1.625rem; --bq-switch-track-w: 3rem; }
+
+    input {
+      position: absolute;
+      inset: 0;
+      inline-size: 100%;
+      block-size: 100%;
+      margin: 0;
+      opacity: 0;
+      cursor: inherit;
     }
-    .track[data-size="sm"] { width: 1.75rem; height: 1rem; }
-    .track[data-size="md"] { width: 2.5rem; height: 1.375rem; }
-    .track[data-size="lg"] { width: 3rem; height: 1.625rem; }
-    input { position: absolute; opacity: 0; width: 0; height: 0; }
+    /* The thumb travels by animating inset-inline-start rather than a
+       transform: a translation is physical, so it would slide the wrong way
+       in an RTL document, and the distance here is far too small for the
+       compositor to matter. */
     .thumb {
-      position: absolute; top: 2px; left: 2px; background: #fff;
-      border-radius: 50%; transition: transform var(--bq-duration-fast) var(--bq-easing-standard);
+      position: absolute;
+      inset-block-start: var(--bq-switch-gap);
+      inset-inline-start: var(--bq-switch-gap);
+      inline-size: calc(var(--bq-switch-track-h) - var(--bq-switch-gap) * 2);
+      block-size: calc(var(--bq-switch-track-h) - var(--bq-switch-gap) * 2);
+      background: #fff;
+      border-radius: var(--bq-radius-full, 9999px);
       box-shadow: var(--bq-shadow-sm);
+      transition: inset-inline-start var(--bq-duration-normal) var(--bq-easing-emphasized);
     }
-    .track[data-size="sm"]  .thumb { width: calc(1rem - 4px);    height: calc(1rem - 4px); }
-    .track[data-size="md"]  .thumb { width: calc(1.375rem - 4px); height: calc(1.375rem - 4px); }
-    .track[data-size="lg"]  .thumb { width: calc(1.625rem - 4px); height: calc(1.625rem - 4px); }
-    :host([checked]) .track { background: var(--bq-color-primary-600,#2563eb); }
-    :host([checked]) .track[data-size="sm"]  .thumb { transform: translateX(0.75rem); }
-    :host([checked]) .track[data-size="md"]  .thumb { transform: translateX(1.125rem); }
-    :host([checked]) .track[data-size="lg"]  .thumb { transform: translateX(1.375rem); }
-    input:focus-visible + .thumb { box-shadow: var(--bq-focus-ring); }
-    .label-text { font-size: var(--bq-font-size-sm,0.875rem); color: var(--bq-text-base,#0f172a); }
-    @media (prefers-reduced-motion: reduce) {
-      .track, .thumb { transition: none; }
+    .control:hover input:not(:disabled) ~ .track { background: var(--bq-text-subtle, #94a3b8); }
+    input:checked ~ .track { background: var(--bq-color-primary-600, #2563eb); }
+    .control:hover input:checked:not(:disabled) ~ .track { background: var(--bq-color-primary-700, #1d4ed8); }
+    input:checked ~ .track .thumb {
+      inset-inline-start: calc(var(--bq-switch-track-w) - var(--bq-switch-track-h) + var(--bq-switch-gap));
+    }
+    input:focus-visible ~ .track { box-shadow: var(--bq-focus-ring); }
+
+    .label-text {
+      font-size: var(--bq-font-size-sm, 0.875rem);
+      color: var(--bq-text-base, #0f172a);
+      line-height: var(--bq-line-height-normal, 1.5);
+    }
+
+    @media (forced-colors: active) {
+      .track { forced-color-adjust: none; background: Canvas; border: 1px solid CanvasText; }
+      input:checked ~ .track { background: Highlight; }
+      .thumb { background: CanvasText; }
+      input:checked ~ .track .thumb { background: HighlightText; }
+      input:focus-visible ~ .track { outline: 2px solid CanvasText; outline-offset: 2px; }
     }
   `,
   connected() {
-    const self = host(this);
+    const self = host<BqSwitchState>(this);
     const scope = bind(self);
+    if (!self.getState<string>('uid')) self.setState('uid', uniqueId('bq-sw'));
+
+    const onValue = () => self.getAttribute('value') || 'on';
 
     // Form proxy for native <form> participation
     const proxy = bindFormProxy(self, scope, {
-      value: () => (self.hasAttribute('checked') ? 'on' : ''),
+      value: () => (self.hasAttribute('checked') ? onValue() : ''),
     });
 
     const handler = (e: Event) => {
@@ -79,11 +143,11 @@ const definition: ComponentDefinition<BqSwitchProps> = {
       if (input?.type !== 'checkbox') return;
       if (input.checked) self.setAttribute('checked', '');
       else self.removeAttribute('checked');
-      proxy.setValue(input.checked ? 'on' : '');
+      proxy.setValue(input.checked ? onValue() : '');
       self.dispatchEvent(
         new CustomEvent('bq-change', {
           detail: {
-            value: self.getAttribute('value') ?? (input.checked ? 'on' : ''),
+            value: input.checked ? onValue() : '',
             checked: input.checked,
           },
           bubbles: true,
@@ -99,28 +163,47 @@ const definition: ComponentDefinition<BqSwitchProps> = {
   updated() {
     syncFormProxy(this);
   },
-  render({ props }) {
+  render({ props, state }) {
+    const uid = state.uid || 'bq-sw';
+    const labelId = `${uid}-label`;
+    const hintId = `${uid}-hint`;
+    const describedBy = props.hint ? hintId : '';
     return html`
-      <label class="control" part="control">
-        <span class="track" data-size="${escapeHtml(props.size)}">
-          <input
-            type="checkbox"
-            part="input"
-            name="${escapeHtml(props.name)}"
-            ${bool('checked', props.checked)}
-            ${bool('disabled', props.disabled)}
-            role="switch"
-            aria-checked="${props.checked ? 'true' : 'false'}"
-            aria-label="${escapeHtml(props.label)}"
-          />
-          <span class="thumb" part="thumb"></span>
-        </span>
-        ${props.label
-          ? `<span class="label-text" part="label">${escapeHtml(props.label)}</span>`
-          : ''}
-      </label>
+      <div class="field" part="wrapper">
+        <label class="control" part="control">
+          <span class="track" part="track" data-size="${escapeHtml(props.size)}">
+            <input
+              type="checkbox"
+              part="input"
+              role="switch"
+              name="${escapeHtml(props.name)}"
+              ${bool('checked', props.checked)}
+              ${bool('disabled', props.disabled)}
+              ${bool('required', props.required)}
+              aria-checked="${props.checked ? 'true' : 'false'}"
+              ${
+                props.label
+                  ? `aria-labelledby="${escapeHtml(labelId)}"`
+                  : `aria-label="${escapeHtml(t('switch.defaultLabel'))}"`
+              }
+              ${describedBy ? `aria-describedby="${escapeHtml(describedBy)}"` : ''}
+            />
+            <span class="thumb" part="thumb"></span>
+          </span>
+          ${
+            props.label
+              ? `<span class="label-text" id="${escapeHtml(labelId)}" part="label">${escapeHtml(props.label)}${props.required ? '<span class="required-mark" aria-hidden="true"> *</span>' : ''}</span>`
+              : ''
+          }
+        </label>
+        ${
+          props.hint
+            ? `<span class="hint" id="${escapeHtml(hintId)}" part="hint">${escapeHtml(props.hint)}</span>`
+            : ''
+        }
+      </div>
     `;
   },
 };
 
-component<BqSwitchProps>('bq-switch', definition);
+component<BqSwitchProps, BqSwitchState>('bq-switch', definition);
diff --git a/src/components/table/BqTable.ts b/src/components/table/BqTable.ts
index dc85b65..6a2e36c 100644
--- a/src/components/table/BqTable.ts
+++ b/src/components/table/BqTable.ts
@@ -17,7 +17,8 @@ import { component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { t } from '../../i18n/index.js';
 import { bind, host, release } from '../../utils/component.js';
-import { baseStyles } from '../../utils/styles.js';
+import { iconCss } from '../../utils/icons.js';
+import { baseStyles, focusRing, reset } from '../../utils/styles.js';
 
 type ColDef = { key: string; label: string; sortable?: boolean };
 type BqTableProps = {
@@ -44,21 +45,52 @@ const definition: ComponentDefinition<BqTableProps> = {
     hover: { type: Boolean, default: false },
     loading: { type: Boolean, default: false },
   },
+  sanitize: { allowAttributes: ['scope', 'colspan'] },
   styles: css`
     ${baseStyles}
-    *, *::before, *::after { box-sizing: border-box; }
+    ${reset}
+    ${focusRing}
+    ${iconCss('chevron-up', 'chevron-down', 'chevrons-up-down')}
     :host { display: block; overflow-x: auto; }
-    table { width: 100%; border-collapse: collapse; font-family: var(--bq-font-family-sans); font-size: var(--bq-font-size-sm,0.875rem); }
-    :host([bordered]) table { border: 1px solid var(--bq-border-base,#e2e8f0); }
-    th, td { padding: 0.75rem 1rem; text-align: left; border-bottom: 1px solid var(--bq-border-base,#e2e8f0); }
-    caption { caption-side: top; text-align: left; font-size: var(--bq-font-size-sm,0.875rem); color: var(--bq-text-muted,#475569); padding: 0.5rem 1rem; font-family: var(--bq-font-family-sans); }
+    table {
+      inline-size: 100%; border-collapse: collapse;
+      font-family: var(--bq-font-family-sans);
+      font-size: var(--bq-font-size-sm,0.875rem);
+      background: var(--bq-bg-base,#fff);
+    }
+    :host([bordered]) table { border: 1px solid var(--bq-border-base,#e2e8f0); border-radius: var(--bq-radius-lg,0.5rem); }
+    th, td {
+      padding: 0.75rem 1rem; text-align: start;
+      border-block-end: 1px solid var(--bq-border-base,#e2e8f0);
+    }
+    caption {
+      caption-side: top; text-align: start;
+      font-size: var(--bq-font-size-sm,0.875rem);
+      color: var(--bq-text-muted,#475569);
+      padding: 0.5rem 1rem; font-family: var(--bq-font-family-sans);
+    }
     :host([bordered]) th, :host([bordered]) td { border: 1px solid var(--bq-border-base,#e2e8f0); }
-    th { background: var(--bq-bg-subtle,#f8fafc); font-weight: var(--bq-font-weight-semibold,600); color: var(--bq-text-base,#0f172a); white-space: nowrap; }
+    th {
+      background: var(--bq-bg-subtle,#f8fafc);
+      font-weight: var(--bq-font-weight-semibold,600);
+      color: var(--bq-text-base,#0f172a);
+      white-space: nowrap;
+      /* A sticky header is what makes a long table readable, and it costs
+         nothing for a short one. */
+      position: sticky; inset-block-start: 0; z-index: var(--bq-z-raised,10);
+    }
+    tbody tr:last-child td { border-block-end: none; }
     td { color: var(--bq-text-muted,#475569); }
-    .sortable { cursor: pointer; user-select: none; }
+    .sortable { cursor: pointer; user-select: none; -webkit-user-select: none; }
     .sortable:hover { background: var(--bq-bg-emphasis,#e2e8f0); }
-    .sort-icon { display: inline-block; margin-left: 0.375rem; opacity: 0.4; }
-    .sort-icon[data-active="true"] { opacity: 1; }
+    .th-inner { display: inline-flex; align-items: center; gap: 0.375rem; }
+    .sort-icon {
+      --bq-icon-size: 0.875rem;
+      opacity: 0.35;
+      transition: opacity var(--bq-duration-fast) var(--bq-easing-standard);
+    }
+    .sortable:hover .sort-icon { opacity: 0.7; }
+    .sort-icon[data-active="true"] { opacity: 1; color: var(--bq-color-primary-600,#2563eb); }
     :host([striped]) tbody tr:nth-child(even) td { background: var(--bq-bg-subtle,#f8fafc); }
     :host([hover]) tbody tr:hover td { background: var(--bq-bg-muted,#f1f5f9); }
     .empty-row td { text-align: center; color: var(--bq-text-subtle,#94a3b8); padding: 2rem; }
@@ -132,8 +164,15 @@ const definition: ComponentDefinition<BqTableProps> = {
     const theads = cols
       .map((col) => {
         const isSorted = col.key === sortKey;
+        // Unsorted columns show a neutral up/down pair, so a sortable column
+        // advertises itself without claiming a direction it does not have.
+        const sortIconName = !isSorted
+          ? 'chevrons-up-down'
+          : sortDir === 'desc'
+            ? 'chevron-down'
+            : 'chevron-up';
         const sortIcon = col.sortable
-          ? `<span class="sort-icon" data-active="${isSorted ? 'true' : 'false'}" aria-hidden="true">${isSorted && sortDir === 'desc' ? '&#9650;' : '&#9660;'}</span>`
+          ? `<span class="icon sort-icon" data-icon="${sortIconName}" data-active="${isSorted ? 'true' : 'false'}" aria-hidden="true"></span>`
           : '';
         const sortLabel = col.sortable
           ? isSorted
@@ -145,7 +184,7 @@ const definition: ComponentDefinition<BqTableProps> = {
         const sortableAttrs = col.sortable
           ? `class="sortable" data-sort-key="${escapeHtml(col.key)}" tabindex="0" aria-sort="${isSorted ? (sortDir === 'asc' ? 'ascending' : 'descending') : 'none'}" title="${escapeHtml(sortLabel)}"`
           : '';
-        return `<th part="th" scope="col" role="columnheader" ${sortableAttrs}>${escapeHtml(col.label)}${sortIcon}</th>`;
+        return `<th part="th" scope="col" role="columnheader" ${sortableAttrs}><span class="th-inner">${escapeHtml(col.label)}${sortIcon}</span></th>`;
       })
       .join('');
     const tbodies = props.loading
diff --git a/src/components/tabs/BqTabs.ts b/src/components/tabs/BqTabs.ts
index 14fcf8f..1c41e8f 100644
--- a/src/components/tabs/BqTabs.ts
+++ b/src/components/tabs/BqTabs.ts
@@ -11,7 +11,7 @@ import { component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { t } from '../../i18n/index.js';
 import { bind, release } from '../../utils/component.js';
-import { baseStyles } from '../../utils/styles.js';
+import { baseStyles, reset } from '../../utils/styles.js';
 
 type BqTabsProps = { 'active-tab': string; variant: string };
 
@@ -37,30 +37,33 @@ const definition: ComponentDefinition<BqTabsProps> = {
   },
   styles: css`
     ${baseStyles}
-    *, *::before, *::after { box-sizing: border-box; }
+    ${reset}
     :host { display: block; }
     .tabs { display: flex; flex-direction: column; }
     .tablist { display: flex; gap: 0.25rem; }
     .tablist[data-variant="default"] { background: var(--bq-bg-subtle,#f8fafc); border-radius: var(--bq-radius-lg); padding: 0.25rem; }
-    .tablist[data-variant="underline"] { border-bottom: 2px solid var(--bq-border-base,#e2e8f0); }
+    .tablist[data-variant="underline"] { border-block-end: 2px solid var(--bq-border-base,#e2e8f0); }
     .tab {
       display: inline-flex; align-items: center; justify-content: center; gap: 0.375rem;
       font-size: var(--bq-font-size-sm,0.875rem); font-weight: var(--bq-font-weight-medium,500);
       font-family: var(--bq-font-family-sans); cursor: pointer; background: none; border: none;
       color: var(--bq-text-muted,#475569); white-space: nowrap;
-      transition: all var(--bq-duration-fast) var(--bq-easing-standard);
+      transition: color var(--bq-duration-fast) var(--bq-easing-standard),
+                  background-color var(--bq-duration-fast) var(--bq-easing-standard),
+                  border-color var(--bq-duration-fast) var(--bq-easing-standard),
+                  box-shadow var(--bq-duration-fast) var(--bq-easing-standard);
     }
     .tab[data-variant="default"]  { padding: 0.375rem 0.875rem; border-radius: var(--bq-radius-md,0.375rem); }
-    .tab[data-variant="underline"] { padding: 0.625rem 1rem; border-bottom: 2px solid transparent; margin-bottom: -2px; border-radius: 0; }
+    .tab[data-variant="underline"] { padding: 0.625rem 1rem; border-block-end: 2px solid transparent; margin-block-end: -2px; border-radius: 0; }
     .tab[data-variant="pills"]    { padding: 0.375rem 0.875rem; border-radius: var(--bq-radius-full,9999px); }
     .tab:hover:not([disabled]):not([aria-selected="true"]) { color: var(--bq-text-base,#0f172a); }
     .tab[data-variant="default"]:hover:not([disabled]):not([aria-selected="true"]) { background: var(--bq-bg-emphasis,#e2e8f0); }
-    .tab[aria-selected="true"][data-variant="default"]   { background: var(--bq-bg-base,#fff); box-shadow: var(--bq-shadow-sm); color: var(--bq-color-primary-600,#2563eb); }
+    .tab[aria-selected="true"][data-variant="default"]   { background: var(--bq-surface-raised,#fff); box-shadow: var(--bq-shadow-sm); color: var(--bq-color-primary-600,#2563eb); }
     .tab[aria-selected="true"][data-variant="underline"] { border-bottom-color: var(--bq-color-primary-600,#2563eb); color: var(--bq-color-primary-600,#2563eb); }
-    .tab[aria-selected="true"][data-variant="pills"]     { background: var(--bq-color-primary-600,#2563eb); color: #fff; }
+    .tab[aria-selected="true"][data-variant="pills"]     { background: var(--bq-color-primary-600,#2563eb); color: var(--bq-text-on-primary,#fff); }
     .tab[disabled] { opacity: 0.45; cursor: not-allowed; }
     .tab:focus-visible { outline: 2px solid transparent; box-shadow: var(--bq-focus-ring); }
-    .panels { padding-top: var(--bq-space-4,1rem); }
+    .panels { padding-block-start: var(--bq-space-4,1rem); }
     @media (prefers-reduced-motion: reduce) {
       .tab { transition: none; }
     }
diff --git a/src/components/tag-input/BqTagInput.ts b/src/components/tag-input/BqTagInput.ts
index d9b912b..5e43922 100644
--- a/src/components/tag-input/BqTagInput.ts
+++ b/src/components/tag-input/BqTagInput.ts
@@ -32,12 +32,16 @@ import type { ComponentDefinition } from '@bquery/bquery/component';
 import { component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { t } from '../../i18n/index.js';
-import { bind, host, release, store } from '../../utils/component.js';
+import { bind, host, release } from '../../utils/component.js';
 import { uniqueId } from '../../utils/dom.js';
-import { captureFocus, restoreFocus } from '../../utils/focus.js';
-import type { FocusSnapshot } from '../../utils/focus.js';
+import {
+  markFocus,
+  restorePreservedFocus,
+  trackFocus,
+} from '../../utils/focus.js';
 import { bindFormProxy, syncFormProxy } from '../../utils/form.js';
-import { baseStyles, reset, srOnly } from '../../utils/styles.js';
+import { iconCss } from '../../utils/icons.js';
+import { baseStyles, focusRing, reset, srOnly } from '../../utils/styles.js';
 import { bindValidation } from '../../utils/validation.js';
 
 type BqTagInputProps = {
@@ -58,9 +62,6 @@ type BqTagInputProps = {
 
 type BqTagInputState = { uid: string; draft: string };
 
-const tagStore = (owner: object) =>
-  store<{ snapshot?: FocusSnapshot | null }>(owner, () => ({}));
-
 /** Splits a joined value into individual tags. */
 export function parseTags(raw: string, separator = ','): string[] {
   const sep = separator || ',';
@@ -111,6 +112,8 @@ const definition: ComponentDefinition<BqTagInputProps, BqTagInputState> = {
     ${baseStyles}
     ${reset}
     ${srOnly}
+    ${focusRing}
+    ${iconCss('x')}
     :host { display: block; }
     .field { display: flex; flex-direction: column; gap: 0.375rem; }
     .label {
@@ -139,17 +142,22 @@ const definition: ComponentDefinition<BqTagInputProps, BqTagInputState> = {
       background: var(--bq-color-primary-50,#eff6ff);
       color: var(--bq-color-primary-700,#1d4ed8);
       border: 1px solid var(--bq-color-primary-200,#bfdbfe);
-      border-radius: var(--bq-radius-sm,0.25rem);
-      padding: 0.125rem 0.25rem 0.125rem 0.5rem;
+      border-radius: var(--bq-radius-md,0.375rem);
+      padding-block: 0.125rem;
+      padding-inline: 0.5rem 0.25rem;
       font-size: var(--bq-font-size-sm,0.875rem);
       font-family: var(--bq-font-family-sans);
     }
     .tag button {
+      display: inline-flex; align-items: center; justify-content: center;
       border: none; background: none; cursor: pointer; line-height: 1;
-      color: inherit; padding: 0 0.125rem;
-      border-radius: var(--bq-radius-sm,0.25rem);
+      color: inherit; padding: 0.125rem;
+      border-radius: var(--bq-radius-full,9999px);
+      --bq-icon-size: 0.75rem;
+      transition: color var(--bq-duration-fast) var(--bq-easing-standard),
+                  background-color var(--bq-duration-fast) var(--bq-easing-standard);
     }
-    .tag button:hover { color: var(--bq-color-danger-600,#dc2626); }
+    .tag button:hover { color: var(--bq-color-danger-600,#dc2626); background: var(--bq-bg-hover,rgba(15,23,42,0.06)); }
     .tag button:focus-visible { outline: 2px solid transparent; box-shadow: var(--bq-focus-ring); }
 
     input {
@@ -235,6 +243,12 @@ const definition: ComponentDefinition<BqTagInputProps, BqTagInputState> = {
         (ch) => ch !== ''
       );
 
+    // Every handler below writes state, and every state write replaces the
+    // shadow tree — including the field the user is typing in. `trackFocus`
+    // records the caret from the same events in the capture phase, and
+    // `updated()` puts it back.
+    trackFocus(self, scope);
+
     scope.on(self.shadowRoot, 'input', (event) => {
       const input = event.target as HTMLInputElement | null;
       if (input?.tagName !== 'INPUT') return;
@@ -321,15 +335,13 @@ const definition: ComponentDefinition<BqTagInputProps, BqTagInputState> = {
     });
   },
   beforeUpdate() {
-    tagStore(this).snapshot = captureFocus(this.shadowRoot);
+    markFocus(this);
   },
   disconnected() {
     release(this);
   },
   updated() {
-    const local = tagStore(this);
-    restoreFocus(this.shadowRoot, local.snapshot);
-    local.snapshot = null;
+    restorePreservedFocus(this);
     syncFormProxy(this);
   },
   render({ props, state }) {
@@ -353,7 +365,7 @@ const definition: ComponentDefinition<BqTagInputProps, BqTagInputState> = {
             data-index="${index}"
             aria-label="${escapeHtml(t('tagInput.remove', { tag }))}"
             ${props.disabled ? 'disabled' : ''}
-          >&times;</button></li>`
+          ><span class="icon" data-icon="x" aria-hidden="true"></span></button></li>`
       )
       .join('');
 
diff --git a/src/components/textarea/BqTextarea.ts b/src/components/textarea/BqTextarea.ts
index 9f4dabb..c703627 100644
--- a/src/components/textarea/BqTextarea.ts
+++ b/src/components/textarea/BqTextarea.ts
@@ -24,10 +24,19 @@ import { escapeHtml } from '@bquery/bquery/security';
 import { t } from '../../i18n/index.js';
 import { uniqueId } from '../../utils/dom.js';
 import { bindFormProxy, syncFormProxy } from '../../utils/form.js';
-import { bind, release, store } from '../../utils/component.js';
-import { captureFocus, restoreFocus, type FocusSnapshot } from '../../utils/focus.js';
+import { bind, release } from '../../utils/component.js';
+import {
+  markFocus,
+  restorePreservedFocus,
+  trackFocus,
+} from '../../utils/focus.js';
 import { bindValidation } from '../../utils/validation.js';
-import { baseStyles } from '../../utils/styles.js';
+import {
+  baseStyles,
+  fieldStyles,
+  focusRing,
+  reset,
+} from '../../utils/styles.js';
 
 type BqTextareaProps = {
   label: string;
@@ -50,9 +59,6 @@ type BqTextareaState = { uid: string };
  * tree, so without this the field the user is typing in is destroyed on
  * every keystroke that reflects a value to an attribute.
  */
-const textareaFocusStore = (owner: object) =>
-  store<{ snapshot?: FocusSnapshot | null }>(owner, () => ({}));
-
 const definition: ComponentDefinition<BqTextareaProps, BqTextareaState> = {
   props: {
     label: { type: String, default: '' },
@@ -73,7 +79,9 @@ const definition: ComponentDefinition<BqTextareaProps, BqTextareaState> = {
   },
   styles: css`
     ${baseStyles}
-    *, *::before, *::after { box-sizing: border-box; }
+    ${reset}
+    ${fieldStyles}
+    ${focusRing}
     :host { display: block; }
     .field { display: flex; flex-direction: column; gap: 0.375rem; }
     .label { font-size: var(--bq-font-size-sm,0.875rem); font-weight: var(--bq-font-weight-medium,500); color: var(--bq-text-base,#0f172a); font-family: var(--bq-font-family-sans); display: flex; align-items: center; gap: 0.25rem; }
@@ -94,7 +102,7 @@ const definition: ComponentDefinition<BqTextareaProps, BqTextareaState> = {
     .hint { font-size: var(--bq-font-size-sm,0.875rem); color: var(--bq-text-muted,#475569); font-family: var(--bq-font-family-sans); }
     .error-msg { font-size: var(--bq-font-size-sm,0.875rem); color: var(--bq-color-danger-600,#dc2626); font-family: var(--bq-font-family-sans); }
     .footer { display: flex; align-items: center; justify-content: space-between; gap: 0.5rem; }
-    .counter { font-size: var(--bq-font-size-sm,0.875rem); color: var(--bq-text-muted,#475569); font-family: var(--bq-font-family-sans); margin-left: auto; }
+    .counter { font-size: var(--bq-font-size-sm,0.875rem); color: var(--bq-text-muted,#475569); font-family: var(--bq-font-family-sans); margin-inline-start: auto; font-variant-numeric: tabular-nums; }
     .counter[data-over="true"] { color: var(--bq-color-danger-600,#dc2626); }
     @media (prefers-reduced-motion: reduce) {
       textarea { transition: none; }
@@ -162,6 +170,11 @@ const definition: ComponentDefinition<BqTextareaProps, BqTextareaState> = {
           new CustomEvent('bq-blur', { bubbles: true, composed: true })
         );
     };
+    // Attribute-driven renders are covered by `beforeUpdate`; this also
+    // covers the ones a future state write would trigger, and costs one
+    // capture-phase listener.
+    trackFocus(self, scope);
+
     const shadow = self.shadowRoot;
     scope.on(shadow, 'input', ih);
     scope.on(shadow, 'change', ch);
@@ -172,11 +185,10 @@ const definition: ComponentDefinition<BqTextareaProps, BqTextareaState> = {
     release(this);
   },
   beforeUpdate() {
-    textareaFocusStore(this).snapshot = captureFocus(this.shadowRoot);
+    markFocus(this);
   },
   updated() {
-    restoreFocus(this.shadowRoot, textareaFocusStore(this).snapshot);
-    textareaFocusStore(this).snapshot = null;
+    restorePreservedFocus(this);
     syncFormProxy(this);
   },
   render({ props, state }) {
diff --git a/src/components/timeline/BqTimeline.ts b/src/components/timeline/BqTimeline.ts
index 408465e..61a8969 100644
--- a/src/components/timeline/BqTimeline.ts
+++ b/src/components/timeline/BqTimeline.ts
@@ -89,7 +89,7 @@ const itemDefinition: ComponentDefinition<BqTimelineItemProps> = {
       border-radius: var(--bq-radius-full,9999px);
       background: var(--bq-color-primary-600,#2563eb);
       box-shadow: 0 0 0 3px var(--bq-color-primary-100,#dbeafe);
-      color: #fff; font-size: 0.5rem; line-height: 1;
+      color: var(--bq-text-on-primary,#fff); font-size: 0.5rem; line-height: 1;
     }
     .item[data-variant="success"] .marker { background: var(--bq-color-success-600,#16a34a); box-shadow: 0 0 0 3px var(--bq-color-success-100,#dcfce7); }
     .item[data-variant="danger"]  .marker { background: var(--bq-color-danger-600,#dc2626);  box-shadow: 0 0 0 3px var(--bq-color-danger-100,#fee2e2); }
diff --git a/src/components/toast/BqToast.ts b/src/components/toast/BqToast.ts
index d8171f9..17ca560 100644
--- a/src/components/toast/BqToast.ts
+++ b/src/components/toast/BqToast.ts
@@ -12,7 +12,8 @@ import { component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { t } from '../../i18n/index.js';
 import { bind, host, release } from '../../utils/component.js';
-import { baseStyles } from '../../utils/styles.js';
+import { iconCss, type IconName } from '../../utils/icons.js';
+import { baseStyles, focusRing, reset } from '../../utils/styles.js';
 
 type BqToastProps = {
   variant: string;
@@ -21,6 +22,14 @@ type BqToastProps = {
   dismissible: boolean;
 };
 
+/** Status glyph per variant. Unknown variants fall back to `info`. */
+const VARIANT_ICON: Record<string, IconName> = {
+  success: 'check-circle',
+  error: 'x-circle',
+  warning: 'alert-triangle',
+  info: 'info',
+};
+
 const definition: ComponentDefinition<BqToastProps> = {
   props: {
     variant: { type: String, default: 'info' },
@@ -30,7 +39,9 @@ const definition: ComponentDefinition<BqToastProps> = {
   },
   styles: css`
     ${baseStyles}
-    *, *::before, *::after { box-sizing: border-box; }
+    ${reset}
+    ${focusRing}
+    ${iconCss('x', 'check-circle', 'x-circle', 'alert-triangle', 'info')}
     :host { display: block; }
     .toast {
       display: flex; align-items: flex-start; gap: 0.75rem;
@@ -40,15 +51,32 @@ const definition: ComponentDefinition<BqToastProps> = {
       animation: slideIn var(--bq-duration-normal,200ms) var(--bq-easing-decelerate);
     }
     @keyframes slideIn { from { opacity: 0; transform: translateY(-0.5rem); } to { opacity: 1; transform: translateY(0); } }
-    .toast[data-variant="success"] { background: var(--bq-color-success-50,#f0fdf4); border-color: var(--bq-color-success-500,#22c55e); color: var(--bq-color-success-700,#15803d); }
-    .toast[data-variant="error"]   { background: var(--bq-color-danger-50,#fef2f2);  border-color: var(--bq-color-danger-500,#ef4444);  color: var(--bq-color-danger-700,#b91c1c); }
-    .toast[data-variant="warning"] { background: var(--bq-color-warning-50,#fffbeb); border-color: var(--bq-color-warning-500,#f59e0b); color: var(--bq-color-warning-700,#b45309); }
-    .toast[data-variant="info"]    { background: var(--bq-color-info-50,#eff6ff);    border-color: var(--bq-color-info-500,#3b82f6);    color: var(--bq-color-info-700,#1d4ed8); }
-    .icon { font-size: 1.1em; flex-shrink: 0; margin-top: 0.05em; }
-    .content { flex: 1; min-width: 0; font-size: var(--bq-font-size-sm,0.875rem); line-height: var(--bq-line-height-normal,1.5); }
-    .close { flex-shrink: 0; display: inline-flex; align-items: center; justify-content: center; background: none; border: none; cursor: pointer; color: inherit; padding: 0.125rem; border-radius: var(--bq-radius-sm,0.25rem); opacity: 0.7; font-size: 0.875rem; }
-    .close:hover { opacity: 1; background: rgba(0,0,0,0.08); }
-    .close:focus-visible { outline: 2px solid transparent; box-shadow: var(--bq-focus-ring); }
+    /* A toast floats over arbitrary content, so it sits on the overlay
+       surface and carries the status colour as a leading edge — a fully
+       tinted panel would fight whatever it happens to land on. */
+    .toast { background: var(--bq-surface-overlay,#fff); color: var(--bq-text-base,#0f172a); border-inline-start-width: 3px; }
+    .toast[data-variant="success"] { border-inline-start-color: var(--bq-color-success-500,#22c55e); }
+    .toast[data-variant="error"]   { border-inline-start-color: var(--bq-color-danger-500,#ef4444); }
+    .toast[data-variant="warning"] { border-inline-start-color: var(--bq-color-warning-500,#f59e0b); }
+    .toast[data-variant="info"]    { border-inline-start-color: var(--bq-color-info-500,#3b82f6); }
+    .toast { border-color: var(--bq-border-base,#e2e8f0); }
+    .status-icon { --bq-icon-size: 1.25rem; margin-block-start: 0.0625rem; }
+    .toast[data-variant="success"] .status-icon { color: var(--bq-color-success-600,#16a34a); }
+    .toast[data-variant="error"]   .status-icon { color: var(--bq-color-danger-600,#dc2626); }
+    .toast[data-variant="warning"] .status-icon { color: var(--bq-color-warning-600,#d97706); }
+    .toast[data-variant="info"]    .status-icon { color: var(--bq-color-info-600,#2563eb); }
+    .content { flex: 1; min-inline-size: 0; font-size: var(--bq-font-size-sm,0.875rem); line-height: var(--bq-line-height-normal,1.5); }
+    .close {
+      flex: none; display: inline-flex; align-items: center; justify-content: center;
+      inline-size: 1.5rem; block-size: 1.5rem;
+      background: none; border: none; cursor: pointer;
+      color: var(--bq-text-muted,#475569);
+      border-radius: var(--bq-radius-md,0.375rem); opacity: 0.7;
+      --bq-icon-size: 1rem;
+      transition: opacity var(--bq-duration-fast) var(--bq-easing-standard),
+                  background-color var(--bq-duration-fast) var(--bq-easing-standard);
+    }
+    .close:hover { opacity: 1; background: var(--bq-bg-hover,rgba(15,23,42,0.08)); }
     @media (prefers-reduced-motion: reduce) {
       .toast { animation: none; }
     }
@@ -75,13 +103,7 @@ const definition: ComponentDefinition<BqToastProps> = {
     release(this);
   },
   render({ props }) {
-    const icons: Record<string, string> = {
-      success: '✓',
-      error: '✕',
-      warning: '⚠',
-      info: 'ℹ',
-    };
-    const icon = icons[props.variant] ?? 'ℹ';
+    const icon = VARIANT_ICON[props.variant] ?? 'info';
     const isAlert = props.variant === 'error' || props.variant === 'warning';
     return html`
       <div
@@ -92,12 +114,12 @@ const definition: ComponentDefinition<BqToastProps> = {
         aria-live="${isAlert ? 'assertive' : 'polite'}"
         aria-atomic="true"
       >
-        <span class="icon" aria-hidden="true">${icon}</span>
+        <span class="icon status-icon" part="icon" data-icon="${icon}" aria-hidden="true"></span>
         <span class="content" part="content"
           ><slot>${escapeHtml(props.message)}</slot></span
         >
         ${props.dismissible
-          ? `<button type="button" class="close" aria-label="${t('toast.close')}">&#10005;</button>`
+          ? `<button type="button" class="close" aria-label="${t('toast.close')}"><span class="icon" data-icon="x" aria-hidden="true"></span></button>`
           : ''}
       </div>
     `;
diff --git a/src/components/tooltip/BqTooltip.ts b/src/components/tooltip/BqTooltip.ts
index 14b7f4e..83ac674 100644
--- a/src/components/tooltip/BqTooltip.ts
+++ b/src/components/tooltip/BqTooltip.ts
@@ -13,7 +13,7 @@ import type { Disposer } from '../../utils/component.js';
 import { bind, host, release, store } from '../../utils/component.js';
 import { uniqueId } from '../../utils/dom.js';
 import { autoPosition } from '../../utils/position.js';
-import { baseStyles } from '../../utils/styles.js';
+import { baseStyles, reset } from '../../utils/styles.js';
 
 type BqTooltipProps = { content: string; placement: string; delay: number };
 type BqTooltipState = { visible: boolean; uid: string };
@@ -55,10 +55,11 @@ const definition: ComponentDefinition<BqTooltipProps, BqTooltipState> = {
   state: { visible: false, uid: '' },
   styles: css`
     ${baseStyles}
+    ${reset}
     :host { display: inline-block; position: relative; }
     .tip {
       position: absolute; z-index: var(--bq-z-tooltip,700);
-      background: var(--bq-color-secondary-900,#0f172a); color: #fff;
+      background: var(--bq-bg-inverse,#0f172a); color: var(--bq-text-inverse,#f8fafc);
       font-family: var(--bq-font-family-sans); font-size: var(--bq-font-size-sm,0.875rem);
       padding: 0.375rem 0.625rem; border-radius: var(--bq-radius-md,0.375rem);
       max-width: min(20rem, 90vw); width: max-content;
diff --git a/src/components/tree/BqTree.ts b/src/components/tree/BqTree.ts
new file mode 100644
index 0000000..f6b0675
--- /dev/null
+++ b/src/components/tree/BqTree.ts
@@ -0,0 +1,484 @@
+/**
+ * Tree view — hierarchical navigation with the ARIA tree keyboard pattern.
+ *
+ * A tree is not a nested list of buttons: the whole widget is one tab stop,
+ * and the arrow keys move a *roving* focus through the nodes that are actually
+ * visible. Right opens a branch or descends into it, Left collapses or climbs
+ * out, Home and End jump to the ends, and typing a letter jumps to the next
+ * node starting with it. That is the entire reason this component exists —
+ * markup alone gets none of it.
+ *
+ * Nodes are supplied as JSON, matching `bq-table`:
+ *
+ * ```html
+ * <bq-tree items='[{"id":"src","label":"src","children":[{"id":"a","label":"a.ts"}]}]'></bq-tree>
+ * ```
+ *
+ * @element bq-tree
+ * @prop {string}  items       - JSON array of nodes
+ * @prop {string}  expanded    - Comma-separated ids of open branches
+ * @prop {string}  selected    - Selected node id
+ * @prop {string}  label       - Accessible name for the tree
+ * @prop {boolean} multiple    - Allow more than one selected node
+ * @prop {boolean} disabled
+ * @fires bq-select - { id: string, ids: string[], node: TreeNode }
+ * @fires bq-expand - { id: string, expanded: boolean }
+ */
+import type { ComponentDefinition } from '@bquery/bquery/component';
+import { component, css, html } from '@bquery/bquery/component';
+import { escapeHtml } from '@bquery/bquery/security';
+import { bind, host, release } from '../../utils/component.js';
+import { uniqueId } from '../../utils/dom.js';
+import { markFocus, restorePreservedFocus } from '../../utils/focus.js';
+import { iconCss } from '../../utils/icons.js';
+import { baseStyles, focusRing, reset } from '../../utils/styles.js';
+
+/** One node of the tree. */
+export interface TreeNode {
+  id: string;
+  label: string;
+  children?: TreeNode[];
+  disabled?: boolean;
+  /** Icon name from the built-in set, drawn before the label. */
+  icon?: string;
+}
+
+/** A node together with where it sits, as the keyboard walk sees it. */
+export interface FlatNode {
+  node: TreeNode;
+  level: number;
+  parentId: string | null;
+  hasChildren: boolean;
+  expanded: boolean;
+}
+
+type BqTreeProps = {
+  items: string;
+  expanded: string;
+  selected: string;
+  label: string;
+  multiple: boolean;
+  disabled: boolean;
+};
+
+type BqTreeState = { uid: string; active: string };
+
+/** Parses the `items` JSON, tolerating malformed input rather than throwing. */
+export function parseNodes(raw: string): TreeNode[] {
+  try {
+    const parsed: unknown = JSON.parse(raw || '[]');
+    return Array.isArray(parsed) ? (parsed as TreeNode[]) : [];
+  } catch {
+    return [];
+  }
+}
+
+/** Splits a comma-separated id list. */
+export function parseIds(raw: string): string[] {
+  return raw
+    .split(',')
+    .map((part) => part.trim())
+    .filter(Boolean);
+}
+
+/**
+ * Flattens the tree to the nodes a user can currently reach.
+ *
+ * Collapsed branches contribute nothing, which is exactly what arrow-key
+ * navigation needs: "the next node" means the next *visible* one, not the
+ * next one in the data.
+ */
+export function visibleNodes(
+  nodes: TreeNode[],
+  expanded: Set<string>,
+  level = 1,
+  parentId: string | null = null
+): FlatNode[] {
+  const out: FlatNode[] = [];
+  for (const node of nodes) {
+    const children = node.children ?? [];
+    const hasChildren = children.length > 0;
+    const isExpanded = hasChildren && expanded.has(node.id);
+    out.push({ node, level, parentId, hasChildren, expanded: isExpanded });
+    if (isExpanded) {
+      out.push(...visibleNodes(children, expanded, level + 1, node.id));
+    }
+  }
+  return out;
+}
+
+/** Steps to the next selectable node, skipping disabled ones. Clamps at the ends. */
+export function stepNode(
+  flat: FlatNode[],
+  from: number,
+  step: 1 | -1
+): number {
+  for (let i = from + step; i >= 0 && i < flat.length; i += step) {
+    if (!flat[i]?.node.disabled) return i;
+  }
+  return from;
+}
+
+/** Finds the next node whose label starts with `char`, wrapping around. */
+export function typeaheadIndex(
+  flat: FlatNode[],
+  from: number,
+  char: string
+): number {
+  const needle = char.toLowerCase();
+  for (let i = 1; i <= flat.length; i += 1) {
+    const index = (from + i) % flat.length;
+    const entry = flat[index];
+    if (entry && !entry.node.disabled && entry.node.label.toLowerCase().startsWith(needle)) {
+      return index;
+    }
+  }
+  return from;
+}
+
+const definition: ComponentDefinition<BqTreeProps, BqTreeState> = {
+  props: {
+    items: { type: String, default: '[]' },
+    expanded: { type: String, default: '' },
+    selected: { type: String, default: '' },
+    label: { type: String, default: '' },
+    multiple: { type: Boolean, default: false },
+    disabled: { type: Boolean, default: false },
+  },
+  state: { uid: '', active: '' },
+  sanitize: { allowAttributes: ['style'] },
+  styles: css`
+    ${baseStyles}
+    ${reset}
+    ${focusRing}
+    ${iconCss(
+      'chevron-right',
+      'folder',
+      'file',
+      'check',
+      'circle',
+      'dot',
+      'home',
+      'user',
+      'users',
+      'image',
+      'mail',
+      'settings',
+      'star',
+      'link'
+    )}
+    :host { display: block; }
+    .tree {
+      font-family: var(--bq-font-family-sans);
+      font-size: var(--bq-font-size-sm, 0.875rem);
+      color: var(--bq-text-base, #0f172a);
+      list-style: none;
+      margin: 0;
+      padding: 0;
+      outline: none;
+    }
+    .node {
+      display: flex;
+      align-items: center;
+      gap: 0.375rem;
+      /* One shared indent unit keeps the guide rails aligned no matter how
+         deep the tree goes. */
+      padding-block: 0.3125rem;
+      padding-inline: calc(0.5rem + (var(--bq-tree-level, 1) - 1) * var(--bq-tree-indent, 1.125rem)) 0.5rem;
+      border-radius: var(--bq-radius-md, 0.375rem);
+      cursor: pointer;
+      user-select: none;
+      -webkit-user-select: none;
+      transition: background-color var(--bq-duration-fast) var(--bq-easing-standard);
+    }
+    .node:hover { background: var(--bq-bg-hover, rgba(15,23,42,0.04)); }
+    .node[aria-selected='true'] {
+      background: var(--bq-bg-selected, rgba(37,99,235,0.1));
+      color: var(--bq-color-primary-700, #1d4ed8);
+      font-weight: var(--bq-font-weight-medium, 500);
+    }
+    .node[aria-disabled='true'] { opacity: 0.5; cursor: not-allowed; }
+    .tree:focus-visible .node[data-active='true'],
+    .node[data-active='true']:focus-visible {
+      outline: 2px solid transparent;
+      box-shadow: var(--bq-focus-ring);
+    }
+    .twisty {
+      flex: none;
+      inline-size: 1rem;
+      block-size: 1rem;
+      display: grid;
+      place-items: center;
+      color: var(--bq-text-subtle, #94a3b8);
+      --bq-icon-size: 0.875rem;
+      transition: transform var(--bq-duration-fast) var(--bq-easing-standard);
+    }
+    .node[aria-expanded='true'] .twisty { transform: rotate(90deg); }
+    /* An RTL tree opens leftwards, so the collapsed arrow has to start
+       pointing the other way. */
+    :host(:dir(rtl)) .twisty { transform: rotate(180deg); }
+    :host(:dir(rtl)) .node[aria-expanded='true'] .twisty { transform: rotate(90deg); }
+    .node-icon { flex: none; color: var(--bq-text-muted, #475569); --bq-icon-size: 1rem; }
+    .node[aria-selected='true'] .node-icon { color: inherit; }
+    .node-label { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+    .group { list-style: none; margin: 0; padding: 0; }
+  `,
+  connected() {
+    const self = host<BqTreeState>(this);
+    const scope = bind(self);
+    if (!self.getState<string>('uid')) self.setState('uid', uniqueId('bq-tree'));
+
+    const nodes = () => parseNodes(self.getAttribute('items') ?? '[]');
+    const expandedSet = () =>
+      new Set(parseIds(self.getAttribute('expanded') ?? ''));
+    const flat = () => visibleNodes(nodes(), expandedSet());
+    const isInteractive = () => !self.hasAttribute('disabled');
+
+    const activeIndex = (list: FlatNode[]): number => {
+      const active = self.getState<string>('active');
+      const found = list.findIndex((entry) => entry.node.id === active);
+      if (found >= 0) return found;
+      return list.findIndex((entry) => !entry.node.disabled);
+    };
+
+    const setActive = (list: FlatNode[], index: number) => {
+      const entry = list[index];
+      if (!entry) return;
+      markFocus(self);
+      self.setState('active', entry.node.id);
+    };
+
+    const setExpanded = (id: string, open: boolean) => {
+      const set = expandedSet();
+      if (open === set.has(id)) return;
+      if (open) set.add(id);
+      else set.delete(id);
+      markFocus(self);
+      self.setAttribute('expanded', Array.from(set).join(','));
+      self.dispatchEvent(
+        new CustomEvent('bq-expand', {
+          detail: { id, expanded: open },
+          bubbles: true,
+          composed: true,
+        })
+      );
+    };
+
+    const select = (entry: FlatNode) => {
+      if (entry.node.disabled) return;
+      const id = entry.node.id;
+      let ids: string[];
+      if (self.hasAttribute('multiple')) {
+        const current = parseIds(self.getAttribute('selected') ?? '');
+        ids = current.includes(id)
+          ? current.filter((value) => value !== id)
+          : [...current, id];
+      } else {
+        ids = [id];
+      }
+      markFocus(self);
+      self.setState('active', id);
+      self.setAttribute('selected', ids.join(','));
+      self.dispatchEvent(
+        new CustomEvent('bq-select', {
+          detail: { id, ids, node: entry.node },
+          bubbles: true,
+          composed: true,
+        })
+      );
+    };
+
+    const entryFor = (target: Element | null): FlatNode | undefined => {
+      const row = target?.closest('.node') as HTMLElement | null;
+      if (!row) return undefined;
+      const id = row.getAttribute('data-id');
+      return flat().find((entry) => entry.node.id === id);
+    };
+
+    scope.on(self.shadowRoot, 'click', (event) => {
+      if (!isInteractive()) return;
+      const target = event.target as Element;
+      const entry = entryFor(target);
+      if (!entry) return;
+      // The twisty is a separate affordance: clicking it opens a branch
+      // without selecting it, which is how every file tree behaves.
+      if (target.closest('.twisty') && entry.hasChildren) {
+        setExpanded(entry.node.id, !entry.expanded);
+        self.setState('active', entry.node.id);
+        return;
+      }
+      if (entry.hasChildren && !entry.expanded) setExpanded(entry.node.id, true);
+      select(entry);
+    });
+
+    scope.on(self.shadowRoot, 'keydown', (event) => {
+      const ke = event as KeyboardEvent;
+      if (!isInteractive()) return;
+      const list = flat();
+      if (list.length === 0) return;
+      const index = activeIndex(list);
+      const entry = list[index];
+
+      switch (ke.key) {
+        case 'ArrowDown':
+          ke.preventDefault();
+          setActive(list, stepNode(list, index, 1));
+          return;
+        case 'ArrowUp':
+          ke.preventDefault();
+          setActive(list, stepNode(list, index, -1));
+          return;
+        case 'ArrowRight':
+          ke.preventDefault();
+          if (!entry) return;
+          if (entry.hasChildren && !entry.expanded) {
+            setExpanded(entry.node.id, true);
+            return;
+          }
+          if (entry.hasChildren) setActive(list, stepNode(list, index, 1));
+          return;
+        case 'ArrowLeft': {
+          ke.preventDefault();
+          if (!entry) return;
+          if (entry.expanded) {
+            setExpanded(entry.node.id, false);
+            return;
+          }
+          // A collapsed node climbs to its parent, so Left repeatedly walks
+          // out of a deep branch instead of doing nothing.
+          const parent = list.findIndex(
+            (candidate) => candidate.node.id === entry.parentId
+          );
+          if (parent >= 0) setActive(list, parent);
+          return;
+        }
+        case 'Home':
+          ke.preventDefault();
+          setActive(list, stepNode(list, -1, 1));
+          return;
+        case 'End':
+          ke.preventDefault();
+          setActive(list, stepNode(list, list.length, -1));
+          return;
+        case 'Enter':
+        case ' ':
+          ke.preventDefault();
+          if (entry) select(entry);
+          return;
+        case '*': {
+          // Expand every sibling of the active node — the pattern's shortcut
+          // for "show me this whole level".
+          ke.preventDefault();
+          if (!entry) return;
+          const set = expandedSet();
+          for (const candidate of list) {
+            if (candidate.parentId === entry.parentId && candidate.hasChildren) {
+              set.add(candidate.node.id);
+            }
+          }
+          markFocus(self);
+          self.setAttribute('expanded', Array.from(set).join(','));
+          return;
+        }
+        default:
+          if (ke.key.length === 1 && !ke.ctrlKey && !ke.metaKey && !ke.altKey) {
+            const next = typeaheadIndex(list, index, ke.key);
+            if (next !== index) {
+              ke.preventDefault();
+              setActive(list, next);
+            }
+          }
+      }
+    });
+  },
+  disconnected() {
+    release(this);
+  },
+  beforeUpdate() {
+    markFocus(this);
+  },
+  updated() {
+    restorePreservedFocus(this);
+    // The roving tab stop has to end up on the node the keyboard moved to,
+    // and the render that moved it also destroyed the element that had focus.
+    const root = this.shadowRoot;
+    const active = root?.querySelector(
+      '.node[data-active="true"]'
+    ) as HTMLElement | null;
+    if (active && root?.activeElement === null && this.matches(':focus-within')) {
+      active.focus();
+    }
+    active?.scrollIntoView?.({ block: 'nearest' });
+  },
+  render({ props, state }) {
+    const uid = state.uid || 'bq-tree';
+    const nodes = parseNodes(props.items);
+    const expanded = new Set(parseIds(props.expanded));
+    const selected = new Set(parseIds(props.selected));
+    const flat = visibleNodes(nodes, expanded);
+
+    // Exactly one node is in the tab order; the arrow keys move it. Without
+    // that, tabbing through a large tree means every node is a stop.
+    const activeId =
+      flat.find((entry) => entry.node.id === state.active)?.node.id ??
+      flat.find((entry) => selected.has(entry.node.id))?.node.id ??
+      flat.find((entry) => !entry.node.disabled)?.node.id ??
+      '';
+
+    const renderLevel = (list: TreeNode[], level: number): string =>
+      list
+        .map((node) => {
+          const children = node.children ?? [];
+          const hasChildren = children.length > 0;
+          const isExpanded = hasChildren && expanded.has(node.id);
+          const isSelected = selected.has(node.id);
+          const isActive = node.id === activeId;
+          const icon = typeof node.icon === 'string' ? node.icon : '';
+          return `<li role="none">
+            <div
+              class="node"
+              part="node"
+              role="treeitem"
+              id="${escapeHtml(`${uid}-${node.id}`)}"
+              data-id="${escapeHtml(node.id)}"
+              data-active="${isActive ? 'true' : 'false'}"
+              style="--bq-tree-level: ${level}"
+              tabindex="${isActive ? '0' : '-1'}"
+              aria-level="${level}"
+              aria-selected="${isSelected ? 'true' : 'false'}"
+              ${hasChildren ? `aria-expanded="${isExpanded ? 'true' : 'false'}"` : ''}
+              ${node.disabled ? 'aria-disabled="true"' : ''}
+            >
+              ${
+                hasChildren
+                  ? `<span class="twisty" part="twisty" aria-hidden="true"><span class="icon" data-icon="chevron-right"></span></span>`
+                  : '<span class="twisty" aria-hidden="true"></span>'
+              }
+              ${icon ? `<span class="icon node-icon" data-icon="${escapeHtml(icon)}" aria-hidden="true"></span>` : ''}
+              <span class="node-label" part="label">${escapeHtml(node.label)}</span>
+            </div>
+            ${
+              isExpanded
+                ? `<ul class="group" role="group">${renderLevel(children, level + 1)}</ul>`
+                : ''
+            }
+          </li>`;
+        })
+        .join('');
+
+    return html`
+      <ul
+        class="tree"
+        part="tree"
+        role="tree"
+        ${props.label ? `aria-label="${escapeHtml(props.label)}"` : ''}
+        ${props.multiple ? 'aria-multiselectable="true"' : ''}
+        ${props.disabled ? 'aria-disabled="true"' : ''}
+      >
+        ${renderLevel(nodes, 1)}
+      </ul>
+    `;
+  },
+};
+
+component<BqTreeProps, BqTreeState>('bq-tree', definition);
diff --git a/src/components/tree/index.ts b/src/components/tree/index.ts
new file mode 100644
index 0000000..f4aaa23
--- /dev/null
+++ b/src/components/tree/index.ts
@@ -0,0 +1 @@
+export * as __bqComponentEntry from './BqTree.js';
diff --git a/src/i18n/en.ts b/src/i18n/en.ts
index b055bb8..d696d26 100644
--- a/src/i18n/en.ts
+++ b/src/i18n/en.ts
@@ -71,6 +71,9 @@ export const en = {
   tabs: {
     listLabel: 'Tabs',
   },
+  switch: {
+    defaultLabel: 'Toggle',
+  },
   slider: {
     ariaLabel: 'Slider',
     valueText: 'Value: {value}',
@@ -142,6 +145,22 @@ export const en = {
     resultCount: '{count} options available',
     selected: '{count} selected',
   },
+  datePicker: {
+    placeholder: 'Select a date',
+    open: 'Open calendar',
+    clear: 'Clear date',
+    prevMonth: 'Previous month',
+    nextMonth: 'Next month',
+    today: 'Today',
+  },
+  copyButton: {
+    copy: 'Copy to clipboard',
+    copied: 'Copied',
+  },
+  pinInput: {
+    cell: 'Digit {index} of {total}',
+    progress: '{count} of {total} characters entered',
+  },
   tagInput: {
     placeholder: 'Add a tag…',
     remove: 'Remove {tag}',
diff --git a/src/index.ts b/src/index.ts
index 0cdf728..bfe4197 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -27,7 +27,9 @@ import { __bqComponentEntry as bannerComponentEntry } from './components/banner/
 import { __bqComponentEntry as buttonGroupComponentEntry } from './components/button-group/index.js';
 import { __bqComponentEntry as fileUploadComponentEntry } from './components/file-upload/index.js';
 import { __bqComponentEntry as kbdComponentEntry } from './components/kbd/index.js';
+import { __bqComponentEntry as meterComponentEntry } from './components/meter/index.js';
 import { __bqComponentEntry as numberInputComponentEntry } from './components/number-input/index.js';
+import { __bqComponentEntry as pinInputComponentEntry } from './components/pin-input/index.js';
 import { __bqComponentEntry as popoverComponentEntry } from './components/popover/index.js';
 import { __bqComponentEntry as ratingComponentEntry } from './components/rating/index.js';
 import { __bqComponentEntry as stepperComponentEntry } from './components/stepper/index.js';
@@ -39,11 +41,14 @@ import { __bqComponentEntry as cardComponentEntry } from './components/card/inde
 import { __bqComponentEntry as checkboxComponentEntry } from './components/checkbox/index.js';
 import { __bqComponentEntry as chipComponentEntry } from './components/chip/index.js';
 import { __bqComponentEntry as comboboxComponentEntry } from './components/combobox/index.js';
+import { __bqComponentEntry as copyButtonComponentEntry } from './components/copy-button/index.js';
+import { __bqComponentEntry as datePickerComponentEntry } from './components/date-picker/index.js';
 import { __bqComponentEntry as dialogComponentEntry } from './components/dialog/index.js';
 import { __bqComponentEntry as dividerComponentEntry } from './components/divider/index.js';
 import { __bqComponentEntry as drawerComponentEntry } from './components/drawer/index.js';
 import { __bqComponentEntry as dropdownMenuComponentEntry } from './components/dropdown-menu/index.js';
 import { __bqComponentEntry as emptyStateComponentEntry } from './components/empty-state/index.js';
+import { __bqComponentEntry as iconComponentEntry } from './components/icon/index.js';
 import { __bqComponentEntry as iconButtonComponentEntry } from './components/icon-button/index.js';
 import { __bqComponentEntry as inputComponentEntry } from './components/input/index.js';
 import { __bqComponentEntry as paginationComponentEntry } from './components/pagination/index.js';
@@ -61,6 +66,7 @@ import { __bqComponentEntry as tagInputComponentEntry } from './components/tag-i
 import { __bqComponentEntry as tabsComponentEntry } from './components/tabs/index.js';
 import { __bqComponentEntry as textareaComponentEntry } from './components/textarea/index.js';
 import { __bqComponentEntry as tooltipComponentEntry } from './components/tooltip/index.js';
+import { __bqComponentEntry as treeComponentEntry } from './components/tree/index.js';
 // Toast is imported directly because its wrapper both registers the component and re-exports showToast().
 import './components/toast/index.js';
 
@@ -78,7 +84,9 @@ Object.defineProperty(registerAll, COMPONENT_ENTRY_MAP_KEY, {
     'button-group': buttonGroupComponentEntry,
     'file-upload': fileUploadComponentEntry,
     'kbd': kbdComponentEntry,
+    'meter': meterComponentEntry,
     'number-input': numberInputComponentEntry,
+    'pin-input': pinInputComponentEntry,
     'popover': popoverComponentEntry,
     'rating': ratingComponentEntry,
     'stepper': stepperComponentEntry,
@@ -90,11 +98,14 @@ Object.defineProperty(registerAll, COMPONENT_ENTRY_MAP_KEY, {
     'checkbox': checkboxComponentEntry,
     'chip': chipComponentEntry,
     'combobox': comboboxComponentEntry,
+    'copy-button': copyButtonComponentEntry,
+    'date-picker': datePickerComponentEntry,
     'dialog': dialogComponentEntry,
     'divider': dividerComponentEntry,
     'drawer': drawerComponentEntry,
     'dropdown-menu': dropdownMenuComponentEntry,
     'empty-state': emptyStateComponentEntry,
+    'icon': iconComponentEntry,
     'icon-button': iconButtonComponentEntry,
     'input': inputComponentEntry,
     'pagination': paginationComponentEntry,
@@ -112,6 +123,7 @@ Object.defineProperty(registerAll, COMPONENT_ENTRY_MAP_KEY, {
     'tabs': tabsComponentEntry,
     'textarea': textareaComponentEntry,
     'tooltip': tooltipComponentEntry,
+    'tree': treeComponentEntry,
   },
   writable: false,
   enumerable: false,
diff --git a/src/theme/dark.ts b/src/theme/dark.ts
index d73f82f..ef62334 100644
--- a/src/theme/dark.ts
+++ b/src/theme/dark.ts
@@ -1,62 +1,36 @@
+import { darkTokens, getDarkSchemeCSS } from './scheme.js';
+
 /**
  * Dark theme for @bquery/ui
  */
 export const darkTheme = {
   name: 'dark',
   colorScheme: 'dark' as const,
-  tokens: {
-    '--bq-bg-base': '#0f172a',
-    '--bq-bg-subtle': '#1e293b',
-    '--bq-bg-muted': '#334155',
-    '--bq-bg-emphasis': '#475569',
-
-    '--bq-text-base': '#f8fafc',
-    '--bq-text-muted': '#cbd5e1',
-    '--bq-text-subtle': '#94a3b8',
-    '--bq-text-on-primary': '#ffffff',
-    '--bq-text-on-danger': '#ffffff',
-
-    '--bq-border-base': '#334155',
-    '--bq-border-emphasis': '#475569',
-    '--bq-border-focus': '#60a5fa',
-
-    '--bq-focus-ring': '0 0 0 3px rgba(96, 165, 250, 0.35)',
-    '--bq-focus-ring-danger': '0 0 0 3px rgba(248, 113, 113, 0.35)',
-  },
+  tokens: darkTokens,
 };
 
 /**
  * Generates the CSS for the dark theme overrides.
+ *
+ * The two selectors are deliberately **separate rules**. `:host-context()`
+ * exists only in Chromium, and an unknown selector invalidates the entire
+ * selector list it appears in — so writing them as `a, b { … }` meant Firefox
+ * and Safari threw away the dark theme wholesale.
+ *
+ * `:host([data-theme="dark"])` covers a component told to be dark directly.
+ * `:host-context()` is kept as a Chromium-only convenience for pages that set
+ * an ancestor attribute without installing the theme stylesheet; everywhere
+ * else that path is handled by the scheme channel in `./scheme.ts`.
  */
 export function getDarkThemeCSS(): string {
+  const declarations = getDarkSchemeCSS();
   return `
-:host([data-theme="dark"]),
-:host-context([data-theme="dark"]) {
-  /* Semantic tokens (dark) */
-  --bq-bg-base: #0f172a;
-  --bq-bg-subtle: #1e293b;
-  --bq-bg-muted: #334155;
-  --bq-bg-emphasis: #475569;
-
-  --bq-text-base: #f8fafc;
-  --bq-text-muted: #cbd5e1;
-  --bq-text-subtle: #94a3b8;
-  --bq-text-on-primary: #ffffff;
-  --bq-text-on-danger: #ffffff;
-
-  --bq-border-base: #334155;
-  --bq-border-emphasis: #475569;
-  --bq-border-focus: #60a5fa;
-
-  --bq-focus-ring: 0 0 0 3px rgba(96, 165, 250, 0.35);
-  --bq-focus-ring-danger: 0 0 0 3px rgba(248, 113, 113, 0.35);
+:host([data-theme="dark"]) {
+${declarations}
+}
 
-  /* Dark color overrides */
-  --bq-color-primary-600: #3b82f6;
-  --bq-color-primary-700: #2563eb;
-  --bq-color-danger-600: #ef4444;
-  --bq-color-success-600: #22c55e;
-  --bq-color-warning-600: #f59e0b;
+:host-context([data-theme="dark"]) {
+${declarations}
 }
 `.trim();
 }
diff --git a/src/theme/default.ts b/src/theme/default.ts
index 7da8890..cb4cd2f 100644
--- a/src/theme/default.ts
+++ b/src/theme/default.ts
@@ -1,4 +1,5 @@
 import { getTokensCSS } from '../tokens/index.js';
+import { getLightSchemeCSS, lightTokens } from './scheme.js';
 
 /**
  * Default (light) theme for @bquery/ui
@@ -6,30 +7,15 @@ import { getTokensCSS } from '../tokens/index.js';
 export const defaultTheme = {
   name: 'default',
   colorScheme: 'light' as const,
-  tokens: {
-    // Semantic color mappings
-    '--bq-bg-base': '#ffffff',
-    '--bq-bg-subtle': '#f8fafc',
-    '--bq-bg-muted': '#f1f5f9',
-    '--bq-bg-emphasis': '#e2e8f0',
-
-    '--bq-text-base': '#0f172a',
-    '--bq-text-muted': '#475569',
-    '--bq-text-subtle': '#94a3b8',
-    '--bq-text-on-primary': '#ffffff',
-    '--bq-text-on-danger': '#ffffff',
-
-    '--bq-border-base': '#e2e8f0',
-    '--bq-border-emphasis': '#cbd5e1',
-    '--bq-border-focus': '#2563eb',
-
-    '--bq-focus-ring': '0 0 0 3px rgba(37, 99, 235, 0.35)',
-    '--bq-focus-ring-danger': '0 0 0 3px rgba(239, 68, 68, 0.35)',
-  },
+  tokens: lightTokens,
 };
 
 /**
  * Generates the CSS for the default light theme, including all design tokens.
+ *
+ * The semantic half is written as `var(--bq-scheme-*, light-value)` so a page
+ * can re-theme components from the document; see `./scheme.ts` for why the
+ * indirection is needed at all.
  */
 export function getDefaultThemeCSS(): string {
   return `
@@ -37,23 +23,7 @@ export function getDefaultThemeCSS(): string {
   ${getTokensCSS()}
 
   /* Semantic tokens (light) */
-  --bq-bg-base: #ffffff;
-  --bq-bg-subtle: #f8fafc;
-  --bq-bg-muted: #f1f5f9;
-  --bq-bg-emphasis: #e2e8f0;
-
-  --bq-text-base: #0f172a;
-  --bq-text-muted: #475569;
-  --bq-text-subtle: #94a3b8;
-  --bq-text-on-primary: #ffffff;
-  --bq-text-on-danger: #ffffff;
-
-  --bq-border-base: #e2e8f0;
-  --bq-border-emphasis: #cbd5e1;
-  --bq-border-focus: #2563eb;
-
-  --bq-focus-ring: 0 0 0 3px rgba(37, 99, 235, 0.35);
-  --bq-focus-ring-danger: 0 0 0 3px rgba(239, 68, 68, 0.35);
+${getLightSchemeCSS()}
 }
 `.trim();
 }
diff --git a/src/theme/index.ts b/src/theme/index.ts
index 704cd68..ec9f3ae 100644
--- a/src/theme/index.ts
+++ b/src/theme/index.ts
@@ -3,68 +3,73 @@
  */
 export { darkTheme, getDarkThemeCSS } from './dark.js';
 export { defaultTheme, getDefaultThemeCSS } from './default.js';
+export { installThemeStyles } from './root.js';
+export {
+  darkTokens,
+  getDarkSchemeCSS,
+  getLightSchemeCSS,
+  getSchemeRootCSS,
+  lightTokens,
+} from './scheme.js';
+export type { SemanticTokenName } from './scheme.js';
 
-export type ColorScheme = 'light' | 'dark' | 'auto';
-
-export interface BqTheme {
-  name: string;
-  colorScheme: 'light' | 'dark';
-  tokens: Record<string, string>;
-}
-
-let currentTheme: ColorScheme = 'auto';
-let autoListener: ((e: MediaQueryListEvent) => void) | null = null;
+import { installThemeStyles } from './root.js';
 
-function applyAutoScheme(): void {
-  const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
-  const root = document.documentElement;
-  if (prefersDark) {
-    root.setAttribute('data-theme', 'dark');
-  } else {
-    root.removeAttribute('data-theme');
-  }
-}
+export type ColorScheme = 'light' | 'dark' | 'auto';
 
-function cleanupAutoListener(): void {
-  if (autoListener) {
-    window
-      .matchMedia('(prefers-color-scheme: dark)')
-      .removeEventListener('change', autoListener);
-    autoListener = null;
-  }
-}
+let currentScheme: ColorScheme = 'auto';
 
 /**
- * Set the global color scheme. Pass 'auto' to follow the user's OS preference
- * (listens for changes in real time).
+ * Sets the global color scheme.
+ *
+ * All three values are expressed the same way — as `data-theme` on the root
+ * element — because the theme stylesheet resolves `auto` in CSS, with a
+ * `prefers-color-scheme` media query. There is no `matchMedia` listener to
+ * leak, and a system-level switch repaints the page without JavaScript running
+ * at all.
+ *
+ * Scoping a scheme to part of a page needs no API: put `data-theme` on any
+ * element and everything below it follows.
  */
 export function setColorScheme(scheme: ColorScheme): void {
-  cleanupAutoListener();
-  currentTheme = scheme;
-  const root = document.documentElement;
-  if (scheme === 'dark') {
-    root.setAttribute('data-theme', 'dark');
-  } else if (scheme === 'light') {
-    root.removeAttribute('data-theme');
-  } else {
-    applyAutoScheme();
-    autoListener = () => applyAutoScheme();
-    window
-      .matchMedia('(prefers-color-scheme: dark)')
-      .addEventListener('change', autoListener);
-  }
+  currentScheme = scheme;
+  if (typeof document === 'undefined') return;
+  installThemeStyles();
+  document.documentElement.setAttribute('data-theme', scheme);
 }
 
-/** Get the current color scheme setting. */
+/** Gets the current color scheme setting, as requested. */
 export function getColorScheme(): ColorScheme {
-  return currentTheme;
+  return currentScheme;
+}
+
+/**
+ * Gets the scheme actually in effect, resolving `auto` against the operating
+ * system preference.
+ */
+export function getResolvedColorScheme(): 'light' | 'dark' {
+  if (currentScheme !== 'auto') return currentScheme;
+  if (typeof window === 'undefined' || typeof window.matchMedia !== 'function')
+    return 'light';
+  return window.matchMedia('(prefers-color-scheme: dark)').matches
+    ? 'dark'
+    : 'light';
 }
 
 /**
- * Apply custom CSS variable overrides to the document root.
+ * Applies custom CSS variable overrides to the document root.
+ *
+ * Overrides set here outrank the theme, because they land in the element's
+ * inline style. To override only one scheme, write the rule against
+ * `[data-theme="dark"]` in your own stylesheet instead.
  */
-export function applyThemeTokens(tokens: Record<string, string>): void {
-  const root = document.documentElement;
+export function applyThemeTokens(
+  tokens: Record<string, string>,
+  target?: HTMLElement
+): void {
+  const root =
+    target ?? (typeof document === 'undefined' ? null : document.documentElement);
+  if (!root) return;
   for (const [key, value] of Object.entries(tokens)) {
     root.style.setProperty(key, value);
   }
diff --git a/src/theme/root.ts b/src/theme/root.ts
new file mode 100644
index 0000000..eb3c9f1
--- /dev/null
+++ b/src/theme/root.ts
@@ -0,0 +1,71 @@
+/**
+ * Installs the document-level half of the theme.
+ *
+ * Components carry their own tokens, so nothing here is needed for them to
+ * render correctly. What it adds is the ability to *switch* them from outside
+ * the shadow boundary: the rules below define the `--bq-scheme-*` channel that
+ * every component resolves its semantic tokens through, keyed off `data-theme`.
+ *
+ * Installation is automatic — importing any component pulls in the shared
+ * stylesheet module, which calls {@link installThemeStyles} once per document.
+ * The rules are inert until something in the page actually carries
+ * `data-theme`, so an application that never opts in is unaffected.
+ */
+import { getSchemeRootCSS } from './scheme.js';
+
+const MARKER = 'bq-theme-root';
+
+const installed = new WeakSet<Document>();
+
+type AdoptingDocument = Document & {
+  adoptedStyleSheets?: CSSStyleSheet[];
+};
+
+/**
+ * Adds the theme stylesheet to a document, once.
+ *
+ * Prefers a constructed stylesheet: it needs no `<style>` element, so it works
+ * under a Content-Security-Policy that forbids inline styles, and it cannot be
+ * knocked out by a framework that re-renders `<head>`.
+ *
+ * @param doc - Target document; defaults to the ambient one. Pass a document
+ *   explicitly when rendering into an iframe or a popup window.
+ * @returns whether the stylesheet is now present.
+ */
+export function installThemeStyles(doc?: Document): boolean {
+  const target = doc ?? (typeof document === 'undefined' ? null : document);
+  if (!target) return false;
+  if (installed.has(target)) return true;
+
+  const css = getSchemeRootCSS();
+  const adopting = target as AdoptingDocument;
+
+  if (
+    typeof CSSStyleSheet === 'function' &&
+    Array.isArray(adopting.adoptedStyleSheets)
+  ) {
+    try {
+      const sheet = new CSSStyleSheet();
+      sheet.replaceSync(css);
+      adopting.adoptedStyleSheets = [...adopting.adoptedStyleSheets, sheet];
+      installed.add(target);
+      return true;
+    } catch {
+      /* Constructable stylesheets unavailable — fall through to <style>. */
+    }
+  }
+
+  const head = target.head ?? target.documentElement;
+  if (!head) return false;
+  if (target.querySelector(`style[data-${MARKER}]`)) {
+    installed.add(target);
+    return true;
+  }
+
+  const style = target.createElement('style');
+  style.setAttribute(`data-${MARKER}`, '');
+  style.textContent = css;
+  head.prepend(style);
+  installed.add(target);
+  return true;
+}
diff --git a/src/theme/scheme.ts b/src/theme/scheme.ts
new file mode 100644
index 0000000..e5d1e30
--- /dev/null
+++ b/src/theme/scheme.ts
@@ -0,0 +1,242 @@
+/**
+ * The semantic token layer, and the mechanism that lets a page switch it.
+ *
+ * Every component embeds its own copy of the tokens in its shadow root, which
+ * is what makes the library work with no stylesheet to install. It also means
+ * a component *defines* `--bq-bg-base` on its own `:host`, and a definition on
+ * the element always beats a value inherited from an ancestor — so a page
+ * cannot re-theme a component just by setting the variable on `<html>`.
+ *
+ * The library used to bridge that with `:host-context([data-theme="dark"])`.
+ * That selector only exists in Chromium; worse, it appeared in a selector list
+ * next to `:host([data-theme="dark"])`, and one unknown selector invalidates
+ * the whole list — so Firefox and Safari dropped the entire dark theme.
+ *
+ * The fix is one level of indirection. Components resolve each semantic token
+ * through a *scheme channel*:
+ *
+ * ```css
+ * :host { --bq-bg-base: var(--bq-scheme-bg-base, #ffffff); }
+ * ```
+ *
+ * `--bq-scheme-bg-base` is never defined on the host, so it resolves the
+ * ordinary way — by inheritance from the document. {@link getSchemeRootCSS}
+ * emits those channel values for `[data-theme="dark"]`, `[data-theme="light"]`
+ * and `[data-theme="auto"]`, in plain CSS that every browser understands, and
+ * they cascade into every shadow root beneath. Nested themed regions work for
+ * free, because inheritance is what the cascade already does.
+ */
+
+/** Semantic tokens, without the `--bq-` prefix. */
+export type SemanticTokenName = keyof typeof LIGHT_TOKENS;
+
+const LIGHT_TOKENS = {
+  'color-scheme': 'light',
+
+  'bg-base': '#ffffff',
+  'bg-subtle': '#f8fafc',
+  'bg-muted': '#f1f5f9',
+  'bg-emphasis': '#e2e8f0',
+  'bg-inverse': '#0f172a',
+
+  /* Surfaces stack: sunken < base < raised < overlay. In light mode they are
+     told apart by shadow, in dark mode by lightness — which is why an overlay
+     needs its own token instead of reusing `bg-base`. */
+  'surface-sunken': '#f8fafc',
+  'surface-raised': '#ffffff',
+  'surface-overlay': '#ffffff',
+
+  /* Translucent interaction layers: they tint whatever they sit on, so one
+     pair works on every surface instead of one per background. */
+  'bg-hover': 'rgba(15, 23, 42, 0.04)',
+  'bg-active': 'rgba(15, 23, 42, 0.08)',
+  'bg-selected': 'rgba(37, 99, 235, 0.1)',
+
+  'text-base': '#0f172a',
+  'text-muted': '#475569',
+  'text-subtle': '#94a3b8',
+  'text-inverse': '#f8fafc',
+  'text-on-primary': '#ffffff',
+  'text-on-danger': '#ffffff',
+
+  'border-base': '#e2e8f0',
+  'border-emphasis': '#cbd5e1',
+  'border-strong': '#94a3b8',
+  'border-focus': '#2563eb',
+
+  'focus-ring': '0 0 0 3px rgba(37, 99, 235, 0.35)',
+  'focus-ring-danger': '0 0 0 3px rgba(239, 68, 68, 0.35)',
+  'focus-ring-success': '0 0 0 3px rgba(22, 163, 74, 0.35)',
+  'focus-ring-warning': '0 0 0 3px rgba(217, 119, 6, 0.35)',
+
+  'overlay-backdrop': 'rgba(15, 23, 42, 0.5)',
+} as const;
+
+const DARK_TOKENS: Record<SemanticTokenName, string> = {
+  'color-scheme': 'dark',
+
+  'bg-base': '#0f172a',
+  'bg-subtle': '#1e293b',
+  'bg-muted': '#334155',
+  'bg-emphasis': '#475569',
+  'bg-inverse': '#f8fafc',
+
+  'surface-sunken': '#020617',
+  'surface-raised': '#1e293b',
+  'surface-overlay': '#1e293b',
+
+  'bg-hover': 'rgba(248, 250, 252, 0.06)',
+  'bg-active': 'rgba(248, 250, 252, 0.12)',
+  'bg-selected': 'rgba(96, 165, 250, 0.18)',
+
+  'text-base': '#f8fafc',
+  'text-muted': '#cbd5e1',
+  'text-subtle': '#94a3b8',
+  'text-inverse': '#0f172a',
+  'text-on-primary': '#ffffff',
+  'text-on-danger': '#ffffff',
+
+  'border-base': '#334155',
+  'border-emphasis': '#475569',
+  'border-strong': '#64748b',
+  'border-focus': '#60a5fa',
+
+  'focus-ring': '0 0 0 3px rgba(96, 165, 250, 0.4)',
+  'focus-ring-danger': '0 0 0 3px rgba(248, 113, 113, 0.4)',
+  'focus-ring-success': '0 0 0 3px rgba(74, 222, 128, 0.4)',
+  'focus-ring-warning': '0 0 0 3px rgba(251, 191, 36, 0.4)',
+
+  'overlay-backdrop': 'rgba(2, 6, 23, 0.72)',
+};
+
+/**
+ * Palette and elevation corrections that only make sense in dark mode.
+ *
+ * The 600-step accents are a shade too dark to read on a slate background, and
+ * a shadow tuned for white paper is invisible on one — dark elevation has to be
+ * carried by near-opaque black instead.
+ */
+const DARK_OVERRIDES: Record<string, string> = {
+  'color-primary-600': '#3b82f6',
+  'color-primary-700': '#2563eb',
+  'color-danger-600': '#ef4444',
+  'color-success-600': '#22c55e',
+  'color-warning-600': '#f59e0b',
+
+  'shadow-xs': '0 1px 2px 0 rgba(0, 0, 0, 0.3)',
+  'shadow-sm': '0 1px 2px 0 rgba(0, 0, 0, 0.4), 0 1px 3px 0 rgba(0, 0, 0, 0.3)',
+  'shadow-md':
+    '0 2px 4px -1px rgba(0, 0, 0, 0.4), 0 4px 8px -2px rgba(0, 0, 0, 0.35)',
+  'shadow-lg':
+    '0 4px 6px -2px rgba(0, 0, 0, 0.4), 0 12px 20px -4px rgba(0, 0, 0, 0.45)',
+  'shadow-xl':
+    '0 8px 10px -6px rgba(0, 0, 0, 0.45), 0 24px 40px -8px rgba(0, 0, 0, 0.55)',
+  'shadow-inner': 'inset 0 1px 2px 0 rgba(0, 0, 0, 0.35)',
+};
+
+/** Light values, keyed by full custom property name. */
+export const lightTokens: Readonly<Record<string, string>> = Object.fromEntries(
+  Object.entries(LIGHT_TOKENS)
+    .filter(([name]) => name !== 'color-scheme')
+    .map(([name, value]) => [`--bq-${name}`, value])
+);
+
+/** Dark values, keyed by full custom property name. */
+export const darkTokens: Readonly<Record<string, string>> = Object.fromEntries(
+  [...Object.entries(DARK_TOKENS), ...Object.entries(DARK_OVERRIDES)]
+    .filter(([name]) => name !== 'color-scheme')
+    .map(([name, value]) => [`--bq-${name}`, value])
+);
+
+function declarations(
+  entries: Iterable<readonly [string, string]>,
+  indent = '  '
+): string {
+  return Array.from(entries)
+    .map(([name, value]) => `${indent}--bq-${name}: ${value};`)
+    .join('\n');
+}
+
+/**
+ * The light defaults, each routed through its scheme channel so a document
+ * that sets the channel wins without needing `:host-context`.
+ */
+export function getLightSchemeCSS(indent = '  '): string {
+  return Object.entries(LIGHT_TOKENS)
+    .map(([name, value]) =>
+      name === 'color-scheme'
+        ? `${indent}color-scheme: var(--bq-scheme-color-scheme, ${value});`
+        : `${indent}--bq-${name}: var(--bq-scheme-${name}, ${value});`
+    )
+    .join('\n');
+}
+
+/**
+ * The dark values as literals.
+ *
+ * Used for the rules that target an explicitly themed element, where the
+ * author has said which scheme they want and the ambient channel must not
+ * second-guess it.
+ */
+export function getDarkSchemeCSS(indent = '  '): string {
+  return [
+    `${indent}color-scheme: dark;`,
+    declarations(
+      Object.entries(DARK_TOKENS).filter(([name]) => name !== 'color-scheme'),
+      indent
+    ),
+    declarations(Object.entries(DARK_OVERRIDES), indent),
+  ].join('\n');
+}
+
+function channel(
+  tokens: Record<string, string>,
+  scheme: string,
+  indent = '  '
+): string {
+  return Object.entries(tokens)
+    .map(([name, value]) =>
+      name === 'color-scheme'
+        ? `${indent}color-scheme: ${scheme};\n${indent}--bq-scheme-color-scheme: ${scheme};`
+        : `${indent}--bq-scheme-${name}: ${value};`
+    )
+    .join('\n');
+}
+
+/**
+ * Document-level CSS that drives the scheme channel.
+ *
+ * Install it once (see `installThemeStyles`) and `data-theme` works on any
+ * element, in any browser: `dark` and `light` pin a scheme for that subtree,
+ * `auto` follows the operating system and re-resolves live with no JavaScript
+ * listening for the change.
+ */
+export function getSchemeRootCSS(): string {
+  const dark = channel(DARK_TOKENS, 'dark');
+  const light = channel(LIGHT_TOKENS, 'light');
+  const darkOverrides = Object.entries(DARK_OVERRIDES)
+    .map(([name, value]) => `  --bq-scheme-${name}: ${value};`)
+    .join('\n');
+
+  return `[data-theme="dark"] {
+${dark}
+${darkOverrides}
+}
+
+[data-theme="light"] {
+${light}
+}
+
+@media (prefers-color-scheme: dark) {
+  [data-theme="auto"] {
+${dark
+  .split('\n')
+  .map((line) => `  ${line}`)
+  .join('\n')}
+${darkOverrides
+  .split('\n')
+  .map((line) => `  ${line}`)
+  .join('\n')}
+  }
+}`;
+}
diff --git a/src/tokens/index.ts b/src/tokens/index.ts
index 01072c6..95ee1a1 100644
--- a/src/tokens/index.ts
+++ b/src/tokens/index.ts
@@ -97,6 +97,8 @@ export function getTokensCSS(): string {
   --bq-font-size-lg: 1.125rem;
   --bq-font-size-xl: 1.25rem;
   --bq-font-size-2xl: 1.5rem;
+  --bq-font-size-3xl: 1.875rem;
+  --bq-font-size-4xl: 2.25rem;
   --bq-font-weight-normal: 400;
   --bq-font-weight-medium: 500;
   --bq-font-weight-semibold: 600;
@@ -104,6 +106,11 @@ export function getTokensCSS(): string {
   --bq-line-height-tight: 1.25;
   --bq-line-height-normal: 1.5;
   --bq-line-height-relaxed: 1.625;
+  /* Headings and all-caps labels need the tracking pulled in or pushed out;
+     body copy is drawn at the font's natural spacing. */
+  --bq-letter-spacing-tight: -0.015em;
+  --bq-letter-spacing-normal: 0;
+  --bq-letter-spacing-wide: 0.04em;
 
   /* === Spacing === */
   --bq-space-0: 0;
@@ -127,20 +134,42 @@ export function getTokensCSS(): string {
   --bq-radius-2xl: 1rem;
   --bq-radius-full: 9999px;
 
-  /* === Shadows === */
-  --bq-shadow-sm: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
-  --bq-shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06);
-  --bq-shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -2px rgba(0, 0, 0, 0.05);
-  --bq-shadow-xl: 0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 10px 10px -5px rgba(0, 0, 0, 0.04);
-  --bq-shadow-inner: inset 0 2px 4px 0 rgba(0, 0, 0, 0.06);
+  /* === Borders === */
+  --bq-border-width: 1px;
+  --bq-border-width-control: 1.5px;
+
+  /* === Control metrics ===
+     One height scale for every control that sits on a form row, so a button,
+     an input and a select line up on the same baseline without each component
+     inventing its own padding. */
+  --bq-control-height-sm: 2rem;
+  --bq-control-height-md: 2.5rem;
+  --bq-control-height-lg: 3rem;
+  --bq-control-height-xl: 3.5rem;
+  --bq-control-padding-sm: 0.75rem;
+  --bq-control-padding-md: 0.875rem;
+  --bq-control-padding-lg: 1rem;
+
+  /* === Shadows ===
+     Tinted with the neutral ramp rather than pure black: a grey-blue shadow
+     reads as depth, while black over a coloured surface reads as dirt. */
+  --bq-shadow-xs: 0 1px 2px 0 rgba(15, 23, 42, 0.04);
+  --bq-shadow-sm: 0 1px 2px 0 rgba(15, 23, 42, 0.06), 0 1px 3px 0 rgba(15, 23, 42, 0.1);
+  --bq-shadow-md: 0 2px 4px -1px rgba(15, 23, 42, 0.06), 0 4px 8px -2px rgba(15, 23, 42, 0.1);
+  --bq-shadow-lg: 0 4px 6px -2px rgba(15, 23, 42, 0.05), 0 12px 20px -4px rgba(15, 23, 42, 0.12);
+  --bq-shadow-xl: 0 8px 10px -6px rgba(15, 23, 42, 0.08), 0 24px 40px -8px rgba(15, 23, 42, 0.16);
+  --bq-shadow-inner: inset 0 1px 2px 0 rgba(15, 23, 42, 0.06);
 
   /* === Motion === */
+  --bq-duration-instant: 75ms;
   --bq-duration-fast: 150ms;
   --bq-duration-normal: 200ms;
   --bq-duration-slow: 300ms;
+  --bq-duration-slower: 450ms;
   --bq-easing-standard: cubic-bezier(0.4, 0, 0.2, 1);
   --bq-easing-decelerate: cubic-bezier(0, 0, 0.2, 1);
   --bq-easing-accelerate: cubic-bezier(0.4, 0, 1, 1);
+  --bq-easing-emphasized: cubic-bezier(0.2, 0, 0, 1);
   --bq-easing-spring: cubic-bezier(0.34, 1.56, 0.64, 1);
 
   /* === Z-Index === */
diff --git a/src/utils/focus.ts b/src/utils/focus.ts
index 0aa08c1..55f243e 100644
--- a/src/utils/focus.ts
+++ b/src/utils/focus.ts
@@ -11,13 +11,15 @@
  * keystroke re-renders on every keystroke, so the user can type exactly one
  * character before losing the field.
  *
- * These helpers bracket a render — capture in `beforeUpdate()`, restore in
- * `updated()` — and put focus and selection back on the node that replaced
- * the one the user was in.
+ * These helpers bracket a render and put focus and selection back on the node
+ * that replaced the one the user was in. Most components want the packaged
+ * form — {@link trackFocus} plus {@link restorePreservedFocus} — rather than
+ * the {@link captureFocus} / {@link restoreFocus} primitives underneath it:
  *
  * ```ts
- * beforeUpdate() { focusStore(this).snapshot = captureFocus(this.shadowRoot); },
- * updated() { restoreFocus(this.shadowRoot, focusStore(this).snapshot); },
+ * connected()    { trackFocus(host(this), bind(this)); },
+ * beforeUpdate() { markFocus(this); },
+ * updated()      { restorePreservedFocus(this); },
  * ```
  */
 
@@ -58,28 +60,51 @@ function cssEscape(value: string): string {
   return value.replace(/["\\]/g, '\\$&');
 }
 
+/**
+ * Attributes that tell two otherwise identical nodes apart.
+ *
+ * A shadow tree usually contains several elements sharing one `part` — every
+ * page button in a pagination bar, every remove button in a tag list. Matching
+ * on `part` alone would put focus back on the first of them, so the selector
+ * also pins whichever of these the element carries.
+ */
+const DISCRIMINATORS = ['data-value', 'data-index', 'data-page', 'name'];
+
+function discriminatorSelector(el: Element): string {
+  for (const attribute of DISCRIMINATORS) {
+    const value = el.getAttribute(attribute);
+    if (value !== null) return `[${attribute}="${cssEscape(value)}"]`;
+  }
+  return '';
+}
+
 /**
  * Derives a selector that will match the equivalent node after a re-render.
  *
- * `part` first: it is this library's convention for naming the meaningful
- * elements of a shadow tree, it is stable across renders, and it is unique
- * per component. Falls back to `id`, then to a tag/class shape.
+ * `id` first: components in this library derive ids from a per-instance uid,
+ * so an id is both stable across renders and unique within the shadow tree.
+ * Falls back to `part` — the convention for naming the meaningful elements of
+ * a shadow tree — and then to a tag/class shape, in both cases narrowed by a
+ * {@link DISCRIMINATORS} attribute when the element carries one.
  */
 function describeElement(el: Element): string | null {
+  const id = el.getAttribute('id');
+  if (id) return `[id="${cssEscape(id)}"]`;
+
+  const extra = discriminatorSelector(el);
+
   const part = el.getAttribute('part');
   if (part) {
     const first = part.trim().split(/\s+/)[0];
-    if (first) return `[part~="${cssEscape(first)}"]`;
+    if (first) return `[part~="${cssEscape(first)}"]${extra}`;
   }
-  const id = el.getAttribute('id');
-  if (id) return `[id="${cssEscape(id)}"]`;
 
   const tag = el.tagName.toLowerCase();
   const classes = Array.from(el.classList);
   if (classes.length > 0) {
-    return `${tag}.${classes.map((c) => CSS_ESCAPE(c)).join('.')}`;
+    return `${tag}.${classes.map((c) => CSS_ESCAPE(c)).join('.')}${extra}`;
   }
-  return tag;
+  return `${tag}${extra}`;
 }
 
 // Class names may contain characters that are invalid bare in a selector.
@@ -159,3 +184,106 @@ export function restoreFocus(
 
   return true;
 }
+
+// ─── Element-keyed convenience layer ─────────────────────────────────────────
+
+/**
+ * `beforeUpdate()` only runs for attribute-driven renders. A component that
+ * keeps draft text in component *state* re-renders through `setState`, which
+ * skips that hook entirely — so those components record the focus position
+ * from the event that is about to change state instead. See {@link trackFocus}.
+ */
+const pendingSnapshots = new WeakMap<object, FocusSnapshot | null>();
+const scheduledClears = new WeakSet<object>();
+
+function scheduleClear(el: HTMLElement): void {
+  if (scheduledClears.has(el)) return;
+  scheduledClears.add(el);
+  const clear = () => {
+    scheduledClears.delete(el);
+    pendingSnapshots.delete(el);
+  };
+  if (typeof queueMicrotask === 'function') queueMicrotask(clear);
+  else Promise.resolve().then(clear);
+}
+
+/**
+ * Records where focus is, to be restored by the next
+ * {@link restorePreservedFocus} call.
+ *
+ * The snapshot expires at the end of the current task. That is the whole
+ * guarantee: a render caused by whatever is running *now* repairs focus, while
+ * an unrelated render minutes later — an attribute set by application code
+ * while the user is somewhere else entirely — does not yank focus back.
+ */
+export function markFocus(el: HTMLElement): void {
+  pendingSnapshots.set(el, captureFocus(el.shadowRoot));
+  scheduleClear(el);
+}
+
+/**
+ * Restores the position recorded by {@link markFocus}. Call from `updated()`.
+ *
+ * The snapshot is deliberately not consumed by the first restore: one event
+ * handler often calls `setState` several times, each render destroys the field
+ * again, and only the first of them would otherwise be repaired.
+ *
+ * @returns whether focus was actually restored.
+ */
+export function restorePreservedFocus(el: HTMLElement): boolean {
+  const snapshot = pendingSnapshots.get(el);
+  if (snapshot === undefined) return false;
+  return restoreFocus(el.shadowRoot, snapshot);
+}
+
+/**
+ * Events after which the focus position is worth recording.
+ *
+ * These are the events a component acts on. Listening in the **capture** phase
+ * on the shadow root means the snapshot is taken before the component's own
+ * (bubble-phase) handler runs, so it describes the tree as the user left it —
+ * caret included, since `input` capture already sees the inserted character.
+ */
+const TRACKED_EVENTS = [
+  'focusin',
+  'input',
+  'keydown',
+  'mousedown',
+  'click',
+  'select',
+] as const;
+
+/** Minimal view of the disposer scope from `./component.js`. */
+interface FocusScope {
+  on(
+    target: EventTarget | null | undefined,
+    type: string,
+    handler: EventListener,
+    options?: AddEventListenerOptions | boolean
+  ): unknown;
+}
+
+/**
+ * Keeps focus and the caret pinned across re-renders, for the whole lifetime
+ * of a component.
+ *
+ * Rendering assigns `shadowRoot.innerHTML`, so every render destroys the node
+ * the user is in. Components used to work around that by marking the focus
+ * position by hand before each `setState` — easy to forget, and it missed the
+ * renders triggered from `focusin`, which is how a field loses focus the very
+ * moment it is clicked.
+ *
+ * One call in `connected()` covers the component instead:
+ *
+ * ```ts
+ * connected() { trackFocus(host(this), bind(this)); },
+ * beforeUpdate() { markFocus(this); },
+ * updated() { restorePreservedFocus(this); },
+ * ```
+ */
+export function trackFocus(el: HTMLElement, scope: FocusScope): void {
+  const root = el.shadowRoot;
+  if (!root) return;
+  const record: EventListener = () => markFocus(el);
+  for (const type of TRACKED_EVENTS) scope.on(root, type, record, true);
+}
diff --git a/src/utils/icons.ts b/src/utils/icons.ts
new file mode 100644
index 0000000..e393434
--- /dev/null
+++ b/src/utils/icons.ts
@@ -0,0 +1,230 @@
+/**
+ * The icon set, delivered as CSS masks.
+ *
+ * Rendered markup goes through the framework sanitizer, and `svg` is on its
+ * *forbidden* list — a list `sanitize.allowTags` cannot re-open. So a component
+ * cannot emit an inline `<svg>` no matter how it is configured, which is why
+ * this library used to draw its affordances with text glyphs (`&times;`,
+ * `&#9660;`, `✓`). Those inherit whatever the platform font decides: different
+ * weights, different baselines, no way to control the stroke, and a close
+ * button that looks like a lowercase x on one OS and a heavy cross on another.
+ *
+ * Component *styles* are not sanitized, so the icons live there instead. Each
+ * one is a `mask-image` data URI painted with `background-color: currentColor`,
+ * which means it inherits text colour, scales with `font-size`, and stays a
+ * single crisp path at any DPI.
+ *
+ * ```ts
+ * styles: css`
+ *   ${baseStyles}
+ *   ${iconCss('chevron-down', 'x')}
+ * `,
+ * render: () => html`<span class="icon" data-icon="x" aria-hidden="true"></span>`
+ * ```
+ *
+ * Pull only the icons a component actually draws: {@link iconCss} emits one
+ * rule per name, so an unused icon costs nothing. To decorate an element the
+ * component already renders, {@link iconMask} returns the declarations on their
+ * own for use inside any selector, including `::before`/`::after`.
+ *
+ * Geometry follows the common 24×24, 2px-stroke, round-cap convention, so the
+ * set sits comfortably next to Lucide, Feather or Heroicons if an application
+ * mixes in its own.
+ */
+import { rawCss } from './styles.js';
+import type { ComponentStyles } from '@bquery/bquery/component';
+
+/** Inner SVG markup for each icon, on a 24×24 canvas. */
+const ICON_BODY = {
+  // ── Status ───────────────────────────────────────────────────────────────
+  check: `<path d='M20 6 9 17l-5-5'/>`,
+  'check-circle': `<path d='M21.8 10A10 10 0 1 1 15.9 2.6'/><path d='m9 11 3 3L22 4'/>`,
+  x: `<path d='M18 6 6 18'/><path d='m6 6 12 12'/>`,
+  'x-circle': `<circle cx='12' cy='12' r='10'/><path d='m15 9-6 6'/><path d='m9 9 6 6'/>`,
+  info: `<circle cx='12' cy='12' r='10'/><path d='M12 16v-4'/><path d='M12 8h.01'/>`,
+  'alert-circle': `<circle cx='12' cy='12' r='10'/><path d='M12 8v4'/><path d='M12 16h.01'/>`,
+  'alert-triangle': `<path d='m21.7 18-8-14a2 2 0 0 0-3.4 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.7-3Z'/><path d='M12 9v4'/><path d='M12 17h.01'/>`,
+  'help-circle': `<circle cx='12' cy='12' r='10'/><path d='M9.1 9a3 3 0 0 1 5.8 1c0 2-3 3-3 3'/><path d='M12 17h.01'/>`,
+  circle: `<circle cx='12' cy='12' r='10'/>`,
+  dot: `<circle cx='12' cy='12' r='5' fill='#000' stroke='none'/>`,
+
+  // ── Direction ────────────────────────────────────────────────────────────
+  'chevron-up': `<path d='m18 15-6-6-6 6'/>`,
+  'chevron-down': `<path d='m6 9 6 6 6-6'/>`,
+  'chevron-left': `<path d='m15 18-6-6 6-6'/>`,
+  'chevron-right': `<path d='m9 18 6-6-6-6'/>`,
+  'chevrons-left': `<path d='m11 17-5-5 5-5'/><path d='m18 17-5-5 5-5'/>`,
+  'chevrons-right': `<path d='m6 17 5-5-5-5'/><path d='m13 17 5-5-5-5'/>`,
+  'chevrons-up-down': `<path d='m7 15 5 5 5-5'/><path d='m7 9 5-5 5 5'/>`,
+  'arrow-up': `<path d='M12 19V5'/><path d='m5 12 7-7 7 7'/>`,
+  'arrow-down': `<path d='M12 5v14'/><path d='m19 12-7 7-7-7'/>`,
+  'arrow-left': `<path d='M19 12H5'/><path d='m12 19-7-7 7-7'/>`,
+  'arrow-right': `<path d='M5 12h14'/><path d='m12 5 7 7-7 7'/>`,
+  'external-link': `<path d='M15 3h6v6'/><path d='M10 14 21 3'/><path d='M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6'/>`,
+
+  // ── Actions ──────────────────────────────────────────────────────────────
+  plus: `<path d='M12 5v14'/><path d='M5 12h14'/>`,
+  minus: `<path d='M5 12h14'/>`,
+  search: `<circle cx='11' cy='11' r='8'/><path d='m21 21-4.3-4.3'/>`,
+  menu: `<path d='M4 6h16'/><path d='M4 12h16'/><path d='M4 18h16'/>`,
+  'more-horizontal': `<circle cx='12' cy='12' r='1.4' fill='#000' stroke='none'/><circle cx='19' cy='12' r='1.4' fill='#000' stroke='none'/><circle cx='5' cy='12' r='1.4' fill='#000' stroke='none'/>`,
+  'more-vertical': `<circle cx='12' cy='12' r='1.4' fill='#000' stroke='none'/><circle cx='12' cy='5' r='1.4' fill='#000' stroke='none'/><circle cx='12' cy='19' r='1.4' fill='#000' stroke='none'/>`,
+  trash: `<path d='M3 6h18'/><path d='M19 6v14a2 2 0 0 1-2 2H7a2 2 0 0 1-2-2V6'/><path d='M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2'/><path d='M10 11v6'/><path d='M14 11v6'/>`,
+  copy: `<rect width='14' height='14' x='8' y='8' rx='2'/><path d='M4 16a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h10a2 2 0 0 1 2 2'/>`,
+  edit: `<path d='M11 4H4a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2v-7'/><path d='M18.5 2.5a2.1 2.1 0 0 1 3 3L12 15l-4 1 1-4Z'/>`,
+  download: `<path d='M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4'/><path d='m7 10 5 5 5-5'/><path d='M12 15V3'/>`,
+  upload: `<path d='M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4'/><path d='m17 8-5-5-5 5'/><path d='M12 3v12'/>`,
+  refresh: `<path d='M3 12a9 9 0 0 1 9-9 9.8 9.8 0 0 1 6.7 2.7L21 8'/><path d='M21 3v5h-5'/><path d='M21 12a9 9 0 0 1-9 9 9.8 9.8 0 0 1-6.7-2.7L3 16'/><path d='M8 16H3v5'/>`,
+  filter: `<path d='M22 3H2l8 9.5V19l4 2v-8.5L22 3Z'/>`,
+  settings: `<circle cx='12' cy='12' r='3'/><path d='M13.8 2.2a1.8 1.8 0 0 0-3.6 0 1.8 1.8 0 0 1-2.7 1.1 1.8 1.8 0 0 0-2.5 2.5 1.8 1.8 0 0 1-1.1 2.7 1.8 1.8 0 0 0 0 3.6 1.8 1.8 0 0 1 1.1 2.7 1.8 1.8 0 0 0 2.5 2.5 1.8 1.8 0 0 1 2.7 1.1 1.8 1.8 0 0 0 3.6 0 1.8 1.8 0 0 1 2.7-1.1 1.8 1.8 0 0 0 2.5-2.5 1.8 1.8 0 0 1 1.1-2.7 1.8 1.8 0 0 0 0-3.6 1.8 1.8 0 0 1-1.1-2.7 1.8 1.8 0 0 0-2.5-2.5 1.8 1.8 0 0 1-2.7-1.1Z'/>`,
+
+  // ── Objects ──────────────────────────────────────────────────────────────
+  eye: `<path d='M2 12s3.5-7 10-7 10 7 10 7-3.5 7-10 7-10-7-10-7Z'/><circle cx='12' cy='12' r='3'/>`,
+  'eye-off': `<path d='M9.9 4.2A11 11 0 0 1 12 4c6.5 0 10 8 10 8a18 18 0 0 1-2.2 3.2'/><path d='M6.6 6.6A18 18 0 0 0 2 12s3.5 7 10 7a11 11 0 0 0 5.4-1.4'/><path d='M14.1 14.1a3 3 0 1 1-4.2-4.2'/><path d='m2 2 20 20'/>`,
+  lock: `<rect width='18' height='11' x='3' y='11' rx='2'/><path d='M7 11V7a5 5 0 0 1 10 0v4'/>`,
+  calendar: `<path d='M8 2v4'/><path d='M16 2v4'/><rect width='18' height='18' x='3' y='4' rx='2'/><path d='M3 10h18'/>`,
+  clock: `<circle cx='12' cy='12' r='10'/><path d='M12 6v6l4 2'/>`,
+  star: `<path d='m12 2 3.1 6.3 6.9 1-5 4.9 1.2 6.8L12 17.8 5.8 21l1.2-6.8-5-4.9 6.9-1Z'/>`,
+  'star-filled': `<path d='m12 2 3.1 6.3 6.9 1-5 4.9 1.2 6.8L12 17.8 5.8 21l1.2-6.8-5-4.9 6.9-1Z' fill='#000'/>`,
+  heart: `<path d='M19 14c1.5-1.5 3-3.2 3-5.5A5.5 5.5 0 0 0 16.5 3c-1.8 0-3 .5-4.5 2-1.5-1.5-2.7-2-4.5-2A5.5 5.5 0 0 0 2 8.5c0 2.3 1.5 4 3 5.5l7 7Z'/>`,
+  user: `<path d='M19 21v-2a4 4 0 0 0-4-4H9a4 4 0 0 0-4 4v2'/><circle cx='12' cy='7' r='4'/>`,
+  users: `<path d='M16 21v-2a4 4 0 0 0-4-4H6a4 4 0 0 0-4 4v2'/><circle cx='9' cy='7' r='4'/><path d='M22 21v-2a4 4 0 0 0-3-3.9'/><path d='M16 3.1a4 4 0 0 1 0 7.8'/>`,
+  mail: `<rect width='20' height='16' x='2' y='4' rx='2'/><path d='m22 7-8.9 5.3a2 2 0 0 1-2.1 0L2 7'/>`,
+  link: `<path d='M10 13a5 5 0 0 0 7.5.5l3-3a5 5 0 0 0-7-7l-1.8 1.7'/><path d='M14 11a5 5 0 0 0-7.5-.5l-3 3a5 5 0 0 0 7 7l1.7-1.7'/>`,
+  image: `<rect width='18' height='18' x='3' y='3' rx='2'/><circle cx='9' cy='9' r='2'/><path d='m21 15-3.1-3.1a2 2 0 0 0-2.8 0L6 21'/>`,
+  file: `<path d='M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z'/><path d='M14 2v4a2 2 0 0 0 2 2h4'/>`,
+  folder: `<path d='M20 20a2 2 0 0 0 2-2V8a2 2 0 0 0-2-2h-7.9a2 2 0 0 1-1.7-.9L9.6 3.9A2 2 0 0 0 7.9 3H4a2 2 0 0 0-2 2v13a2 2 0 0 0 2 2Z'/>`,
+  home: `<path d='M3 9.5 12 2l9 7.5V20a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2Z'/><path d='M9 22V12h6v10'/>`,
+  sun: `<circle cx='12' cy='12' r='4'/><path d='M12 2v2'/><path d='M12 20v2'/><path d='m4.9 4.9 1.4 1.4'/><path d='m17.7 17.7 1.4 1.4'/><path d='M2 12h2'/><path d='M20 12h2'/><path d='m6.3 17.7-1.4 1.4'/><path d='m19.1 4.9-1.4 1.4'/>`,
+  moon: `<path d='M12 3a6 6 0 0 0 9 9 9 9 0 1 1-9-9Z'/>`,
+  loader: `<path d='M12 2v4'/><path d='m16.2 7.8 2.9-2.9'/><path d='M18 12h4'/><path d='m16.2 16.2 2.9 2.9'/><path d='M12 18v4'/><path d='m4.9 19.1 2.9-2.9'/><path d='M2 12h4'/><path d='m4.9 4.9 2.9 2.9'/>`,
+} as const;
+
+/** Every icon this library ships. */
+export type IconName = keyof typeof ICON_BODY;
+
+/** Sorted list of every available icon name. */
+export const iconNames: readonly IconName[] = Object.keys(
+  ICON_BODY
+).sort() as IconName[];
+
+/** Whether a string names an icon in the set. */
+export function isIconName(value: string): value is IconName {
+  return Object.prototype.hasOwnProperty.call(ICON_BODY, value);
+}
+
+/**
+ * Percent-encodes the characters a data URI cannot carry literally.
+ *
+ * Deliberately not `encodeURIComponent`: the SVG source is written with single
+ * quotes and no `?`/`&`, so escaping the five characters that actually matter
+ * keeps the URI roughly a third shorter and still readable in devtools.
+ */
+function encodeSvg(svg: string): string {
+  return svg
+    .replace(/%/g, '%25')
+    .replace(/</g, '%3C')
+    .replace(/>/g, '%3E')
+    .replace(/#/g, '%23')
+    .replace(/"/g, '%22')
+    .replace(/\s+/g, ' ');
+}
+
+const svgCache = new Map<IconName, string>();
+
+/**
+ * The `url(...)` value for one icon, ready to assign to `mask-image`.
+ *
+ * The mask is painted from the source's *alpha*, so the stroke colour in the
+ * document is irrelevant — what shows through is whatever
+ * `background-color` the rule sets.
+ */
+export function iconUrl(name: IconName): string {
+  const cached = svgCache.get(name);
+  if (cached) return cached;
+  const svg =
+    `<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' ` +
+    `stroke='#000' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'>` +
+    `${ICON_BODY[name]}</svg>`;
+  const url = `url("data:image/svg+xml,${encodeSvg(svg)}")`;
+  svgCache.set(name, url);
+  return url;
+}
+
+/**
+ * The mask declarations for one icon, without a selector.
+ *
+ * Use inside a rule that already sizes and colours the box — typically a
+ * `::before` on an element the component renders anyway:
+ *
+ * ```ts
+ * `.chip::after { ${iconMaskText('x')} background: currentColor; }`
+ * ```
+ */
+export function iconMaskText(name: IconName): string {
+  const url = iconUrl(name);
+  return `-webkit-mask-image: ${url}; mask-image: ${url};`;
+}
+
+/** {@link iconMaskText} as a composable `css` payload. */
+export function iconMask(name: IconName): ComponentStyles {
+  return rawCss(iconMaskText(name));
+}
+
+/**
+ * The shared `.icon` box: a square that tracks the current font size and takes
+ * its colour from the text around it.
+ *
+ * `flex: none` matters — an icon inside a flex row is the one thing that must
+ * never be squeezed, and a squeezed mask silently crops the glyph rather than
+ * overflowing visibly.
+ */
+const ICON_BASE_TEXT = `
+  .icon {
+    display: inline-block;
+    flex: none;
+    inline-size: var(--bq-icon-size, 1em);
+    block-size: var(--bq-icon-size, 1em);
+    background-color: currentColor;
+    -webkit-mask-repeat: no-repeat;
+    mask-repeat: no-repeat;
+    -webkit-mask-position: center;
+    mask-position: center;
+    -webkit-mask-size: contain;
+    mask-size: contain;
+  }
+  /* Windows high-contrast paints backgrounds away; keep the glyph visible. */
+  @media (forced-colors: active) {
+    .icon { background-color: CanvasText; }
+  }
+`;
+
+/** The `.icon` base rule on its own, for components that build their own set. */
+export const iconBase: ComponentStyles = rawCss(ICON_BASE_TEXT);
+
+function iconRules(names: readonly IconName[]): string {
+  const seen = new Set<IconName>();
+  let out = '';
+  for (const name of names) {
+    if (seen.has(name)) continue;
+    seen.add(name);
+    out += `\n  .icon[data-icon="${name}"] { ${iconMaskText(name)} }`;
+  }
+  return out;
+}
+
+/**
+ * A stylesheet fragment carrying the `.icon` box plus the named icons.
+ *
+ * Name only what the component renders. Every icon is a data URI of a few
+ * hundred bytes, and a component that pulls the whole set pays for all of it
+ * in every shadow root that adopts the sheet.
+ */
+export function iconCss(...names: IconName[]): ComponentStyles {
+  return rawCss(`${ICON_BASE_TEXT}${iconRules(names)}`);
+}
+
+/** Every icon in one fragment. Sized for `bq-icon`; too heavy for anything else. */
+export function allIconCss(): ComponentStyles {
+  return rawCss(`${ICON_BASE_TEXT}${iconRules(iconNames)}`);
+}
diff --git a/src/utils/index.ts b/src/utils/index.ts
index 881b6f5..33aefec 100644
--- a/src/utils/index.ts
+++ b/src/utils/index.ts
@@ -9,8 +9,25 @@ export {
   unlinkDescribedBy,
 } from './aria.js';
 export { cn } from './cn.js';
-export { captureFocus, restoreFocus } from './focus.js';
+export {
+  captureFocus,
+  markFocus,
+  restoreFocus,
+  restorePreservedFocus,
+  trackFocus,
+} from './focus.js';
 export type { FocusSnapshot } from './focus.js';
+export {
+  allIconCss,
+  iconBase,
+  iconCss,
+  iconMask,
+  iconMaskText,
+  iconNames,
+  iconUrl,
+  isIconName,
+} from './icons.js';
+export type { IconName } from './icons.js';
 export { bind, host, release, store } from './component.js';
 export type { ComponentScope, Disposer } from './component.js';
 export {
@@ -58,6 +75,10 @@ export type {
 } from './position.js';
 export {
   baseStyles,
+  fieldStyles,
+  fieldStylesText,
+  focusRing,
+  focusRingStyles,
   focusVisible,
   focusVisibleStyles,
   getBaseStyles,
diff --git a/src/utils/styles.ts b/src/utils/styles.ts
index 8c250db..69c8304 100644
--- a/src/utils/styles.ts
+++ b/src/utils/styles.ts
@@ -4,11 +4,14 @@
  *
  * Components should compose their styles with the `css` tagged template from
  * `@bquery/bquery/component` and interpolate the {@link ComponentStyles}
- * exports from this module (`baseStyles`, `focusVisible`, `srOnly`, `reset`):
+ * exports from this module (`baseStyles`, `reset`, `focusRing`, `fieldStyles`,
+ * `srOnly`):
  *
  * ```ts
  * styles: css`
  *   ${baseStyles}
+ *   ${reset}
+ *   ${focusRing}
  *   .thing { color: var(--bq-text-base); }
  * `
  * ```
@@ -27,6 +30,7 @@ import { css } from '@bquery/bquery/component';
 import type { ComponentStyles } from '@bquery/bquery/component';
 import { getDefaultThemeCSS } from '../theme/default.js';
 import { getDarkThemeCSS } from '../theme/dark.js';
+import { installThemeStyles } from '../theme/root.js';
 
 /**
  * Wraps already-trusted CSS text in a {@link ComponentStyles} payload.
@@ -42,6 +46,12 @@ export function rawCss(text: string): ComponentStyles {
   return css(chunks as unknown as TemplateStringsArray);
 }
 
+// Every component imports this module for its base styles, so this is the one
+// place guaranteed to run no matter which entrypoint an application uses —
+// the bundle root, a single `@bquery/ui/components/button` import, or the CDN
+// build. The rules it installs are inert until a page sets `data-theme`.
+installThemeStyles();
+
 const BASE_STYLE_TEXT = `${getDefaultThemeCSS()}\n${getDarkThemeCSS()}`;
 
 /**
@@ -55,6 +65,37 @@ export function getBaseStyles(): string {
   return BASE_STYLE_TEXT;
 }
 
+/**
+ * Elements that should show a focus ring when keyboard-focused.
+ *
+ * Written as `:where(...)` so the whole selector has zero specificity: a
+ * component that wants a different ring on one element only has to name it,
+ * without an `!important` or an id-strength selector to outrank this.
+ */
+const FOCUSABLE_SELECTOR = `:where(a[href], button, input, select, summary, textarea, [tabindex]:not([tabindex="-1"]))`;
+
+const FOCUS_RING_TEXT = `
+  ${FOCUSABLE_SELECTOR}:focus-visible {
+    outline: 2px solid transparent;
+    outline-offset: 2px;
+    box-shadow: var(--bq-focus-ring, 0 0 0 3px rgba(37, 99, 235, 0.35));
+  }
+  /* Windows high-contrast throws box-shadow away, so the ring has to come
+     back as a real outline or keyboard focus becomes invisible. */
+  @media (forced-colors: active) {
+    ${FOCUSABLE_SELECTOR}:focus-visible {
+      outline: 2px solid Highlight;
+      outline-offset: 2px;
+    }
+  }
+`;
+
+/** The standard keyboard focus ring, applied to the usual focusable elements. */
+export const focusRingStyles = FOCUS_RING_TEXT;
+
+/** {@link focusRingStyles} as a composable `css` payload. */
+export const focusRing: ComponentStyles = rawCss(FOCUS_RING_TEXT);
+
 const FOCUS_VISIBLE_TEXT = `
   :host(:focus-within) *:focus-visible,
   *:focus-visible {
@@ -64,7 +105,12 @@ const FOCUS_VISIBLE_TEXT = `
   }
 `;
 
-/** Focus-visible outline using the CSS custom property --bq-focus-ring. */
+/**
+ * Focus-visible outline using the CSS custom property --bq-focus-ring.
+ *
+ * @deprecated Prefer {@link focusRing}: this variant matches `*`, so it also
+ * rings non-interactive containers and outranks a component's own rules.
+ */
 export const focusVisibleStyles = FOCUS_VISIBLE_TEXT;
 
 /** {@link focusVisibleStyles} as a composable `css` payload. */
@@ -93,10 +139,66 @@ export const srOnly: ComponentStyles = rawCss(SR_ONLY_TEXT);
 const RESET_TEXT = `
   *, *::before, *::after { box-sizing: border-box; }
   :host([hidden]) { display: none !important; }
+  /* Honour the OS "reduce motion" setting everywhere at once. Durations are
+     collapsed rather than set to \`none\` so transition/animation events still
+     fire and any logic waiting on them keeps working. */
+  @media (prefers-reduced-motion: reduce) {
+    *, *::before, *::after {
+      animation-duration: 0.01ms !important;
+      animation-iteration-count: 1 !important;
+      transition-duration: 0.01ms !important;
+      scroll-behavior: auto !important;
+    }
+  }
 `;
 
 /**
  * Minimal per-component reset. Every component repeats the same box-sizing and
- * `[hidden]` rules, so they live here once.
+ * `[hidden]` rules, so they live here once — together with the reduced-motion
+ * opt-out, which is far too easy to forget one component at a time.
  */
 export const reset: ComponentStyles = rawCss(RESET_TEXT);
+
+const FIELD_TEXT = `
+  .field {
+    display: flex;
+    flex-direction: column;
+    gap: 0.375rem;
+    font-family: var(--bq-font-family-sans);
+  }
+  .label {
+    display: flex;
+    align-items: center;
+    gap: 0.25rem;
+    font-size: var(--bq-font-size-sm, 0.875rem);
+    font-weight: var(--bq-font-weight-medium, 500);
+    line-height: var(--bq-line-height-normal, 1.5);
+    color: var(--bq-text-base, #0f172a);
+  }
+  .required-mark { color: var(--bq-color-danger-600, #dc2626); }
+  .hint,
+  .error-msg {
+    font-size: var(--bq-font-size-sm, 0.875rem);
+    line-height: var(--bq-line-height-normal, 1.5);
+    font-family: var(--bq-font-family-sans);
+  }
+  .hint { color: var(--bq-text-muted, #475569); }
+  .error-msg {
+    display: flex;
+    align-items: center;
+    gap: 0.25rem;
+    color: var(--bq-color-danger-600, #dc2626);
+  }
+  :host([disabled]) .label,
+  :host([disabled]) .hint { opacity: 0.6; }
+`;
+
+/**
+ * Label, hint, error and required-marker typography shared by every form
+ * control, so a hint under a text field and a hint under a slider are the same
+ * size, colour and rhythm.
+ */
+export const fieldStyles: ComponentStyles = rawCss(FIELD_TEXT);
+
+/** {@link fieldStyles} as raw CSS text. */
+export const fieldStylesText = FIELD_TEXT;
diff --git a/stories/copy-button.stories.ts b/stories/copy-button.stories.ts
new file mode 100644
index 0000000..af0258d
--- /dev/null
+++ b/stories/copy-button.stories.ts
@@ -0,0 +1,49 @@
+import type { Meta, StoryObj } from '@storybook/web-components';
+import { storyHtml } from '@bquery/bquery/storybook';
+
+/**
+ * Copies text to the clipboard and confirms it did, because a copy button
+ * without feedback is indistinguishable from a dead one.
+ */
+const meta: Meta = {
+  title: 'Components/Copy Button',
+  tags: ['autodocs'],
+  render: (args) => storyHtml`
+    <bq-copy-button
+      value=${args.value}
+      variant=${args.variant}
+      size=${args.size}
+      ?disabled=${args.disabled}
+    ></bq-copy-button>
+  `,
+  argTypes: {
+    variant: { control: 'select', options: ['ghost', 'outline', 'solid'] },
+    size: { control: 'select', options: ['sm', 'md', 'lg'] },
+    disabled: { control: 'boolean' },
+    value: { control: 'text' },
+  },
+  args: { value: 'npm install @bquery/ui', variant: 'ghost', size: 'md', disabled: false },
+};
+export default meta;
+type Story = StoryObj;
+
+export const Default: Story = {};
+
+export const CopiesAnotherElement: Story = {
+  render: () => storyHtml`
+    <div style="display:flex;align-items:center;gap:0.5rem;background:#f8fafc;border:1px solid #e2e8f0;border-radius:0.5rem;padding:0.5rem 0.75rem">
+      <code id="install-snippet" style="flex:1">npm install @bquery/ui</code>
+      <bq-copy-button from="#install-snippet"></bq-copy-button>
+    </div>
+  `,
+};
+
+export const Variants: Story = {
+  render: () => storyHtml`
+    <div style="display:flex;gap:0.75rem;align-items:center">
+      <bq-copy-button value="ghost" variant="ghost"></bq-copy-button>
+      <bq-copy-button value="outline" variant="outline"></bq-copy-button>
+      <bq-copy-button value="solid" variant="solid"></bq-copy-button>
+    </div>
+  `,
+};
diff --git a/stories/date-picker.stories.ts b/stories/date-picker.stories.ts
new file mode 100644
index 0000000..d5522a6
--- /dev/null
+++ b/stories/date-picker.stories.ts
@@ -0,0 +1,59 @@
+import type { Meta, StoryObj } from '@storybook/web-components';
+import { storyHtml } from '@bquery/bquery/storybook';
+
+/**
+ * A text field with a calendar popup. Values are ISO `YYYY-MM-DD` on the
+ * attribute; what the user sees is formatted for the requested locale, as are
+ * the month names, weekday headers and the first day of the week.
+ */
+const meta: Meta = {
+  title: 'Components/Date Picker',
+  tags: ['autodocs'],
+  render: (args) => storyHtml`
+    <div style="min-height:26rem">
+      <bq-date-picker
+        label=${args.label}
+        value=${args.value}
+        min=${args.min}
+        max=${args.max}
+        locale=${args.locale}
+        hint=${args.hint}
+        error=${args.error}
+        size=${args.size}
+        first-day-of-week=${args.firstDayOfWeek}
+        ?clearable=${args.clearable}
+        ?disabled=${args.disabled}
+      ></bq-date-picker>
+    </div>
+  `,
+  argTypes: {
+    locale: { control: 'select', options: ['en-US', 'en-GB', 'de-DE', 'fr-FR', 'ja-JP'] },
+    firstDayOfWeek: { control: { type: 'number', min: 0, max: 6 } },
+    size: { control: 'select', options: ['sm', 'md', 'lg'] },
+    clearable: { control: 'boolean' },
+    disabled: { control: 'boolean' },
+  },
+  args: {
+    label: 'Due date',
+    value: '2026-03-15',
+    min: '',
+    max: '',
+    locale: 'en-US',
+    hint: '',
+    error: '',
+    size: 'md',
+    firstDayOfWeek: 1,
+    clearable: true,
+    disabled: false,
+  },
+};
+export default meta;
+type Story = StoryObj;
+
+export const Default: Story = {};
+export const German: Story = { args: { locale: 'de-DE', label: 'Fälligkeitsdatum' } };
+export const SundayFirst: Story = { args: { locale: 'en-US', firstDayOfWeek: 0 } };
+export const RestrictedRange: Story = {
+  args: { min: '2026-03-10', max: '2026-03-24', hint: 'Only the third week of March is open.' },
+};
+export const WithError: Story = { args: { error: 'Pick a date in the future.' } };
diff --git a/stories/icon.stories.ts b/stories/icon.stories.ts
new file mode 100644
index 0000000..cef29e5
--- /dev/null
+++ b/stories/icon.stories.ts
@@ -0,0 +1,61 @@
+import type { Meta, StoryObj } from '@storybook/web-components';
+import { storyHtml } from '@bquery/bquery/storybook';
+import { iconNames } from '../src/utils/icons.js';
+
+/**
+ * One glyph from the built-in set, drawn as a CSS mask so it inherits the
+ * surrounding text colour and stays a single crisp path at any size.
+ */
+const meta: Meta = {
+  title: 'Components/Icon',
+  tags: ['autodocs'],
+  render: (args) =>
+    storyHtml`<bq-icon name=${args.name} size=${args.size} label=${args.label}></bq-icon>`,
+  argTypes: {
+    name: { control: 'select', options: [...iconNames] },
+    size: { control: 'text' },
+    label: { control: 'text' },
+  },
+  args: { name: 'check', size: '1.5rem', label: '' },
+};
+export default meta;
+type Story = StoryObj;
+
+export const Default: Story = {};
+
+export const InheritsTextColor: Story = {
+  render: () => storyHtml`
+    <div style="display:flex;gap:1.5rem;align-items:center;font-size:1.25rem">
+      <span style="color:#2563eb"><bq-icon name="info"></bq-icon> Info</span>
+      <span style="color:#16a34a"><bq-icon name="check-circle"></bq-icon> Done</span>
+      <span style="color:#dc2626"><bq-icon name="alert-triangle"></bq-icon> Failed</span>
+    </div>
+  `,
+};
+
+export const ScalesWithFontSize: Story = {
+  render: () => storyHtml`
+    <div style="display:flex;gap:1rem;align-items:center">
+      <span style="font-size:0.875rem"><bq-icon name="star"></bq-icon></span>
+      <span style="font-size:1.25rem"><bq-icon name="star"></bq-icon></span>
+      <span style="font-size:2rem"><bq-icon name="star"></bq-icon></span>
+      <span style="font-size:3rem"><bq-icon name="star"></bq-icon></span>
+    </div>
+  `,
+};
+
+export const Catalog: Story = {
+  render: () => storyHtml`
+    <div style="display:grid;grid-template-columns:repeat(auto-fill,minmax(7rem,1fr));gap:0.75rem">
+      ${iconNames
+        .map(
+          (name) => `
+        <div style="display:flex;flex-direction:column;align-items:center;gap:0.375rem;padding:0.75rem;border:1px solid #e2e8f0;border-radius:0.5rem">
+          <bq-icon name="${name}" size="1.5rem"></bq-icon>
+          <code style="font-size:0.6875rem;color:#475569">${name}</code>
+        </div>`
+        )
+        .join('')}
+    </div>
+  `,
+};
diff --git a/stories/meter.stories.ts b/stories/meter.stories.ts
new file mode 100644
index 0000000..7368c39
--- /dev/null
+++ b/stories/meter.stories.ts
@@ -0,0 +1,60 @@
+import type { Meta, StoryObj } from '@storybook/web-components';
+import { storyHtml } from '@bquery/bquery/storybook';
+
+/**
+ * A scalar measurement inside a known range — disk usage, password strength,
+ * a budget. Unlike a progress bar it can move in either direction, and the
+ * `low`/`high`/`optimum` bands colour it by whether the reading is healthy.
+ */
+const meta: Meta = {
+  title: 'Components/Meter',
+  tags: ['autodocs'],
+  render: (args) => storyHtml`
+    <bq-meter
+      value=${args.value}
+      min=${args.min}
+      max=${args.max}
+      label=${args.label}
+      size=${args.size}
+      ?show-value=${args.showValue}
+    ></bq-meter>
+  `,
+  argTypes: {
+    value: { control: { type: 'range', min: 0, max: 100 } },
+    size: { control: 'select', options: ['sm', 'md', 'lg'] },
+    showValue: { control: 'boolean' },
+    label: { control: 'text' },
+  },
+  args: { value: 64, min: 0, max: 100, label: 'Storage used', size: 'md', showValue: true },
+};
+export default meta;
+type Story = StoryObj;
+
+export const Default: Story = {};
+
+export const LowerIsBetter: Story = {
+  render: () => storyHtml`
+    <div style="display:flex;flex-direction:column;gap:1rem;max-width:24rem">
+      <bq-meter label="Disk usage" value="18" low="40" high="80" optimum="0" show-value></bq-meter>
+      <bq-meter label="Disk usage" value="62" low="40" high="80" optimum="0" show-value></bq-meter>
+      <bq-meter label="Disk usage" value="94" low="40" high="80" optimum="0" show-value></bq-meter>
+    </div>
+  `,
+};
+
+export const HigherIsBetter: Story = {
+  render: () => storyHtml`
+    <div style="display:flex;flex-direction:column;gap:1rem;max-width:24rem">
+      <bq-meter label="Battery" value="12" low="20" high="80" optimum="100" show-value></bq-meter>
+      <bq-meter label="Battery" value="55" low="20" high="80" optimum="100" show-value></bq-meter>
+      <bq-meter label="Battery" value="93" low="20" high="80" optimum="100" show-value></bq-meter>
+    </div>
+  `,
+};
+
+export const CustomValueText: Story = {
+  args: { label: 'Storage', value: 72 },
+  render: (args) => storyHtml`
+    <bq-meter label=${args.label} value=${args.value} value-text="72 GB of 100 GB" show-value></bq-meter>
+  `,
+};
diff --git a/stories/pin-input.stories.ts b/stories/pin-input.stories.ts
new file mode 100644
index 0000000..ff2694c
--- /dev/null
+++ b/stories/pin-input.stories.ts
@@ -0,0 +1,59 @@
+import type { Meta, StoryObj } from '@storybook/web-components';
+import { storyHtml } from '@bquery/bquery/storybook';
+
+/**
+ * A row of single-character cells for verification codes. Typing advances,
+ * Backspace steps back, and a pasted code spreads across the cells.
+ */
+const meta: Meta = {
+  title: 'Components/Pin Input',
+  tags: ['autodocs'],
+  render: (args) => storyHtml`
+    <bq-pin-input
+      length=${args.length}
+      type=${args.type}
+      label=${args.label}
+      hint=${args.hint}
+      error=${args.error}
+      size=${args.size}
+      ?mask=${args.mask}
+      ?disabled=${args.disabled}
+    ></bq-pin-input>
+  `,
+  argTypes: {
+    length: { control: { type: 'number', min: 2, max: 10 } },
+    type: { control: 'select', options: ['numeric', 'alphanumeric', 'text'] },
+    size: { control: 'select', options: ['sm', 'md', 'lg'] },
+    mask: { control: 'boolean' },
+    disabled: { control: 'boolean' },
+    label: { control: 'text' },
+    hint: { control: 'text' },
+    error: { control: 'text' },
+  },
+  args: {
+    length: 6,
+    type: 'numeric',
+    size: 'md',
+    mask: false,
+    disabled: false,
+    label: 'Verification code',
+    hint: 'We sent a six-digit code to your phone.',
+    error: '',
+  },
+};
+export default meta;
+type Story = StoryObj;
+
+export const Default: Story = {};
+export const Alphanumeric: Story = { args: { type: 'alphanumeric', length: 5, hint: '' } };
+export const Masked: Story = { args: { mask: true, length: 4, label: 'PIN', hint: '' } };
+export const WithError: Story = { args: { error: 'That code has expired.', hint: '' } };
+export const Sizes: Story = {
+  render: () => storyHtml`
+    <div style="display:flex;flex-direction:column;gap:1.25rem">
+      <bq-pin-input size="sm" length="4" label="Small"></bq-pin-input>
+      <bq-pin-input size="md" length="4" label="Medium"></bq-pin-input>
+      <bq-pin-input size="lg" length="4" label="Large"></bq-pin-input>
+    </div>
+  `,
+};
diff --git a/stories/tree.stories.ts b/stories/tree.stories.ts
new file mode 100644
index 0000000..ff4f780
--- /dev/null
+++ b/stories/tree.stories.ts
@@ -0,0 +1,58 @@
+import type { Meta, StoryObj } from '@storybook/web-components';
+import { storyHtml } from '@bquery/bquery/storybook';
+
+const FILES = JSON.stringify([
+  {
+    id: 'src',
+    label: 'src',
+    icon: 'folder',
+    children: [
+      { id: 'index', label: 'index.ts', icon: 'file' },
+      {
+        id: 'components',
+        label: 'components',
+        icon: 'folder',
+        children: [
+          { id: 'button', label: 'BqButton.ts', icon: 'file' },
+          { id: 'input', label: 'BqInput.ts', icon: 'file' },
+        ],
+      },
+      { id: 'utils', label: 'utils', icon: 'folder', children: [{ id: 'dom', label: 'dom.ts', icon: 'file' }] },
+    ],
+  },
+  { id: 'readme', label: 'README.md', icon: 'file' },
+  { id: 'lock', label: 'node_modules', icon: 'folder', disabled: true },
+]);
+
+/**
+ * Hierarchical navigation with the full ARIA tree keyboard pattern: one tab
+ * stop for the whole widget, arrows to move, Right/Left to open and close,
+ * and first-letter typeahead.
+ */
+const meta: Meta = {
+  title: 'Components/Tree',
+  tags: ['autodocs'],
+  render: (args) => storyHtml`
+    <bq-tree
+      items=${FILES}
+      label=${args.label}
+      expanded=${args.expanded}
+      selected=${args.selected}
+      ?multiple=${args.multiple}
+    ></bq-tree>
+  `,
+  argTypes: {
+    label: { control: 'text' },
+    expanded: { control: 'text' },
+    selected: { control: 'text' },
+    multiple: { control: 'boolean' },
+  },
+  args: { label: 'Project files', expanded: 'src', selected: '', multiple: false },
+};
+export default meta;
+type Story = StoryObj;
+
+export const Default: Story = {};
+export const Collapsed: Story = { args: { expanded: '' } };
+export const DeepBranchOpen: Story = { args: { expanded: 'src,components', selected: 'button' } };
+export const MultiSelect: Story = { args: { multiple: true, selected: 'readme', expanded: 'src' } };
diff --git a/tests/checkbox-radio-switch.test.ts b/tests/checkbox-radio-switch.test.ts
index 2feccd3..7c8ddfa 100644
--- a/tests/checkbox-radio-switch.test.ts
+++ b/tests/checkbox-radio-switch.test.ts
@@ -104,6 +104,51 @@ describe('BqRadio', () => {
     expect(input?.getAttribute('value')).toBe('red');
   });
 
+  // Each radio lives in its own shadow root, so the platform's "one checked
+  // per name" rule cannot see the siblings — the component has to enforce it.
+  it('unchecks the other radios in its group', () => {
+    const form = doc.createElement('form');
+    doc.body.appendChild(form);
+    const make = (value: string, checked = false) => {
+      const el = doc.createElement('bq-radio');
+      el.setAttribute('name', 'color');
+      el.setAttribute('value', value);
+      if (checked) el.setAttribute('checked', '');
+      form.appendChild(el);
+      return el;
+    };
+    const red = make('red', true);
+    const blue = make('blue');
+
+    const input = blue.shadowRoot?.querySelector('input') as HTMLInputElement;
+    input.checked = true;
+    input.dispatchEvent(new win.Event('change', { bubbles: true, composed: true }));
+
+    expect(blue.hasAttribute('checked')).toBe(true);
+    expect(red.hasAttribute('checked')).toBe(false);
+  });
+
+  it('leaves an unrelated group alone', () => {
+    const form = doc.createElement('form');
+    doc.body.appendChild(form);
+    const other = doc.createElement('bq-radio');
+    other.setAttribute('name', 'size');
+    other.setAttribute('value', 'lg');
+    other.setAttribute('checked', '');
+    form.appendChild(other);
+
+    const el = doc.createElement('bq-radio');
+    el.setAttribute('name', 'color');
+    el.setAttribute('value', 'red');
+    form.appendChild(el);
+
+    const input = el.shadowRoot?.querySelector('input') as HTMLInputElement;
+    input.checked = true;
+    input.dispatchEvent(new win.Event('change', { bubbles: true, composed: true }));
+
+    expect(other.hasAttribute('checked')).toBe(true);
+  });
+
   it('should render label text', () => {
     const el = doc.createElement('bq-radio');
     el.setAttribute('label', 'Option A');
diff --git a/tests/combobox.test.ts b/tests/combobox.test.ts
index 95ad36e..1ddf2c3 100644
--- a/tests/combobox.test.ts
+++ b/tests/combobox.test.ts
@@ -451,6 +451,44 @@ describe('bq-combobox', () => {
     expect(el.checkValidity()).toBe(true);
   });
 
+  // Focusing the field opens the list, and opening re-renders — so the very
+  // first interaction already destroys the node the user just focused.
+  it('keeps focus in the field when focusing opens the list', async () => {
+    const el = create();
+    await waitForFrame();
+
+    input(el).focus();
+    await waitForFrame();
+
+    expect(el.hasAttribute('data-open')).toBe(true);
+    expect(el.shadowRoot?.activeElement).toBe(input(el));
+  });
+
+  // Typing drives `setState`, which re-renders without running
+  // `beforeUpdate()` — so the focus position is recorded from the event
+  // instead. Without that the user loses the field after one character.
+  it('keeps focus and caret in the field while typing', async () => {
+    const el = create();
+    await waitForFrame();
+
+    input(el).focus();
+    await waitForFrame();
+
+    // Re-query: focusing already replaced the shadow tree.
+    const field = input(el);
+    field.value = 'ap';
+    field.setSelectionRange(2, 2);
+    field.dispatchEvent(
+      new win.Event('input', { bubbles: true, composed: true })
+    );
+    await waitForFrame();
+
+    const next = input(el);
+    expect(next.value).toBe('ap');
+    expect(el.shadowRoot?.activeElement).toBe(next);
+    expect(next.selectionStart).toBe(2);
+  });
+
   it('leaves no document listeners behind after removal', async () => {
     const el = create();
     await waitForFrame();
diff --git a/tests/component-css.test.ts b/tests/component-css.test.ts
new file mode 100644
index 0000000..2500401
--- /dev/null
+++ b/tests/component-css.test.ts
@@ -0,0 +1,108 @@
+/**
+ * Parses the stylesheet every component actually ships.
+ *
+ * Component CSS is assembled from template literals and never seen by a
+ * compiler, so a stray brace, an unclosed comment or a bad interpolation
+ * produces a stylesheet that a browser silently discards from the error
+ * onwards — the component simply renders unstyled, with nothing logged.
+ *
+ * Two components have already been broken by a backtick inside a CSS comment,
+ * which terminates the template literal. This runs the real text through a CSS
+ * parser so that class of mistake fails here instead of in a screenshot.
+ */
+import { beforeAll, describe, expect, it } from 'bun:test';
+import postcss from 'postcss';
+
+const win = (globalThis as unknown as Record<string, unknown>)[
+  'window'
+] as Window & typeof globalThis;
+const doc = win.document as unknown as Document;
+
+/** Reads the stylesheet the runtime injected into a component's shadow root. */
+function shadowCss(tag: string): string {
+  const el = doc.createElement(tag);
+  doc.body.appendChild(el);
+  const style = el.shadowRoot?.querySelector(
+    'style[data-bquery-component-style]'
+  );
+  const text = style?.textContent ?? '';
+  el.remove();
+  return text;
+}
+
+describe('component stylesheets', () => {
+  let tags: string[] = [];
+
+  beforeAll(async () => {
+    await import('../src/components/index.js');
+    // happy-dom has no Constructable Stylesheets, so the runtime falls back to
+    // a <style> element — which is exactly the text we want to read.
+    tags = Array.from(
+      new Set(
+        [
+          'accordion', 'alert', 'avatar', 'avatar-group', 'badge', 'banner',
+          'breadcrumbs', 'button', 'button-group', 'card', 'checkbox', 'chip',
+          'combobox', 'copy-button', 'date-picker', 'dialog', 'divider',
+          'drawer', 'dropdown-menu', 'empty-state', 'file-upload', 'icon',
+          'icon-button', 'input', 'kbd', 'meter', 'number-input', 'pagination',
+          'pin-input', 'popover', 'progress', 'radio', 'rating',
+          'segmented-control', 'select', 'skeleton', 'slider', 'spinner',
+          'stat-card', 'stepper', 'switch', 'table', 'tabs', 'tag-input',
+          'textarea', 'timeline', 'toast', 'tooltip', 'tree',
+        ].map((name) => `bq-${name}`)
+      )
+    );
+  });
+
+  it('covers every registered component', () => {
+    for (const tag of tags) {
+      expect(win.customElements.get(tag)).toBeDefined();
+    }
+  });
+
+  it('emits CSS that parses', () => {
+    const broken: string[] = [];
+    for (const tag of tags) {
+      const css = shadowCss(tag);
+      if (!css) {
+        broken.push(`${tag}: no stylesheet`);
+        continue;
+      }
+      try {
+        postcss.parse(css, { from: `${tag}.css` });
+      } catch (error) {
+        broken.push(`${tag}: ${(error as Error).message}`);
+      }
+    }
+    expect(broken).toEqual([]);
+  });
+
+  it('leaves no unresolved template interpolation in the output', () => {
+    const broken: string[] = [];
+    for (const tag of tags) {
+      // `${…}` surviving into the CSS means a fragment was interpolated as a
+      // plain string and escaped, or a helper returned undefined.
+      if (/\$\{/.test(shadowCss(tag))) broken.push(tag);
+    }
+    expect(broken).toEqual([]);
+  });
+
+  it('escapes nothing that would corrupt a declaration', () => {
+    const broken: string[] = [];
+    for (const tag of tags) {
+      const css = shadowCss(tag);
+      // `css` HTML-escapes interpolated *strings*; a fragment that arrived as
+      // one instead of as ComponentStyles shows up as an entity.
+      if (/&(?:quot|amp|lt|gt|#x27|#x60);/.test(css)) broken.push(tag);
+    }
+    expect(broken).toEqual([]);
+  });
+
+  it('carries the token block and the dark scheme into every component', () => {
+    for (const tag of tags) {
+      const css = shadowCss(tag);
+      expect(css).toContain('--bq-color-primary-600');
+      expect(css).toContain(':host([data-theme="dark"])');
+    }
+  });
+});
diff --git a/tests/date-picker.test.ts b/tests/date-picker.test.ts
new file mode 100644
index 0000000..942cd87
--- /dev/null
+++ b/tests/date-picker.test.ts
@@ -0,0 +1,357 @@
+// DOM environment is provided by tests/setup.ts (preloaded via bunfig.toml)
+import { afterEach, beforeAll, describe, expect, it } from 'bun:test';
+import {
+  addDays,
+  addMonths,
+  buildMonthGrid,
+  clampDate,
+  formatISODate,
+  isSameDay,
+  parseISODate,
+  weekdayNames,
+} from '../src/components/date-picker/BqDatePicker.js';
+import { waitForFrame } from './helpers.ts';
+
+const win = (globalThis as unknown as Record<string, unknown>)[
+  'window'
+] as Window & typeof globalThis;
+const doc = win.document as unknown as Document;
+
+describe('parseISODate', () => {
+  it('reads a well-formed date as UTC', () => {
+    const date = parseISODate('2026-03-15');
+    expect(date?.getUTCFullYear()).toBe(2026);
+    expect(date?.getUTCMonth()).toBe(2);
+    expect(date?.getUTCDate()).toBe(15);
+  });
+
+  it('rejects anything that is not exactly YYYY-MM-DD', () => {
+    expect(parseISODate('2026-3-15')).toBeNull();
+    expect(parseISODate('15/03/2026')).toBeNull();
+    expect(parseISODate('')).toBeNull();
+  });
+
+  // Date.UTC happily rolls 31 February into March; a date picker must not.
+  it('rejects a day that does not exist in that month', () => {
+    expect(parseISODate('2026-02-31')).toBeNull();
+    expect(parseISODate('2025-02-29')).toBeNull();
+    expect(parseISODate('2024-02-29')).not.toBeNull();
+  });
+
+  it('rejects out-of-range components', () => {
+    expect(parseISODate('2026-13-01')).toBeNull();
+    expect(parseISODate('2026-00-10')).toBeNull();
+  });
+});
+
+describe('formatISODate', () => {
+  it('round-trips with parseISODate', () => {
+    const iso = '2026-12-31';
+    expect(formatISODate(parseISODate(iso) as Date)).toBe(iso);
+  });
+
+  it('pads single-digit months and days', () => {
+    expect(formatISODate(new Date(Date.UTC(2026, 0, 5)))).toBe('2026-01-05');
+  });
+});
+
+describe('addDays', () => {
+  it('crosses a month boundary', () => {
+    const next = addDays(parseISODate('2026-01-31') as Date, 1);
+    expect(formatISODate(next)).toBe('2026-02-01');
+  });
+
+  it('steps backwards across a year boundary', () => {
+    const prev = addDays(parseISODate('2026-01-01') as Date, -1);
+    expect(formatISODate(prev)).toBe('2025-12-31');
+  });
+});
+
+describe('addMonths', () => {
+  // Without clamping, 31 January + 1 month lands in March and paging through
+  // a calendar skips February entirely.
+  it('clamps the day to the length of the target month', () => {
+    expect(formatISODate(addMonths(parseISODate('2026-01-31') as Date, 1))).toBe(
+      '2026-02-28'
+    );
+    expect(formatISODate(addMonths(parseISODate('2024-01-31') as Date, 1))).toBe(
+      '2024-02-29'
+    );
+  });
+
+  it('rolls the year over in both directions', () => {
+    expect(formatISODate(addMonths(parseISODate('2026-12-15') as Date, 1))).toBe(
+      '2027-01-15'
+    );
+    expect(formatISODate(addMonths(parseISODate('2026-01-15') as Date, -1))).toBe(
+      '2025-12-15'
+    );
+  });
+});
+
+describe('buildMonthGrid', () => {
+  it('always fills six weeks', () => {
+    expect(buildMonthGrid(2026, 2, 1)).toHaveLength(42);
+    expect(buildMonthGrid(2026, 1, 1)).toHaveLength(42);
+  });
+
+  it('starts on the requested weekday', () => {
+    const monday = buildMonthGrid(2026, 2, 1)[0] as Date;
+    expect(monday.getUTCDay()).toBe(1);
+    const sunday = buildMonthGrid(2026, 2, 0)[0] as Date;
+    expect(sunday.getUTCDay()).toBe(0);
+  });
+
+  it('contains every day of the month it is built for', () => {
+    const grid = buildMonthGrid(2026, 1, 1).map(formatISODate);
+    expect(grid).toContain('2026-02-01');
+    expect(grid).toContain('2026-02-28');
+  });
+});
+
+describe('clampDate', () => {
+  const min = parseISODate('2026-03-01') as Date;
+  const max = parseISODate('2026-03-31') as Date;
+
+  it('pulls a date into range', () => {
+    expect(formatISODate(clampDate(parseISODate('2026-02-01') as Date, min, max))).toBe(
+      '2026-03-01'
+    );
+    expect(formatISODate(clampDate(parseISODate('2026-04-30') as Date, min, max))).toBe(
+      '2026-03-31'
+    );
+  });
+
+  it('leaves an in-range date alone, bounds or not', () => {
+    const date = parseISODate('2026-03-10') as Date;
+    expect(clampDate(date, min, max)).toBe(date);
+    expect(clampDate(date, null, null)).toBe(date);
+  });
+});
+
+describe('isSameDay', () => {
+  it('compares by calendar day', () => {
+    expect(isSameDay(parseISODate('2026-03-15'), parseISODate('2026-03-15'))).toBe(
+      true
+    );
+    expect(isSameDay(parseISODate('2026-03-15'), parseISODate('2026-03-16'))).toBe(
+      false
+    );
+  });
+
+  it('is false when either side is missing', () => {
+    expect(isSameDay(null, parseISODate('2026-03-15'))).toBe(false);
+  });
+});
+
+describe('weekdayNames', () => {
+  it('returns seven names rotated to the first day of the week', () => {
+    const monday = weekdayNames('en-US', 1);
+    const sunday = weekdayNames('en-US', 0);
+    expect(monday).toHaveLength(7);
+    expect(sunday[0]).toBe(monday[6] as string);
+  });
+
+  it('falls back to the default locale for an invalid tag', () => {
+    expect(weekdayNames('not a locale', 1)).toHaveLength(7);
+  });
+});
+
+describe('bq-date-picker', () => {
+  beforeAll(async () => {
+    await import('../src/components/date-picker/index.js');
+  });
+
+  afterEach(() => {
+    doc.body.innerHTML = '';
+  });
+
+  const create = (attrs: Record<string, string> = {}): HTMLElement => {
+    const el = doc.createElement('bq-date-picker');
+    el.setAttribute('locale', 'en-US');
+    for (const [k, v] of Object.entries(attrs)) el.setAttribute(k, v);
+    doc.body.appendChild(el);
+    return el;
+  };
+
+  const field = (el: HTMLElement): HTMLInputElement =>
+    el.shadowRoot?.querySelector('input') as HTMLInputElement;
+
+  const days = (el: HTMLElement): HTMLElement[] =>
+    Array.from(el.shadowRoot?.querySelectorAll('.day') ?? []);
+
+  const click = (target: Element | null) =>
+    target?.dispatchEvent(new win.Event('click', { bubbles: true, composed: true }));
+
+  const press = (el: HTMLElement, key: string, init: Record<string, unknown> = {}) =>
+    (el.shadowRoot?.querySelector('.day[tabindex="0"]') as HTMLElement)?.dispatchEvent(
+      new win.KeyboardEvent('keydown', {
+        key,
+        bubbles: true,
+        composed: true,
+        cancelable: true,
+        ...init,
+      })
+    );
+
+  it('registers as a custom element', () => {
+    expect(win.customElements.get('bq-date-picker')).toBeDefined();
+  });
+
+  it('shows the value formatted for the locale, not as ISO', async () => {
+    const el = create({ value: '2026-03-15' });
+    await waitForFrame();
+    expect(field(el).getAttribute('value')).toBe('Mar 15, 2026');
+  });
+
+  it('opens the calendar from the trigger', async () => {
+    const el = create({ value: '2026-03-15' });
+    await waitForFrame();
+
+    click(el.shadowRoot?.querySelector('.calendar-btn') ?? null);
+    await waitForFrame();
+
+    expect(el.hasAttribute('data-open')).toBe(true);
+    expect(field(el).getAttribute('aria-expanded')).toBe('true');
+    expect(days(el)).toHaveLength(42);
+  });
+
+  it('marks the selected day', async () => {
+    const el = create({ value: '2026-03-15' });
+    await waitForFrame();
+    click(el.shadowRoot?.querySelector('.calendar-btn') ?? null);
+    await waitForFrame();
+
+    const selected = el.shadowRoot?.querySelector('.day[aria-selected="true"]');
+    expect(selected?.getAttribute('data-date')).toBe('2026-03-15');
+  });
+
+  it('selects a day on click and closes', async () => {
+    const el = create({ value: '2026-03-15' });
+    await waitForFrame();
+    click(el.shadowRoot?.querySelector('.calendar-btn') ?? null);
+    await waitForFrame();
+
+    let changed = '';
+    el.addEventListener('bq-change', (e) => {
+      changed = (e as CustomEvent<{ value: string }>).detail.value;
+    });
+    click(
+      el.shadowRoot?.querySelector('.day[data-date="2026-03-20"]') ?? null
+    );
+    await waitForFrame();
+
+    expect(el.getAttribute('value')).toBe('2026-03-20');
+    expect(changed).toBe('2026-03-20');
+    expect(el.hasAttribute('data-open')).toBe(false);
+  });
+
+  it('pages between months', async () => {
+    const el = create({ value: '2026-03-15' });
+    await waitForFrame();
+    click(el.shadowRoot?.querySelector('.calendar-btn') ?? null);
+    await waitForFrame();
+
+    click(el.shadowRoot?.querySelector('[data-dir="next"]') ?? null);
+    await waitForFrame();
+    expect(el.shadowRoot?.querySelector('.month-label')?.textContent?.trim()).toBe(
+      'April 2026'
+    );
+  });
+
+  it('moves the cursor a week at a time with the arrow keys', async () => {
+    const el = create({ value: '2026-03-15' });
+    await waitForFrame();
+    click(el.shadowRoot?.querySelector('.calendar-btn') ?? null);
+    await waitForFrame();
+
+    press(el, 'ArrowDown');
+    await waitForFrame();
+    expect(
+      el.shadowRoot?.querySelector('.day[tabindex="0"]')?.getAttribute('data-date')
+    ).toBe('2026-03-22');
+  });
+
+  it('closes on Escape without changing the value', async () => {
+    const el = create({ value: '2026-03-15' });
+    await waitForFrame();
+    click(el.shadowRoot?.querySelector('.calendar-btn') ?? null);
+    await waitForFrame();
+
+    press(el, 'Escape');
+    await waitForFrame();
+    expect(el.hasAttribute('data-open')).toBe(false);
+    expect(el.getAttribute('value')).toBe('2026-03-15');
+  });
+
+  it('disables days outside the allowed range', async () => {
+    const el = create({ value: '2026-03-15', min: '2026-03-10', max: '2026-03-20' });
+    await waitForFrame();
+    click(el.shadowRoot?.querySelector('.calendar-btn') ?? null);
+    await waitForFrame();
+
+    const early = el.shadowRoot?.querySelector('.day[data-date="2026-03-09"]');
+    const inside = el.shadowRoot?.querySelector('.day[data-date="2026-03-12"]');
+    expect(early?.hasAttribute('disabled')).toBe(true);
+    expect(inside?.hasAttribute('disabled')).toBe(false);
+  });
+
+  it('rejects typed text that is not a valid date', async () => {
+    const el = create({ value: '2026-03-15' });
+    await waitForFrame();
+
+    const input = field(el);
+    input.value = 'tomorrow-ish';
+    input.dispatchEvent(new win.Event('change', { bubbles: true, composed: true }));
+    await waitForFrame();
+
+    expect(el.getAttribute('value')).toBe('2026-03-15');
+  });
+
+  it('accepts a typed ISO date', async () => {
+    const el = create({ value: '2026-03-15' });
+    await waitForFrame();
+
+    const input = field(el);
+    input.value = '2026-04-01';
+    input.dispatchEvent(new win.Event('change', { bubbles: true, composed: true }));
+    await waitForFrame();
+
+    expect(el.getAttribute('value')).toBe('2026-04-01');
+  });
+
+  it('submits the ISO value through a hidden input inside a form', async () => {
+    const form = doc.createElement('form');
+    doc.body.appendChild(form);
+    const el = doc.createElement('bq-date-picker');
+    el.setAttribute('name', 'due');
+    el.setAttribute('value', '2026-03-15');
+    form.appendChild(el);
+    await waitForFrame();
+
+    const proxy = form.querySelector('input[name="due"]') as HTMLInputElement | null;
+    expect(proxy?.value).toBe('2026-03-15');
+  });
+
+  it('starts the week on the requested day', async () => {
+    const el = create({ value: '2026-03-15', 'first-day-of-week': '0' });
+    await waitForFrame();
+    click(el.shadowRoot?.querySelector('.calendar-btn') ?? null);
+    await waitForFrame();
+
+    const headers = Array.from(
+      el.shadowRoot?.querySelectorAll('th') ?? []
+    ).map((th) => th.textContent?.trim());
+    expect(headers[0]).toBe('Sun');
+  });
+
+  it('leaves no document listeners behind after removal', async () => {
+    const el = create();
+    await waitForFrame();
+    click(el.shadowRoot?.querySelector('.calendar-btn') ?? null);
+    await waitForFrame();
+    el.remove();
+    await waitForFrame();
+    expect(el.isConnected).toBe(false);
+  });
+});
diff --git a/tests/icons.test.ts b/tests/icons.test.ts
new file mode 100644
index 0000000..86fcb3c
--- /dev/null
+++ b/tests/icons.test.ts
@@ -0,0 +1,154 @@
+// DOM environment is provided by tests/setup.ts (preloaded via bunfig.toml)
+import { beforeAll, afterEach, describe, expect, it } from 'bun:test';
+import {
+  allIconCss,
+  iconCss,
+  iconMaskText,
+  iconNames,
+  iconUrl,
+  isIconName,
+} from '../src/utils/icons.js';
+import { waitForFrame } from './helpers.ts';
+
+const win = (globalThis as unknown as Record<string, unknown>)[
+  'window'
+] as Window & typeof globalThis;
+const doc = win.document as unknown as Document;
+
+describe('icon set', () => {
+  it('exposes a sorted, non-empty catalogue', () => {
+    expect(iconNames.length).toBeGreaterThan(30);
+    expect([...iconNames]).toEqual([...iconNames].sort());
+  });
+
+  it('recognises its own names and rejects others', () => {
+    expect(isIconName('check')).toBe(true);
+    expect(isIconName('definitely-not-an-icon')).toBe(false);
+  });
+
+  it('encodes each icon as a data URI usable inside url()', () => {
+    for (const name of iconNames) {
+      const url = iconUrl(name);
+      expect(url.startsWith('url("data:image/svg+xml,')).toBe(true);
+      // A raw <, > or " would terminate the URI or the attribute around it.
+      const payload = url.slice('url("'.length, -2);
+      expect(payload).not.toContain('<');
+      expect(payload).not.toContain('>');
+      expect(payload).not.toContain('"');
+    }
+  });
+
+  it('returns the identical URL for repeated lookups', () => {
+    expect(iconUrl('check')).toBe(iconUrl('check'));
+  });
+
+  // A mask that fails to parse renders as an empty box, with nothing logged.
+  it('decodes back to a well-formed SVG document', () => {
+    for (const name of iconNames) {
+      const svg = decodeURIComponent(
+        iconUrl(name).slice('url("data:image/svg+xml,'.length, -2)
+      );
+      expect(svg.startsWith('<svg ')).toBe(true);
+      expect(svg.endsWith('</svg>')).toBe(true);
+      const opens = (svg.match(/<(?!\/)/g) ?? []).length;
+      const closes =
+        (svg.match(/\/>/g) ?? []).length + (svg.match(/<\//g) ?? []).length;
+      expect(opens).toBe(closes);
+    }
+  });
+
+  it('emits both the prefixed and unprefixed mask properties', () => {
+    const text = iconMaskText('x');
+    expect(text).toContain('-webkit-mask-image:');
+    expect(text).toContain('mask-image:');
+  });
+
+  it('only emits rules for the icons a component asks for', () => {
+    const text = iconCss('check', 'x').text;
+    expect(text).toContain('.icon[data-icon="check"]');
+    expect(text).toContain('.icon[data-icon="x"]');
+    expect(text).not.toContain('.icon[data-icon="calendar"]');
+  });
+
+  it('drops duplicate names rather than repeating the rule', () => {
+    const text = iconCss('check', 'check').text;
+    expect(text.split('.icon[data-icon="check"]').length - 1).toBe(1);
+  });
+
+  it('emits every icon in the full sheet', () => {
+    const text = allIconCss().text;
+    for (const name of iconNames) {
+      expect(text).toContain(`.icon[data-icon="${name}"]`);
+    }
+  });
+
+  it('keeps the glyph visible under forced colors', () => {
+    expect(iconCss('check').text).toContain('forced-colors: active');
+  });
+});
+
+describe('bq-icon', () => {
+  beforeAll(async () => {
+    await import('../src/components/icon/index.js');
+  });
+
+  afterEach(() => {
+    doc.body.innerHTML = '';
+  });
+
+  const create = (attrs: Record<string, string> = {}): HTMLElement => {
+    const el = doc.createElement('bq-icon');
+    for (const [k, v] of Object.entries(attrs)) el.setAttribute(k, v);
+    doc.body.appendChild(el);
+    return el;
+  };
+
+  it('registers as a custom element', () => {
+    expect(win.customElements.get('bq-icon')).toBeDefined();
+  });
+
+  it('renders the named glyph', async () => {
+    const el = create({ name: 'check' });
+    await waitForFrame();
+    const icon = el.shadowRoot?.querySelector('.icon');
+    expect(icon?.getAttribute('data-icon')).toBe('check');
+  });
+
+  it('is decorative unless given a label', async () => {
+    const el = create({ name: 'trash' });
+    await waitForFrame();
+    expect(el.shadowRoot?.querySelector('.icon')?.getAttribute('aria-hidden')).toBe(
+      'true'
+    );
+
+    el.setAttribute('label', 'Delete');
+    await waitForFrame();
+    const labelled = el.shadowRoot?.querySelector('.icon');
+    expect(labelled?.getAttribute('role')).toBe('img');
+    expect(labelled?.getAttribute('aria-label')).toBe('Delete');
+    expect(labelled?.hasAttribute('aria-hidden')).toBe(false);
+  });
+
+  it('renders nothing for an unknown name', async () => {
+    const el = create({ name: 'not-an-icon' });
+    await waitForFrame();
+    expect(el.shadowRoot?.querySelector('[data-icon]')).toBeNull();
+  });
+
+  // `size` is the one prop that reaches an inline style, so it is the one that
+  // could otherwise close the declaration and inject another.
+  it('refuses a size that is not a plain length', async () => {
+    const el = create({ name: 'check', size: 'red; background: url(x)' });
+    await waitForFrame();
+    const icon = el.shadowRoot?.querySelector('.icon');
+    expect(icon?.getAttribute('style')).toBeNull();
+  });
+
+  it('applies a well-formed size', async () => {
+    const el = create({ name: 'check', size: '2rem' });
+    await waitForFrame();
+    expect(el.shadowRoot?.querySelector('.icon')?.getAttribute('style')).toContain(
+      '2rem'
+    );
+  });
+});
diff --git a/tests/input-enhancements.test.ts b/tests/input-enhancements.test.ts
index a989996..9315020 100644
--- a/tests/input-enhancements.test.ts
+++ b/tests/input-enhancements.test.ts
@@ -49,9 +49,11 @@ describe('BqInput — password toggle', () => {
     const el = doc.createElement('bq-input');
     el.setAttribute('type', 'password');
     doc.body.appendChild(el);
-    const icon = el.shadowRoot?.querySelector('.password-toggle .pw-icon');
+    const icon = el.shadowRoot?.querySelector('.password-toggle .icon');
     expect(icon).not.toBeNull();
     expect(icon?.getAttribute('aria-hidden')).toBe('true');
+    // Hidden by default, so the eye offers "show".
+    expect(icon?.getAttribute('data-icon')).toBe('eye');
   });
 
   it('should disable the password toggle when the input is disabled', () => {
diff --git a/tests/meter-copy-button.test.ts b/tests/meter-copy-button.test.ts
new file mode 100644
index 0000000..0f7da97
--- /dev/null
+++ b/tests/meter-copy-button.test.ts
@@ -0,0 +1,270 @@
+// DOM environment is provided by tests/setup.ts (preloaded via bunfig.toml)
+import { afterEach, beforeAll, describe, expect, it } from 'bun:test';
+import { meterLevel } from '../src/components/meter/BqMeter.js';
+import { writeClipboard } from '../src/components/copy-button/BqCopyButton.js';
+import { waitForFrame } from './helpers.ts';
+
+const win = (globalThis as unknown as Record<string, unknown>)[
+  'window'
+] as Window & typeof globalThis;
+const doc = win.document as unknown as Document;
+
+describe('meterLevel', () => {
+  // Disk usage: low is good.
+  it('treats the low band as optimum when the optimum sits below it', () => {
+    expect(meterLevel(10, 0, 100, 40, 80, 0)).toBe('optimum');
+    expect(meterLevel(60, 0, 100, 40, 80, 0)).toBe('suboptimum');
+    expect(meterLevel(95, 0, 100, 40, 80, 0)).toBe('poor');
+  });
+
+  // Battery charge: high is good.
+  it('treats the high band as optimum when the optimum sits above it', () => {
+    expect(meterLevel(95, 0, 100, 20, 80, 100)).toBe('optimum');
+    expect(meterLevel(50, 0, 100, 20, 80, 100)).toBe('suboptimum');
+    expect(meterLevel(10, 0, 100, 20, 80, 100)).toBe('poor');
+  });
+
+  // A reading that should stay in the middle, like a pH or a temperature.
+  it('treats the middle band as optimum when the optimum sits inside it', () => {
+    expect(meterLevel(50, 0, 100, 30, 70, 50)).toBe('optimum');
+    expect(meterLevel(10, 0, 100, 30, 70, 50)).toBe('suboptimum');
+    expect(meterLevel(90, 0, 100, 30, 70, 50)).toBe('suboptimum');
+  });
+});
+
+describe('bq-meter', () => {
+  beforeAll(async () => {
+    await import('../src/components/meter/index.js');
+  });
+
+  afterEach(() => {
+    doc.body.innerHTML = '';
+  });
+
+  const create = (attrs: Record<string, string> = {}): HTMLElement => {
+    const el = doc.createElement('bq-meter');
+    for (const [k, v] of Object.entries(attrs)) el.setAttribute(k, v);
+    doc.body.appendChild(el);
+    return el;
+  };
+
+  it('registers as a custom element', () => {
+    expect(win.customElements.get('bq-meter')).toBeDefined();
+  });
+
+  it('exposes the meter role and its bounds', async () => {
+    const el = create({ value: '40', min: '0', max: '200', label: 'Disk' });
+    await waitForFrame();
+    const meter = el.shadowRoot?.querySelector('[role="meter"]');
+    expect(meter?.getAttribute('aria-valuenow')).toBe('40');
+    expect(meter?.getAttribute('aria-valuemin')).toBe('0');
+    expect(meter?.getAttribute('aria-valuemax')).toBe('200');
+    expect(meter?.getAttribute('aria-label')).toBe('Disk');
+  });
+
+  // The width is an inline style, which the sanitizer drops unless the
+  // component opts in — so this asserts the opt-in as much as the maths.
+  it('fills the bar to the right proportion', async () => {
+    const el = create({ value: '25', max: '200' });
+    await waitForFrame();
+    expect(
+      el.shadowRoot?.querySelector('.bar')?.getAttribute('style')
+    ).toContain('12.5%');
+  });
+
+  it('clamps a value outside the range', async () => {
+    const el = create({ value: '500', max: '100' });
+    await waitForFrame();
+    expect(
+      el.shadowRoot?.querySelector('[role="meter"]')?.getAttribute('aria-valuenow')
+    ).toBe('100');
+  });
+
+  it('stays uncoloured until bands are given', async () => {
+    const el = create({ value: '90' });
+    await waitForFrame();
+    expect(el.shadowRoot?.querySelector('.bar')?.hasAttribute('data-level')).toBe(
+      false
+    );
+  });
+
+  it('grades the bar once bands are given', async () => {
+    const el = create({ value: '90', low: '40', high: '80', optimum: '0' });
+    await waitForFrame();
+    expect(el.shadowRoot?.querySelector('.bar')?.getAttribute('data-level')).toBe(
+      'poor'
+    );
+  });
+
+  it('shows the reading only when asked', async () => {
+    const el = create({ value: '40', label: 'Disk' });
+    await waitForFrame();
+    expect(el.shadowRoot?.querySelector('.value')).toBeNull();
+
+    el.setAttribute('show-value', '');
+    await waitForFrame();
+    expect(el.shadowRoot?.querySelector('.value')?.textContent?.trim()).toBe(
+      '40 / 100'
+    );
+  });
+
+  it('prefers an explicit value-text', async () => {
+    const el = create({ value: '40', 'value-text': '40 GB of 100 GB', 'show-value': '' });
+    await waitForFrame();
+    expect(
+      el.shadowRoot?.querySelector('[role="meter"]')?.getAttribute('aria-valuetext')
+    ).toBe('40 GB of 100 GB');
+  });
+});
+
+describe('writeClipboard', () => {
+  it('refuses to copy an empty string', async () => {
+    expect(await writeClipboard('')).toBe(false);
+  });
+
+  it('uses the async clipboard API when it is available', async () => {
+    const nav = globalThis.navigator as unknown as Record<string, unknown>;
+    const original = nav['clipboard'];
+    let written = '';
+    Object.defineProperty(globalThis.navigator, 'clipboard', {
+      value: {
+        writeText: (text: string) => {
+          written = text;
+          return Promise.resolve();
+        },
+      },
+      configurable: true,
+    });
+    try {
+      expect(await writeClipboard('hello')).toBe(true);
+      expect(written).toBe('hello');
+    } finally {
+      if (original === undefined) {
+        delete (globalThis.navigator as unknown as Record<string, unknown>)[
+          'clipboard'
+        ];
+      } else {
+        Object.defineProperty(globalThis.navigator, 'clipboard', {
+          value: original,
+          configurable: true,
+        });
+      }
+    }
+  });
+});
+
+describe('bq-copy-button', () => {
+  beforeAll(async () => {
+    await import('../src/components/copy-button/index.js');
+  });
+
+  afterEach(() => {
+    doc.body.innerHTML = '';
+  });
+
+  it('registers as a custom element', () => {
+    expect(win.customElements.get('bq-copy-button')).toBeDefined();
+  });
+
+  it('starts in the idle state with the copy glyph', async () => {
+    const el = doc.createElement('bq-copy-button');
+    el.setAttribute('value', 'npm i @bquery/ui');
+    doc.body.appendChild(el);
+    await waitForFrame();
+
+    const button = el.shadowRoot?.querySelector('.btn');
+    expect(button?.getAttribute('data-copied')).toBe('false');
+    expect(
+      el.shadowRoot?.querySelector('.icon')?.getAttribute('data-icon')
+    ).toBe('copy');
+  });
+
+  it('confirms after a successful copy and reports what was copied', async () => {
+    Object.defineProperty(globalThis.navigator, 'clipboard', {
+      value: { writeText: () => Promise.resolve() },
+      configurable: true,
+    });
+
+    const el = doc.createElement('bq-copy-button');
+    el.setAttribute('value', 'npm i @bquery/ui');
+    doc.body.appendChild(el);
+    await waitForFrame();
+
+    let detail: { value: string; ok: boolean } | null = null;
+    el.addEventListener('bq-copy', (e) => {
+      detail = (e as CustomEvent<{ value: string; ok: boolean }>).detail;
+    });
+
+    el.shadowRoot
+      ?.querySelector('.btn')
+      ?.dispatchEvent(new win.Event('click', { bubbles: true, composed: true }));
+    await waitForFrame(2);
+
+    expect(detail).not.toBeNull();
+    expect((detail as unknown as { value: string }).value).toBe(
+      'npm i @bquery/ui'
+    );
+    expect(
+      el.shadowRoot?.querySelector('.btn')?.getAttribute('data-copied')
+    ).toBe('true');
+    expect(
+      el.shadowRoot?.querySelector('.icon')?.getAttribute('data-icon')
+    ).toBe('check');
+  });
+
+  it('reads the text from another element when given a selector', async () => {
+    const source = doc.createElement('pre');
+    source.id = 'snippet';
+    source.textContent = 'bun add @bquery/ui';
+    doc.body.appendChild(source);
+
+    let copied = '';
+    Object.defineProperty(globalThis.navigator, 'clipboard', {
+      value: {
+        writeText: (text: string) => {
+          copied = text;
+          return Promise.resolve();
+        },
+      },
+      configurable: true,
+    });
+
+    const el = doc.createElement('bq-copy-button');
+    el.setAttribute('from', '#snippet');
+    doc.body.appendChild(el);
+    await waitForFrame();
+
+    el.shadowRoot
+      ?.querySelector('.btn')
+      ?.dispatchEvent(new win.Event('click', { bubbles: true, composed: true }));
+    await waitForFrame(2);
+
+    expect(copied).toBe('bun add @bquery/ui');
+  });
+
+  it('does nothing while disabled', async () => {
+    let calls = 0;
+    Object.defineProperty(globalThis.navigator, 'clipboard', {
+      value: {
+        writeText: () => {
+          calls += 1;
+          return Promise.resolve();
+        },
+      },
+      configurable: true,
+    });
+
+    const el = doc.createElement('bq-copy-button');
+    el.setAttribute('value', 'x');
+    el.setAttribute('disabled', '');
+    doc.body.appendChild(el);
+    await waitForFrame();
+
+    el.shadowRoot
+      ?.querySelector('.btn')
+      ?.dispatchEvent(new win.Event('click', { bubbles: true, composed: true }));
+    await waitForFrame(2);
+
+    expect(calls).toBe(0);
+  });
+});
diff --git a/tests/new-components.test.ts b/tests/new-components.test.ts
index e54d0da..2356235 100644
--- a/tests/new-components.test.ts
+++ b/tests/new-components.test.ts
@@ -177,7 +177,9 @@ describe('BqStepper', () => {
     const steps = Array.from(el.shadowRoot?.querySelectorAll('.step') ?? []);
     expect(steps).toHaveLength(3);
     expect(steps[0]?.getAttribute('data-status')).toBe('complete');
-    expect(steps[0]?.querySelector('.marker')?.textContent).toBe('✓');
+    expect(
+      steps[0]?.querySelector('.marker .icon')?.getAttribute('data-icon')
+    ).toBe('check');
     expect(steps[1]?.getAttribute('data-status')).toBe('current');
     expect(steps[1]?.getAttribute('aria-current')).toBe('step');
     expect(steps[2]?.getAttribute('data-status')).toBe('upcoming');
diff --git a/tests/pin-input.test.ts b/tests/pin-input.test.ts
new file mode 100644
index 0000000..0b0e734
--- /dev/null
+++ b/tests/pin-input.test.ts
@@ -0,0 +1,194 @@
+// DOM environment is provided by tests/setup.ts (preloaded via bunfig.toml)
+import { afterEach, beforeAll, describe, expect, it } from 'bun:test';
+import {
+  applyPinEdit,
+  sanitizePin,
+} from '../src/components/pin-input/BqPinInput.js';
+import { waitForFrame } from './helpers.ts';
+
+const win = (globalThis as unknown as Record<string, unknown>)[
+  'window'
+] as Window & typeof globalThis;
+const doc = win.document as unknown as Document;
+
+describe('sanitizePin', () => {
+  it('keeps only digits in numeric mode', () => {
+    expect(sanitizePin('1a2b3', 'numeric', 6)).toBe('123');
+  });
+
+  it('keeps letters and digits in alphanumeric mode', () => {
+    expect(sanitizePin('a1-b2', 'alphanumeric', 6)).toBe('a1b2');
+  });
+
+  it('drops whitespace in text mode but keeps punctuation', () => {
+    expect(sanitizePin('a b-c', 'text', 6)).toBe('ab-c');
+  });
+
+  it('truncates to the number of cells', () => {
+    expect(sanitizePin('123456789', 'numeric', 4)).toBe('1234');
+  });
+
+  it('falls back to numeric for an unknown type', () => {
+    expect(sanitizePin('1a2', 'nonsense', 6)).toBe('12');
+  });
+});
+
+describe('applyPinEdit', () => {
+  it('overwrites from the given index rather than inserting', () => {
+    expect(applyPinEdit('1234', 1, '99', 4)).toBe('1994');
+  });
+
+  it('pads a short value so a late cell can be filled first', () => {
+    expect(applyPinEdit('', 2, '7', 4)).toBe('  7');
+  });
+
+  it('never grows past the cell count', () => {
+    expect(applyPinEdit('12', 1, '999999', 4)).toBe('1999');
+  });
+});
+
+describe('bq-pin-input', () => {
+  beforeAll(async () => {
+    await import('../src/components/pin-input/index.js');
+  });
+
+  afterEach(() => {
+    doc.body.innerHTML = '';
+  });
+
+  const create = (attrs: Record<string, string> = {}): HTMLElement => {
+    const el = doc.createElement('bq-pin-input');
+    el.setAttribute('length', '4');
+    for (const [k, v] of Object.entries(attrs)) el.setAttribute(k, v);
+    doc.body.appendChild(el);
+    return el;
+  };
+
+  const cells = (el: HTMLElement): HTMLInputElement[] =>
+    Array.from(el.shadowRoot?.querySelectorAll('.cell') ?? []);
+
+  const type = (el: HTMLElement, index: number, char: string) => {
+    const cell = cells(el)[index] as HTMLInputElement;
+    cell.focus();
+    cell.value = char;
+    cell.dispatchEvent(new win.Event('input', { bubbles: true, composed: true }));
+  };
+
+  const press = (el: HTMLElement, index: number, key: string) =>
+    cells(el)[index]?.dispatchEvent(
+      new win.KeyboardEvent('keydown', {
+        key,
+        bubbles: true,
+        composed: true,
+        cancelable: true,
+      })
+    );
+
+  it('registers as a custom element', () => {
+    expect(win.customElements.get('bq-pin-input')).toBeDefined();
+  });
+
+  it('renders one cell per character of the code', async () => {
+    const el = create({ length: '6' });
+    await waitForFrame();
+    expect(cells(el)).toHaveLength(6);
+  });
+
+  it('collects typed characters into the value and advances', async () => {
+    const el = create();
+    await waitForFrame();
+
+    type(el, 0, '1');
+    await waitForFrame();
+    expect(el.getAttribute('value')).toBe('1');
+    expect(el.shadowRoot?.activeElement?.getAttribute('data-index')).toBe('1');
+
+    type(el, 1, '2');
+    await waitForFrame();
+    expect(el.getAttribute('value')).toBe('12');
+  });
+
+  it('rejects characters that do not match the type', async () => {
+    const el = create({ type: 'numeric' });
+    await waitForFrame();
+    type(el, 0, 'a');
+    await waitForFrame();
+    expect(el.getAttribute('value') ?? '').toBe('');
+    expect(cells(el)[0]?.value ?? '').toBe('');
+  });
+
+  it('clears the current cell on Backspace, then steps back', async () => {
+    const el = create({ value: '12' });
+    await waitForFrame();
+
+    press(el, 1, 'Backspace');
+    await waitForFrame();
+    expect(el.getAttribute('value')).toBe('1');
+
+    press(el, 1, 'Backspace');
+    await waitForFrame();
+    expect(el.getAttribute('value')).toBe('');
+  });
+
+  it('moves between cells with the arrow keys', async () => {
+    const el = create({ value: '1234' });
+    await waitForFrame();
+    cells(el)[2]?.focus();
+    press(el, 2, 'ArrowLeft');
+    await waitForFrame();
+    expect(el.shadowRoot?.activeElement?.getAttribute('data-index')).toBe('1');
+  });
+
+  it('spreads a paste across the remaining cells', async () => {
+    const el = create();
+    await waitForFrame();
+
+    const event = new win.Event('paste', {
+      bubbles: true,
+      composed: true,
+      cancelable: true,
+    }) as Event & { clipboardData: { getData(): string } };
+    Object.defineProperty(event, 'clipboardData', {
+      value: { getData: () => '9876' },
+    });
+    cells(el)[0]?.dispatchEvent(event);
+    await waitForFrame();
+
+    expect(el.getAttribute('value')).toBe('9876');
+  });
+
+  it('announces completion once every cell is filled', async () => {
+    const el = create({ value: '123' });
+    await waitForFrame();
+
+    let completed = '';
+    el.addEventListener('bq-complete', (e) => {
+      completed = (e as CustomEvent<{ value: string }>).detail.value;
+    });
+    type(el, 3, '4');
+    await waitForFrame();
+
+    expect(completed).toBe('1234');
+  });
+
+  it('submits through a hidden input inside a form', async () => {
+    const form = doc.createElement('form');
+    doc.body.appendChild(form);
+    const el = doc.createElement('bq-pin-input');
+    el.setAttribute('name', 'code');
+    el.setAttribute('value', '1234');
+    form.appendChild(el);
+    await waitForFrame();
+
+    const proxy = form.querySelector(
+      'input[name="code"]'
+    ) as HTMLInputElement | null;
+    expect(proxy?.value).toBe('1234');
+  });
+
+  it('masks the characters when asked', async () => {
+    const el = create({ mask: '', value: '12' });
+    await waitForFrame();
+    expect(cells(el)[0]?.getAttribute('type')).toBe('password');
+  });
+});
diff --git a/tests/sanitizer-allowlist.test.ts b/tests/sanitizer-allowlist.test.ts
new file mode 100644
index 0000000..970848c
--- /dev/null
+++ b/tests/sanitizer-allowlist.test.ts
@@ -0,0 +1,122 @@
+/**
+ * Guards against attributes that silently vanish from rendered output.
+ *
+ * Component markup is sanitized before it reaches the shadow root, and the
+ * framework's allowlist is narrower than it looks — `scope`, `colspan`,
+ * `style`, `spellcheck` and `inputmode` are all dropped unless a component
+ * opts in through `sanitize.allowAttributes`. Nothing warns when that happens;
+ * the attribute is simply not there, which is how `bq-table` shipped a
+ * "no data" cell that spanned one column instead of the whole row.
+ *
+ * So the check lives here: parse every render template, and fail on any
+ * attribute the sanitizer would throw away.
+ */
+import { describe, expect, it } from 'bun:test';
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** Tags the sanitizer keeps, plus `slot`, which the component runtime adds. */
+const KNOWN_TAGS = new Set(
+  `a abbr address article aside b bdi bdo blockquote br button caption cite code
+   col colgroup data dd del details dfn div dl dt em figcaption figure footer
+   form h1 h2 h3 h4 h5 h6 header hgroup hr i img input ins kbd label legend li
+   main mark nav ol optgroup option p picture pre progress q rp rt ruby s samp
+   section select small source span strong sub summary sup table tbody td
+   textarea tfoot th thead time tr u ul var wbr slot`.split(/\s+/)
+);
+
+/** The sanitizer's own allowlist. */
+const BASE_ATTRIBUTES = new Set(
+  `alt class dir height hidden href id lang loading name rel role src srcset
+   tabindex target title type width`.split(/\s+/)
+);
+
+/** What the component runtime adds on top of it. */
+const RUNTIME_ATTRIBUTES = new Set(
+  `part disabled checked placeholder value rows cols readonly required maxlength
+   minlength max min step pattern autocomplete autofocus for multiple selected
+   wrap`.split(/\s+/)
+);
+
+const COMPONENTS_DIR = join(import.meta.dir, '..', 'src', 'components');
+
+function componentFiles(): { name: string; path: string; source: string }[] {
+  return readdirSync(COMPONENTS_DIR, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .flatMap((entry) => {
+      const dir = join(COMPONENTS_DIR, entry.name);
+      return readdirSync(dir)
+        .filter((file) => file.startsWith('Bq') && file.endsWith('.ts'))
+        .map((file) => ({
+          name: `${entry.name}/${file}`,
+          path: join(dir, file),
+          source: readFileSync(join(dir, file), 'utf8'),
+        }));
+    });
+}
+
+/** Reads the component's own `sanitize.allowAttributes` opt-ins. */
+function declaredAllowList(source: string): Set<string> {
+  const match = /sanitize:\s*\{[\s\S]*?allowAttributes:\s*\[([\s\S]*?)\]/.exec(
+    source
+  );
+  if (!match?.[1]) return new Set();
+  return new Set(
+    Array.from(match[1].matchAll(/['"]([^'"]+)['"]/g), (m) =>
+      (m[1] ?? '').toLowerCase()
+    )
+  );
+}
+
+/**
+ * Collects the attribute names a render template emits.
+ *
+ * Only opening tags of known HTML elements are inspected — scanning the file
+ * as a whole would trip over TypeScript generics such as `Record<string, …>`.
+ */
+function renderedAttributes(source: string): Set<string> {
+  const renderStart = source.indexOf('render(');
+  if (renderStart < 0) return new Set();
+  const body = source.slice(renderStart);
+  const attributes = new Set<string>();
+
+  for (const tag of body.matchAll(/<([a-zA-Z][\w-]*)((?:[^<>]|\n)*?)>/g)) {
+    if (!KNOWN_TAGS.has((tag[1] ?? '').toLowerCase())) continue;
+    for (const attribute of (tag[2] ?? '').matchAll(
+      /(?:^|[\s"'`])([a-zA-Z][a-zA-Z0-9-]*)\s*=\s*["']/g
+    )) {
+      attributes.add((attribute[1] ?? '').toLowerCase());
+    }
+  }
+  return attributes;
+}
+
+describe('sanitizer allowlist', () => {
+  const files = componentFiles();
+
+  it('finds the component sources', () => {
+    expect(files.length).toBeGreaterThan(40);
+  });
+
+  it('never renders an attribute the sanitizer would strip', () => {
+    const offenders: string[] = [];
+
+    for (const file of files) {
+      const allowed = declaredAllowList(file.source);
+      for (const attribute of renderedAttributes(file.source)) {
+        if (
+          attribute.startsWith('aria-') ||
+          attribute.startsWith('data-') ||
+          BASE_ATTRIBUTES.has(attribute) ||
+          RUNTIME_ATTRIBUTES.has(attribute) ||
+          allowed.has(attribute)
+        ) {
+          continue;
+        }
+        offenders.push(`${file.name}: ${attribute}`);
+      }
+    }
+
+    expect(offenders).toEqual([]);
+  });
+});
diff --git a/tests/slider-pagination.test.ts b/tests/slider-pagination.test.ts
index 5ae4cd9..7b42b32 100644
--- a/tests/slider-pagination.test.ts
+++ b/tests/slider-pagination.test.ts
@@ -1,15 +1,43 @@
 import { beforeAll, describe, expect, it } from 'bun:test';
+import { sliderFill } from '../src/components/slider/BqSlider.js';
 
 const win = (globalThis as unknown as Record<string, unknown>)[
   'window'
 ] as Window & typeof globalThis;
 const doc = win.document as unknown as Document;
 
+describe('sliderFill', () => {
+  it('reports how much of the track is behind the thumb', () => {
+    expect(sliderFill(50, 0, 100)).toBe(50);
+    expect(sliderFill(5, 0, 20)).toBe(25);
+  });
+
+  it('clamps a value outside the range', () => {
+    expect(sliderFill(-10, 0, 100)).toBe(0);
+    expect(sliderFill(999, 0, 100)).toBe(100);
+  });
+
+  it('returns zero for a degenerate range rather than dividing by it', () => {
+    expect(sliderFill(5, 10, 10)).toBe(0);
+    expect(sliderFill(Number.NaN, 0, 100)).toBe(0);
+  });
+});
+
 describe('BqSlider', () => {
   beforeAll(async () => {
     await import('../src/components/slider/index.js');
   });
 
+  // The filled portion is a gradient stop driven by an inline custom property,
+  // which the sanitizer drops unless the component opts in.
+  it('paints the filled portion of the track', () => {
+    const el = doc.createElement('bq-slider');
+    el.setAttribute('value', '25');
+    doc.body.appendChild(el);
+    const input = el.shadowRoot?.querySelector('input[type="range"]');
+    expect(input?.getAttribute('style')).toContain('--bq-slider-fill: 25%');
+  });
+
   it('should define bq-slider as a custom element', () => {
     expect(win.customElements.get('bq-slider')).toBeDefined();
   });
diff --git a/tests/styles.test.ts b/tests/styles.test.ts
index 3d8044d..e8abb64 100644
--- a/tests/styles.test.ts
+++ b/tests/styles.test.ts
@@ -68,7 +68,33 @@ describe('style payloads', () => {
   it('emits the token block and both color schemes exactly once', () => {
     const text = baseStyles.text;
     expect(text).toContain('--bq-color-primary-600');
-    expect(text).toContain('--bq-bg-base: #ffffff');
     expect(text).toContain('[data-theme="dark"]');
   });
+
+  // A component defines the semantic tokens on its own `:host`, and a value set
+  // on the element always beats one inherited from an ancestor. Routing them
+  // through `--bq-scheme-*` — which is never defined on the host — is what lets
+  // a page re-theme components from the document.
+  it('resolves semantic tokens through the scheme channel', () => {
+    expect(baseStyles.text).toContain(
+      '--bq-bg-base: var(--bq-scheme-bg-base, #ffffff)'
+    );
+    expect(baseStyles.text).toContain(
+      'color-scheme: var(--bq-scheme-color-scheme, light)'
+    );
+  });
+
+  // `:host-context()` only exists in Chromium, and one unknown selector
+  // invalidates the whole list it sits in — pairing the two in `a, b { … }`
+  // dropped the entire dark theme in Firefox and Safari.
+  it('keeps :host-context out of the selector list that carries dark mode', () => {
+    const rules = baseStyles.text
+      .split('}')
+      .map((chunk) => chunk.split('{')[0] ?? '');
+    for (const selector of rules) {
+      if (!selector.includes(':host-context')) continue;
+      expect(selector).not.toContain(',');
+    }
+    expect(baseStyles.text).toContain(':host([data-theme="dark"]) {');
+  });
 });
diff --git a/tests/tag-input.test.ts b/tests/tag-input.test.ts
index 921db8a..99d734d 100644
--- a/tests/tag-input.test.ts
+++ b/tests/tag-input.test.ts
@@ -232,7 +232,8 @@ describe('bq-tag-input', () => {
     await waitForFrame();
 
     expect(input(el).value).toBe('');
-    expect(el.getAttribute('value')).toBe('');
+    // Nothing was ever committed, so the attribute was never reflected.
+    expect(el.getAttribute('value') ?? '').toBe('');
   });
 
   it('commits a pending draft on blur rather than discarding it', async () => {
diff --git a/tests/theme-scheme.test.ts b/tests/theme-scheme.test.ts
new file mode 100644
index 0000000..5e32fd3
--- /dev/null
+++ b/tests/theme-scheme.test.ts
@@ -0,0 +1,129 @@
+// DOM environment is provided by tests/setup.ts (preloaded via bunfig.toml)
+import { afterEach, describe, expect, it } from 'bun:test';
+import {
+  darkTokens,
+  getDarkSchemeCSS,
+  getLightSchemeCSS,
+  getSchemeRootCSS,
+  lightTokens,
+} from '../src/theme/scheme.js';
+import { installThemeStyles } from '../src/theme/root.js';
+import {
+  getColorScheme,
+  getResolvedColorScheme,
+  setColorScheme,
+} from '../src/theme/index.js';
+
+const win = (globalThis as unknown as Record<string, unknown>)[
+  'window'
+] as Window & typeof globalThis;
+const doc = win.document as unknown as Document;
+
+describe('semantic token tables', () => {
+  it('defines the same tokens in both schemes', () => {
+    for (const name of Object.keys(lightTokens)) {
+      expect(darkTokens[name]).toBeDefined();
+    }
+  });
+
+  it('never lands on the same value for foreground and background', () => {
+    expect(lightTokens['--bq-bg-base']).not.toBe(lightTokens['--bq-text-base']);
+    expect(darkTokens['--bq-bg-base']).not.toBe(darkTokens['--bq-text-base']);
+  });
+
+  it('lifts overlay surfaces off the page in dark mode', () => {
+    // In light mode a popup is told apart from the page by its shadow; in dark
+    // mode the shadow is invisible, so the surface itself has to be lighter.
+    expect(darkTokens['--bq-surface-overlay']).not.toBe(
+      darkTokens['--bq-bg-base']
+    );
+  });
+});
+
+describe('getLightSchemeCSS', () => {
+  it('routes every semantic token through the scheme channel', () => {
+    const css = getLightSchemeCSS();
+    for (const name of Object.keys(lightTokens)) {
+      const channel = name.replace('--bq-', '--bq-scheme-');
+      expect(css).toContain(`${name}: var(${channel},`);
+    }
+  });
+
+  it('lets the channel drive color-scheme too, so native widgets follow', () => {
+    expect(getLightSchemeCSS()).toContain(
+      'color-scheme: var(--bq-scheme-color-scheme, light)'
+    );
+  });
+});
+
+describe('getDarkSchemeCSS', () => {
+  it('writes literal values, so an explicit theme outranks the ambient one', () => {
+    const css = getDarkSchemeCSS();
+    expect(css).toContain('--bq-bg-base: #0f172a;');
+    expect(css).not.toContain('var(--bq-scheme-bg-base');
+  });
+
+  it('strengthens the shadows, which are invisible on a dark surface otherwise', () => {
+    expect(getDarkSchemeCSS()).toContain('--bq-shadow-lg:');
+  });
+});
+
+describe('getSchemeRootCSS', () => {
+  const css = getSchemeRootCSS();
+
+  it('handles all three settings from plain CSS', () => {
+    expect(css).toContain('[data-theme="dark"]');
+    expect(css).toContain('[data-theme="light"]');
+    expect(css).toContain('[data-theme="auto"]');
+    expect(css).toContain('prefers-color-scheme: dark');
+  });
+
+  // The whole point of the channel: a page sets it on an ancestor and it
+  // inherits into every shadow root, with no `:host-context` involved.
+  it('uses no selector that only Chromium understands', () => {
+    expect(css).not.toContain(':host-context');
+    expect(css).not.toContain('::part');
+  });
+
+  it('is not scoped to the root element, so a themed section works too', () => {
+    expect(css).not.toContain(':root[data-theme="dark"]');
+  });
+});
+
+describe('setColorScheme', () => {
+  afterEach(() => {
+    doc.documentElement.removeAttribute('data-theme');
+  });
+
+  it('records the requested scheme', () => {
+    setColorScheme('dark');
+    expect(getColorScheme()).toBe('dark');
+    expect(doc.documentElement.getAttribute('data-theme')).toBe('dark');
+  });
+
+  // Light used to be expressed by *removing* the attribute, which meant a
+  // light island inside a dark page was impossible.
+  it('marks light explicitly rather than by absence', () => {
+    setColorScheme('light');
+    expect(doc.documentElement.getAttribute('data-theme')).toBe('light');
+  });
+
+  it('leaves auto for CSS to resolve instead of a media listener', () => {
+    setColorScheme('auto');
+    expect(doc.documentElement.getAttribute('data-theme')).toBe('auto');
+  });
+
+  it('resolves a pinned scheme without consulting the OS', () => {
+    setColorScheme('dark');
+    expect(getResolvedColorScheme()).toBe('dark');
+    setColorScheme('light');
+    expect(getResolvedColorScheme()).toBe('light');
+  });
+});
+
+describe('installThemeStyles', () => {
+  it('is idempotent for a document it has already handled', () => {
+    expect(installThemeStyles(doc)).toBe(true);
+    expect(installThemeStyles(doc)).toBe(true);
+  });
+});
diff --git a/tests/tree.test.ts b/tests/tree.test.ts
new file mode 100644
index 0000000..80f5fe4
--- /dev/null
+++ b/tests/tree.test.ts
@@ -0,0 +1,255 @@
+// DOM environment is provided by tests/setup.ts (preloaded via bunfig.toml)
+import { afterEach, beforeAll, describe, expect, it } from 'bun:test';
+import {
+  parseIds,
+  parseNodes,
+  stepNode,
+  typeaheadIndex,
+  visibleNodes,
+  type TreeNode,
+} from '../src/components/tree/BqTree.js';
+import { waitForFrame } from './helpers.ts';
+
+const win = (globalThis as unknown as Record<string, unknown>)[
+  'window'
+] as Window & typeof globalThis;
+const doc = win.document as unknown as Document;
+
+const NODES: TreeNode[] = [
+  {
+    id: 'src',
+    label: 'src',
+    children: [
+      { id: 'index', label: 'index.ts' },
+      { id: 'utils', label: 'utils', children: [{ id: 'dom', label: 'dom.ts' }] },
+    ],
+  },
+  { id: 'readme', label: 'README.md' },
+  { id: 'locked', label: 'node_modules', disabled: true },
+];
+
+describe('parseNodes', () => {
+  it('reads a JSON array', () => {
+    expect(parseNodes('[{"id":"a","label":"A"}]')).toHaveLength(1);
+  });
+
+  it('returns an empty tree for malformed or non-array JSON', () => {
+    expect(parseNodes('not json')).toEqual([]);
+    expect(parseNodes('{"id":"a"}')).toEqual([]);
+    expect(parseNodes('')).toEqual([]);
+  });
+});
+
+describe('parseIds', () => {
+  it('splits, trims and drops empties', () => {
+    expect(parseIds(' a , b ,, c ')).toEqual(['a', 'b', 'c']);
+    expect(parseIds('')).toEqual([]);
+  });
+});
+
+describe('visibleNodes', () => {
+  it('hides the contents of a collapsed branch', () => {
+    const flat = visibleNodes(NODES, new Set());
+    expect(flat.map((entry) => entry.node.id)).toEqual([
+      'src',
+      'readme',
+      'locked',
+    ]);
+  });
+
+  it('reveals a branch once it is expanded', () => {
+    const flat = visibleNodes(NODES, new Set(['src']));
+    expect(flat.map((entry) => entry.node.id)).toEqual([
+      'src',
+      'index',
+      'utils',
+      'readme',
+      'locked',
+    ]);
+  });
+
+  it('records depth and parent for each visible node', () => {
+    const flat = visibleNodes(NODES, new Set(['src', 'utils']));
+    const dom = flat.find((entry) => entry.node.id === 'dom');
+    expect(dom?.level).toBe(3);
+    expect(dom?.parentId).toBe('utils');
+  });
+});
+
+describe('stepNode', () => {
+  const flat = visibleNodes(NODES, new Set());
+
+  it('skips disabled nodes', () => {
+    expect(stepNode(flat, 1, 1)).toBe(1);
+  });
+
+  it('stops at the ends instead of wrapping', () => {
+    expect(stepNode(flat, 0, -1)).toBe(0);
+  });
+
+  it('advances to the next enabled node', () => {
+    expect(stepNode(flat, 0, 1)).toBe(1);
+  });
+});
+
+describe('typeaheadIndex', () => {
+  const flat = visibleNodes(NODES, new Set());
+
+  it('jumps to the next node starting with the letter', () => {
+    expect(typeaheadIndex(flat, 0, 'r')).toBe(1);
+  });
+
+  it('wraps around the end of the list', () => {
+    expect(typeaheadIndex(flat, 1, 's')).toBe(0);
+  });
+
+  it('stays put when nothing matches', () => {
+    expect(typeaheadIndex(flat, 0, 'z')).toBe(0);
+  });
+});
+
+describe('bq-tree', () => {
+  beforeAll(async () => {
+    await import('../src/components/tree/index.js');
+  });
+
+  afterEach(() => {
+    doc.body.innerHTML = '';
+  });
+
+  const create = (attrs: Record<string, string> = {}): HTMLElement => {
+    const el = doc.createElement('bq-tree');
+    el.setAttribute('items', JSON.stringify(NODES));
+    for (const [k, v] of Object.entries(attrs)) el.setAttribute(k, v);
+    doc.body.appendChild(el);
+    return el;
+  };
+
+  const nodes = (el: HTMLElement): HTMLElement[] =>
+    Array.from(el.shadowRoot?.querySelectorAll('.node') ?? []);
+
+  const press = (el: HTMLElement, index: number, key: string) =>
+    nodes(el)[index]?.dispatchEvent(
+      new win.KeyboardEvent('keydown', {
+        key,
+        bubbles: true,
+        composed: true,
+        cancelable: true,
+      })
+    );
+
+  it('registers as a custom element', () => {
+    expect(win.customElements.get('bq-tree')).toBeDefined();
+  });
+
+  it('exposes the ARIA tree roles', async () => {
+    const el = create({ label: 'Files' });
+    await waitForFrame();
+    expect(el.shadowRoot?.querySelector('[role="tree"]')?.getAttribute('aria-label')).toBe(
+      'Files'
+    );
+    expect(nodes(el)[0]?.getAttribute('role')).toBe('treeitem');
+    expect(nodes(el)[0]?.getAttribute('aria-level')).toBe('1');
+    expect(nodes(el)[0]?.getAttribute('aria-expanded')).toBe('false');
+  });
+
+  it('keeps exactly one node in the tab order', async () => {
+    const el = create();
+    await waitForFrame();
+    const tabbable = nodes(el).filter(
+      (node) => node.getAttribute('tabindex') === '0'
+    );
+    expect(tabbable).toHaveLength(1);
+  });
+
+  // A leaf node has no `aria-expanded` at all; only branches do.
+  it('marks branches but not leaves as expandable', async () => {
+    const el = create();
+    await waitForFrame();
+    expect(nodes(el)[1]?.hasAttribute('aria-expanded')).toBe(false);
+  });
+
+  it('opens a branch with ArrowRight and closes it with ArrowLeft', async () => {
+    const el = create();
+    await waitForFrame();
+
+    press(el, 0, 'ArrowRight');
+    await waitForFrame();
+    expect(el.getAttribute('expanded')).toBe('src');
+    expect(nodes(el)).toHaveLength(5);
+
+    press(el, 0, 'ArrowLeft');
+    await waitForFrame();
+    expect(el.getAttribute('expanded')).toBe('');
+  });
+
+  it('climbs to the parent when a collapsed child gets ArrowLeft', async () => {
+    const el = create({ expanded: 'src' });
+    await waitForFrame();
+
+    press(el, 1, 'ArrowLeft');
+    await waitForFrame();
+    expect(nodes(el)[0]?.getAttribute('tabindex')).toBe('0');
+  });
+
+  it('moves the roving tab stop with ArrowDown', async () => {
+    const el = create();
+    await waitForFrame();
+    press(el, 0, 'ArrowDown');
+    await waitForFrame();
+    expect(nodes(el)[1]?.getAttribute('tabindex')).toBe('0');
+  });
+
+  it('selects on click and reports the node', async () => {
+    const el = create();
+    await waitForFrame();
+
+    let detail: { id: string; ids: string[] } | null = null;
+    el.addEventListener('bq-select', (e) => {
+      detail = (e as CustomEvent<{ id: string; ids: string[] }>).detail;
+    });
+    nodes(el)[1]?.dispatchEvent(
+      new win.Event('click', { bubbles: true, composed: true })
+    );
+    await waitForFrame();
+
+    expect(el.getAttribute('selected')).toBe('readme');
+    expect(detail?.id).toBe('readme');
+  });
+
+  it('accumulates selection when multiple is set', async () => {
+    const el = create({ multiple: '', selected: 'readme' });
+    await waitForFrame();
+    nodes(el)[0]?.dispatchEvent(
+      new win.Event('click', { bubbles: true, composed: true })
+    );
+    await waitForFrame();
+    expect(el.getAttribute('selected')).toBe('readme,src');
+  });
+
+  it('refuses to select a disabled node', async () => {
+    const el = create();
+    await waitForFrame();
+    nodes(el)[2]?.dispatchEvent(
+      new win.Event('click', { bubbles: true, composed: true })
+    );
+    await waitForFrame();
+    expect(el.getAttribute('selected') ?? '').toBe('');
+  });
+
+  it('jumps to a node by first letter', async () => {
+    const el = create();
+    await waitForFrame();
+    press(el, 0, 'r');
+    await waitForFrame();
+    expect(nodes(el)[1]?.getAttribute('tabindex')).toBe('0');
+  });
+
+  it('leaves no document listeners behind after removal', async () => {
+    const el = create();
+    await waitForFrame();
+    el.remove();
+    await waitForFrame();
+    expect(el.isConnected).toBe(false);
+  });
+});

From d81fdef8e50dbcb8610a386b452a4689c245c7b4 Mon Sep 17 00:00:00 2001
From: Jonas Pfalzgraf <jolun.swtor@gmail.com>
Date: Fri, 31 Jul 2026 15:23:54 +0000
Subject: [PATCH 4/5] improvements

---
 AGENT.md                                   |  24 +++
 docs/guide/theming.md                      |  18 ++
 src/components/alert/BqAlert.ts            |  40 ++--
 src/components/avatar/BqAvatar.ts          |   2 +-
 src/components/badge/BqBadge.ts            |  12 +-
 src/components/banner/BqBanner.ts          |   8 +-
 src/components/button/BqButton.ts          |   2 +-
 src/components/card/BqCard.ts              |  84 +++++++-
 src/components/chip/BqChip.ts              |  12 +-
 src/components/file-upload/BqFileUpload.ts |   4 +-
 src/components/icon-button/BqIconButton.ts |   6 +-
 src/components/spinner/BqSpinner.ts        |   8 +-
 src/components/switch/BqSwitch.ts          |  16 +-
 src/components/tabs/BqTabs.ts              | 102 +++++++---
 src/components/tag-input/BqTagInput.ts     |   6 +-
 src/components/timeline/BqTimeline.ts      |  10 +-
 src/theme/scheme.ts                        |  50 +++++
 src/utils/component.ts                     |  61 ++++--
 src/utils/index.ts                         |   2 +-
 tests/component-css.test.ts                |  20 ++
 tests/component-utils.test.ts              |  83 +++++++-
 tests/render-loops.test.ts                 | 219 +++++++++++++++++++++
 22 files changed, 678 insertions(+), 111 deletions(-)
 create mode 100644 tests/render-loops.test.ts

diff --git a/AGENT.md b/AGENT.md
index cd2c51a..4372bb7 100644
--- a/AGENT.md
+++ b/AGENT.md
@@ -87,6 +87,21 @@ Anything reaching outside the component — `document`/`window` listeners, timer
 elements — must be registered on the scope. `tests/component-utils.test.ts`
 asserts that the overlay components leave no document listeners behind.
 
+**`connected()` runs twice.** The runtime mounts an element from
+`attributeChangedCallback` during upgrade, and the `connectedCallback` that
+follows sees it already mounted and takes its reconnect path — so any element
+carrying an observed attribute in the initial HTML runs `connected()` a second
+time. `bind()` absorbs that: calling it again unwinds the previous scope, so
+exactly one set of listeners stays live. Consequences to respect:
+
+- Call `bind()` **once**, at the top of `connected()`. Use `scopeOf(owner)` to
+  add teardown from another hook.
+- `connected()` must be safe to run twice for everything it does *besides*
+  registering on the scope. Anything not on the scope — a `queueMicrotask` that
+  mutates light DOM, an event dispatched on connect — will happen twice.
+
+This is what made `bq-dropdown-menu` toggle twice per click and never open.
+
 Use `store(owner, init)` when a value created in `connected()` has to stay
 reachable from `updated()`.
 
@@ -144,6 +159,15 @@ runs. `beforeUpdate` covers attribute-driven renders, which no event precedes.
 `setState` renders skip `beforeUpdate` entirely, which is why the event-driven
 half is needed at all.
 
+### Tinted surfaces
+
+Never paint a background from a 50/100/200 palette step. Those are *light*
+colours in both schemes, so a badge or an alert built on them stays near-white
+on a dark page — which is how alerts, badges, chips, avatars and tags all
+shipped broken in dark mode. Use `--bq-intent-{primary|success|danger|warning|
+info|neutral}-{bg|fg|border}`, which flip with the scheme.
+`tests/component-css.test.ts` fails the build on a violation.
+
 ### Theming across the shadow boundary
 
 Semantic tokens resolve through a scheme channel — `--bq-bg-base:
diff --git a/docs/guide/theming.md b/docs/guide/theming.md
index 0f39145..ea97fc4 100644
--- a/docs/guide/theming.md
+++ b/docs/guide/theming.md
@@ -87,6 +87,24 @@ theme in both schemes. To override only one scheme, write a rule against
 | `--bq-focus-ring`       | The focus ring `box-shadow`                           |
 | `--bq-overlay-backdrop` | Dialog and drawer scrims                              |
 
+### Intent surfaces
+
+A tinted status surface — an alert, a badge, a chip, a tag — needs a *pair* of
+colours that swap together with the scheme. Reaching into the palette for
+`--bq-color-success-100` on `--bq-color-success-700` hard-codes a light
+treatment: those steps are near-white and near-black no matter what the page is
+doing, so the badge stays glaring white on a dark page.
+
+| Token | Used for |
+| ----- | -------- |
+| `--bq-intent-{intent}-bg` | The tinted panel or pill |
+| `--bq-intent-{intent}-fg` | Text and icons on that tint |
+| `--bq-intent-{intent}-border` | Its outline |
+
+`{intent}` is one of `primary`, `success`, `danger`, `warning`, `info`,
+`neutral`. Use these anywhere you would otherwise reach for a 50/100/200 step
+as a background.
+
 The surfaces are a stack — sunken, base, raised, overlay. In light mode they
 are told apart by shadow; in dark mode shadows are invisible, so each level is
 a slightly different lightness. That is why an overlay has its own token rather
diff --git a/src/components/alert/BqAlert.ts b/src/components/alert/BqAlert.ts
index 879d066..2dda229 100644
--- a/src/components/alert/BqAlert.ts
+++ b/src/components/alert/BqAlert.ts
@@ -47,22 +47,30 @@ const definition: ComponentDefinition<BqAlertProps> = {
          as a status band without the heavy full outline it used to have. */
       border-inline-start-width: 3px;
     }
-    .alert[data-variant="info"]    { background: var(--bq-color-info-50,#eff6ff);    border-color: var(--bq-color-info-200,#bfdbfe);    border-inline-start-color: var(--bq-color-info-500,#3b82f6);    color: var(--bq-color-info-800,#1e40af); }
-    .alert[data-variant="success"] { background: var(--bq-color-success-50,#f0fdf4); border-color: var(--bq-color-success-200,#bbf7d0); border-inline-start-color: var(--bq-color-success-500,#22c55e); color: var(--bq-color-success-800,#166534); }
-    .alert[data-variant="warning"] { background: var(--bq-color-warning-50,#fffbeb); border-color: var(--bq-color-warning-200,#fde68a); border-inline-start-color: var(--bq-color-warning-500,#f59e0b); color: var(--bq-color-warning-800,#92400e); }
-    .alert[data-variant="danger"]  { background: var(--bq-color-danger-50,#fef2f2);  border-color: var(--bq-color-danger-200,#fecaca);  border-inline-start-color: var(--bq-color-danger-500,#ef4444);  color: var(--bq-color-danger-800,#991b1b); }
-
-    /* Dark mode cannot use the 50-step tints — they are near-white. A
-       translucent wash of the accent over the page keeps the same hue
-       relationship at the right lightness. */
-    :host([data-theme="dark"]) .alert[data-variant="info"],
-    :host([data-theme="dark"]) .alert[data-variant="success"],
-    :host([data-theme="dark"]) .alert[data-variant="warning"],
-    :host([data-theme="dark"]) .alert[data-variant="danger"] { background: var(--bq-bg-subtle,#1e293b); }
-    :host([data-theme="dark"]) .alert[data-variant="info"]    { border-color: var(--bq-color-info-800,#1e40af);    color: var(--bq-color-info-200,#bfdbfe); }
-    :host([data-theme="dark"]) .alert[data-variant="success"] { border-color: var(--bq-color-success-800,#166534); color: var(--bq-color-success-200,#bbf7d0); }
-    :host([data-theme="dark"]) .alert[data-variant="warning"] { border-color: var(--bq-color-warning-800,#92400e); color: var(--bq-color-warning-200,#fde68a); }
-    :host([data-theme="dark"]) .alert[data-variant="danger"]  { border-color: var(--bq-color-danger-800,#991b1b);  color: var(--bq-color-danger-200,#fecaca); }
+    .alert[data-variant="info"] {
+      background: var(--bq-intent-info-bg,#dbeafe);
+      border-color: var(--bq-intent-info-border,#bfdbfe);
+      border-inline-start-color: var(--bq-color-info-500,#3b82f6);
+      color: var(--bq-intent-info-fg,#1d4ed8);
+    }
+    .alert[data-variant="success"] {
+      background: var(--bq-intent-success-bg,#dcfce7);
+      border-color: var(--bq-intent-success-border,#bbf7d0);
+      border-inline-start-color: var(--bq-color-success-500,#22c55e);
+      color: var(--bq-intent-success-fg,#15803d);
+    }
+    .alert[data-variant="warning"] {
+      background: var(--bq-intent-warning-bg,#fef3c7);
+      border-color: var(--bq-intent-warning-border,#fde68a);
+      border-inline-start-color: var(--bq-color-warning-500,#f59e0b);
+      color: var(--bq-intent-warning-fg,#b45309);
+    }
+    .alert[data-variant="danger"] {
+      background: var(--bq-intent-danger-bg,#fee2e2);
+      border-color: var(--bq-intent-danger-border,#fecaca);
+      border-inline-start-color: var(--bq-color-danger-500,#ef4444);
+      color: var(--bq-intent-danger-fg,#b91c1c);
+    }
 
     .status-icon { --bq-icon-size: 1.25rem; margin-block-start: 0.0625rem; }
     .content { flex: 1; min-inline-size: 0; }
diff --git a/src/components/avatar/BqAvatar.ts b/src/components/avatar/BqAvatar.ts
index 09dce4f..ff8f790 100644
--- a/src/components/avatar/BqAvatar.ts
+++ b/src/components/avatar/BqAvatar.ts
@@ -83,7 +83,7 @@ const definition: ComponentDefinition<BqAvatarProps> = {
     :host { display: inline-block; position: relative; }
     .avatar {
       overflow: hidden; display: flex; align-items: center; justify-content: center;
-      background: var(--bq-color-primary-100,#dbeafe); color: var(--bq-color-primary-700,#1d4ed8);
+      background: var(--bq-intent-primary-bg,#dbeafe); color: var(--bq-intent-primary-fg,#1d4ed8);
       font-weight: var(--bq-font-weight-semibold,600); font-family: var(--bq-font-family-sans);
       user-select: none; flex-shrink: 0;
     }
diff --git a/src/components/badge/BqBadge.ts b/src/components/badge/BqBadge.ts
index f87df2a..c1e1c37 100644
--- a/src/components/badge/BqBadge.ts
+++ b/src/components/badge/BqBadge.ts
@@ -32,12 +32,12 @@ const definition: ComponentDefinition<BqBadgeProps> = {
     .badge[data-size="sm"] { font-size: 0.6875rem; padding: 0.125rem 0.5rem; }
     .badge[data-size="md"] { font-size: 0.75rem; padding: 0.2rem 0.6rem; }
     .badge[data-size="lg"] { font-size: 0.875rem; padding: 0.3rem 0.75rem; }
-    .badge[data-variant="primary"]   { background: var(--bq-color-primary-100,#dbeafe); color: var(--bq-color-primary-700,#1d4ed8); }
-    .badge[data-variant="secondary"] { background: var(--bq-color-secondary-100,#f1f5f9); color: var(--bq-color-secondary-700,#334155); }
-    .badge[data-variant="success"]   { background: var(--bq-color-success-100,#dcfce7); color: var(--bq-color-success-700,#15803d); }
-    .badge[data-variant="danger"]    { background: var(--bq-color-danger-100,#fee2e2); color: var(--bq-color-danger-700,#b91c1c); }
-    .badge[data-variant="warning"]   { background: var(--bq-color-warning-100,#fef3c7); color: var(--bq-color-warning-700,#b45309); }
-    .badge[data-variant="info"]      { background: var(--bq-color-info-100,#dbeafe); color: var(--bq-color-info-700,#1d4ed8); }
+    .badge[data-variant="primary"]   { background: var(--bq-intent-primary-bg); color: var(--bq-intent-primary-fg); }
+    .badge[data-variant="secondary"] { background: var(--bq-intent-neutral-bg); color: var(--bq-intent-neutral-fg); }
+    .badge[data-variant="success"]   { background: var(--bq-intent-success-bg); color: var(--bq-intent-success-fg); }
+    .badge[data-variant="danger"]    { background: var(--bq-intent-danger-bg); color: var(--bq-intent-danger-fg); }
+    .badge[data-variant="warning"]   { background: var(--bq-intent-warning-bg); color: var(--bq-intent-warning-fg); }
+    .badge[data-variant="info"]      { background: var(--bq-intent-info-bg); color: var(--bq-intent-info-fg); }
     .badge[data-variant="outline"]   { background: transparent; color: var(--bq-text-base,#0f172a); border: 1.5px solid var(--bq-border-emphasis,#cbd5e1); }
   `,
   render({ props }) {
diff --git a/src/components/banner/BqBanner.ts b/src/components/banner/BqBanner.ts
index 22eb677..c3137e0 100644
--- a/src/components/banner/BqBanner.ts
+++ b/src/components/banner/BqBanner.ts
@@ -69,10 +69,10 @@ const definition: ComponentDefinition<BqBannerProps> = {
     .dismiss:hover { background: var(--bq-bg-hover,rgba(15,23,42,0.08)); }
     .dismiss { --bq-icon-size: 1rem; }
     .dismiss:focus-visible { outline: 2px solid transparent; box-shadow: var(--bq-focus-ring); }
-    .banner[data-variant="info"]    { background: var(--bq-color-info-100,#dbeafe);    color: var(--bq-color-info-700,#1d4ed8);    border-bottom-color: var(--bq-color-info-200,#bfdbfe); }
-    .banner[data-variant="success"] { background: var(--bq-color-success-100,#dcfce7); color: var(--bq-color-success-700,#15803d); border-bottom-color: var(--bq-color-success-200,#bbf7d0); }
-    .banner[data-variant="warning"] { background: var(--bq-color-warning-100,#fef3c7); color: var(--bq-color-warning-700,#b45309); border-bottom-color: var(--bq-color-warning-200,#fde68a); }
-    .banner[data-variant="danger"]  { background: var(--bq-color-danger-100,#fee2e2);  color: var(--bq-color-danger-700,#b91c1c);  border-bottom-color: var(--bq-color-danger-200,#fecaca); }
+    .banner[data-variant="info"]      { background: var(--bq-intent-info-bg); color: var(--bq-intent-info-fg); border-bottom-color: var(--bq-intent-info-border); }
+    .banner[data-variant="success"]   { background: var(--bq-intent-success-bg); color: var(--bq-intent-success-fg); border-bottom-color: var(--bq-intent-success-border); }
+    .banner[data-variant="warning"]   { background: var(--bq-intent-warning-bg); color: var(--bq-intent-warning-fg); border-bottom-color: var(--bq-intent-warning-border); }
+    .banner[data-variant="danger"]    { background: var(--bq-intent-danger-bg); color: var(--bq-intent-danger-fg); border-bottom-color: var(--bq-intent-danger-border); }
     .banner[data-variant="neutral"] { background: var(--bq-bg-muted,#f1f5f9);          color: var(--bq-text-base,#0f172a);         border-bottom-color: var(--bq-border-base,#e2e8f0); }
     @media (prefers-reduced-motion: reduce) {
       .dismiss { transition: none; }
diff --git a/src/components/button/BqButton.ts b/src/components/button/BqButton.ts
index c268ac1..6c40eca 100644
--- a/src/components/button/BqButton.ts
+++ b/src/components/button/BqButton.ts
@@ -98,7 +98,7 @@ const definition: ComponentDefinition<BqButtonProps, BqButtonState> = {
     .btn[data-variant="secondary"] { background-color: var(--bq-bg-muted,#f1f5f9); color: var(--bq-text-base,#0f172a); border-color: var(--bq-border-base,#e2e8f0); }
     .btn[data-variant="secondary"]:hover:not(:disabled):not([aria-disabled="true"]) { background-color: var(--bq-bg-emphasis,#e2e8f0); border-color: var(--bq-border-emphasis,#cbd5e1); }
     .btn[data-variant="outline"] { background-color: transparent; color: var(--bq-color-primary-600,#2563eb); border-color: var(--bq-color-primary-600,#2563eb); }
-    .btn[data-variant="outline"]:hover:not(:disabled):not([aria-disabled="true"]) { background-color: var(--bq-color-primary-50,#eff6ff); }
+    .btn[data-variant="outline"]:hover:not(:disabled):not([aria-disabled="true"]) { background-color: var(--bq-bg-selected,rgba(37,99,235,0.1)); }
     .btn[data-variant="ghost"] { background-color: transparent; color: var(--bq-text-base,#0f172a); border-color: transparent; }
     .btn[data-variant="ghost"]:hover:not(:disabled):not([aria-disabled="true"]) { background-color: var(--bq-bg-hover,rgba(15,23,42,0.06)); }
     .btn[data-variant="danger"] {
diff --git a/src/components/card/BqCard.ts b/src/components/card/BqCard.ts
index de9e867..b16c5b3 100644
--- a/src/components/card/BqCard.ts
+++ b/src/components/card/BqCard.ts
@@ -11,10 +11,38 @@
 import type { ComponentDefinition } from '@bquery/bquery/component';
 import { component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
+import { bind, host, release } from '../../utils/component.js';
 import { baseStyles, reset } from '../../utils/styles.js';
 
 type BqCardProps = { title: string; elevated: boolean; padding: string };
 
+/**
+ * Marks the header and footer bands as empty when nothing is slotted into them.
+ *
+ * `:empty` cannot answer this: the band always contains a `<slot>` element, so
+ * it is never empty in the CSS sense even when nothing is assigned to it. The
+ * card used to rely on that and drew a bordered grey strip under every card
+ * that had no footer.
+ */
+function syncSlotState(el: HTMLElement): void {
+  const root = el.shadowRoot;
+  if (!root) return;
+  for (const name of ['header', 'footer']) {
+    const band = root.querySelector(`.card-${name}`);
+    const slot = root.querySelector(
+      `slot[name="${name}"]`
+    ) as HTMLSlotElement | null;
+    if (!band) continue;
+    const assigned = slot?.assignedNodes({ flatten: true }) ?? [];
+    const filled =
+      assigned.some(
+        (node) =>
+          node.nodeType === 1 || (node.textContent ?? '').trim().length > 0
+      ) || (name === 'header' && Boolean(el.getAttribute('title')));
+    band.toggleAttribute('data-empty', !filled);
+  }
+}
+
 const definition: ComponentDefinition<BqCardProps> = {
   props: {
     title: { type: String, default: '' },
@@ -30,32 +58,66 @@ const definition: ComponentDefinition<BqCardProps> = {
       border-radius: var(--bq-radius-xl,0.75rem);
       border: 1px solid var(--bq-border-base,#e2e8f0);
       overflow: hidden; font-family: var(--bq-font-family-sans);
+      color: var(--bq-text-base,#0f172a);
     }
     :host([elevated]) .card { box-shadow: var(--bq-shadow-md); }
     .card-header {
+      display: flex; align-items: center; gap: var(--bq-space-3,0.75rem);
       padding: var(--bq-space-5,1.25rem) var(--bq-space-6,1.5rem);
-      border-bottom: 1px solid var(--bq-border-base,#e2e8f0);
+      border-block-end: 1px solid var(--bq-border-base,#e2e8f0);
+    }
+    .card-title {
+      font-size: var(--bq-font-size-lg,1.125rem);
+      font-weight: var(--bq-font-weight-semibold,600);
+      letter-spacing: var(--bq-letter-spacing-tight,-0.015em);
+      color: var(--bq-text-base,#0f172a);
+      margin: 0;
     }
-    .card-header:empty { display: none; }
-    .card-title { font-size: var(--bq-font-size-lg,1.125rem); font-weight: var(--bq-font-weight-semibold,600); color: var(--bq-text-base,#0f172a); margin: 0; }
     .card-body[data-padding="none"] { padding: 0; }
     .card-body[data-padding="sm"]   { padding: var(--bq-space-3,0.75rem); }
     .card-body[data-padding="md"]   { padding: var(--bq-space-6,1.5rem); }
     .card-body[data-padding="lg"]   { padding: var(--bq-space-8,2rem); }
     .card-footer {
+      display: flex; align-items: center; gap: var(--bq-space-3,0.75rem);
       padding: var(--bq-space-4,1rem) var(--bq-space-6,1.5rem);
-      border-top: 1px solid var(--bq-border-base,#e2e8f0);
+      border-block-start: 1px solid var(--bq-border-base,#e2e8f0);
       background: var(--bq-bg-subtle,#f8fafc);
     }
-    .card-footer:empty { display: none; }
+    .card-header[data-empty],
+    .card-footer[data-empty] { display: none; }
   `,
+  connected() {
+    const self = host(this);
+    const scope = bind(self);
+    // The slots only exist after the first render.
+    queueMicrotask(() => {
+      if (!self.isConnected) return;
+      for (const slot of Array.from(
+        self.shadowRoot?.querySelectorAll('slot') ?? []
+      )) {
+        scope.on(slot, 'slotchange', () => syncSlotState(self));
+      }
+      syncSlotState(self);
+    });
+  },
+  disconnected() {
+    release(this);
+  },
+  updated() {
+    // Every render replaces the slots, so the bands are unmarked again.
+    syncSlotState(this);
+  },
   render({ props }) {
-    const headerContent = props.title
-      ? `<div class="card-header" part="header"><h3 class="card-title">${escapeHtml(props.title)}</h3><slot name="header"></slot></div>`
-      : '<slot name="header"></slot>';
     return html`
       <article part="card" class="card">
-        ${headerContent}
+        <div class="card-header" part="header" data-empty>
+          ${
+            props.title
+              ? `<h3 class="card-title" part="title">${escapeHtml(props.title)}</h3>`
+              : ''
+          }
+          <slot name="header"></slot>
+        </div>
         <div
           part="body"
           class="card-body"
@@ -63,7 +125,9 @@ const definition: ComponentDefinition<BqCardProps> = {
         >
           <slot></slot>
         </div>
-        <div part="footer" class="card-footer"><slot name="footer"></slot></div>
+        <div part="footer" class="card-footer" data-empty>
+          <slot name="footer"></slot>
+        </div>
       </article>
     `;
   },
diff --git a/src/components/chip/BqChip.ts b/src/components/chip/BqChip.ts
index 40afa76..56ad287 100644
--- a/src/components/chip/BqChip.ts
+++ b/src/components/chip/BqChip.ts
@@ -52,12 +52,12 @@ const definition: ComponentDefinition<BqChipProps> = {
     .chip[data-size="sm"] { font-size: 0.75rem; padding: 0.25rem 0.625rem; }
     .chip[data-size="md"] { font-size: 0.875rem; padding: 0.375rem 0.75rem; }
     .chip[data-size="lg"] { font-size: 1rem; padding: 0.5rem 1rem; }
-    .chip[data-variant="primary"]   { background: var(--bq-color-primary-100,#dbeafe); color: var(--bq-color-primary-700,#1d4ed8); }
-    .chip[data-variant="secondary"] { background: var(--bq-color-secondary-100,#f1f5f9); color: var(--bq-color-secondary-700,#334155); }
-    .chip[data-variant="success"]   { background: var(--bq-color-success-100,#dcfce7); color: var(--bq-color-success-700,#15803d); }
-    .chip[data-variant="danger"]    { background: var(--bq-color-danger-100,#fee2e2); color: var(--bq-color-danger-700,#b91c1c); }
-    .chip[data-variant="warning"]   { background: var(--bq-color-warning-100,#fef3c7); color: var(--bq-color-warning-700,#b45309); }
-    .chip[data-variant="info"]      { background: var(--bq-color-info-100,#dbeafe); color: var(--bq-color-info-700,#1d4ed8); }
+    .chip[data-variant="primary"]   { background: var(--bq-intent-primary-bg); color: var(--bq-intent-primary-fg); }
+    .chip[data-variant="secondary"] { background: var(--bq-intent-neutral-bg); color: var(--bq-intent-neutral-fg); }
+    .chip[data-variant="success"]   { background: var(--bq-intent-success-bg); color: var(--bq-intent-success-fg); }
+    .chip[data-variant="danger"]    { background: var(--bq-intent-danger-bg); color: var(--bq-intent-danger-fg); }
+    .chip[data-variant="warning"]   { background: var(--bq-intent-warning-bg); color: var(--bq-intent-warning-fg); }
+    .chip[data-variant="info"]      { background: var(--bq-intent-info-bg); color: var(--bq-intent-info-fg); }
     .chip[aria-pressed="true"] { border-color: currentColor; }
     .chip[aria-disabled="true"] { opacity: 0.5; cursor: not-allowed; pointer-events: none; }
     .remove-btn {
diff --git a/src/components/file-upload/BqFileUpload.ts b/src/components/file-upload/BqFileUpload.ts
index b730b1a..de52c95 100644
--- a/src/components/file-upload/BqFileUpload.ts
+++ b/src/components/file-upload/BqFileUpload.ts
@@ -113,10 +113,10 @@ const definition: ComponentDefinition<BqFileUploadProps, BqFileUploadState> = {
       transition: border-color var(--bq-duration-fast) var(--bq-easing-standard),
                   background-color var(--bq-duration-fast) var(--bq-easing-standard);
     }
-    .zone:hover:not(:disabled) { border-color: var(--bq-color-primary-600,#2563eb); background: var(--bq-color-primary-50,#eff6ff); }
+    .zone:hover:not(:disabled) { border-color: var(--bq-color-primary-600,#2563eb); background: var(--bq-bg-selected,rgba(37,99,235,0.1)); }
     .zone:focus-visible { outline: 2px solid transparent; box-shadow: var(--bq-focus-ring); }
     .zone:disabled { opacity: 0.55; cursor: not-allowed; }
-    :host([data-dragging]) .zone { border-color: var(--bq-color-primary-600,#2563eb); background: var(--bq-color-primary-50,#eff6ff); }
+    :host([data-dragging]) .zone { border-color: var(--bq-color-primary-600,#2563eb); background: var(--bq-bg-selected,rgba(37,99,235,0.1)); }
     :host([error]) .zone { border-color: var(--bq-color-danger-600,#dc2626); }
     .browse { color: var(--bq-color-primary-600,#2563eb); font-weight: var(--bq-font-weight-semibold,600); }
     .dropzone-icon { display: inline-flex; color: var(--bq-text-subtle,#94a3b8); }
diff --git a/src/components/icon-button/BqIconButton.ts b/src/components/icon-button/BqIconButton.ts
index cf4b07c..425e31a 100644
--- a/src/components/icon-button/BqIconButton.ts
+++ b/src/components/icon-button/BqIconButton.ts
@@ -55,10 +55,10 @@ const definition: ComponentDefinition<BqIconButtonProps, BqIconButtonState> = {
     .btn[data-size="lg"] { width: 3rem; height: 3rem; font-size: 1.25rem; }
     .btn[data-variant="primary"] { background-color: var(--bq-color-primary-600,#2563eb); color: #fff; border-color: var(--bq-color-primary-600,#2563eb); }
     .btn[data-variant="primary"]:hover:not(:disabled):not([aria-disabled="true"]) { background-color: var(--bq-color-primary-700,#1d4ed8); }
-    .btn[data-variant="secondary"] { background-color: var(--bq-color-secondary-100,#f1f5f9); color: var(--bq-color-secondary-700,#334155); border-color: var(--bq-color-secondary-200,#e2e8f0); }
+    .btn[data-variant="secondary"] { background-color: var(--bq-bg-muted,#f1f5f9); color: var(--bq-text-base,#0f172a); border-color: var(--bq-border-base,#e2e8f0); }
     .btn[data-variant="outline"] { background-color: transparent; color: var(--bq-color-primary-600,#2563eb); border-color: var(--bq-color-primary-600,#2563eb); }
-    .btn[data-variant="ghost"] { background-color: transparent; color: var(--bq-color-secondary-700,#334155); }
-    .btn[data-variant="ghost"]:hover:not(:disabled):not([aria-disabled="true"]) { background-color: var(--bq-color-secondary-100,#f1f5f9); }
+    .btn[data-variant="ghost"] { background-color: transparent; color: var(--bq-text-base,#0f172a); }
+    .btn[data-variant="ghost"]:hover:not(:disabled):not([aria-disabled="true"]) { background-color: var(--bq-bg-hover,rgba(15,23,42,0.06)); }
     .btn[data-variant="danger"] { background-color: var(--bq-color-danger-600,#dc2626); color: #fff; border-color: var(--bq-color-danger-600,#dc2626); }
     .btn:focus-visible { outline: 2px solid transparent; box-shadow: var(--bq-focus-ring); }
     .btn:disabled, .btn[aria-disabled="true"] { opacity: 0.5; cursor: not-allowed; }
diff --git a/src/components/spinner/BqSpinner.ts b/src/components/spinner/BqSpinner.ts
index d5770b8..b048a20 100644
--- a/src/components/spinner/BqSpinner.ts
+++ b/src/components/spinner/BqSpinner.ts
@@ -32,10 +32,10 @@ const definition: ComponentDefinition<BqSpinnerProps> = {
     .spinner[data-size="md"] { width: 1.75rem; height: 1.75rem; border-width: 2.5px; }
     .spinner[data-size="lg"] { width: 2.5rem; height: 2.5rem; border-width: 3px; }
     .spinner[data-size="xl"] { width: 3.5rem; height: 3.5rem; border-width: 4px; }
-    .spinner[data-variant="primary"]   { border-color: var(--bq-color-primary-200,#bfdbfe); border-top-color: var(--bq-color-primary-600,#2563eb); }
-    .spinner[data-variant="secondary"] { border-color: var(--bq-color-secondary-200,#e2e8f0); border-top-color: var(--bq-color-secondary-600,#475569); }
-    .spinner[data-variant="danger"]    { border-color: var(--bq-color-danger-100,#fee2e2); border-top-color: var(--bq-color-danger-600,#dc2626); }
-    .spinner[data-variant="success"]   { border-color: var(--bq-color-success-100,#dcfce7); border-top-color: var(--bq-color-success-600,#16a34a); }
+    .spinner[data-variant="primary"]   { border-color: var(--bq-border-base,#e2e8f0); border-top-color: var(--bq-color-primary-600,#2563eb); }
+    .spinner[data-variant="secondary"] { border-color: var(--bq-border-base,#e2e8f0); border-top-color: var(--bq-color-secondary-600,#475569); }
+    .spinner[data-variant="danger"]    { border-color: var(--bq-border-base,#e2e8f0); border-top-color: var(--bq-color-danger-600,#dc2626); }
+    .spinner[data-variant="success"]   { border-color: var(--bq-border-base,#e2e8f0); border-top-color: var(--bq-color-success-600,#16a34a); }
     .spinner[data-variant="white"]     { border-color: rgba(255,255,255,0.3); border-top-color: #fff; }
     @keyframes spin { to { transform: rotate(360deg); } }
     @media (prefers-reduced-motion: reduce) {
diff --git a/src/components/switch/BqSwitch.ts b/src/components/switch/BqSwitch.ts
index 9951d6a..75ab56c 100644
--- a/src/components/switch/BqSwitch.ts
+++ b/src/components/switch/BqSwitch.ts
@@ -62,13 +62,19 @@ const definition: ComponentDefinition<BqSwitchProps, BqSwitchState> = {
 
     /* One custom property drives width, height, thumb size and travel, so a
        new size is one line rather than four coordinated ones. */
+    .switch {
+      position: relative;
+      display: inline-grid;
+      place-items: center;
+      flex: none;
+    }
     .track {
       --bq-switch-track-h: 1.375rem;
       --bq-switch-track-w: 2.5rem;
       --bq-switch-gap: 2px;
       position: relative;
-      display: inline-block;
-      flex: none;
+      display: block;
+      pointer-events: none;
       inline-size: var(--bq-switch-track-w);
       block-size: var(--bq-switch-track-h);
       background: var(--bq-border-strong, #94a3b8);
@@ -171,7 +177,7 @@ const definition: ComponentDefinition<BqSwitchProps, BqSwitchState> = {
     return html`
       <div class="field" part="wrapper">
         <label class="control" part="control">
-          <span class="track" part="track" data-size="${escapeHtml(props.size)}">
+          <span class="switch">
             <input
               type="checkbox"
               part="input"
@@ -188,7 +194,9 @@ const definition: ComponentDefinition<BqSwitchProps, BqSwitchState> = {
               }
               ${describedBy ? `aria-describedby="${escapeHtml(describedBy)}"` : ''}
             />
-            <span class="thumb" part="thumb"></span>
+            <span class="track" part="track" data-size="${escapeHtml(props.size)}">
+              <span class="thumb" part="thumb"></span>
+            </span>
           </span>
           ${
             props.label
diff --git a/src/components/tabs/BqTabs.ts b/src/components/tabs/BqTabs.ts
index 1c41e8f..899aeb2 100644
--- a/src/components/tabs/BqTabs.ts
+++ b/src/components/tabs/BqTabs.ts
@@ -10,7 +10,7 @@ import type { ComponentDefinition } from '@bquery/bquery/component';
 import { component, css, html } from '@bquery/bquery/component';
 import { escapeHtml } from '@bquery/bquery/security';
 import { t } from '../../i18n/index.js';
-import { bind, release } from '../../utils/component.js';
+import { bind, release, store } from '../../utils/component.js';
 import { baseStyles, reset } from '../../utils/styles.js';
 
 type BqTabsProps = { 'active-tab': string; variant: string };
@@ -30,6 +30,28 @@ function getPanelId(tabId: string): string | null {
   return ariaIdPart ? `panel-${ariaIdPart}` : null;
 }
 
+/**
+ * Writes an attribute only when the value would actually change.
+ *
+ * `setAttribute` produces a mutation record even when the value is identical,
+ * and this component writes `id` onto its light-DOM panels from `updated()`
+ * while a MutationObserver watches the subtree for `id` — so an unconditional
+ * write re-entered its own observer, re-rendered, wrote again, and hung the
+ * main thread outright. Any page using the documented panel markup froze on
+ * load.
+ */
+function setAttr(el: Element, name: string, value: string): void {
+  if (el.getAttribute(name) !== value) el.setAttribute(name, value);
+}
+
+function removeAttr(el: Element, name: string): void {
+  if (el.hasAttribute(name)) el.removeAttribute(name);
+}
+
+/** The subtree observer, so `updated()` can pause its own writes. */
+const tabsStore = (owner: object) =>
+  store<{ observer?: MutationObserver | null }>(owner, () => ({}));
+
 const definition: ComponentDefinition<BqTabsProps> = {
   props: {
     'active-tab': { type: String, default: '' },
@@ -92,6 +114,9 @@ const definition: ComponentDefinition<BqTabsProps> = {
 
     // MutationObserver to re-render when child items change
     const obs = new MutationObserver(() => {
+      // Records queued before `updated()` paused the observer still arrive
+      // here; ignore them rather than re-entering the render.
+      if (!tabsStore(self).observer) return;
       readTabs();
       // Trigger re-render by touching an attribute
       const cur = (self as HTMLElement).getAttribute('active-tab') ?? '';
@@ -103,7 +128,11 @@ const definition: ComponentDefinition<BqTabsProps> = {
       attributes: true,
       attributeFilter: ['label', 'disabled', 'id'],
     });
-    scope.add(() => obs.disconnect());
+    tabsStore(self).observer = obs;
+    scope.add(() => {
+      tabsStore(self).observer = null;
+      obs.disconnect();
+    });
 
     const clickH = (e: Event) => {
       const btn = (e.target as Element).closest(
@@ -157,37 +186,50 @@ const definition: ComponentDefinition<BqTabsProps> = {
     release(this);
   },
   updated() {
-    // Sync panel visibility after each render
-    const active = this.getAttribute('active-tab') ?? '';
-    this.querySelectorAll<HTMLElement>('[data-tab]').forEach((panel) => {
-      const tabId = panel.getAttribute('data-tab') ?? '';
-      const isActive = tabId === active;
-      const panelId = panel.id || getPanelId(tabId);
-      const button = Array.from(
-        this.shadowRoot?.querySelectorAll<HTMLElement>('.tab[data-tab-id]') ?? []
-      ).find((candidate) => candidate.getAttribute('data-tab-id') === tabId);
-      const labelledBy = button?.id || (button ? getTabButtonId(tabId) : null);
+    // The panels live in the light DOM, so wiring them up means writing to the
+    // very subtree this component observes. Pause the observer for the pass and
+    // write only what changes: either guard alone is enough to break the loop,
+    // and both together mean a future edit here cannot reintroduce it.
+    const local = tabsStore(this);
+    const observer = local.observer;
+    local.observer = null;
+    observer?.disconnect();
 
-      if (panelId) {
-        panel.id = panelId;
-      }
-      panel.hidden = !isActive;
-      panel.setAttribute('role', 'tabpanel');
-      panel.setAttribute('tabindex', isActive ? '0' : '-1');
-      if (labelledBy) {
-        panel.setAttribute('aria-labelledby', labelledBy);
-      } else {
-        panel.removeAttribute('aria-labelledby');
-      }
-      panel.setAttribute('aria-hidden', isActive ? 'false' : 'true');
-      if (button) {
-        if (panelId) {
-          button.setAttribute('aria-controls', panelId);
-        } else {
-          button.removeAttribute('aria-controls');
+    try {
+      const active = this.getAttribute('active-tab') ?? '';
+      this.querySelectorAll<HTMLElement>('[data-tab]').forEach((panel) => {
+        const tabId = panel.getAttribute('data-tab') ?? '';
+        const isActive = tabId === active;
+        const panelId = panel.id || getPanelId(tabId);
+        const button = Array.from(
+          this.shadowRoot?.querySelectorAll<HTMLElement>('.tab[data-tab-id]') ??
+            []
+        ).find((candidate) => candidate.getAttribute('data-tab-id') === tabId);
+        const labelledBy = button?.id || (button ? getTabButtonId(tabId) : null);
+
+        if (panelId) setAttr(panel, 'id', panelId);
+        if (panel.hidden !== !isActive) panel.hidden = !isActive;
+        setAttr(panel, 'role', 'tabpanel');
+        setAttr(panel, 'tabindex', isActive ? '0' : '-1');
+        if (labelledBy) setAttr(panel, 'aria-labelledby', labelledBy);
+        else removeAttr(panel, 'aria-labelledby');
+        setAttr(panel, 'aria-hidden', isActive ? 'false' : 'true');
+        if (button) {
+          if (panelId) setAttr(button, 'aria-controls', panelId);
+          else removeAttr(button, 'aria-controls');
         }
+      });
+    } finally {
+      if (observer && this.isConnected) {
+        observer.observe(this, {
+          childList: true,
+          subtree: true,
+          attributes: true,
+          attributeFilter: ['label', 'disabled', 'id'],
+        });
+        local.observer = observer;
       }
-    });
+    }
   },
   render({ props, state }) {
     const items =
diff --git a/src/components/tag-input/BqTagInput.ts b/src/components/tag-input/BqTagInput.ts
index 5e43922..a008e5f 100644
--- a/src/components/tag-input/BqTagInput.ts
+++ b/src/components/tag-input/BqTagInput.ts
@@ -139,9 +139,9 @@ const definition: ComponentDefinition<BqTagInputProps, BqTagInputState> = {
     .tags { display: contents; list-style: none; margin: 0; padding: 0; }
     .tag {
       display: inline-flex; align-items: center; gap: 0.25rem;
-      background: var(--bq-color-primary-50,#eff6ff);
-      color: var(--bq-color-primary-700,#1d4ed8);
-      border: 1px solid var(--bq-color-primary-200,#bfdbfe);
+      background: var(--bq-intent-primary-bg,#dbeafe);
+      color: var(--bq-intent-primary-fg,#1d4ed8);
+      border: 1px solid var(--bq-intent-primary-border,#bfdbfe);
       border-radius: var(--bq-radius-md,0.375rem);
       padding-block: 0.125rem;
       padding-inline: 0.5rem 0.25rem;
diff --git a/src/components/timeline/BqTimeline.ts b/src/components/timeline/BqTimeline.ts
index 61a8969..d281a53 100644
--- a/src/components/timeline/BqTimeline.ts
+++ b/src/components/timeline/BqTimeline.ts
@@ -88,13 +88,13 @@ const itemDefinition: ComponentDefinition<BqTimelineItemProps> = {
       width: 0.875rem; height: 0.875rem; margin-top: 0.25rem; flex: 0 0 auto;
       border-radius: var(--bq-radius-full,9999px);
       background: var(--bq-color-primary-600,#2563eb);
-      box-shadow: 0 0 0 3px var(--bq-color-primary-100,#dbeafe);
+      box-shadow: 0 0 0 3px var(--bq-intent-primary-bg,#dbeafe);
       color: var(--bq-text-on-primary,#fff); font-size: 0.5rem; line-height: 1;
     }
-    .item[data-variant="success"] .marker { background: var(--bq-color-success-600,#16a34a); box-shadow: 0 0 0 3px var(--bq-color-success-100,#dcfce7); }
-    .item[data-variant="danger"]  .marker { background: var(--bq-color-danger-600,#dc2626);  box-shadow: 0 0 0 3px var(--bq-color-danger-100,#fee2e2); }
-    .item[data-variant="warning"] .marker { background: var(--bq-color-warning-600,#d97706); box-shadow: 0 0 0 3px var(--bq-color-warning-100,#fef3c7); }
-    .item[data-variant="info"]    .marker { background: var(--bq-color-info-600,#2563eb);    box-shadow: 0 0 0 3px var(--bq-color-info-100,#dbeafe); }
+    .item[data-variant="success"] .marker { background: var(--bq-color-success-600,#16a34a); box-shadow: 0 0 0 3px var(--bq-intent-success-bg,#dcfce7); }
+    .item[data-variant="danger"]  .marker { background: var(--bq-color-danger-600,#dc2626);  box-shadow: 0 0 0 3px var(--bq-intent-danger-bg,#fee2e2); }
+    .item[data-variant="warning"] .marker { background: var(--bq-color-warning-600,#d97706); box-shadow: 0 0 0 3px var(--bq-intent-warning-bg,#fef3c7); }
+    .item[data-variant="info"]    .marker { background: var(--bq-color-info-600,#2563eb);    box-shadow: 0 0 0 3px var(--bq-intent-info-bg,#dbeafe); }
     .item[data-variant="neutral"] .marker { background: var(--bq-text-subtle,#94a3b8);       box-shadow: 0 0 0 3px var(--bq-bg-emphasis,#e2e8f0); }
 
     .connector { flex: 1 1 auto; width: 2px; background: var(--bq-border-base,#e2e8f0); margin-top: 0.25rem; min-height: 0.5rem; }
diff --git a/src/theme/scheme.ts b/src/theme/scheme.ts
index e5d1e30..03c51c9 100644
--- a/src/theme/scheme.ts
+++ b/src/theme/scheme.ts
@@ -70,6 +70,33 @@ const LIGHT_TOKENS = {
   'focus-ring-warning': '0 0 0 3px rgba(217, 119, 6, 0.35)',
 
   'overlay-backdrop': 'rgba(15, 23, 42, 0.5)',
+
+  /* Intent surfaces.
+   *
+   * The palette itself is scheme-independent, so a component that paints a
+   * badge with `--bq-color-success-100` on `--bq-color-success-700` text is
+   * hard-coding a *light* treatment: those steps are near-white and near-black
+   * whatever the page is doing. Every tinted surface in the library — alerts,
+   * badges, chips, avatars, tags — goes through these instead, so the tint
+   * flips with the scheme while the meaning stays put. */
+  'intent-primary-bg': '#dbeafe',
+  'intent-primary-fg': '#1d4ed8',
+  'intent-primary-border': '#bfdbfe',
+  'intent-success-bg': '#dcfce7',
+  'intent-success-fg': '#15803d',
+  'intent-success-border': '#bbf7d0',
+  'intent-danger-bg': '#fee2e2',
+  'intent-danger-fg': '#b91c1c',
+  'intent-danger-border': '#fecaca',
+  'intent-warning-bg': '#fef3c7',
+  'intent-warning-fg': '#b45309',
+  'intent-warning-border': '#fde68a',
+  'intent-info-bg': '#dbeafe',
+  'intent-info-fg': '#1d4ed8',
+  'intent-info-border': '#bfdbfe',
+  'intent-neutral-bg': '#f1f5f9',
+  'intent-neutral-fg': '#334155',
+  'intent-neutral-border': '#e2e8f0',
 } as const;
 
 const DARK_TOKENS: Record<SemanticTokenName, string> = {
@@ -107,6 +134,29 @@ const DARK_TOKENS: Record<SemanticTokenName, string> = {
   'focus-ring-warning': '0 0 0 3px rgba(251, 191, 36, 0.4)',
 
   'overlay-backdrop': 'rgba(2, 6, 23, 0.72)',
+
+  /* Deep, desaturated tints of the same hue: dark enough to sit on the page
+   * without glowing, saturated enough to keep the intent readable. The
+   * foreground jumps to the 300 step, which is the lightest one that still
+   * carries the hue at small text sizes. */
+  'intent-primary-bg': '#172554',
+  'intent-primary-fg': '#93c5fd',
+  'intent-primary-border': '#1e40af',
+  'intent-success-bg': '#052e16',
+  'intent-success-fg': '#86efac',
+  'intent-success-border': '#166534',
+  'intent-danger-bg': '#450a0a',
+  'intent-danger-fg': '#fca5a5',
+  'intent-danger-border': '#991b1b',
+  'intent-warning-bg': '#451a03',
+  'intent-warning-fg': '#fcd34d',
+  'intent-warning-border': '#92400e',
+  'intent-info-bg': '#172554',
+  'intent-info-fg': '#93c5fd',
+  'intent-info-border': '#1e40af',
+  'intent-neutral-bg': '#1e293b',
+  'intent-neutral-fg': '#cbd5e1',
+  'intent-neutral-border': '#334155',
 };
 
 /**
diff --git a/src/utils/component.ts b/src/utils/component.ts
index 888eaae..3afb606 100644
--- a/src/utils/component.ts
+++ b/src/utils/component.ts
@@ -94,14 +94,56 @@ function scopeSet(owner: object): Set<Disposer> {
   return set;
 }
 
+/** Runs and clears every disposer in a set, tolerating re-entrant edits. */
+function unwind(set: Set<Disposer>): void {
+  // Snapshot first: a disposer may register or remove others while running.
+  const pending = Array.from(set);
+  set.clear();
+  for (const dispose of pending) {
+    try {
+      dispose();
+    } catch {
+      /* teardown must never block the rest of the unwind */
+    }
+  }
+}
+
 /**
- * Returns the disposer scope for a component instance, creating it on first
- * use. Calling `bind()` twice returns a scope backed by the same registry, so
- * it is safe to call from any hook.
+ * Opens a disposer scope for a component instance.
+ *
+ * **Calling `bind()` again unwinds the previous scope first.** That is not
+ * defensive tidiness — the component runtime really does call `connected()`
+ * twice for any element that carries an observed attribute in the initial
+ * HTML: `attributeChangedCallback` mounts the element during upgrade, and the
+ * `connectedCallback` that follows sees it already mounted and takes its
+ * reconnect path. Every listener, observer and timer was therefore registered
+ * twice, and the runtime replaced its own scope reference in between, so the
+ * first set could never be released.
+ *
+ * The symptoms were not subtle: `bq-dropdown-menu` toggled twice per click and
+ * so never opened at all. Re-binding collapses both calls onto one live set of
+ * registrations, and a genuine reconnect — where `disconnected()` already ran
+ * `release()` — finds the set empty and unwinds nothing.
+ *
+ * Call it once, at the top of `connected()`. Use {@link scopeOf} to reach an
+ * existing scope from another hook.
  */
 export function bind(owner: object): ComponentScope {
   const set = scopeSet(owner);
+  if (set.size > 0) unwind(set);
+  return makeScope(set);
+}
+
+/**
+ * Returns the scope for an owner **without** unwinding it.
+ *
+ * For hooks other than `connected()` that need to register more teardown.
+ */
+export function scopeOf(owner: object): ComponentScope {
+  return makeScope(scopeSet(owner));
+}
 
+function makeScope(set: Set<Disposer>): ComponentScope {
   const add = (dispose: Disposer): Disposer => {
     set.add(dispose);
     return () => {
@@ -142,16 +184,7 @@ export function bind(owner: object): ComponentScope {
       return remove;
     },
     dispose() {
-      // Snapshot first: a disposer may register or remove others while running.
-      const pending = Array.from(set);
-      set.clear();
-      for (const dispose of pending) {
-        try {
-          dispose();
-        } catch {
-          /* teardown must never block the rest of the unwind */
-        }
-      }
+      unwind(set);
     },
   };
 }
@@ -163,5 +196,5 @@ export function bind(owner: object): ComponentScope {
 export function release(owner: object): void {
   const set = scopes.get(owner);
   if (!set || set.size === 0) return;
-  bind(owner).dispose();
+  unwind(set);
 }
diff --git a/src/utils/index.ts b/src/utils/index.ts
index 33aefec..d305828 100644
--- a/src/utils/index.ts
+++ b/src/utils/index.ts
@@ -28,7 +28,7 @@ export {
   isIconName,
 } from './icons.js';
 export type { IconName } from './icons.js';
-export { bind, host, release, store } from './component.js';
+export { bind, host, release, scopeOf, store } from './component.js';
 export type { ComponentScope, Disposer } from './component.js';
 export {
   dispatch,
diff --git a/tests/component-css.test.ts b/tests/component-css.test.ts
index 2500401..9412ff6 100644
--- a/tests/component-css.test.ts
+++ b/tests/component-css.test.ts
@@ -105,4 +105,24 @@ describe('component stylesheets', () => {
       expect(css).toContain(':host([data-theme="dark"])');
     }
   });
+
+  // The palette is scheme-independent on purpose, so the 50/100/200 steps are
+  // *light* colours whatever the page is doing. A badge painted with
+  // `--bq-color-success-100` stayed near-white in dark mode — as did the
+  // alerts, chips, avatars and tags. Tinted surfaces go through
+  // `--bq-intent-*-bg` instead, which flips with the scheme.
+  it('paints no surface with a palette step that cannot change scheme', () => {
+    const offenders: string[] = [];
+    const rule = /background(?:-color)?\s*:\s*[^;{}]*--bq-color-[a-z]+-(?:50|100|200)\b/g;
+
+    for (const tag of tags) {
+      // Only the component's own rules; the token block itself legitimately
+      // defines every palette step.
+      const css = shadowCss(tag).split(':host-context([data-theme="dark"])').pop() ?? '';
+      for (const match of css.matchAll(rule)) {
+        offenders.push(`${tag}: ${match[0].trim()}`);
+      }
+    }
+    expect(offenders).toEqual([]);
+  });
 });
diff --git a/tests/component-utils.test.ts b/tests/component-utils.test.ts
index f0030e0..3f75c70 100644
--- a/tests/component-utils.test.ts
+++ b/tests/component-utils.test.ts
@@ -1,5 +1,11 @@
 import { beforeAll, describe, expect, it } from 'bun:test';
-import { bind, host, release, store } from '../src/utils/component.js';
+import {
+  bind,
+  host,
+  release,
+  scopeOf,
+  store,
+} from '../src/utils/component.js';
 import { waitForFrame } from './helpers.js';
 
 const win = (globalThis as unknown as Record<string, unknown>)[
@@ -7,6 +13,81 @@ const win = (globalThis as unknown as Record<string, unknown>)[
 ] as Window & typeof globalThis;
 const doc = win.document as unknown as Document;
 
+describe('bind() re-entry', () => {
+  // The component runtime calls `connected()` twice for any element that
+  // carries an observed attribute in the initial HTML: `attributeChangedCallback`
+  // mounts it during upgrade, then `connectedCallback` sees it already mounted
+  // and takes its reconnect path. Every listener was registered twice, and the
+  // runtime had replaced its own scope reference in between, so the first set
+  // could never be released. `bq-dropdown-menu` toggled twice per click and so
+  // never opened at all.
+  it('unwinds the previous scope when connected() runs again', () => {
+    const owner = {};
+    const target = doc.createElement('div');
+    let calls = 0;
+    const handler = () => {
+      calls += 1;
+    };
+
+    bind(owner).on(target, 'ping', handler);
+    bind(owner).on(target, 'ping', handler);
+
+    target.dispatchEvent(new win.Event('ping'));
+    expect(calls).toBe(1);
+  });
+
+  it('still tears everything down on release', () => {
+    const owner = {};
+    const target = doc.createElement('div');
+    let calls = 0;
+
+    bind(owner).on(target, 'ping', () => {
+      calls += 1;
+    });
+    bind(owner).on(target, 'ping', () => {
+      calls += 1;
+    });
+    release(owner);
+
+    target.dispatchEvent(new win.Event('ping'));
+    expect(calls).toBe(0);
+  });
+
+  // A real reconnect runs `disconnected()` first, so the set is already empty
+  // and re-binding must not swallow the new registration.
+  it('re-registers cleanly after a genuine disconnect', () => {
+    const owner = {};
+    const target = doc.createElement('div');
+    let calls = 0;
+    const handler = () => {
+      calls += 1;
+    };
+
+    bind(owner).on(target, 'ping', handler);
+    release(owner);
+    bind(owner).on(target, 'ping', handler);
+
+    target.dispatchEvent(new win.Event('ping'));
+    expect(calls).toBe(1);
+  });
+
+  it('scopeOf adds to the existing scope instead of replacing it', () => {
+    const owner = {};
+    const target = doc.createElement('div');
+    let calls = 0;
+
+    bind(owner).on(target, 'ping', () => {
+      calls += 1;
+    });
+    scopeOf(owner).on(target, 'ping', () => {
+      calls += 1;
+    });
+
+    target.dispatchEvent(new win.Event('ping'));
+    expect(calls).toBe(2);
+  });
+});
+
 describe('component scope', () => {
   it('removes listeners registered through the scope on release', () => {
     const owner = {};
diff --git a/tests/render-loops.test.ts b/tests/render-loops.test.ts
new file mode 100644
index 0000000..a027a81
--- /dev/null
+++ b/tests/render-loops.test.ts
@@ -0,0 +1,219 @@
+/**
+ * Guards against components that fight their own MutationObserver.
+ *
+ * Several components write to their light-DOM children from `updated()` while
+ * observing that same subtree. `setAttribute` produces a mutation record even
+ * when the value is unchanged, so an unconditional write re-enters the
+ * observer, re-renders, writes again — and pins the main thread. `bq-tabs`
+ * shipped exactly that: any page using the documented panel markup froze on
+ * load, and no unit test noticed because the runtime's observer timing differs
+ * from a browser's.
+ *
+ * These tests assert the invariant that makes the loop impossible: a second
+ * pass over already-correct DOM must write nothing at all.
+ */
+import { afterEach, beforeAll, describe, expect, it } from 'bun:test';
+import { waitForFrame } from './helpers.ts';
+
+const win = (globalThis as unknown as Record<string, unknown>)[
+  'window'
+] as Window & typeof globalThis;
+const doc = win.document as unknown as Document;
+
+/** Counts attribute writes that actually change something, and those that do not. */
+function countWrites(el: Element): {
+  redundant: number;
+  restore: () => void;
+} {
+  const original = el.setAttribute.bind(el);
+  let redundant = 0;
+  (el as unknown as { setAttribute: Element['setAttribute'] }).setAttribute = (
+    name: string,
+    value: string
+  ) => {
+    if (el.getAttribute(name) === value) redundant += 1;
+    original(name, value);
+  };
+  return {
+    get redundant() {
+      return redundant;
+    },
+    restore() {
+      delete (el as unknown as Record<string, unknown>)['setAttribute'];
+    },
+  } as { redundant: number; restore: () => void };
+}
+
+describe('bq-tabs light-DOM sync', () => {
+  beforeAll(async () => {
+    await import('../src/components/tabs/index.js');
+  });
+
+  afterEach(() => {
+    doc.body.innerHTML = '';
+  });
+
+  const create = (): HTMLElement => {
+    const el = doc.createElement('bq-tabs');
+    el.setAttribute('active-tab', 'one');
+    el.innerHTML = `
+      <div data-tab-item id="one" label="One"></div>
+      <div data-tab-item id="two" label="Two"></div>
+      <div data-tab="one">First panel</div>
+      <div data-tab="two">Second panel</div>`;
+    doc.body.appendChild(el);
+    return el;
+  };
+
+  it('wires the panels up', async () => {
+    const el = create();
+    await waitForFrame();
+
+    const panel = el.querySelector('[data-tab="one"]') as HTMLElement;
+    expect(panel.getAttribute('role')).toBe('tabpanel');
+    expect(panel.getAttribute('aria-hidden')).toBe('false');
+    expect(panel.id).toBeTruthy();
+
+    const hidden = el.querySelector('[data-tab="two"]') as HTMLElement;
+    expect(hidden.getAttribute('aria-hidden')).toBe('true');
+    expect(hidden.hidden).toBe(true);
+  });
+
+  // The loop's fuel: writing an attribute that already holds that value.
+  it('writes nothing to a panel that is already correct', async () => {
+    const el = create();
+    await waitForFrame();
+
+    const panel = el.querySelector('[data-tab="one"]') as HTMLElement;
+    const spy = countWrites(panel);
+    try {
+      // Force another render over already-wired DOM.
+      el.setAttribute('variant', 'pills');
+      await waitForFrame();
+      expect(spy.redundant).toBe(0);
+    } finally {
+      spy.restore();
+    }
+  });
+
+  it('still updates the panels when the active tab changes', async () => {
+    const el = create();
+    await waitForFrame();
+
+    el.setAttribute('active-tab', 'two');
+    await waitForFrame();
+
+    expect(
+      (el.querySelector('[data-tab="two"]') as HTMLElement).getAttribute(
+        'aria-hidden'
+      )
+    ).toBe('false');
+    expect(
+      (el.querySelector('[data-tab="one"]') as HTMLElement).getAttribute(
+        'aria-hidden'
+      )
+    ).toBe('true');
+  });
+});
+
+describe('bq-card slot bands', () => {
+  beforeAll(async () => {
+    await import('../src/components/card/index.js');
+  });
+
+  afterEach(() => {
+    doc.body.innerHTML = '';
+  });
+
+  // `:empty` cannot see this: the band always contains a <slot> element, so a
+  // card with no footer used to draw a bordered grey strip anyway.
+  it('hides the footer band when nothing is slotted into it', async () => {
+    const el = doc.createElement('bq-card');
+    el.textContent = 'Body only';
+    doc.body.appendChild(el);
+    await waitForFrame();
+
+    expect(
+      el.shadowRoot?.querySelector('.card-footer')?.hasAttribute('data-empty')
+    ).toBe(true);
+  });
+
+  it('shows the footer band once something is slotted', async () => {
+    const el = doc.createElement('bq-card');
+    el.innerHTML = 'Body<div slot="footer">Actions</div>';
+    doc.body.appendChild(el);
+    await waitForFrame();
+
+    expect(
+      el.shadowRoot?.querySelector('.card-footer')?.hasAttribute('data-empty')
+    ).toBe(false);
+  });
+
+  it('shows the header band for a title as well as for a slot', async () => {
+    const titled = doc.createElement('bq-card');
+    titled.setAttribute('title', 'Report');
+    doc.body.appendChild(titled);
+
+    const slotted = doc.createElement('bq-card');
+    slotted.innerHTML = '<div slot="header">Custom</div>Body';
+    doc.body.appendChild(slotted);
+
+    const bare = doc.createElement('bq-card');
+    bare.textContent = 'Body';
+    doc.body.appendChild(bare);
+    await waitForFrame();
+
+    expect(
+      titled.shadowRoot?.querySelector('.card-header')?.hasAttribute('data-empty')
+    ).toBe(false);
+    expect(
+      slotted.shadowRoot
+        ?.querySelector('.card-header')
+        ?.hasAttribute('data-empty')
+    ).toBe(false);
+    expect(
+      bare.shadowRoot?.querySelector('.card-header')?.hasAttribute('data-empty')
+    ).toBe(true);
+  });
+});
+
+describe('bq-switch structure', () => {
+  beforeAll(async () => {
+    await import('../src/components/switch/index.js');
+  });
+
+  afterEach(() => {
+    doc.body.innerHTML = '';
+  });
+
+  // The checked styling hangs entirely off `input:checked ~ .track`. Nesting
+  // the track inside the input's parent instead of beside it made every
+  // checked state silently do nothing — the switch rendered permanently off.
+  it('keeps the track a following sibling of the input', async () => {
+    const el = doc.createElement('bq-switch');
+    el.setAttribute('checked', '');
+    doc.body.appendChild(el);
+    await waitForFrame();
+
+    const input = el.shadowRoot?.querySelector('input');
+    expect(input).not.toBeNull();
+    const track = input?.nextElementSibling;
+    expect(track?.classList.contains('track')).toBe(true);
+    expect(track?.querySelector('.thumb')).not.toBeNull();
+  });
+
+  it('reflects checked onto the input the selector keys off', async () => {
+    const el = doc.createElement('bq-switch');
+    doc.body.appendChild(el);
+    await waitForFrame();
+    expect(
+      (el.shadowRoot?.querySelector('input') as HTMLInputElement).checked
+    ).toBe(false);
+
+    el.setAttribute('checked', '');
+    await waitForFrame();
+    expect(
+      (el.shadowRoot?.querySelector('input') as HTMLInputElement).checked
+    ).toBe(true);
+  });
+});

From 9200406ff7776d085ec477f5f9f6fe5713adfdbd Mon Sep 17 00:00:00 2001
From: Jonas Pfalzgraf <jolun.swtor@gmail.com>
Date: Fri, 31 Jul 2026 15:30:22 +0000
Subject: [PATCH 5/5] fix(tests): remove exponential backtracking from the
 sanitizer audit regex
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`[^<>]` already matches newlines — a character class is unaffected by the `s`
flag — so `(?:[^<>]|\n)*?` gave the group two ways to match the same character.
CodeQL flagged it: an unterminated tag such as `<A` followed by many newlines
backtracks exponentially.

One unambiguous class matches the same text in linear time; the audit still
finds the attributes it is meant to catch.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 tests/sanitizer-allowlist.test.ts | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/tests/sanitizer-allowlist.test.ts b/tests/sanitizer-allowlist.test.ts
index 970848c..520a8bb 100644
--- a/tests/sanitizer-allowlist.test.ts
+++ b/tests/sanitizer-allowlist.test.ts
@@ -80,7 +80,11 @@ function renderedAttributes(source: string): Set<string> {
   const body = source.slice(renderStart);
   const attributes = new Set<string>();
 
-  for (const tag of body.matchAll(/<([a-zA-Z][\w-]*)((?:[^<>]|\n)*?)>/g)) {
+  // `[^<>]` already matches newlines — a character class is not affected by
+  // the `s` flag — so spelling out `(?:[^<>]|\n)` made the two branches
+  // ambiguous and the group exponentially backtrackable on an unterminated
+  // tag. One unambiguous class matches the same text in linear time.
+  for (const tag of body.matchAll(/<([a-zA-Z][\w-]*)([^<>]*)>/g)) {
     if (!KNOWN_TAGS.has((tag[1] ?? '').toLowerCase())) continue;
     for (const attribute of (tag[2] ?? '').matchAll(
       /(?:^|[\s"'`])([a-zA-Z][a-zA-Z0-9-]*)\s*=\s*["']/g