npm - @adia-ai/web-components - Versions diffs - 0.7.11 → 0.7.13 - Mend

@adia-ai/web-components 0.7.11 → 0.7.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (46) hide show

package/CHANGELOG.md +29 -4
package/README.md +7 -7
package/USAGE.md +2 -2
package/components/button/button.css +4 -3
package/components/frame/frame.a2ui.json +11 -1
package/components/frame/frame.yaml +19 -1
package/components/theme-provider/theme-provider.a2ui.json +88 -0
package/components/theme-provider/theme-provider.class.js +134 -0
package/components/theme-provider/theme-provider.css +18 -0
package/components/theme-provider/theme-provider.d.ts +45 -0
package/components/theme-provider/theme-provider.js +22 -0
package/components/theme-provider/theme-provider.test.js +94 -0
package/components/theme-provider/theme-provider.yaml +96 -0
package/dist/host.min.css +1 -1
package/dist/host.sheet.js +11 -0
package/dist/prose.min.css +1 -0
package/dist/prose.sheet.js +11 -0
package/dist/themes.min.css +1 -0
package/dist/themes.sheet.js +11 -0
package/dist/verse.min.css +1 -0
package/dist/verse.sheet.js +11 -0
package/dist/web-components.min.css +1 -1
package/dist/web-components.sheet.js +11 -0
package/package.json +7 -1
package/styles/README.md +1 -1
package/styles/colors/parameters.css +1 -1
package/styles/colors/primitives-accent.css +1 -1
package/styles/colors/primitives-brand.css +1 -1
package/styles/colors/primitives-danger.css +1 -1
package/styles/colors/primitives-info.css +1 -1
package/styles/colors/primitives-neutral.css +1 -1
package/styles/colors/primitives-success.css +1 -1
package/styles/colors/primitives-warning.css +1 -1
package/styles/colors/scrims.css +1 -1
package/styles/colors/semantics/aliases.css +1 -1
package/styles/colors/semantics/buckets.css +1 -1
package/styles/colors/semantics/core.css +1 -1
package/styles/colors/semantics/data-viz.css +1 -1
package/styles/colors/semantics/features.css +1 -1
package/styles/colors/surfaces.css +1 -1
package/styles/components.css +1 -0
package/styles/design-tokens-export.js +1 -1
package/styles/host.css +1 -1
package/styles/prose.css +1 -1
package/styles/themes.css +12 -12
package/web-components.sheet.d.ts +7 -0

package/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,30 @@
 # Changelog — @adia-ai/web-components
