@adia-ai/web-modules 0.6.18 → 0.6.19

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog — @adia-ai/web-modules
 
+## [0.6.19] — 2026-05-21
+
+### Added — `./shell/with-css` opt-in export (FEEDBACK-25)
+
+- `import '@adia-ai/web-modules/shell/with-css'` registers the JS-backed
+  shell elements (`admin-shell`, `admin-sidebar`, `admin-command`) AND
+  mounts the shell layout CSS in one side-effect import. The default
+  `./shell` subpath stays CSS-free to preserve the explicit-import contract
+  (ADR-0030); `/with-css` is the named opt-in. New `shell/with-css.js` +
+  `shell/with-css.d.ts`.
+
+### Added — `types` condition on CSS subpath exports (FEEDBACK-26)
+
+- The `shell` / `chat` / `editor` / `simple` / `runtime` / `theme` `.css`
+  subpath exports now carry a `types` condition (`css-module.d.ts` stub),
+  fixing TS2882 under `moduleResolution: bundler`.
+
+### Docs — per-cluster import contract (FEEDBACK-25)
+
+- README documents that the per-cluster JS import registers only the
+  JS-backed elements — the CSS-only structural children (`admin-content`,
+  `admin-topbar`, `admin-page`, …) need no JS registration by design — plus
+  the new `/with-css` opt-in.
+
 ## [0.6.18] — 2026-05-21
 
 ### Added — `admin-sidebar` resize-handle diagnostic (FB-17)

package/README.md

