@sorb/leaf 0.2.1 → 0.4.0

package/dist/index.js

@@ -27,18 +27,40 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.js
-var src_exports = {};
-__export(src_exports, {
+var src_exports2 = {};
+__export(src_exports2, {
+  MODE_STYLESHEET_ID: () => MODE_STYLESHEET_ID,
   PreviewBanner: () => PreviewBanner,
   SorbProvider: () => SorbProvider,
+  ThemeToggle: () => ThemeToggle,
+  angularMaterialTarget: () => angularMaterialTarget,
+  applyLegacyMap: () => applyLegacyMap,
+  buildModeStylesheet: () => buildModeStylesheet,
+  clearLegacyMap: () => clearLegacyMap,
+  clearModeStylesheet: () => clearModeStylesheet,
+  computeLegacyOverride: () => computeLegacyOverride,
+  dataThemeDarkMode: () => dataThemeDarkMode,
+  indexLegacyMap: () => indexLegacyMap,
+  injectModeStylesheet: () => injectModeStylesheet,
+  mantineTarget: () => mantineTarget,
+  muiTarget: () => muiTarget,
+  normalizeProp: () => normalizeProp,
+  normalizeValue: () => normalizeValue,
+  primevueTarget: () => primevueTarget,
+  reactBootstrapTarget: () => reactBootstrapTarget,
   sanitizeCssValue: () => sanitizeCssValue,
+  shadcnTarget: () => shadcnTarget,
+  sorbInit: () => sorbInit,
+  tailwindDarkMode: () => tailwindDarkMode,
+  tailwindV4Target: () => tailwindV4Target,
   useIsPreview: () => useIsPreview,
   usePreviewState: () => usePreviewState,
+  useTheme: () => useTheme,
   useToken: () => useToken,
   useTokens: () => useTokens,
   verifyResolved: () => verifyResolved
 });
-module.exports = __toCommonJS(src_exports);
+module.exports = __toCommonJS(src_exports2);
 
 // src/TokenProvider.jsx
 var import_react2 = __toESM(require("react"));
@@ -134,6 +156,170 @@ var applyTokens = (tokens) => {
     root.style.setProperty(`--${key}`, result.value);
   });
 };
+var clearTokenOverrides = (tokens) => {
+  const root = document.documentElement;
+  Object.keys(tokens).forEach((key) => {
+    root.style.removeProperty(`--${key}`);
+  });
+};
+var MODE_STYLESHEET_ID = "sorb-tokens";
+var injectModeStylesheet = (css) => {
+  let tag = document.getElementById(MODE_STYLESHEET_ID);
+  if (!tag) {
+    tag = document.createElement("style");
+    tag.id = MODE_STYLESHEET_ID;
+    document.head.appendChild(tag);
+  }
+  tag.textContent = css;
+};
+var clearModeStylesheet = () => {
+  const tag = document.getElementById(MODE_STYLESHEET_ID);
+  if (tag && tag.parentNode) tag.parentNode.removeChild(tag);
+};
+
+// src/modeStylesheet.js
+var buildModeStylesheet = (lightVars, darkVars, darkMode) => {
+  const lightDecls = normalizeDecls(lightVars);
+  const hasDark = !!darkMode && !!darkVars && Object.keys(darkVars).length > 0;
+  if (!hasDark) {
+    return `:root {
+${indent(lightDecls)}
+}
+`;
+  }
+  const darkDecls = normalizeDecls(darkVars);
+  const darkSelector = darkMode.darkSelector;
+  const lightSelector = darkMode.lightSelector;
+  const mediaScopeSelector = lightSelector ? `:root:not(${lightSelector})` : ":root";
+  const lines = [];
+  lines.push(":root {");
+  lines.push(indent([...lightDecls, "color-scheme: light;"]));
+  lines.push("}");
+  lines.push("@media (prefers-color-scheme: dark) {");
+  lines.push(`  ${mediaScopeSelector} {`);
+  lines.push(indent([...darkDecls, "color-scheme: dark;"], 2));
+  lines.push("  }");
+  lines.push("}");
+  lines.push(`${darkSelector} {`);
+  lines.push(indent([...darkDecls, "color-scheme: dark;"]));
+  lines.push("}");
+  if (lightSelector) {
+    lines.push(`${lightSelector} {`);
+    lines.push(indent([...lightDecls, "color-scheme: light;"]));
+    lines.push("}");
+  }
+  return `${lines.join("\n")}
+`;
+};
+var normalizeDecls = (vars) => {
+  if (!vars) return [];
+  return Object.entries(vars).reduce((acc, [key, value]) => {
+    const result = sanitizeCssValue(String(value));
+    if (!result.ok) return acc;
+    const cssVar = key.startsWith("--") ? key : `--${key}`;
+    acc.push(`${cssVar}: ${result.value};`);
+    return acc;
+  }, []);
+};
+var indent = (lines, level = 1) => {
+  const pad = "  ".repeat(level);
+  return lines.map((l) => `${pad}${l}`).join("\n");
+};
+
+// node_modules/@sorb/core/src/index.js
+var TIERS = Object.freeze(["component", "semantic", "primitive"]);
+var TIER_RANK = Object.freeze({ component: 0, semantic: 1, primitive: 2 });
+var DEFAULT_ROLE_IDS = Object.freeze({
+  color: Object.freeze([
+    "color.surface",
+    "color.surface-raised",
+    "color.surface-sunken",
+    "color.ink",
+    "color.ink-muted",
+    "color.ink-on-brand",
+    "color.brand",
+    "color.brand-hover",
+    "color.brand-contrast",
+    "color.accent",
+    "color.accent-hover",
+    "color.accent-contrast",
+    "color.danger",
+    "color.danger-hover",
+    "color.success",
+    "color.success-hover",
+    "color.focus-ring",
+    "color.border",
+    "color.border-subtle",
+    "color.border-strong"
+  ]),
+  radius: Object.freeze(["radius.control", "radius.card", "radius.pill"]),
+  shadow: Object.freeze(["shadow.raised", "shadow.overlay"]),
+  typography: Object.freeze([
+    "typography.display.fontSize",
+    "typography.display.fontWeight",
+    "typography.display.lineHeight",
+    "typography.heading.fontSize",
+    "typography.heading.fontWeight",
+    "typography.heading.lineHeight",
+    "typography.body.fontSize",
+    "typography.body.fontWeight",
+    "typography.body.lineHeight",
+    "typography.caption.fontSize",
+    "typography.caption.fontWeight",
+    "typography.caption.lineHeight"
+  ])
+});
+var ALL_ROLE_IDS = Object.freeze([
+  ...DEFAULT_ROLE_IDS.color,
+  ...DEFAULT_ROLE_IDS.radius,
+  ...DEFAULT_ROLE_IDS.shadow,
+  ...DEFAULT_ROLE_IDS.typography
+]);
+var connectors = Object.freeze({
+  source: /* @__PURE__ */ new Map(),
+  codeSource: /* @__PURE__ */ new Map(),
+  target: /* @__PURE__ */ new Map()
+});
+function registerTarget(adapter) {
+  if (!adapter || typeof adapter.id !== "string" || !adapter.id) {
+    throw new Error("registerTarget: adapter.id must be a non-empty string");
+  }
+  if (typeof adapter.emitFormat !== "string" || !adapter.emitFormat) {
+    throw new Error(`registerTarget(${JSON.stringify(adapter.id)}): emitFormat must be a non-empty string`);
+  }
+  if (!Array.isArray(adapter.expectPrefixes)) {
+    throw new Error(`registerTarget(${JSON.stringify(adapter.id)}): expectPrefixes must be an array`);
+  }
+  if (connectors.target.has(adapter.id)) {
+    console.warn(`registerTarget: overwriting existing target adapter ${JSON.stringify(adapter.id)}`);
+  }
+  connectors.target.set(adapter.id, adapter);
+  return adapter;
+}
+
+// src/targets/reactBootstrap.js
+var SORB_TOKENSET_FORMAT_ID = "sorb/tokenset-esm";
+var reactBootstrapTarget = {
+  id: "react-bootstrap",
+  emitFormat: SORB_TOKENSET_FORMAT_ID,
+  // The Bootstrap-styled vocab namespace (matches `sorb-demo/src/sorbConfig.js`'s
+  // `preview.expectPrefixes: ['bs-']`).
+  expectPrefixes: ["bs-"],
+  // Left undefined on purpose — see file header.
+  inject: void 0,
+  // Bootstrap 5.3's native dark-mode convention (real-dark-mode spec D1): a
+  // `data-bs-theme` attribute on any ancestor (Bootstrap recommends
+  // `<html>`) selects the mode; absent ⇒ OS `prefers-color-scheme` governs.
+  darkMode: {
+    strategy: "attribute",
+    attribute: "data-bs-theme",
+    darkSelector: '[data-bs-theme="dark"]',
+    lightSelector: '[data-bs-theme="light"]'
+  }
+};
+if (typeof registerTarget === "function") {
+  registerTarget(reactBootstrapTarget);
+}
 
 // src/previewGuard.js
 var DEFAULT_ORIGIN = "http://localhost:7777";