+## [0.7.13] — 2026-06-06
+### Fixed
+- **`./css/sheet` subpath export now resolves TS types.** The 0.7.12 `.sheet.js` twin (constructable-`CSSStyleSheet` mirror of `web-components.min.css`) shipped its `./css/sheet` export with `import`/`default` but no `types` — TS consumers got no types for `constructSheet()`. Added `web-components.sheet.d.ts` (`export function constructSheet(): CSSStyleSheet | null`), the `types` condition (types-first), and the `.d.ts` to `files[]` so the tarball packs it. Caught by `verify:exports-conditionals`.
+- **`button-ui[color=warning]` hover contrast** — the warning fill's hover surface now uses `--a-warning-bg` (the -20 tint) instead of `--a-warning-strong`, whose mid-tone read muddy under the dark `--a-warning-fg`. Demo (`theme-provider.html`) card header wrapped in `<header>` for canonical structure. (dogfood-audit: warning-strong-vs-bg; check:card-structure.)
+### Docs
+- README CDN snippets refreshed to the current line: `@0.6` → `@0.7`, primitive count 95 → 122, pin example → `@adia-ai/web-components@0.7.13`.
+## [0.7.12] — 2026-06-04
+### Added
+- **New `<theme-provider>` element — adopt the AdiaUI foundation from anywhere, no `<head>` link.** A Light-DOM, `display: contents` infra wrapper (the 122nd primitive) that adopts the foundation — design tokens + resets + page-frame + every primitive's CSS, the constructable-stylesheet twin of `web-components.min.css` (byte-identical to the CDN bundle) — into `document.adoptedStyleSheets` once, deduped, at module-eval. So SPA roots / embedded apps / dynamic mounts render fully-styled **without** a hand-wired `<link rel="stylesheet">` in `<head>`. Opt-in `theme="ocean|forest|…"` (named preset) + `scale="verse|prose"` (typographic register) adopt their layer twin **on demand** (`theme=` matches the `[theme]` hook directly; `scale=` maps onto the existing `[verse]`/`[prose]` attribute). Coexists with the render-blocking `<link>` path (same bytes) — link for multi-page / top-level surfaces (cacheable, no flash), provider for no-`<head>` contexts. Deliberately **not** in the all-primitives barrel (it carries the whole foundation) — import `@adia-ai/web-components/components/theme-provider` explicitly. Files: `components/theme-provider/{theme-provider.js,.class.js,.css,.yaml,.html,.test.js}`.
+- **CDN `.sheet.js` twins.** `bundle-css.mjs` co-emits a constructable-`CSSStyleSheet` twin beside each foundation `.min.css` — `web-components.sheet.js`, `host.sheet.js`, and the `themes` / `verse` / `prose` register twins — from the **same minified buffer** (byte-identical to the `.min.css`, verified by `check:css-bundles-fresh`, exposed as the `./css/sheet` export). A page that links `web-components.min.css` and one that adopts `web-components.sheet.js` render identically. Powers `<theme-provider>` and any runtime style injector that can't add a `<head>` link.
+### Changed
+- **BREAKING (pre-1.0 PATCH cadence) — the token-theme attribute `data-theme` is renamed `theme`.** `<html data-theme="ocean">` → `<html theme="ocean">`; `[data-theme="…"]` selectors → `[theme="…"]`; the token-root selector `:root, theme-ui, [data-theme]` → `:root, theme-ui, [theme], theme-provider` across the 14 foundation files (so `<theme-provider>` is itself a token-root). Cleaner, and it converges with `<canvas-ui theme="…">`, which already scoped AdiaUI themes the same way. Done as a repo-wide word-boundary sweep — compound attributes (`data-theme-slug`, `data-themes-grid`, `data-themed`, …) are preserved (the sweep also touched the styles/, traits/, and patterns/ trees). **Consumers using `data-theme="…"` must switch to `theme="…"`** — see `docs/MIGRATION GUIDE.md`.
+- **CDN bundles rebuilt** — `dist/web-components.min.{css,js}` + `dist/host.min.css` regenerated so the `[theme]` rename, `<theme-provider>` registration, and the new register twins reach `@adia-ai/web-components@0.7` CDN consumers.
+### Fixed
+- **`dts-codegen` reads the authoritative tag.** It reconstructed each demo's tag as `${name}-ui`, which mangles a no-`-ui` infra tag (`<theme-provider>` is the first) — it now reads `x-adiaui.tag` from the sidecar. Behavior-neutral for all 121 `-ui` components (their `name-ui` === `tag`); correct for infra tags. File: `scripts/build/dts-codegen.mjs`.
 ## [0.7.11] — 2026-06-04
 ### Added
