@machfivetechchicago/machvive-webmcp-ai 5.6.0 → 5.7.0

package/README.md

@@ -29,6 +29,8 @@ elements with Shadow DOM that work anywhere `customElements` does.
 | WebMCP analytics | `<machvive-webmcp-analytics>` | Captures every tool call for listing, editing, export, replay, and dataLayer |
 | Lorum Ipsum | `<machvive-lorum-ipsum>` | Placeholder copy that projects slotted content |
 
+<img width="1098" height="894" alt="m5t_machvive_ai_webmcp" src="https://github.com/user-attachments/assets/a1433ff0-f8a9-46fb-ad59-735aed155ff8" />
+
 ## ⚡ Integration with Vite (Vanilla JS)
 
 This package is optimized for modern ESM environments like Vite. You can import individual components or the entire library at once.
@@ -206,6 +208,52 @@ Each call then pushes `{ event: 'webmcp_tool_call', webmcp_tool, webmcp_status,
 webmcp_duration_ms, webmcp_params }`. Without the attribute, push individual entries
 on demand with `callLog.pushToDataLayer(id)` or the per-entry button in the UI.
 
+## 🌓 Theming
+
+The UI components follow the viewer's OS preference automatically — no
+configuration, no flash of the wrong palette. Set `theme` to override:
+
+```html
+<machvive-webmcp-inspect></machvive-webmcp-inspect>              <!-- follows the OS -->
+<machvive-webmcp-analytics theme="dark"></machvive-webmcp-analytics>
+<machvive-webmcp-inspect theme="light"></machvive-webmcp-inspect>
+```
+
+`theme` is also a reflected property, so `el.theme = 'dark'` and
+`el.theme = null` (back to following the OS) work from script.
+
+### Overriding the palette
+
+Colors are CSS custom properties on the host. Custom properties inherit *through*
+shadow boundaries where ordinary styles do not, so you can restyle the components
+from your own stylesheet without `::part` or `!important`:
+
+```css
+machvive-webmcp-inspect,
+machvive-webmcp-analytics {
+  --mv-accent: #7c3aed;
+  --mv-bg: #ffffff;
+  --mv-fg: #111827;
+  --mv-border: #e5e7eb;
+}
+```
+
+Every token has both a light and a dark value; overriding one replaces it in both
+themes unless you scope your override inside your own media query.
+
+| Token | Role |
+| --- | --- |
+| `--mv-fg` / `--mv-muted` / `--mv-faint` | Text: primary, secondary, hints |
+| `--mv-bg` / `--mv-surface` / `--mv-input-bg` | Panel, raised areas, form fields |
+| `--mv-border` / `--mv-border-soft` / `--mv-control-border` | Outlines, dividers, controls |
+| `--mv-hover` / `--mv-selected` | Interactive states |
+| `--mv-accent` / `--mv-accent-fg` | Primary button |
+| `--mv-ok-bg` / `--mv-ok-fg` / `--mv-err-bg` / `--mv-err-fg` | Status badges |
+| `--mv-danger` / `--mv-danger-border` | Destructive actions |
+
+Every combination of OS preference and `theme` is verified to meet WCAG AA
+(≥ 4.5:1) across the full UI. If you override tokens, re-check your own contrast.
+
 ## TypeScript
 
 Declarations ship with the package — no `@types/*` needed. Importing a component

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@machfivetechchicago/machvive-webmcp-ai",
-  "version": "5.6.0",
+  "version": "5.7.0",
   "description": "I don't want to use your product's agent; I want my agent to be able to use your product.",
   "keywords": [
     "WebMCP",

package/src/wc/machvive-lorum-ipsum/machvive-lorum-ipsum.d.ts

@@ -1,5 +1,8 @@
 /** Placeholder-copy element. Projects light DOM through a slot. */
-export class MachviveLorumIpsum extends HTMLElement {}
+export class MachviveLorumIpsum extends HTMLElement {
+  /** Forces a palette regardless of the OS preference. null follows the OS. */
+  theme: 'light' | 'dark' | null;
+}
 
 declare global {
   interface HTMLElementTagNameMap {

package/src/wc/machvive-lorum-ipsum/machvive-lorum-ipsum.js

@@ -4,10 +4,26 @@ export class MachviveLorumIpsum extends HTMLElement {
     this.attachShadow({ mode: 'open' });
   }
 
+
+  /** Forces a palette regardless of the OS preference. null follows the OS. */
+  get theme() {
+    return this.getAttribute('theme');
+  }
+
+  set theme(value) {
+    if (value == null) this.removeAttribute('theme');
+    else this.setAttribute('theme', value);
+  }
+
   connectedCallback() {
     this.shadowRoot.innerHTML = `
       <style>
         :host { display: block; font-family: sans-serif; color: #333; }
+        @media (prefers-color-scheme: dark) {
+          :host(:not([theme="light"])) { color: #e8eaed; }
+        }
+        :host([theme="dark"]) { color: #e8eaed; }
+        :host([theme="light"]) { color: #333; }
       </style>
       <div>
         <slot>Lorem ipsum dolor sit amet...</slot>

package/src/wc/machvive-webmcp-analytics/machvive-webmcp-analytics.d.ts

@@ -68,6 +68,8 @@ export function installAnalytics(log?: CallLog): boolean;
 
 export class MachviveWebmcpAnalytics extends HTMLElement {
   readonly log: CallLog;
+  /** Forces a palette regardless of the OS preference. null follows the OS. */
+  theme: 'light' | 'dark' | null;
 }
 
 declare global {

package/src/wc/machvive-webmcp-analytics/machvive-webmcp-analytics.js

@@ -13,6 +13,7 @@
 // exactly what capturing every call requires — finds no registry to instrument
 // and silently captures nothing.
 import '../machvive-webmcp-polyfill/machvive-webmcp-polyfill.js';
+import { THEME_CSS } from '../shared/theme.js';
 
 export const CALL_EVENT = 'machvive-webmcp-call';
 export const DB_NAME = 'machvive-webmcp';
@@ -368,33 +369,45 @@ export function installAnalytics(log = callLog) {
 }
 
 const STYLES = `
-  :host { display: block; font: 13px/1.5 system-ui, sans-serif; color: #1a1a1a; }
+  ${THEME_CSS}
+
+  /* Painting the background is not optional: this component sets its own text
+     colour per theme, so it cannot rely on inheriting a compatible surface from
+     whatever page embeds it. */
+  :host { display: block; font: 13px/1.5 system-ui, sans-serif;
+          color: var(--mv-fg); background: var(--mv-bg); }
   :host([hidden]) { display: none; }
   .bar { display: flex; gap: 6px; align-items: center; flex-wrap: wrap; margin-bottom: 8px; }
   .count { font-weight: 600; margin-right: auto; }
-  button { font: inherit; padding: 3px 9px; border: 1px solid #ccc; border-radius: 4px;
-           background: #fff; cursor: pointer; }
-  button:hover { background: #f2f2f2; }
-  button.danger { color: #a01; border-color: #d8a0a0; }
-  ol { list-style: none; margin: 0; padding: 0; border: 1px solid #e2e2e2; border-radius: 6px;
-       max-height: 380px; overflow-y: auto; }
-  li { border-bottom: 1px solid #eee; }
+  /* color is required, not decorative: form controls do not inherit it, so
+     without this the UA picks one per theme and white-on-white can result. */
+  button { font: inherit; color: var(--mv-fg); padding: 3px 9px;
+           border: 1px solid var(--mv-control-border); border-radius: 4px;
+           background: var(--mv-bg); cursor: pointer; }
+  button:hover { background: var(--mv-hover); }
+  button.danger { color: var(--mv-danger); border-color: var(--mv-danger-border); }
+  ol { list-style: none; margin: 0; padding: 0; border: 1px solid var(--mv-border);
+       border-radius: 6px; max-height: 380px; overflow-y: auto; background: var(--mv-bg); }
+  li { border-bottom: 1px solid var(--mv-border-soft); }
   li:last-child { border-bottom: 0; }
   .row { display: flex; gap: 8px; align-items: center; padding: 6px 10px; cursor: pointer; }
-  .row:hover { background: #fafafa; }
+  .row:hover { background: var(--mv-hover); }
   .tool { font-family: ui-monospace, monospace; font-weight: 600; }
   .status { font-size: 11px; padding: 1px 6px; border-radius: 10px; }
-  .status.ok { background: #e6f4ea; color: #137333; }
-  .status.error { background: #fce8e6; color: #c5221f; }
-  .ms { color: #777; font-size: 11px; margin-left: auto; }
-  .detail { padding: 8px 10px; background: #fbfbfb; border-top: 1px solid #eee; }
-  .detail label { display: block; font-size: 11px; color: #666; margin: 6px 0 2px; }
+  .status.ok { background: var(--mv-ok-bg); color: var(--mv-ok-fg); }
+  .status.error { background: var(--mv-err-bg); color: var(--mv-err-fg); }
+  .ms { color: var(--mv-muted); font-size: 11px; margin-left: auto; }
+  .detail { padding: 8px 10px; background: var(--mv-surface);
+            border-top: 1px solid var(--mv-border-soft); }
+  .detail label { display: block; font-size: 11px; color: var(--mv-muted); margin: 6px 0 2px; }
   textarea { width: 100%; box-sizing: border-box; font-family: ui-monospace, monospace;
-             font-size: 12px; border: 1px solid #ddd; border-radius: 4px; padding: 5px; }
-  pre { margin: 0; padding: 6px; background: #fff; border: 1px solid #eee; border-radius: 4px;
+             font-size: 12px; color: var(--mv-fg); background: var(--mv-input-bg);
+             border: 1px solid var(--mv-control-border); border-radius: 4px; padding: 5px; }
+  pre { margin: 0; padding: 6px; color: var(--mv-fg); background: var(--mv-bg);
+        border: 1px solid var(--mv-border-soft); border-radius: 4px;
         font-size: 12px; overflow-x: auto; white-space: pre-wrap; word-break: break-word; }
-  .empty { padding: 20px; text-align: center; color: #888; }
-  .err { color: #c5221f; }
+  .empty { padding: 20px; text-align: center; color: var(--mv-faint); }
+  .err { color: var(--mv-err-fg); }
 `;
 
 export class MachviveWebmcpAnalytics extends HTMLElement {
@@ -403,7 +416,7 @@ export class MachviveWebmcpAnalytics extends HTMLElement {
   #onChange = () => this.#render();
 
   static get observedAttributes() {
-    return ['datalayer'];
+    return ['datalayer', 'theme'];
   }
 
   constructor() {
@@ -426,6 +439,17 @@ export class MachviveWebmcpAnalytics extends HTMLElement {
     globalThis.window.removeEventListener(CALL_EVENT, this.#maybeAutoPush);
   }
 
+
+  /** Forces a palette regardless of the OS preference. null follows the OS. */
+  get theme() {
+    return this.getAttribute('theme');
+  }
+
+  set theme(value) {
+    if (value == null) this.removeAttribute('theme');
+    else this.setAttribute('theme', value);
+  }
+
   /** The shared call log, for page code that wants direct access. */
   get log() {
     return this.#log;

package/src/wc/machvive-webmcp-inspect/machvive-webmcp-inspect.d.ts

@@ -2,7 +2,11 @@
  * Lists registered WebMCP tools, builds a form from each tool's inputSchema,
  * and executes it. Inline by default; `floating` docks it as an overlay.
  */
+export type MachviveTheme = 'light' | 'dark' | null;
+
 export class MachviveWebmcpInspect extends HTMLElement {
+  /** Forces a palette regardless of the OS preference. null follows the OS. */
+  theme: MachviveTheme;
   /** Opens the panel (floating mode only). */
   show(): void;
   /** Closes the panel (floating mode only). */

package/src/wc/machvive-webmcp-inspect/machvive-webmcp-inspect.js

@@ -9,6 +9,7 @@
  * invocation (`callTool`) are additions the bare spec does not provide.
  */
 import { TOOLS_CHANGED_EVENT } from '../machvive-webmcp-polyfill/machvive-webmcp-polyfill.js';
+import { THEME_CSS } from '../shared/theme.js';
 
 /** Reads a form control back as the JSON type its schema calls for. */
 function readControl(input, schema = {}) {
@@ -31,58 +32,78 @@ function readControl(input, schema = {}) {
 }
 
 const STYLES = `
-  :host { display: block; font: 13px/1.5 system-ui, sans-serif; color: #1a1a1a; }
+  ${THEME_CSS}
+
+  /* See analytics: a component that themes its own text must paint its own
+     surface rather than assume the embedding page supplies a matching one. */
+  :host { display: block; font: 13px/1.5 system-ui, sans-serif;
+          color: var(--mv-fg); background: var(--mv-bg); }
   :host([hidden]) { display: none; }
 
   /* Floating mode docks the panel without disturbing page layout. */
+  /* Floating mode is a detached panel: the .panel and .fab paint themselves, so
+     the host must stay transparent or it draws a block over the page. */
   :host([floating]) { position: fixed; right: 16px; bottom: 16px; z-index: 2147483000;
-                      display: block; width: auto; }
+                      display: block; width: auto; background: transparent; }
   :host([floating]) .panel { display: none; width: min(420px, calc(100vw - 32px));
                              max-height: min(70vh, 560px); overflow: auto;
-                             box-shadow: 0 8px 28px rgba(0,0,0,.18); background: #fff; }
+                             box-shadow: 0 8px 28px var(--mv-shadow); background: var(--mv-bg); }
   :host([floating][open]) .panel { display: block; }
   :host([floating]) .fab { display: inline-flex; }
   .fab { display: none; align-items: center; gap: 6px; margin-top: 8px; float: right;
-         padding: 7px 13px; border-radius: 999px; border: 1px solid #ccc; background: #fff;
-         cursor: pointer; font: inherit; box-shadow: 0 2px 8px rgba(0,0,0,.14); }
+         padding: 7px 13px; border-radius: 999px; border: 1px solid var(--mv-control-border);
+         background: var(--mv-bg); color: var(--mv-fg); cursor: pointer; font: inherit;
+         box-shadow: 0 2px 8px var(--mv-shadow); }
 
-  .panel { border: 1px solid #e2e2e2; border-radius: 8px; overflow: hidden; }
+  .panel { border: 1px solid var(--mv-border); border-radius: 8px; overflow: hidden;
+           background: var(--mv-bg); }
   header { display: flex; align-items: center; gap: 8px; padding: 7px 10px;
-           background: #fafafa; border-bottom: 1px solid #eee; font-weight: 600; }
+           background: var(--mv-surface); color: var(--mv-fg);
+           border-bottom: 1px solid var(--mv-border-soft); font-weight: 600; }
   header .close { margin-left: auto; border: 0; background: none; cursor: pointer;
-                  font-size: 16px; line-height: 1; color: #666; }
+                  font-size: 16px; line-height: 1; color: var(--mv-muted); }
   :host(:not([floating])) header .close { display: none; }
 
   .body { display: flex; min-height: 150px; }
   @media (max-width: 520px) { .body { flex-direction: column; } }
 
-  .tools { flex: 0 0 150px; border-right: 1px solid #eee; overflow-y: auto; }
-  @media (max-width: 520px) { .tools { flex: none; border-right: 0; border-bottom: 1px solid #eee; } }
+  .tools { flex: 0 1 auto; min-width: 120px; max-width: 200px;
+           border-right: 1px solid var(--mv-border-soft); overflow-y: auto; }
+  @media (max-width: 520px) { .tools { flex: none; max-width: none; border-right: 0;
+                                       border-bottom: 1px solid var(--mv-border-soft); } }
+  /* Tool names are arbitrary identifiers; long ones must wrap inside the column
+     rather than spill over the divider. */
   .tools button { display: block; width: 100%; text-align: left; padding: 6px 10px;
-                  border: 0; background: none; cursor: pointer; font: inherit;
-                  font-family: ui-monospace, monospace; border-bottom: 1px solid #f4f4f4; }
-  .tools button:hover { background: #f6f6f6; }
-  .tools button[aria-current="true"] { background: #e8f0fe; font-weight: 600; }
+                  border: 0; background: none; color: var(--mv-fg); cursor: pointer;
+                  font: inherit; font-family: ui-monospace, monospace; font-size: 12px;
+                  overflow-wrap: anywhere; border-bottom: 1px solid var(--mv-border-soft); }
+  .tools button:hover { background: var(--mv-hover); }
+  .tools button[aria-current="true"] { background: var(--mv-selected); font-weight: 600; }
 
   .form { flex: 1; padding: 10px; min-width: 0; }
-  .desc { color: #666; margin: 0 0 8px; }
+  .desc { color: var(--mv-muted); margin: 0 0 8px; }
   label { display: block; margin-bottom: 7px; }
   .name { font-family: ui-monospace, monospace; font-size: 12px; }
-  .req { color: #c5221f; }
-  .hint { color: #888; font-size: 11px; }
+  .req { color: var(--mv-err-fg); }
+  .hint { color: var(--mv-faint); font-size: 11px; }
+  /* color/background are required, not decorative: form controls do not inherit
+     them, so without these the UA picks per-theme defaults and text can render
+     white on white. */
   input, select, textarea { width: 100%; box-sizing: border-box; font: inherit; font-size: 12px;
-                            padding: 4px 6px; border: 1px solid #ddd; border-radius: 4px; }
+                            color: var(--mv-fg); background: var(--mv-input-bg); padding: 4px 6px;
+                            border: 1px solid var(--mv-control-border); border-radius: 4px; }
   input[type="checkbox"] { width: auto; }
   textarea { font-family: ui-monospace, monospace; }
-  .run { margin-top: 4px; padding: 5px 14px; border: 1px solid #1a73e8; border-radius: 4px;
-         background: #1a73e8; color: #fff; cursor: pointer; font: inherit; }
+  .run { margin-top: 4px; padding: 5px 14px; border: 1px solid var(--mv-accent);
+         border-radius: 4px; background: var(--mv-accent); color: var(--mv-accent-fg);
+         cursor: pointer; font: inherit; }
   .run:disabled { opacity: .6; cursor: default; }
-  pre { margin: 8px 0 0; padding: 7px; background: #fafafa; border: 1px solid #eee;
-        border-radius: 4px; font-size: 12px; white-space: pre-wrap; word-break: break-word;
-        max-height: 180px; overflow: auto; }
-  pre.error { background: #fce8e6; border-color: #f5c6c2; color: #c5221f; }
-  .field-error { color: #c5221f; font-size: 11px; }
-  .empty { padding: 20px; text-align: center; color: #888; }
+  pre { margin: 8px 0 0; padding: 7px; color: var(--mv-fg); background: var(--mv-surface);
+        border: 1px solid var(--mv-border-soft); border-radius: 4px; font-size: 12px;
+        white-space: pre-wrap; word-break: break-word; max-height: 180px; overflow: auto; }
+  pre.error { background: var(--mv-err-bg); border-color: var(--mv-err-border); color: var(--mv-err-fg); }
+  .field-error { color: var(--mv-err-fg); font-size: 11px; }
+  .empty { padding: 20px; text-align: center; color: var(--mv-faint); }
 `;
 
 export class MachviveWebmcpInspect extends HTMLElement {
@@ -91,7 +112,7 @@ export class MachviveWebmcpInspect extends HTMLElement {
   #onToolsChanged = () => this.#render();
 
   static get observedAttributes() {
-    return ['floating', 'open'];
+    return ['floating', 'open', 'theme'];
   }
 
   constructor() {
@@ -113,6 +134,17 @@ export class MachviveWebmcpInspect extends HTMLElement {
     if (this.shadowRoot?.getElementById('root')) this.#render();
   }
 
+
+  /** Forces a palette regardless of the OS preference. null follows the OS. */
+  get theme() {
+    return this.getAttribute('theme');
+  }
+
+  set theme(value) {
+    if (value == null) this.removeAttribute('theme');
+    else this.setAttribute('theme', value);
+  }
+
   /** Opens the panel (floating mode only). */
   show() {
     this.setAttribute('open', '');

package/src/wc/shared/theme.js

@@ -0,0 +1,86 @@
+/**
+ * Shared design tokens for the WebMCP UI components.
+ *
+ * Tokens are plain custom properties on :host, so a consumer can override any of
+ * them from outside the shadow DOM — custom properties inherit through shadow
+ * boundaries where ordinary styles do not.
+ *
+ * Resolution order, matching how a component should behave:
+ *   1. light palette on :host                      (the default)
+ *   2. dark palette when the OS asks for dark      (unless theme="light" opts out)
+ *   3. dark palette when theme="dark"              (explicit, wins over the OS)
+ */
+
+const LIGHT = `
+    --mv-fg: #1a1a1a;
+    --mv-muted: #666;
+    --mv-faint: #6e6e6e;
+    --mv-bg: #fff;
+    --mv-surface: #fafafa;
+    --mv-input-bg: #fff;
+    --mv-border: #e2e2e2;
+    --mv-border-soft: #eee;
+    --mv-control-border: #ccc;
+    --mv-hover: #f2f2f2;
+    --mv-selected: #e8f0fe;
+    --mv-accent: #1565c0;
+    --mv-accent-fg: #fff;
+    --mv-ok-bg: #e6f4ea;
+    --mv-ok-fg: #0f6b2e;
+    --mv-err-bg: #fce8e6;
+    --mv-err-fg: #b3261e;
+    --mv-err-border: #f5c6c2;
+    --mv-danger: #a4161a;
+    --mv-danger-border: #d8a0a0;
+    --mv-shadow: rgba(0, 0, 0, .18);
+`;
+
+const DARK = `
+    --mv-fg: #e8eaed;
+    --mv-muted: #9aa0a6;
+    --mv-faint: #8b9096;
+    --mv-bg: #1f2125;
+    --mv-surface: #282b30;
+    --mv-input-bg: #16181b;
+    --mv-border: #3c4046;
+    --mv-border-soft: #33363b;
+    --mv-control-border: #4a4f56;
+    --mv-hover: #32363c;
+    --mv-selected: #1e3a5f;
+    --mv-accent: #5b9bf8;
+    --mv-accent-fg: #0b1220;
+    --mv-ok-bg: #16351f;
+    --mv-ok-fg: #7ee2a0;
+    --mv-err-bg: #3f1d1c;
+    --mv-err-fg: #ff9d97;
+    --mv-err-border: #5c2c2a;
+    --mv-danger: #ff9d97;
+    --mv-danger-border: #5c2c2a;
+    --mv-shadow: rgba(0, 0, 0, .5);
+`;
+
+/**
+ * CSS declaring both palettes. Prepend to a component's stylesheet.
+ *
+ * `color-scheme: light dark` lets UA-rendered parts (scrollbars, select popups,
+ * checkboxes, focus rings) follow the same theme as the tokens — without it the
+ * browser would paint light controls onto a dark panel.
+ */
+export const THEME_CSS = `
+  :host {
+    color-scheme: light dark;
+${LIGHT}  }
+
+  @media (prefers-color-scheme: dark) {
+    :host(:not([theme="light"])) {
+${DARK}    }
+  }
+
+  /* Explicit choice beats the OS preference, in both directions. */
+  :host([theme="dark"]) {
+${DARK}  }
+
+  :host([theme="light"]) {
+    color-scheme: light;
+${LIGHT}  }
+`;