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

@adia-ai/web-components 0.7.11 → 0.7.12

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 (42) hide show

package/CHANGELOG.md +17 -1
package/README.md +2 -2
package/USAGE.md +2 -2
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 +5 -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/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,21 @@
 # Changelog — @adia-ai/web-components
+## [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
@@ -3042,7 +3058,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:

package/README.md CHANGED Viewed

@@ -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/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);
+  });
+});

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

@@ -0,0 +1,96 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UIThemeProvider
+tag: theme-provider
+status: experimental
+component: ThemeProvider
+category: layout
+version: 1
+description: |
+  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).
+props:
+  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: ""
+    reflect: true
+  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: ""
+    reflect: true
+events: {}
+slots: {}
+states:
+  - name: idle
+    description: Default — foundation adopted into the document; children rendered.
+traits: []
+tokens: {}
+a2ui:
+  rules:
+    - rule: 'Wrap a client-mounted surface root (SPA shell, embedded app, dynamic mount) in <theme-provider> so it self-provides the AdiaUI foundation — no <head> stylesheet link required.'
+      reason: 'Adopts the foundation bundle into the document from anywhere in the tree (document.adoptedStyleSheets).'
+    - rule: 'For multi-page / top-level pages, prefer a render-blocking <link rel="stylesheet" href=".../web-components.min.css"> in <head> instead — cacheable across navigations, styled on the first frame. <theme-provider> and the link deliver byte-identical CSS, so they coexist.'
+      reason: 'Link for multi-page (no flash); provider for SPA/embedded (no head access).'
+    - rule: 'Theme the wrapped subtree with theme="ocean" (a named preset) and/or scale="verse|prose" (compact / long-form register) — the provider adopts the matching opt-in layer on demand. The base foundation is OS light/dark automatically. Keep <theme-provider> at/near the mount root — display:contents means an ancestor "> " child selector will not reach its children.'
+      reason: 'theme/scale each fetch + adopt their layer (themes.css / verse.css / prose.css) on demand; display:contents preserves custom-property inheritance but not child-combinator reach (Light DOM, ADR-0033).'
+anti_patterns: []
+examples:
+  - name: spa-root
+    description: A client-mounted app root that self-provides the foundation (no head link).
+    a2ui: >-
+      [
+        { "id": "root", "component": "ThemeProvider", "children": ["panel"] },
+        { "id": "panel", "component": "Frame", "children": ["body", "actions"] },
+        { "id": "body", "component": "Section", "children": ["copy"] },
+        { "id": "copy", "component": "Text", "variant": "body", "textContent": "Fully styled — no <head> stylesheet link." },
+        { "id": "actions", "component": "Footer", "children": ["go"] },
+        { "id": "go", "component": "Button", "text": "Continue", "variant": "primary" }
+      ]
+keywords:
+  - style
+  - provider
+  - foundation
+  - tokens
+  - reset
+  - adopt
+  - stylesheet
+  - shell
+  - embed
+  - spa
+synonyms:
+  provider:
+    - provider
+    - root
+    - host
+  foundation:
+    - foundation
+    - tokens
+    - styles
+related:
+  - Frame
+  - Card