@@ -2986,7 +3011,7 @@ The future non-side-effect `class` subpath per component (allowing class import
 All `change` / `input` event dispatches across form-bearing components now emit a `CustomEvent` carrying `detail: { value: this.value }` (value-semantic primitives) or `detail: { value: this.value, checked: this.checked }` (boolean-semantic — switch / check / radio / option-card). Backwards-compatible — `e.target.value` still works since the host's `value` property is updated before dispatch.
-Driven by [consumer feedback](/Users/kimba/Projects/adia/color-app/docs/outbound/FEEDBACK-adia-packages.md) from Design Tokens Studio (2026-05-12) — eliminates the `(e.target as any).value` pattern in TypeScript consumers.
+Driven by consumer feedback from Design Tokens Studio (2026-05-12) — eliminates the `(e.target as any).value` pattern in TypeScript consumers.
 **Value-semantic primitives swept** (`detail: { value }`):
 - `<input-ui>` (input.js — 9 dispatch sites)
@@ -3042,7 +3067,7 @@ that don't surface in the export). Pure-JS OKLCH → OKLab → linear-sRGB
 - **`styles/design-tokens-export.js`** (new ~430 lines) — extraction module:
   CSSOM scanner with authoritative-selector filter (`:root, theme-ui,
-  [data-theme]` only — skipping attribute-scoped overrides that would
+  [theme]` only — skipping attribute-scoped overrides that would
   pollute the cssVar map under last-wins semantics), symbolic
   `var()` / `light-dark()` chain walker, OKLCH color-math pipeline, four
   output formatters (DTCG / hex / float-RGB / HSL-decimal). Public API:
@@ -3192,7 +3217,7 @@ Lockstep version bump only — source byte-identical to v0.3.4. Internal `@adia-
 Lockstep version bump only — source byte-identical to v0.3.3. Internal `@adia-ai/*` dep ranges remain at `^0.3.0`. See root [CHANGELOG.md `## [0.3.4]`](../../CHANGELOG.md) for the cut narrative.
 ## [0.3.3] - 2026-05-07
-**Lockstep cut.** All 9 published `@adia-ai/*` packages now share version `0.3.3`, governed by [`docs/specs/package-architecture.md` § 15](../../../docs/specs/package-architecture.md#15-versioning-policy).
+**Lockstep cut.** All 9 published `@adia-ai/*` packages now share version `0.3.3`, governed by [`docs/specs/package-architecture.md` § 15](../../docs/specs/package-architecture.md#15-versioning-policy).
 ### Changed
@@ -3205,7 +3230,7 @@ Lockstep version bump only — source byte-identical to v0.3.3. Internal `@adia-
 ## [0.3.2] - 2026-05-06
 **9-package lockstep patch cut to v0.3.2.** All lockstep members share
-one version per [`docs/specs/package-architecture.md` § 15](../../../docs/specs/package-architecture.md#15-versioning-policy).
+one version per [`docs/specs/package-architecture.md` § 15](../../docs/specs/package-architecture.md#15-versioning-policy).
 Internal `@adia-ai/*` dep ranges unchanged at `^0.3.0`.
 ### No source changes

package/README.md CHANGED Viewed

@@ -38,13 +38,13 @@ Since **v0.6.30**, this package ships pre-flattened + minified bundles under `di
 ```html
 <!-- CSS: all primitives, tokens, resets (443 KB raw / ~50 KB gzipped) -->
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@adia-ai/web-components@0.6/dist/web-components.min.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@adia-ai/web-components@0.7/dist/web-components.min.css">
-<!-- JS: registers all 95 primitives (~250 KB gzipped via Brotli) -->
-<script type="module" src="https://cdn.jsdelivr.net/npm/@adia-ai/web-components@0.6/dist/web-components.min.js"></script>
+<!-- JS: registers all 122 primitives (~250 KB gzipped via Brotli) -->
+<script type="module" src="https://cdn.jsdelivr.net/npm/@adia-ai/web-components@0.7/dist/web-components.min.js"></script>
 ```
-The `@0.6` range tracks the latest `0.6.x` patch automatically (won't jump to a breaking `0.7`). For reproducible builds, pin an exact version instead — e.g. `@adia-ai/web-components@0.6.45/dist/web-components.min.css`.
+The `@0.7` range tracks the latest `0.6.x` patch automatically (won't jump to a breaking `0.8`). For reproducible builds, pin an exact version instead — e.g. `@adia-ai/web-components@0.7.13/dist/web-components.min.css`.
 For composite shells, add the corresponding bundle from `@adia-ai/web-modules` — see [its README](../web-modules/#cdn-no-bundler--codepen-marketing-pages-static-html) or the [CDN usage guide](https://ui-kit.exe.xyz/site/cdn-usage). The kitchen-sink path is `@adia-ai/web-modules/dist/everything.min.js` (all primitives + all 4 shells; ~190 KB gzipped) — one tag for CodePen demos.
@@ -59,7 +59,7 @@ For composite shells, add the corresponding bundle from `@adia-ai/web-modules`
 ESM-only — bundlers (Vite, esbuild, webpack 5+, Rollup) resolve `import` for both `.js` and `.css`; in plain HTML use `<script type="module">` + `<link rel="stylesheet">`.
 ```js
-import '@adia-ai/web-components';          // registers every *-ui tag (95 primitives)
+import '@adia-ai/web-components';          // registers every *-ui tag (122 primitives)
 import '@adia-ai/web-components/css';      // every primitive's CSS (one stylesheet)
 ```
@@ -336,12 +336,12 @@ generation engine consume.
 ## Themes, density, scale
 ```html
-<div data-theme="ocean" density="compact" size="sm">
+<div theme="ocean" density="compact" size="sm">
   …all descendants re-theme / re-densify / re-scale automatically…
 </div>
 ```
-- `[data-theme]` — 8 themes: `default`, `ocean`, `forest`, `sunset`,
+- `[theme]` — 8 themes: `default`, `ocean`, `forest`, `sunset`,
   `lavender`, `rose`, `slate`, `midnight`
 - `[density]` — `compact` (0.85×) · `spacious` (1.15×)
 - `[size]` — `sm`|`md`|`lg` shifts the entire typescale + component

package/USAGE.md CHANGED Viewed

@@ -673,14 +673,14 @@ The same applies to `bind()` — call it once in the constructor or use a field,
 AdiaUI is parametric. Three attributes drive global appearance:
 ```html
-<div data-theme="ocean" density="compact" size="sm">
+<div theme="ocean" density="compact" size="sm">
   <!-- all descendants re-theme / re-densify / re-scale -->
 </div>
 ```
 | Attribute | Values | Effect |
 |---|---|---|
-| `[data-theme]` | `default`, `ocean`, `forest`, `sunset`, `lavender`, `rose`, `slate`, `midnight` | Swaps the OKLCH color ramp |
+| `[theme]` | `default`, `ocean`, `forest`, `sunset`, `lavender`, `rose`, `slate`, `midnight` | Swaps the OKLCH color ramp |
 | `[density]` | `compact` (0.85×), `spacious` (1.15×) | Multiplies `--a-density` token |
 | `[size]` | `sm`, `md`, `lg` | Shifts typescale + component dimensions |
 | `[radius]` | `sharp` (0), `rounded` (1), `round` (2) | Multiplies `--a-radius-k` token |

package/components/button/button.css CHANGED Viewed

@@ -23,9 +23,10 @@ button-ui[variant="primary"]:not([disabled]):hover { --button-bg: var(--a-accent
 button-ui[color="danger"]:not([disabled]):hover     { --button-bg: var(--a-danger-strong); }
 button-ui[color="success"]:not([disabled]):hover    { --button-bg: var(--a-success-strong); }
 button-ui[color="info"]:not([disabled]):hover       { --button-bg: var(--a-info-strong); }
-/* warning fill → -strong like the rest; its mid-tone can read muddy under
-   the dark --a-warning-fg — revisit the warning ramp upstream if so. */
-button-ui[color="warning"]:not([disabled]):hover    { --button-bg: var(--a-warning-strong); }
+/* warning fill → -bg (NOT -strong like the rest): warning's -strong mid-tone
+   reads muddy under the dark --a-warning-fg, so the hover surface uses the
+   -20 tint (--a-warning-bg) for clean contrast. (dogfood-audit: warning-strong-vs-bg) */
+button-ui[color="warning"]:not([disabled]):hover    { --button-bg: var(--a-warning-bg); }
 /* Outline / ghost — no fill on hover; fg goes rest-color → `-strong`.
    Ghost reads --button-fg-ghost-hover (default --a-fg-strong) so consumers

package/components/frame/frame.a2ui.json CHANGED Viewed

@@ -52,7 +52,17 @@
       "Modal",
       "Col"
     ],
-    "slots": {},
+    "slots": {
+      "body": {
+        "description": "The scrolling region — the only one with overflow. The native `<section>` child takes this role by tag + DOM order; any element can opt in via `slot=\"body\"`. Scrolls between the pinned header and footer (requires a definite-height parent)."
+      },
+      "footer": {
+        "description": "Pinned bottom region — typically an action bar kept visible while the body scrolls. The native `<footer>` child takes this role by tag + DOM order; any element can opt in via `slot=\"footer\"`. Optional."
+      },
+      "header": {
+        "description": "Pinned top region — stays fixed while the body scrolls. The native `<header>` child takes this role by tag + DOM order; any element can opt in via `slot=\"header\"` (a CSS [slot] match in Light DOM, not native projection — ADR-0033), e.g. `<section slot=\"header\">` as a pinned rail. Optional."
+      }
+    },
     "states": [
       {
         "description": "Default, ready for interaction.",

package/components/frame/frame.yaml CHANGED Viewed

@@ -25,7 +25,25 @@ description: |
   not broken).
 props: {}
 events: {}
-slots: {}
+slots:
+  header:
+    description: >-
+      Pinned top region — stays fixed while the body scrolls. The native
+      `<header>` child takes this role by tag + DOM order; any element can opt
+      in via `slot="header"` (a CSS [slot] match in Light DOM, not native
+      projection — ADR-0033), e.g. `<section slot="header">` as a pinned rail.
+      Optional.
+  body:
+    description: >-
+      The scrolling region — the only one with overflow. The native `<section>`
+      child takes this role by tag + DOM order; any element can opt in via
+      `slot="body"`. Scrolls between the pinned header and footer (requires a
+      definite-height parent).
+  footer:
+    description: >-
+      Pinned bottom region — typically an action bar kept visible while the body
+      scrolls. The native `<footer>` child takes this role by tag + DOM order;
+      any element can opt in via `slot="footer"`. Optional.
 states:
   - name: idle
     description: Default, ready for interaction.

package/components/theme-provider/theme-provider.a2ui.json ADDED Viewed

@@ -0,0 +1,88 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/ThemeProvider.json",
+  "title": "ThemeProvider",
+  "description": "Foundation-providing wrapper — adopts the AdiaUI foundation (design tokens +\nresets + page-frame + every primitive's CSS) into the document from anywhere\nin the DOM, so a surface renders fully-styled WITHOUT a hand-wired\n<link rel=\"stylesheet\"> in <head>. Layout-transparent (display: contents): the\nelement owns no box; children lay out as if it weren't there.\n\nMechanism: it imports the constructable-stylesheet twin of web-components.min.css\n(byte-identical to the CDN bundle, emitted from the same build buffer) and\nadopts it once into document.adoptedStyleSheets, deduped — adoption fires at\nmodule load, before paint. Coexists with the render-blocking <link> path; both\ndeliver the same bytes. Use a <link> (-> the CDN web-components.min.css) for\nmulti-page / top-level surfaces (cacheable across navigations, zero flash); use\n<theme-provider> for SPA roots, embedded apps, and dynamic mounts where you do\nnot control <head> (e.g. <embed-shell>, an A2UI surface, a micro-frontend).\n\nTheming: the base foundation is OS light/dark via light-dark() tokens. Two opt-in\nattributes adopt their layer on demand — theme=\"ocean|forest|slate|…\" applies a\nnamed preset (adopts the themes layer; matches the [theme] hook) and\nscale=\"verse|prose\" sets the compact / long-form typographic register (adopts the\nmatching register layer; maps onto the [verse]/[prose] attribute). Each layer is\nfetched only when its attribute is set, so a bare provider stays lean.\nOpt-in infra: NOT in the all-in-one @adia-ai/web-components barrel (it carries\nthe whole foundation); import @adia-ai/web-components/components/theme-provider\nexplicitly. Distinct from <frame-ui> (a layout skeleton, owns no CSS delivery)\nand the page shells (chrome over the same foundation).\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "theme": {
+      "description": "Named theme preset for the wrapped subtree (default, ocean, forest, sunset, lavender, rose, slate, midnight). Adopts the themes layer on demand + matches the [theme=\"…\"] hook.",
+      "type": "string",
+      "default": ""
+    },
+    "component": {
+      "const": "ThemeProvider"
+    },
+    "scale": {
+      "description": "Typographic / density register for the subtree — \"verse\" (compact) or \"prose\" (long-form). Adopts the matching register layer on demand; maps onto the [verse]/[prose] attribute (additive).",
+      "type": "string",
+      "default": ""
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "layout",
+    "composes": [],
+    "events": {},
+    "examples": [
+      {
+        "description": "A client-mounted app root that self-provides the foundation (no head link).",
+        "a2ui": "[\n  { \"id\": \"root\", \"component\": \"ThemeProvider\", \"children\": [\"panel\"] },\n  { \"id\": \"panel\", \"component\": \"Frame\", \"children\": [\"body\", \"actions\"] },\n  { \"id\": \"body\", \"component\": \"Section\", \"children\": [\"copy\"] },\n  { \"id\": \"copy\", \"component\": \"Text\", \"variant\": \"body\", \"textContent\": \"Fully styled — no <head> stylesheet link.\" },\n  { \"id\": \"actions\", \"component\": \"Footer\", \"children\": [\"go\"] },\n  { \"id\": \"go\", \"component\": \"Button\", \"text\": \"Continue\", \"variant\": \"primary\" }\n]",
+        "name": "spa-root"
+      }
+    ],
+    "keywords": [
+      "style",
+      "provider",
+      "foundation",
+      "tokens",
+      "reset",
+      "adopt",
+      "stylesheet",
+      "shell",
+      "embed",
+      "spa"
+    ],
+    "name": "UIThemeProvider",
+    "related": [
+      "Frame",
+      "Card"
+    ],
+    "slots": {},
+    "states": [
+      {
+        "description": "Default — foundation adopted into the document; children rendered.",
+        "name": "idle"
+      }
+    ],
+    "status": "experimental",
+    "synonyms": {
+      "foundation": [
+        "foundation",
+        "tokens",
+        "styles"
+      ],
+      "provider": [
+        "provider",
+        "root",
+        "host"
+      ]
+    },
+    "tag": "theme-provider",
+    "tokens": {},
+    "traits": [],
+    "version": 1
+  }
+}

package/components/theme-provider/theme-provider.class.js ADDED Viewed

@@ -0,0 +1,134 @@
+/**
+ * Non-side-effect class export for `<theme-provider>`.
+ *
+ * Importing this file gives you the class (and adopts the foundation as a
+ * module-eval side effect) without auto-registering the tag. The auto-register
+ * path is `@adia-ai/web-components/components/theme-provider` (which imports this
+ * file + calls `defineIfFree()`).
+ *
+ * `<theme-provider>` — the foundation-providing wrapper. Adopt the AdiaUI
+ * foundation (design tokens + resets + page-frame + every primitive's CSS) into
+ * the document from anywhere in the DOM, so a surface renders fully-styled
+ * WITHOUT a hand-wired `<link rel="stylesheet">` in `<head>`. Layout-transparent
+ * (`display: contents`): the element owns no box; children lay out as if it
+ * weren't there.
+ *
+ * Mechanism: imports the constructable-stylesheet twin of `web-components.min.css`
+ * — byte-identical to the CDN bundle (emitted from the same buffer by
+ * `scripts/build/bundle-css.mjs`) — and adopts it once into
+ * `document.adoptedStyleSheets`, deduped by sheet identity. Adoption fires at
+ * module evaluation (the earliest point), so importing the element provides the
+ * foundation before the body paints in the common case.
+ *
+ * Coexists with the render-blocking `<link>` path — both deliver the same bytes.
+ * Use a `<link>` (→ the CDN `web-components.min.css`) for multi-page / top-level
+ * surfaces (cacheable across navigations, zero flash); use `<theme-provider>`
+ * for SPA roots, embedded apps, and dynamic mounts where you don't control
+ * `<head>` (e.g. `<embed-shell>`, an A2UI surface, a micro-frontend).
+ *
+ * Scope (v1): the provider supplies the FOUNDATION only — design tokens, resets,
+ * page-frame, and every primitive's CSS. OS light/dark resolves automatically
+ * (the tokens are `light-dark()`-based). Named themes (`[theme]`) and the
+ * `verse` / `prose` context registers live in OPT-IN layers (themes.css /
+ * verse.css / prose.css) that are NOT in the foundation bundle, so setting
+ * `theme` / `verse` on the wrapper does nothing until those layers are also
+ * adopted — a planned `theme=` / `verse` provider option (the token-root selector
+ * is pre-wired for it; see .brain/notes/theme-provider-design-2026-06-04.md).
+ *
+ * Deliberately NOT in the all-in-one `@adia-ai/web-components` barrel — it's
+ * opt-in infra (it carries the whole foundation). Import it explicitly:
+ *   `import '@adia-ai/web-components/components/theme-provider';`
+ *
+ * @see ../../USAGE.md  ·  .brain/notes/theme-provider-design-2026-06-04.md
+ */
+import { UIElement } from '../../core/element.js';
+import constructFoundationSheet from '../../dist/web-components.sheet.js';
+/**
+ * Adopt the foundation sheet into the document exactly once. Idempotent across
+ * any number of `<theme-provider>` instances (dedup by sheet identity). No-ops in
+ * a non-DOM context — `constructFoundationSheet()` returns `null` on SSR/Node.
+ */
+function provideFoundation() {
+  const sheet = constructFoundationSheet();
+  if (!sheet) return;
+  if (!document.adoptedStyleSheets.includes(sheet)) {
+    document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];
+  }
+}
+// Opt-in context registers — themes (named `[theme]` presets), and the `verse` /
+// `prose` `scale` registers. Each is its own constructable-sheet twin (built by
+// scripts/build/bundle-css.mjs, byte-identical to its .min.css). Adopted on demand
+// the first time a provider needs one, deduped by sheet identity. Dynamic-imported
+// (static paths, so bundlers can code-split) so the element stays lean — a provider
+// that does no theming never pulls these in.
+const TWIN_LOADED = { themes: false, verse: false, prose: false };
+function loadTwin(name) {
+  switch (name) {
+    case 'themes': return import('../../dist/themes.sheet.js');
+    case 'verse': return import('../../dist/verse.sheet.js');
+    case 'prose': return import('../../dist/prose.sheet.js');
+    default: return null;
+  }
+}
+function ensureTwin(name) {
+  if (TWIN_LOADED[name]) return;
+  const p = loadTwin(name);
+  if (!p) return;
+  TWIN_LOADED[name] = true;
+  p.then((mod) => {
+    const sheet = mod?.default?.();
+    if (sheet && !document.adoptedStyleSheets.includes(sheet)) {
+      document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];
+    }
+  }).catch(() => { TWIN_LOADED[name] = false; }); // allow a later retry on failure
+}
+// Adopt the base foundation as early as this module evaluates — before any element
+// connects, before the body paints when imported from <head>. Importing the
+// provider IS the act of providing the foundation, wherever the element lands.
+provideFoundation();
+export class UIThemeProvider extends UIElement {
+  static properties = {
+    // Named theme preset (ocean / forest / slate / …). Reflected, so the attribute
+    // — which IS the `[theme="…"]` CSS hook in themes.css — tracks the property.
+    theme: { type: String, reflect: true },
+    // Typographic/density register: "verse" (compact) | "prose" (long-form).
+    // Mapped onto the existing `[verse]` / `[prose]` attribute below (additive —
+    // the register CSS is untouched), so every register rule incl. `[size]`
+    // sub-tiers applies for free.
+    scale: { type: String, reflect: true },
+  };
+  static template = () => null;
+  connected() {
+    // Layout-transparent + invisible to the a11y tree (the template-engine /
+    // traits-host convention). Set imperatively so it holds even in the frame
+    // before the adopted foundation's own `display: contents` rule applies.
+    this.style.display = 'contents';
+    if (!this.hasAttribute('role')) this.setAttribute('role', 'presentation');
+    provideFoundation(); // belt-and-suspenders for late registration
+    this.#applyContext();
+  }
+  updated() {
+    this.#applyContext();
+  }
+  // Adopt the opt-in twins for the current theme/scale, and map `scale` onto the
+  // existing register attribute. Idempotent (safe to call on every update).
+  #applyContext() {
+    // `theme="ocean"` already matches `[theme="ocean"]` (the attr is on the host);
+    // adopt themes.sheet.js so those preset rules exist in the document.
+    if (this.theme) ensureTwin('themes');
+    const scale = this.scale;
+    this.toggleAttribute('verse', scale === 'verse');
+    this.toggleAttribute('prose', scale === 'prose');
+    if (scale === 'verse') ensureTwin('verse');
+    else if (scale === 'prose') ensureTwin('prose');
+  }
+}

package/components/theme-provider/theme-provider.css ADDED Viewed

@@ -0,0 +1,18 @@
+/**
+ * `<theme-provider>` — layout-transparent foundation host.
+ *
+ * The element exists to adopt the AdiaUI foundation into the document (see
+ * theme-provider.class.js); it owns no layout. `display: contents` removes its
+ * box so children lay out as if the wrapper weren't there. The class also sets
+ * this imperatively on connect — belt-and-suspenders for the frame before this
+ * adopted rule applies.
+ *
+ * NOTE: a `>` child combinator from an ancestor does NOT pierce a
+ * `display: contents` wrapper (FB-53) — keep `<theme-provider>` at/near the
+ * mount root, not spliced mid-layout-chain.
+ */
+@scope (theme-provider) {
+  :where(:scope) {
+    display: contents;
+  }
+}

package/components/theme-provider/theme-provider.d.ts ADDED Viewed

@@ -0,0 +1,45 @@
+/**
+ * `<theme-provider>` — Foundation-providing wrapper — adopts the AdiaUI foundation (design tokens +
+resets + page-frame + every primitive's CSS) into the document from anywhere
+in the DOM, so a surface renders fully-styled WITHOUT a hand-wired
+<link rel="stylesheet"> in <head>. Layout-transparent (display: contents): the
+element owns no box; children lay out as if it weren't there.
+Mechanism: it imports the constructable-stylesheet twin of web-components.min.css
+(byte-identical to the CDN bundle, emitted from the same build buffer) and
+adopts it once into document.adoptedStyleSheets, deduped — adoption fires at
+module load, before paint. Coexists with the render-blocking <link> path; both
+deliver the same bytes. Use a <link> (-> the CDN web-components.min.css) for
+multi-page / top-level surfaces (cacheable across navigations, zero flash); use
+<theme-provider> for SPA roots, embedded apps, and dynamic mounts where you do
+not control <head> (e.g. <embed-shell>, an A2UI surface, a micro-frontend).
+Theming: the base foundation is OS light/dark via light-dark() tokens. Two opt-in
+attributes adopt their layer on demand — theme="ocean|forest|slate|…" applies a
+named preset (adopts the themes layer; matches the [theme] hook) and
+scale="verse|prose" sets the compact / long-form typographic register (adopts the
+matching register layer; maps onto the [verse]/[prose] attribute). Each layer is
+fetched only when its attribute is set, so a bare provider stays lean.
+Opt-in infra: NOT in the all-in-one @adia-ai/web-components barrel (it carries
+the whole foundation); import @adia-ai/web-components/components/theme-provider
+explicitly. Distinct from <frame-ui> (a layout skeleton, owns no CSS delivery)
+and the page shells (chrome over the same foundation).
+ *
+ * @see https://ui-kit.exe.xyz/site/components/theme-provider
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+import { UIElement } from '../../core/element.js';
+export class UIThemeProvider extends UIElement {
+  /** Named theme preset for the wrapped subtree (default, ocean, forest, sunset, lavender, rose, slate, midnight). Adopts the themes layer on demand + matches the [theme="…"] hook. */
+  theme: string;
+  /** Typographic / density register for the subtree — "verse" (compact) or "prose" (long-form). Adopts the matching register layer on demand; maps onto the [verse]/[prose] attribute (additive). */
+  scale: string;
+}