@@ -176,6 +362,26 @@ var shouldLoadPreview = (config) => {
   return { allowed: false, origin, reason: "origin-not-allowlisted" };
 };
 
+// src/previewVocab.js
+var countMatchingPrefixes = (tokens, prefixes) => {
+  const list = Array.isArray(prefixes) ? prefixes : [];
+  return Object.keys(tokens || {}).filter((key) => list.some((p) => key.startsWith(p))).length;
+};
+var checkPreviewVocabulary = ({ tokens, expectPrefixes, previewId }) => {
+  if (!Array.isArray(expectPrefixes) || expectPrefixes.length === 0) return false;
+  const appliedCount = Object.keys(tokens || {}).length;
+  if (appliedCount === 0) return false;
+  const matched = countMatchingPrefixes(tokens, expectPrefixes);
+  if (matched > 0) return false;
+  try {
+    console.warn(
+      `[Sorb] preview ${previewId ? `"${previewId}" ` : ""}applied ${appliedCount} tokens but none match expected prefixes ${JSON.stringify(expectPrefixes)} \u2014 the app may not visibly re-skin (token-vocabulary mismatch).`
+    );
+  } catch (e) {
+  }
+  return true;
+};
+
 // src/bridgeAuth.js
 var bridgeHeaders = (key, base) => {
   const headers = base ? { ...base } : {};
@@ -185,8 +391,163 @@ var bridgeHeaders = (key, base) => {
   return headers;
 };
 
-// src/TokenProvider.jsx
-var import_jsx_runtime = require("react/jsx-runtime");
+// src/connection.js
+var DEFAULT_CLOUD_BASE = "https://api.sorbcloud.com";
+var getOrgKey = (config) => {
+  if (!config) return null;
+  const key = config.orgKey || config.publishableKey;
+  return typeof key === "string" && key.trim() !== "" ? key.trim() : null;
+};
+var shouldResolveOrgConnection = (config) => {
+  const key = getOrgKey(config);
+  if (!key) return false;
+  const explicitOrigin = config && config.preview && config.preview.origin;
+  return !(typeof explicitOrigin === "string" && explicitOrigin.trim() !== "");
+};
+var resolveOrgConnection = async (orgKey, opts) => {
+  const { cloudBase = DEFAULT_CLOUD_BASE, fetchImpl } = opts || {};
+  const doFetch = fetchImpl || (typeof fetch !== "undefined" ? fetch : null);
+  if (!doFetch || typeof orgKey !== "string" || orgKey.trim() === "") return null;
+  try {
+    const base = cloudBase.replace(/\/$/, "");
+    const url = `${base}/api/orgs/resolve?key=${encodeURIComponent(orgKey.trim())}`;
+    const res = await doFetch(url);
+    if (!res || !res.ok) return null;
+    const data = await res.json();
+    if (!data || typeof data !== "object") return null;
+    if (typeof data.bridgeUrl !== "string" || data.bridgeUrl.trim() === "") return null;
+    const bridgeMode = typeof data.bridgeMode === "string" ? data.bridgeMode : "C";
+    return {
+      bridgeMode,
+      bridgeUrl: data.bridgeUrl,
+      orgId: typeof data.orgId === "string" ? data.orgId : null,
+      tokenSource: typeof data.tokenSource === "string" ? data.tokenSource : null,
+      // sorb-cloud's /api/orgs/resolve returns this as a boolean (entitlement
+      // flag), not an object — see cloud src/lib/orgResolve.ts.
+      previewPersistence: typeof data.previewPersistence === "boolean" ? data.previewPersistence : null,
+      transport: data.transport === "poll" || data.transport === "sse" ? data.transport : bridgeMode === "A" ? "sse" : "poll"
+    };
+  } catch (e) {
+    return null;
+  }
+};
+var buildEffectivePreviewConfig = (config, resolved) => {
+  const base = config && config.preview || {};
+  if (!resolved) return base;
+  const orgKey = getOrgKey(config);
+  return {
+    ...base,
+    enabled: true,
+    origin: resolved.bridgeUrl,
+    allowedOrigins: [...Array.isArray(base.allowedOrigins) ? base.allowedOrigins : [], resolved.bridgeUrl],
+    key: base.key || orgKey || void 0
+  };
+};
+var buildEffectiveConfig = (config, resolved) => {
+  if (!resolved) return config;
+  return { ...config, preview: buildEffectivePreviewConfig(config, resolved) };
+};
+
+// src/sse.js
+var buildSubscribeUrl = (bridgeUrl, orgId, previewId, key) => {
+  const base = String(bridgeUrl).replace(/\/$/, "");
+  const path = `${base}/orgs/${encodeURIComponent(orgId)}/preview/${encodeURIComponent(previewId)}/subscribe`;
+  if (typeof key === "string" && key.trim() !== "") {
+    return `${path}?key=${encodeURIComponent(key.trim())}`;
+  }
+  return path;
+};
+var parsePreviewFrame = (raw) => {
+  let frame;
+  try {
+    frame = JSON.parse(raw);
+  } catch (e) {
+    return null;
+  }
+  if (!frame || typeof frame !== "object") return null;
+  if (frame.type === "ping") return { type: "ping" };
+  if (frame.type === "delete") return { type: "delete", tokens: null };
+  if ((frame.type === "snapshot" || frame.type === "update") && frame.tokens && typeof frame.tokens === "object") {
+    return { type: frame.type, tokens: frame.tokens };
+  }
+  return null;
+};
+var createPreviewSubscription = ({ EventSourceImpl, url, onTokens, onDelete, onError }) => {
+  if (typeof EventSourceImpl !== "function") return null;
+  const es = new EventSourceImpl(url);
+  es.onmessage = (evt) => {
+    const parsed = parsePreviewFrame(evt && evt.data);
+    if (!parsed || parsed.type === "ping") return;
+    if (parsed.type === "delete") {
+      if (onDelete) onDelete();
+      return;
+    }
+    onTokens(parsed.tokens);
+  };
+  const handleError = (evt) => {
+    if (onError) onError(evt);
+  };
+  if (typeof es.addEventListener === "function") {
+    es.addEventListener("error", handleError);
+  } else {
+    es.onerror = handleError;
+  }
+  return () => {
+    try {
+      es.close();
+    } catch (e) {
+    }
+  };
+};
+
+// src/previewMode.js
+var isModeAwarePreviewBody = (body) => !!body && typeof body === "object" && !Array.isArray(body) && "tokens" in body;
+var resolvePreviewBody = (body, fallbackDarkMode) => {
+  if (!isModeAwarePreviewBody(body)) {
+    return { kind: "flat", tokens: (
+      /** @type {import('./types').TokenSet} */
+      body
+    ) };
+  }
+  const wrapper = (
+    /** @type {{ tokens: import('./types').TokenSet, darkTokens?: import('./types').TokenSet, darkMode?: import('@sorb/core').DarkModeConvention }} */
+    body
+  );
+  const darkTokens = wrapper.darkTokens;
+  if (darkTokens && Object.keys(darkTokens).length > 0) {
+    return {
+      kind: "mode-aware",
+      lightTokens: wrapper.tokens,
+      darkTokens,
+      darkMode: wrapper.darkMode ?? fallbackDarkMode
+    };
+  }
+  return { kind: "flat", tokens: wrapper.tokens };
+};
+
+// src/modeAction.js
+var darkClassName = (darkModeConvention) => {
+  const selector = String(darkModeConvention?.darkSelector || "").trim();
+  const match = /^\.([a-zA-Z0-9_-]+)$/.exec(selector);
+  return match ? match[1] : "dark";
+};
+var resolveModeAction = (darkModeConvention, next) => {
+  const strategy = darkModeConvention?.strategy || "attribute";
+  if (strategy === "media") {
+    return { type: "none" };
+  }
+  if (strategy === "class") {
+    const className = darkClassName(darkModeConvention);
+    return next === "dark" ? { type: "class-add", className } : { type: "class-remove", className };
+  }
+  const attribute = darkModeConvention?.attribute || "data-bs-theme";
+  return next === "auto" ? { type: "attr-remove", attribute } : { type: "attr-set", attribute, value: next };
+};
+
+// src/core.js
+var EventSourceCtor = typeof EventSource !== "undefined" ? EventSource : null;
+var matchMediaFn = typeof matchMedia !== "undefined" ? matchMedia : null;
+var DARK_MEDIA_QUERY = "(prefers-color-scheme: dark)";
 var devWarn = (msg) => {
   try {
     if (typeof process !== "undefined" && process.env && true) {
@@ -195,54 +556,187 @@ var devWarn = (msg) => {
   } catch (e) {
   }
 };
-var SorbProvider = ({ config, children }) => {
-  const [activeTokens, setActiveTokens] = (0, import_react2.useState)(config.tokens);
-  const [isPreview, setIsPreview] = (0, import_react2.useState)(false);
-  const [previewId, setPreviewId] = (0, import_react2.useState)(null);
-  const pollRef = (0, import_react2.useRef)(null);
-  const loadCommitted = (0, import_react2.useCallback)(() => {
-    applyTokens(config.tokens);
-    setActiveTokens(config.tokens);
-    setIsPreview(false);
-    setPreviewId(null);
-  }, [config.tokens]);
-  const loadPreview = (0, import_react2.useCallback)(
-    async (id) => {
-      const guard = shouldLoadPreview(config);
-      if (!guard.allowed) {
-        loadCommitted();
-        return false;
-      }
-      const origin = guard.origin;
-      try {
-        const res = await fetch(`${origin}/preview/${id}`, {
-          headers: bridgeHeaders(config.preview?.key)
-        });
-        if (!res.ok) throw new Error("preview not found");
-        const tokens = await res.json();
-        applyTokens(tokens);
-        setActiveTokens(tokens);
-        setIsPreview(true);
-        setPreviewId(id);
-        return true;
-      } catch (e) {
-        loadCommitted();
-        return false;
-      }
-    },
-    [config, loadCommitted]
-  );
-  const clearPreview = (0, import_react2.useCallback)(() => {
-    if (pollRef.current) clearInterval(pollRef.current);
-    const params = new URLSearchParams(location.search);
-    params.delete("preview");
-    const qs = params.toString();
-    history.replaceState(null, "", qs ? `?${qs}` : location.pathname);
+var warnedDeprecations = /* @__PURE__ */ new Set();
+function warnDeprecated(resolved) {
+  if (typeof process !== "undefined" && false) return;
+  for (let i = 0; i < resolved.length; i++) {
+    const token = resolved[i];
+    if (!token.deprecated) continue;
+    if (warnedDeprecations.has(token.id)) continue;
+    warnedDeprecations.add(token.id);
+    const replacedBy = token.replacedBy || token.$extensions && token.$extensions.sorb && token.$extensions.sorb.replacedBy || null;
+    if (replacedBy) {
+      console.warn("[@sorb/leaf] Deprecated token: " + token.id + " \u2014 use " + replacedBy + " instead");
+    } else {
+      console.warn("[@sorb/leaf] Deprecated token: " + token.id + " is deprecated");
+    }
+  }
+}
+function sorbInit(config) {
+  let activeTokens = config.tokens;
+  let isPreview = false;
+  let previewId = null;
+  let previewMismatch = false;
+  let pollId = null;
+  let cancelled = false;
+  let unsubscribeSSE = null;
+  const hasDarkMode = !!(config.darkTokens && Object.keys(config.darkTokens).length > 0);
+  const darkModeConvention = config.darkModeConvention || reactBootstrapTarget.darkMode;
+  let mode = "auto";
+  let systemScheme = matchMediaFn ? matchMediaFn(DARK_MEDIA_QUERY).matches ? "dark" : "light" : "light";
+  const listeners = /* @__PURE__ */ new Set();
+  const getState = () => ({
+    tokens: activeTokens,
+    isPreview,
+    previewId,
+    previewMismatch,
+    mode,
+    resolvedScheme: mode === "auto" ? systemScheme : mode
+  });
+  const notify = () => {
+    const state = getState();
+    listeners.forEach((listener) => listener(state));
+  };
+  const subscribe = (listener) => {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+  };
+  let mql = null;
+  const onSchemeChange = (e) => {
+    systemScheme = e.matches ? "dark" : "light";
+    notify();
+  };
+  if (matchMediaFn) {
+    mql = matchMediaFn(DARK_MEDIA_QUERY);
+    if (typeof mql.addEventListener === "function") mql.addEventListener("change", onSchemeChange);
+    else if (typeof mql.addListener === "function") mql.addListener(onSchemeChange);
+  }
+  let inlineTokens = null;
+  const applyFlat = (tokens) => {
+    clearModeStylesheet();
+    applyTokens(tokens);
+    inlineTokens = tokens;
+  };
+  const applyModeAware = (lightTokens, darkTokens, convention) => {
+    if (inlineTokens) {
+      clearTokenOverrides(inlineTokens);
+      inlineTokens = null;
+    }
+    injectModeStylesheet(buildModeStylesheet(lightTokens, darkTokens, convention));
+  };
+  const loadCommitted = () => {
+    if (hasDarkMode) {
+      applyModeAware(config.tokens, config.darkTokens, darkModeConvention);
+    } else {
+      applyFlat(config.tokens);
+    }
+    activeTokens = config.tokens;
+    isPreview = false;
+    previewId = null;
+    previewMismatch = false;
+    notify();
+  };
+  const applyPreviewTokens = (body, id, effectiveConfig) => {
+    const resolved = resolvePreviewBody(body, darkModeConvention);
+    let flatTokens;
+    if (resolved.kind === "mode-aware") {
+      applyModeAware(resolved.lightTokens, resolved.darkTokens, resolved.darkMode);
+      flatTokens = resolved.lightTokens;
+    } else {
+      applyFlat(resolved.tokens);
+      flatTokens = resolved.tokens;
+    }
+    activeTokens = flatTokens;
+    isPreview = true;
+    previewId = id;
+    previewMismatch = checkPreviewVocabulary({
+      tokens: flatTokens,
+      expectPrefixes: effectiveConfig.preview?.expectPrefixes,
+      previewId: id
+    });
+    notify();
+  };
+  const loadPreview = async (id, effectiveConfig) => {
+    const cfg = effectiveConfig || config;
+    const guard = shouldLoadPreview(cfg);
+    if (!guard.allowed) {
+      loadCommitted();
+      return false;
+    }
+    const origin = guard.origin;
+    try {
+      const res = await fetch(`${origin}/preview/${id}`, {
+        headers: bridgeHeaders(cfg.preview?.key)
+      });
+      if (!res.ok) throw new Error("preview not found");
+      const tokens = await res.json();
+      applyPreviewTokens(tokens, id, cfg);
+      return true;
+    } catch (e) {
+      loadCommitted();
+      return false;
+    }
+  };
+  const clearPreview = () => {
+    if (pollId) {
+      clearInterval(pollId);
+      pollId = null;
+    }
+    if (typeof location !== "undefined" && typeof history !== "undefined") {
+      const params = new URLSearchParams(location.search);
+      params.delete("preview");
+      const qs = params.toString();
+      history.replaceState(null, "", qs ? `?${qs}` : location.pathname);
+    }
     loadCommitted();
-  }, [loadCommitted]);
-  (0, import_react2.useEffect)(() => {
-    const guard = shouldLoadPreview(config);
-    const id = new URLSearchParams(location.search).get("preview");
+  };
+  const setMode = (next) => {
+    mode = next;
+    if (typeof document !== "undefined") {
+      const action = resolveModeAction(darkModeConvention, next);
+      switch (action.type) {
+        case "attr-set":
+          document.documentElement.setAttribute(action.attribute, action.value);
+          break;
+        case "attr-remove":
+          document.documentElement.removeAttribute(action.attribute);
+          break;
+        case "class-add":
+          document.documentElement.classList.add(action.className);
+          break;
+        case "class-remove":
+          document.documentElement.classList.remove(action.className);
+          break;
+        case "none":
+        default:
+          break;
+      }
+    }
+    notify();
+  };
+  const destroy = () => {
+    cancelled = true;
+    if (pollId) clearInterval(pollId);
+    if (unsubscribeSSE) unsubscribeSSE();
+    if (mql) {
+      if (typeof mql.removeEventListener === "function") mql.removeEventListener("change", onSchemeChange);
+      else if (typeof mql.removeListener === "function") mql.removeListener(onSchemeChange);
+    }
+    listeners.clear();
+  };
+  const init = async () => {
+    if (config.resolved && config.resolved.length) warnDeprecated(config.resolved);
+    let effectiveConfig = config;
+    let resolvedConnection = null;
+    if (shouldResolveOrgConnection(config)) {
+      resolvedConnection = await resolveOrgConnection(getOrgKey(config), {
+        cloudBase: config.cloudBase
+      });
+      if (cancelled) return;
+      effectiveConfig = buildEffectiveConfig(config, resolvedConnection);
+    }
+    const guard = shouldLoadPreview(effectiveConfig);
+    const id = typeof location !== "undefined" ? new URLSearchParams(location.search).get("preview") : null;
     if (!guard.allowed || !id) {
       if (id && !guard.allowed) {
         devWarn(
@@ -252,16 +746,213 @@ var SorbProvider = ({ config, children }) => {
       loadCommitted();
       return;
     }
-    loadPreview(id).then((ok) => {
-      if (!ok) return;
-      const interval = config.preview?.pollInterval ?? 1500;
-      pollRef.current = setInterval(() => loadPreview(id), interval);
-    });
+    const ok = await loadPreview(id, effectiveConfig);
+    if (!ok || cancelled) return;
+    const useSSE = resolvedConnection && resolvedConnection.transport === "sse" && resolvedConnection.orgId && EventSourceCtor;
+    if (useSSE) {
+      const url = buildSubscribeUrl(
+        resolvedConnection.bridgeUrl,
+        resolvedConnection.orgId,
+        id,
+        effectiveConfig.preview?.key
+      );
+      unsubscribeSSE = createPreviewSubscription({
+        EventSourceImpl: EventSourceCtor,
+        url,
+        onTokens: (tokens) => applyPreviewTokens(tokens, id, effectiveConfig),
+        onDelete: () => loadCommitted(),
+        onError: () => devWarn("SSE preview subscription error \u2014 preview may be stale")
+      });
+    }
+    if (!unsubscribeSSE) {
+      const interval = effectiveConfig.preview?.pollInterval ?? 1500;
+      pollId = setInterval(() => loadPreview(id, effectiveConfig), interval);
+    }
+  };
+  init();
+  return { getState, subscribe, setMode, clearPreview, destroy };
+}
+
+// src/legacyMap.js
+var normalizeProp = (prop) => {
+  if (typeof prop !== "string") return "";
+  return prop.trim().replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/_/g, "-").toLowerCase();
+};
+var canonicalizeColor = (v) => {
+  const hex = v.match(/^#([0-9a-f]{3,8})$/);
+  if (hex) {
+    let h = hex[1];
+    if (h.length === 3 || h.length === 4) {
+      h = h.split("").map((c) => c + c).join("");
+    }
+    if (h.length !== 6 && h.length !== 8) return null;
+    const r = parseInt(h.slice(0, 2), 16);
+    const g = parseInt(h.slice(2, 4), 16);
+    const b = parseInt(h.slice(4, 6), 16);
+    if (h.length === 8) {
+      const a = parseInt(h.slice(6, 8), 16) / 255;
+      const as = String(Math.round(a * 1e3) / 1e3);
+      return `rgba(${r}, ${g}, ${b}, ${as})`;
+    }
+    return `rgb(${r}, ${g}, ${b})`;
+  }
+  const fn = v.match(/^(rgba?)\(([^)]*)\)$/);
+  if (fn) {
+    const parts = fn[2].split(",").map((p) => p.trim()).filter((p) => p !== "");
+    if (parts.length === 3) return `rgb(${parts[0]}, ${parts[1]}, ${parts[2]})`;
+    if (parts.length === 4) return `rgba(${parts[0]}, ${parts[1]}, ${parts[2]}, ${parts[3]})`;
+  }
+  return null;
+};
+var normalizeValue = (value) => {
+  if (value == null) return "";
+  let v = String(value).trim().toLowerCase();
+  if (v === "") return "";
+  v = v.replace(/\s+/g, " ");
+  const color = canonicalizeColor(v);
+  if (color) return color;
+  if (/^-?\d*\.?\d+$/.test(v)) v = `${v}px`;
+  return v;
+};
+var indexLegacyMap = (legacyMap) => {
+  const idx = /* @__PURE__ */ new Map();
+  if (!Array.isArray(legacyMap)) return idx;
+  for (const row of legacyMap) {
+    if (!row || row.cssVar == null || row.raw == null || row.prop == null) continue;
+    const p = normalizeProp(row.prop);
+    const entry = {
+      normValue: normalizeValue(row.raw),
+      cssVar: String(row.cssVar).replace(/^--/, ""),
+      raw: String(row.raw)
+    };
+    const list = idx.get(p);
+    if (list) list.push(entry);
+    else idx.set(p, [entry]);
+  }
+  return idx;
+};
+var computeLegacyOverride = (prop, computedValue, legacyMap) => {
+  const idx = legacyMap instanceof Map ? legacyMap : indexLegacyMap(legacyMap);
+  const list = idx.get(normalizeProp(prop));
+  if (!list || list.length === 0) return null;
+  const target = normalizeValue(computedValue);
+  if (target === "") return null;
+  for (const entry of list) {
+    if (entry.normValue === target) {
+      return `var(--${entry.cssVar}, ${entry.raw})`;
+    }
+  }
+  return null;
+};
+
+// src/legacyDom.js
+var applyLegacyMap = (root, legacyMap) => {
+  const restores = [];
+  const handle = { restores };
+  if (typeof document === "undefined") return handle;
+  const start = root ?? document.body;
+  if (!start || !Array.isArray(legacyMap) || legacyMap.length === 0) return handle;
+  const idx = indexLegacyMap(legacyMap);
+  if (idx.size === 0) return handle;
+  const props = Array.from(idx.keys());
+  const getView = () => {
+    const doc = start.ownerDocument || (start.nodeType === 9 ? start : document);
+    return doc.defaultView || (typeof window !== "undefined" ? window : null);
+  };
+  const view = getView();
+  if (!view || typeof view.getComputedStyle !== "function") return handle;
+  const visit = (el) => {
+    if (!el || el.nodeType !== 1) return;
+    const cs = view.getComputedStyle(el);
+    for (const prop of props) {
+      const computed = cs.getPropertyValue(prop);
+      const override = computeLegacyOverride(prop, computed, idx);
+      if (override == null) continue;
+      const prev = el.style.getPropertyValue(prop);
+      restores.push({ el: (
+        /** @type {HTMLElement} */
+        el
+      ), prop, prev });
+      el.style.setProperty(prop, override);
+    }
+  };
+  if (start.nodeType === 1) visit(
+    /** @type {Element} */
+    start
+  );
+  const all = start.querySelectorAll ? start.querySelectorAll("*") : [];
+  for (const el of all) visit(el);
+  return handle;
+};
+var clearLegacyMap = (handle) => {
+  if (!handle || !Array.isArray(handle.restores)) return;
+  for (const { el, prop, prev } of handle.restores) {
+    if (!el || !el.style) continue;
+    if (prev === "" || prev == null) el.style.removeProperty(prop);
+    else el.style.setProperty(prop, prev);
+  }
+  handle.restores = [];
+};
+
+// src/TokenProvider.jsx
+var import_jsx_runtime = require("react/jsx-runtime");
+var matchMediaFn2 = typeof matchMedia !== "undefined" ? matchMedia : null;
+var DARK_MEDIA_QUERY2 = "(prefers-color-scheme: dark)";
+var SorbProvider = ({ config, legacyMap, children }) => {
+  const instanceRef = (0, import_react2.useRef)(null);
+  const legacyHandleRef = (0, import_react2.useRef)(null);
+  const [state, setState] = import_react2.default.useState(() => ({
+    tokens: config.tokens,
+    isPreview: false,
+    previewId: null,
+    previewMismatch: false,
+    mode: "auto",
+    resolvedScheme: matchMediaFn2 ? matchMediaFn2(DARK_MEDIA_QUERY2).matches ? "dark" : "light" : "light"
+  }));
+  const resolvedLegacyMap = legacyMap ?? config.legacyMap ?? null;
+  (0, import_react2.useEffect)(() => {
+    const instance = sorbInit(config);
+    instanceRef.current = instance;
+    setState(instance.getState());
+    const unsubscribe = instance.subscribe(setState);
     return () => {
-      if (pollRef.current) clearInterval(pollRef.current);
+      unsubscribe();
+      instance.destroy();
+      instanceRef.current = null;
     };
   }, []);
-  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(TokenContext.Provider, { value: { tokens: activeTokens, isPreview, previewId, clearPreview }, children });
+  (0, import_react2.useEffect)(() => {
+    if (!resolvedLegacyMap || resolvedLegacyMap.length === 0) return void 0;
+    if (typeof document === "undefined") return void 0;
+    if (legacyHandleRef.current) clearLegacyMap(legacyHandleRef.current);
+    legacyHandleRef.current = applyLegacyMap(document.body, resolvedLegacyMap);
+    return () => {
+      if (legacyHandleRef.current) {
+        clearLegacyMap(legacyHandleRef.current);
+        legacyHandleRef.current = null;
+      }
+    };
+  }, [resolvedLegacyMap, state.tokens]);
+  const setMode = (0, import_react2.useCallback)((next) => {
+    if (instanceRef.current) instanceRef.current.setMode(next);
+  }, []);
+  const clearPreview = (0, import_react2.useCallback)(() => {
+    if (instanceRef.current) instanceRef.current.clearPreview();
+  }, []);
+  const value = (0, import_react2.useMemo)(
+    () => ({
+      tokens: state.tokens,
+      isPreview: state.isPreview,
+      previewId: state.previewId,
+      previewMismatch: state.previewMismatch,
+      clearPreview,
+      mode: state.mode,
+      setMode,
+      resolvedScheme: state.resolvedScheme
+    }),
+    [state, clearPreview, setMode]
+  );
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(TokenContext.Provider, { value, children });
 };
 
 // src/PreviewBanner.jsx
@@ -283,15 +974,21 @@ var useIsPreview = () => {
   return useTokenContext().isPreview;
 };
 var usePreviewState = () => {
-  const { isPreview, previewId, clearPreview } = useTokenContext();
-  return { isPreview, previewId, clearPreview };
+  const { isPreview, previewId, previewMismatch, clearPreview } = useTokenContext();
+  return { isPreview, previewId, previewMismatch, clearPreview };
+};
+var useTheme = () => {
+  const { mode, setMode, resolvedScheme } = useTokenContext();
+  return { mode, setMode, resolvedScheme };
 };
 
 // src/PreviewBanner.jsx
 var import_jsx_runtime2 = require("react/jsx-runtime");
 var PreviewBanner = () => {
-  const { isPreview, previewId, clearPreview } = usePreviewState();
+  const { isPreview, previewId, previewMismatch, clearPreview } = usePreviewState();
   if (!isPreview) return null;
+  const background = previewMismatch ? "var(--sorb-preview-warning-bg, #B54708)" : "#3B5BDB";
+  const accent = previewMismatch ? "var(--sorb-preview-warning-accent, #F59E0B)" : "transparent";
   return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(
     "div",
     {
@@ -302,7 +999,8 @@ var PreviewBanner = () => {
         bottom: 0,
         left: 0,
         right: 0,
-        background: "#3B5BDB",
+        background,
+        borderTop: `3px solid ${accent}`,
         color: "#fff",
         padding: "10px 20px",
         display: "flex",
@@ -317,7 +1015,7 @@ var PreviewBanner = () => {
       },
       children: [
         /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("span", { children: [
-          /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("strong", { style: { fontWeight: 600 }, children: "Sorb preview active" }),
+          /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("strong", { style: { fontWeight: 600 }, children: previewMismatch ? "Sorb preview active \u2014 may not re-skin" : "Sorb preview active" }),
           previewId && /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
             "code",
             {
@@ -332,7 +1030,7 @@ var PreviewBanner = () => {
               children: previewId
             }
           ),
-          /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("span", { style: { marginLeft: "8px", opacity: 0.75, fontSize: "12px" }, children: "Token changes from Figma are live" })
+          /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("span", { style: { marginLeft: "8px", opacity: 0.75, fontSize: "12px" }, children: previewMismatch ? "No matching tokens for this app \u2014 colours may be unchanged" : "Token changes from Figma are live" })
         ] }),
         /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
           "button",
@@ -360,6 +1058,55 @@ var PreviewBanner = () => {
   );
 };
 
+// src/ThemeToggle.jsx
+var import_react4 = __toESM(require("react"));
+var import_jsx_runtime3 = require("react/jsx-runtime");
+var OPTIONS = [
+  { value: "light", label: "Light" },
+  { value: "dark", label: "Dark" },
+  { value: "auto", label: "Auto" }
+];
+var ThemeToggle = ({ className } = {}) => {
+  const { mode, setMode } = useTheme();
+  return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
+    "div",
+    {
+      role: "radiogroup",
+      "aria-label": "Color mode",
+      className,
+      style: {
+        display: "inline-flex",
+        gap: "4px",
+        fontFamily: 'system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif',
+        fontSize: "13px"
+      },
+      children: OPTIONS.map(({ value, label }) => {
+        const active = mode === value;
+        return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
+          "button",
+          {
+            type: "button",
+            role: "radio",
+            "aria-checked": active,
+            onClick: () => setMode(value),
+            style: {
+              padding: "4px 10px",
+              borderRadius: "6px",
+              border: "1px solid rgba(0,0,0,0.15)",
+              background: active ? "var(--sorb-theme-toggle-active-bg, #3B5BDB)" : "transparent",
+              color: active ? "#fff" : "inherit",
+              cursor: "pointer",
+              fontWeight: active ? 600 : 400
+            },
+            children: label
+          },
+          value
+        );
+      })
+    }
+  );
+};
+
 // src/verify.js
 var toCssVar = (name) => {
   const s = String(name).trim();
@@ -404,4 +1151,177 @@ var verifyResolved = async (tokens, { origin = "http://localhost:7777", key, fet
     return { ok: false, reason: "bridge-unreachable", error: e && e.message };
   }
 };
+
+// src/darkModeConventions.js
+var tailwindDarkMode = {
+  strategy: "class",
+  darkSelector: ".dark"
+};
+var dataThemeDarkMode = {
+  strategy: "attribute",
+  attribute: "data-theme",
+  darkSelector: '[data-theme="dark"]',
+  lightSelector: '[data-theme="light"]'
+};
+
+// src/targets/mantine.js
+var SORB_MANTINE_VARS_FORMAT_ID = "sorb/mantine-vars";
+var mantineTarget = {
+  id: "mantine",
+  emitFormat: SORB_MANTINE_VARS_FORMAT_ID,
+  // Kit-vocab expectPrefixes (field-correction, non-negotiable): the
+  // payload-side kit namespace, NEVER the framework's own `mantine-`
+  // var prefix — a framework-prefix guard false-positives on every working
+  // preview (verified P2/P3 across the demo program). Overridable via
+  // `config.preview.expectPrefixes`.
+  expectPrefixes: ["color-", "button-", "radius-"],
+  // Left undefined on purpose — see file header.
+  inject: void 0,
+  // CONVENTION-DECLARED, NOT demo-verified — the Mantine JJ demo never built
+  // dark mode (acid-wash is a variant push, not a mode). Mantine v7's
+  // documented color-scheme convention sets a `data-mantine-color-scheme`
+  // attribute (MantineProvider manages it; `useMantineColorScheme` /
+  // `<ColorSchemeScript>` toggle it). Feeds the real-dark-mode program's D1
+  // phase; verification lands there, not here.
+  darkMode: {
+    strategy: "attribute",
+    attribute: "data-mantine-color-scheme",
+    darkSelector: '[data-mantine-color-scheme="dark"]',
+    lightSelector: '[data-mantine-color-scheme="light"]'
+  }
+};
+if (typeof registerTarget === "function") {
+  registerTarget(mantineTarget);
+}
+
+// src/targets/tailwindV4.js
+var SORB_TAILWIND_FORMAT_ID = "sorb/tailwind-theme";
+var tailwindV4Target = {
+  id: "tailwind-v4",
+  emitFormat: SORB_TAILWIND_FORMAT_ID,
+  // Payload-side KIT vocabulary (framework-targets-productization field-
+  // correction), never a framework var prefix — a plain Sorb kit's own
+  // token-family prefixes, matching what `@theme inline` references.
+  expectPrefixes: ["color-", "radius-", "space-", "font-"],
+  // Left undefined on purpose — see file header.
+  inject: void 0,
+  // CONVENTION-DECLARED, not demo-verified (the JJ demos never built dark
+  // mode): Tailwind's documented `darkMode: 'class'` convention — a `.dark`
+  // class toggled on `documentElement`. Feeds the real-dark-mode program's D1
+  // phase; verification lands there.
+  darkMode: tailwindDarkMode
+};
+if (typeof registerTarget === "function") {
+  registerTarget(tailwindV4Target);
+}
+
+// src/targets/shadcn.js
+var SORB_SHADCN_FORMAT_ID = "sorb/shadcn-theme";
+var shadcnTarget = {
+  id: "shadcn",
+  emitFormat: SORB_SHADCN_FORMAT_ID,
+  // Payload-side KIT vocabulary (framework-targets-productization field-
+  // correction), never a framework/shadcn var prefix — shadcn's own vars
+  // (`--background`, `--primary`, …) are the OUTPUT of this format, not the
+  // guarded payload; the guard is against the underlying Sorb kit vocab the
+  // format's :root map references.
+  expectPrefixes: ["color-", "radius-", "space-", "font-"],
+  // Left undefined on purpose — see file header.
+  inject: void 0,
+  // CONVENTION-DECLARED, not demo-verified (the JJ demos never built dark
+  // mode): shadcn ships on top of Tailwind's `darkMode: 'class'` convention
+  // (a `.dark` class toggled on `documentElement`, per shadcn/ui's own
+  // docs). Feeds the real-dark-mode program's D1 phase; verification lands
+  // there.
+  darkMode: tailwindDarkMode
+};
+if (typeof registerTarget === "function") {
+  registerTarget(shadcnTarget);
+}
+
+// src/targets/primevue.js
+var SORB_PRIMEVUE_PRESET_FORMAT_ID = "sorb/primevue-preset";
+var primevueTarget = {
+  id: "primevue",
+  emitFormat: SORB_PRIMEVUE_PRESET_FORMAT_ID,
+  // Kit-vocab expectPrefixes (field-correction, non-negotiable): the
+  // payload-side kit namespace, NEVER a PrimeVue-owned prefix (`p-`) — a
+  // framework-prefix guard false-positives on every working preview
+  // (verified P2/P3 across the demo program). This target's preset draws
+  // from a wider slice of the kit vocab than Mantine/MUI (component-tier
+  // overrides for Tag/Toast/Menubar), hence the longer list. Overridable via
+  // `config.preview.expectPrefixes`.
+  expectPrefixes: ["color-", "button-", "card-", "badge-", "input-", "nav-", "toast-", "radius-"],
+  // Left undefined on purpose — see file header.
+  inject: void 0,
+  // CONVENTION-DECLARED, NOT demo-verified — the PrimeVue JJ demo never
+  // built dark mode (acid-wash is a variant push, not a mode). PrimeVue v4's
+  // documented dark-mode convention is a `.p-dark` selector class (default
+  // `darkModeSelector` in `definePreset`/PrimeVue config), toggled on an
+  // ancestor (typically `<html>`). Feeds the real-dark-mode program's D1
+  // phase; verification lands there, not here.
+  darkMode: {
+    strategy: "class",
+    darkSelector: ".p-dark"
+  }
+};
+if (typeof registerTarget === "function") {
+  registerTarget(primevueTarget);
+}
+
+// src/targets/mui.js
+var SORB_MUI_VARS_FORMAT_ID = "sorb/mui-vars";
+var muiTarget = {
+  id: "mui",
+  emitFormat: SORB_MUI_VARS_FORMAT_ID,
+  // Kit-vocab expectPrefixes (field-correction, non-negotiable): the
+  // payload-side kit namespace, NEVER the framework's own `mui-` var
+  // prefix — a framework-prefix guard false-positives on every working
+  // preview (verified P2/P3 across the demo program). Overridable via
+  // `config.preview.expectPrefixes`.
+  expectPrefixes: ["color-", "radius-"],
+  // Left undefined on purpose — see file header.
+  inject: void 0,
+  // CONVENTION-DECLARED, NOT demo-verified — the MUI JJ demo never built
+  // dark mode (acid-wash is a variant push, not a mode). MUI v6's documented
+  // `cssVariables: { colorSchemeSelector: 'data' }` convention sets a
+  // `data-mui-color-scheme` attribute (`InitColorSchemeScript` / MUI's
+  // `ThemeProvider` manage it). Feeds the real-dark-mode program's D1 phase;
+  // verification lands there, not here.
+  darkMode: {
+    strategy: "attribute",
+    attribute: "data-mui-color-scheme",
+    darkSelector: '[data-mui-color-scheme="dark"]',
+    lightSelector: '[data-mui-color-scheme="light"]'
+  }
+};
+if (typeof registerTarget === "function") {
+  registerTarget(muiTarget);
+}
+
+// src/targets/angularMaterial.js
+var SORB_MAT_SYS_VARS_FORMAT_ID = "sorb/mat-sys-vars";
+var angularMaterialTarget = {
+  id: "angular-material",
+  emitFormat: SORB_MAT_SYS_VARS_FORMAT_ID,
+  // Kit-vocab expectPrefixes (field-correction, non-negotiable): the
+  // payload-side kit namespace, NEVER Angular Material's own `mat-sys-`
+  // var prefix — a framework-prefix guard false-positives on every working
+  // preview (verified P2/P3 across the demo program). Overridable via
+  // `config.preview.expectPrefixes`.
+  expectPrefixes: ["color-", "radius-"],
+  // Left undefined on purpose — see file header. Non-React (Angular) target;
+  // the leaf-core inject seam stays deferred.
+  inject: void 0,
+  // CONVENTION-DECLARED + UNCONFIRMED — see file header "DARK MODE" section.
+  // Best-known default given Angular Material 20's `light-dark()`/
+  // `color-scheme` mechanism has no single canonical selector name.
+  darkMode: {
+    strategy: "class",
+    darkSelector: ".dark"
+  }
+};
+if (typeof registerTarget === "function") {
+  registerTarget(angularMaterialTarget);
+}
 //# sourceMappingURL=index.js.map