@@ -33,6 +33,13 @@ import '@adia-ai/web-modules/theme';             // theme-panel
 import '@adia-ai/web-modules/runtime';           // gen-root + a2ui-root
 ```
 
+> The per-cluster import registers the **JS-backed** elements only. Each
+> cluster also has **CSS-only** structural children (e.g. `admin-content`,
+> `admin-topbar`, `admin-page` — see the [Clusters](#clusters) table) that
+> need no JS registration: they are plain custom elements styled entirely
+> by the cluster CSS. `customElements.get()` returning `undefined` for one
+> of them is expected, not a bug.
+
 ## Import: CSS (since v0.4.5)
 
 > ⚠️ **Required — shell layouts depend on this CSS.** Shell JS modules
@@ -58,6 +65,27 @@ import '@adia-ai/web-modules/runtime/gen-root.css';
 
 > **For pre-v0.4.5 consumers:** if you were importing CSS via the relative `node_modules` path (`'../node_modules/@adia-ai/web-modules/editor/editor-shell/editor-shell.css'`), switch to the package-specifier form above. The relative-path form is fragile under pnpm, Yarn PnP, and npm hoisting; the new package-specifier form works under all three.
 
+## Import: JS + CSS in one line (`/with-css`)
+
+For the `shell` cluster, the `/with-css` opt-in collapses the JS + CSS
+imports into a single side-effect import:
+
+```js
+import '@adia-ai/web-modules/shell/with-css';
+```
+
+This registers the JS-backed shell elements (`admin-shell`,
+`admin-sidebar`, `admin-command`) **and** mounts the shell layout CSS
+(`admin-shell.css` bundles every sub-component style). It is the one-line
+equivalent of `import '@adia-ai/web-modules/shell'` +
+`import '@adia-ai/web-modules/shell/admin-shell.css'`.
+
+The default `@adia-ai/web-modules/shell` subpath stays CSS-free to
+preserve the explicit-import contract ([ADR-0030](../../.brain/adrs/0030-shell-with-css-opt-in-carve-out.md));
+`/with-css` is the named opt-in. Per-element companions
+(`@adia-ai/web-modules/shell/admin-shell/with-css`) also exist for
+finer-grained imports.
+
 Each cluster carries a **shell host** (behavior-only orchestrator) plus
 a **family of bespoke shell-tier children** (cluster-namespaced custom
 elements with state-as-attribute semantics) per [ADR-0023](../../.brain/adrs/0023-bespoke-shell-tier-children.md). The bespoke vocabulary is the only recognized authoring shape since v0.4.0 ([ADR-0024](../../.brain/adrs/0024-legacy-shell-shapes-retired.md)).

package/css-module.d.ts

@@ -0,0 +1,6 @@
+// Ambient declaration so TypeScript (moduleResolution: bundler / node16)
+// can resolve CSS side-effect subpath imports — e.g.
+//   import '@adia-ai/web-components/css';
+// without a TS2882 "no type declarations for side-effect import" error.
+// See FEEDBACK-26.
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/web-modules",
-  "version": "0.6.18",
+  "version": "0.6.19",
   "description": "AdiaUI composite custom elements \u2014 shell, chat, editor, runtime clusters built from @adia-ai/web-components primitives. Subpath exports per cluster.",
   "type": "module",
   "exports": {
@@ -14,6 +14,11 @@
       "import": "./shell/index.js",
       "default": "./shell/index.js"
     },
+    "./shell/with-css": {
+      "types": "./shell/with-css.d.ts",
+      "import": "./shell/with-css.js",
+      "default": "./shell/with-css.js"
+    },
     "./shell/*": {
       "types": "./shell/*/*.d.ts",
       "import": "./shell/*/*.js",
@@ -24,9 +29,18 @@
       "import": "./shell/*/with-css.js",
       "default": "./shell/*/with-css.js"
     },
-    "./shell/*.css": "./shell/*/*.css",
-    "./shell/*/*.css": "./shell/*/*.css",
-    "./shell/*/css/*.css": "./shell/*/css/*.css",
+    "./shell/*.css": {
+      "types": "./css-module.d.ts",
+      "default": "./shell/*/*.css"
+    },
+    "./shell/*/*.css": {
+      "types": "./css-module.d.ts",
+      "default": "./shell/*/*.css"
+    },
+    "./shell/*/css/*.css": {
+      "types": "./css-module.d.ts",
+      "default": "./shell/*/css/*.css"
+    },
     "./chat": {
       "types": "./chat/index.d.ts",
       "import": "./chat/index.js",
@@ -42,9 +56,18 @@
       "import": "./chat/*/with-css.js",
       "default": "./chat/*/with-css.js"
     },
-    "./chat/*.css": "./chat/*/*.css",
-    "./chat/*/*.css": "./chat/*/*.css",
-    "./chat/*/css/*.css": "./chat/*/css/*.css",
+    "./chat/*.css": {
+      "types": "./css-module.d.ts",
+      "default": "./chat/*/*.css"
+    },
+    "./chat/*/*.css": {
+      "types": "./css-module.d.ts",
+      "default": "./chat/*/*.css"
+    },
+    "./chat/*/css/*.css": {
+      "types": "./css-module.d.ts",
+      "default": "./chat/*/css/*.css"
+    },
     "./editor": {
       "types": "./editor/index.d.ts",
       "import": "./editor/index.js",
@@ -65,9 +88,18 @@
       "import": "./editor/*/with-css.js",
       "default": "./editor/*/with-css.js"
     },
-    "./editor/*.css": "./editor/*/*.css",
-    "./editor/*/*.css": "./editor/*/*.css",
-    "./editor/*/css/*.css": "./editor/*/css/*.css",
+    "./editor/*.css": {
+      "types": "./css-module.d.ts",
+      "default": "./editor/*/*.css"
+    },
+    "./editor/*/*.css": {
+      "types": "./css-module.d.ts",
+      "default": "./editor/*/*.css"
+    },
+    "./editor/*/css/*.css": {
+      "types": "./css-module.d.ts",
+      "default": "./editor/*/css/*.css"
+    },
     "./simple": {
       "types": "./simple/index.d.ts",
       "import": "./simple/index.js",
@@ -83,9 +115,18 @@
       "import": "./simple/*/with-css.js",
       "default": "./simple/*/with-css.js"
     },
-    "./simple/*.css": "./simple/*/*.css",
-    "./simple/*/*.css": "./simple/*/*.css",
-    "./simple/*/css/*.css": "./simple/*/css/*.css",
+    "./simple/*.css": {
+      "types": "./css-module.d.ts",
+      "default": "./simple/*/*.css"
+    },
+    "./simple/*/*.css": {
+      "types": "./css-module.d.ts",
+      "default": "./simple/*/*.css"
+    },
+    "./simple/*/css/*.css": {
+      "types": "./css-module.d.ts",
+      "default": "./simple/*/css/*.css"
+    },
     "./runtime": {
       "types": "./runtime/index.d.ts",
       "import": "./runtime/index.js",
@@ -96,9 +137,18 @@
       "import": "./runtime/*/*.js",
       "default": "./runtime/*/*.js"
     },
-    "./runtime/*.css": "./runtime/*/*.css",
-    "./runtime/*/*.css": "./runtime/*/*.css",
-    "./runtime/*/css/*.css": "./runtime/*/css/*.css",
+    "./runtime/*.css": {
+      "types": "./css-module.d.ts",
+      "default": "./runtime/*/*.css"
+    },
+    "./runtime/*/*.css": {
+      "types": "./css-module.d.ts",
+      "default": "./runtime/*/*.css"
+    },
+    "./runtime/*/css/*.css": {
+      "types": "./css-module.d.ts",
+      "default": "./runtime/*/css/*.css"
+    },
     "./theme": {
       "types": "./theme/index.d.ts",
       "import": "./theme/index.js",
@@ -109,9 +159,18 @@
       "import": "./theme/*/*.js",
       "default": "./theme/*/*.js"
     },
-    "./theme/*.css": "./theme/*/*.css",
-    "./theme/*/*.css": "./theme/*/*.css",
-    "./theme/*/css/*.css": "./theme/*/css/*.css",
+    "./theme/*.css": {
+      "types": "./css-module.d.ts",
+      "default": "./theme/*/*.css"
+    },
+    "./theme/*/*.css": {
+      "types": "./css-module.d.ts",
+      "default": "./theme/*/*.css"
+    },
+    "./theme/*/css/*.css": {
+      "types": "./css-module.d.ts",
+      "default": "./theme/*/css/*.css"
+    },
     "./generative": {
       "types": "./generative/index.d.ts",
       "import": "./generative/index.js",
@@ -149,6 +208,7 @@
     "!generative/**/*.examples.js",
     "!generative/**/*.html",
     "index.js",
+    "css-module.d.ts",
     "README.md",
     "CHANGELOG.md"
   ],

package/shell/with-css.d.ts

@@ -0,0 +1,3 @@
+// Opt-in `/with-css` companion for the shell cluster (FEEDBACK-25).
+// Side-effect-only module — no type surface.
+export {};

package/shell/with-css.js

@@ -0,0 +1,21 @@
+/**
+ * Opt-in `/with-css` companion for the whole shell cluster.
+ *
+ * Side-effect-only module. Importing this:
+ *   1. Loads `./index.js` — registers the JS-backed shell vocabulary
+ *      (admin-shell, admin-sidebar, admin-command)
+ *   2. Side-effect-imports `./admin-shell/admin-shell.css` — the shell
+ *      layout CSS. One file bundles every sub-component style (topbar,
+ *      content, page, scroll, statusbar), so the CSS-only shell elements
+ *      (admin-topbar, admin-content, admin-page, admin-page-header,
+ *      admin-page-body, admin-scroll) are styled by it too.
+ *
+ * Consumer-facing entry point:
+ *   import '@adia-ai/web-modules/shell/with-css';
+ *
+ * The default `@adia-ai/web-modules/shell` subpath preserves the
+ * explicit-import CSS contract (ADR-0030); this `/with-css` companion is
+ * the named opt-in for a one-line working shell. See FEEDBACK-25.
+ */
+import './index.js';
+import './admin-shell/admin-shell.css';