package/components/theme-provider/theme-provider.js ADDED Viewed

@@ -0,0 +1,22 @@
+/**
+ * `<theme-provider>` — auto-registers the tag on import, and adopts the AdiaUI
+ * foundation into the document (the side effect lives in the class module).
+ *
+ *   import '@adia-ai/web-components/components/theme-provider';
+ *   <theme-provider> … your app … </theme-provider>
+ *
+ * Opt-in infra: NOT pulled by the `@adia-ai/web-components` barrel (it carries
+ * the full foundation CSS as a constructable sheet). For the class without
+ * auto-registering the tag, import the `class` subpath:
+ *
+ *   import { UIThemeProvider } from '@adia-ai/web-components/components/theme-provider/class';
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+import { defineIfFree } from '../../core/register.js';
+import { UIThemeProvider } from './theme-provider.class.js';
+defineIfFree('theme-provider', UIThemeProvider);
+export { UIThemeProvider };

package/components/theme-provider/theme-provider.test.js ADDED Viewed

@@ -0,0 +1,94 @@
+/**
+ * <theme-provider> tests
+ *
+ * The provider adopts the AdiaUI foundation (a constructable stylesheet) into
+ * `document.adoptedStyleSheets` — once, deduped — and renders `display: contents`
+ * + `role=presentation`. The real foundation sheet (`web-components.sheet.js`,
+ * ~512 KB of LightningCSS output) is mocked here with a 1-rule stub so the test
+ * exercises the ELEMENT's contract (adopt-once, dedup, transparency), not the
+ * bundle's CSS. Byte-parity of the real sheet is covered by `check:css-bundles-fresh`.
+ */
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+// Stub the heavy foundation sheet — same default-export shape as the generated
+// module: a constructSheet() returning a memoized CSSStyleSheet singleton.
+vi.mock('../../dist/web-components.sheet.js', () => {
+  let sheet = null;
+  return {
+    default: () => {
+      if (typeof CSSStyleSheet === 'undefined') return null;
+      if (!sheet) { sheet = new CSSStyleSheet(); sheet.replaceSync('theme-provider{display:contents}'); }
+      return sheet;
+    },
+  };
+});
+// Stub the opt-in twins — the element dynamic-imports these when theme=/scale= is
+// set. We test the attribute contract (sync), not the adopted CSS. (Factories are
+// inlined because vi.mock hoists above any shared `const`.)
+vi.mock('../../dist/themes.sheet.js', () => ({ default: () => { const s = new CSSStyleSheet(); s.replaceSync(':root{}'); return s; } }));
+vi.mock('../../dist/verse.sheet.js', () => ({ default: () => { const s = new CSSStyleSheet(); s.replaceSync(':root{}'); return s; } }));
+vi.mock('../../dist/prose.sheet.js', () => ({ default: () => { const s = new CSSStyleSheet(); s.replaceSync(':root{}'); return s; } }));
+import '../../core/element.js';
+import './theme-provider.js'; // registers the tag + adopts the (mocked) foundation at module-eval
+const tick = () => new Promise((r) => queueMicrotask(r));
+function mount(html) {
+  const wrap = document.createElement('div');
+  wrap.innerHTML = html;
+  document.body.appendChild(wrap);
+  return wrap.firstElementChild;
+}
+describe('<theme-provider>', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+  it('adopts the foundation sheet at import (module-eval side effect)', () => {
+    expect(document.adoptedStyleSheets.length).toBeGreaterThanOrEqual(1);
+  });
+  it('is display:contents + role=presentation on connect', async () => {
+    const el = mount('<theme-provider><span>hi</span></theme-provider>');
+    await tick();
+    expect(el.style.display).toBe('contents');
+    expect(el.getAttribute('role')).toBe('presentation');
+  });
+  it('does not clobber an author-set role', async () => {
+    const el = mount('<theme-provider role="group"><span>hi</span></theme-provider>');
+    await tick();
+    expect(el.getAttribute('role')).toBe('group');
+  });
+  it('dedupes — N instances adopt the foundation exactly once', async () => {
+    const before = document.adoptedStyleSheets.length; // singleton already adopted at import
+    mount('<theme-provider></theme-provider>');
+    mount('<theme-provider></theme-provider>');
+    mount('<theme-provider></theme-provider>');
+    await tick();
+    expect(document.adoptedStyleSheets.length).toBe(before);
+  });
+  it('reflects theme= to the [theme] attribute hook', async () => {
+    const el = mount('<theme-provider theme="ocean"><span>x</span></theme-provider>');
+    await tick();
+    expect(el.getAttribute('theme')).toBe('ocean');
+  });
+  it('scale="verse" maps to the [verse] register attribute', async () => {
+    const el = mount('<theme-provider scale="verse"><span>x</span></theme-provider>');
+    await tick();
+    expect(el.hasAttribute('verse')).toBe(true);
+    expect(el.hasAttribute('prose')).toBe(false);
+  });
+  it('scale="prose" maps to the [prose] register attribute', async () => {
+    const el = mount('<theme-provider scale="prose"><span>x</span></theme-provider>');
+    await tick();
+    expect(el.hasAttribute('prose')).toBe(true);
+    expect(el.hasAttribute('verse')).toBe(false);
+  });
+});