@takazudo/zdtp 0.4.3 → 0.4.5

package/dist/astro/host-adapter.js

@@ -1,56 +1,56 @@
-import { c as h, g as u, a as g, b as w, d as y, e as P } from "../panel-config-3tBEHjvZ.js";
-import { g as d, Z as b } from "../tweak-state-BEx1SHu7.js";
-import { s as _, l as A, a as c, c as k, b as I } from "../autoload-state-B1MWY_Pp.js";
-const l = "tokenpanel-config";
-function E() {
+import { c as w, g as u, a as g, b as y, d as P, e as b, f as _ } from "../panel-config-CipeKMTz.js";
+import { g as d, Z as A } from "../tweak-state-xt-tSQ_t.js";
+import { s as k, l as I, a as c, c as E, b as C } from "../autoload-state-DF7TsTgY.js";
+const i = "tokenpanel-config";
+function S() {
   if (typeof document > "u")
     throw new Error(
       "[design-token-panel] host-adapter loaded without a document; expected to run in a browser context."
     );
-  const n = document.getElementById(l);
+  const n = document.getElementById(i);
   if (!n)
     throw new Error(
-      `[design-token-panel] Inline config script #${l} not found. Ensure <DesignTokenPanelHost config={...} /> is rendered on this page before the host script runs.`
+      `[design-token-panel] Inline config script #${i} not found. Ensure <DesignTokenPanelHost config={...} /> is rendered on this page before the host script runs.`
     );
-  const o = n.textContent ?? "";
+  const a = n.textContent ?? "";
   let e;
   try {
-    e = JSON.parse(o);
-  } catch (a) {
+    e = JSON.parse(a);
+  } catch (o) {
     throw new Error(
-      `[design-token-panel] Failed to parse inline config from #${l}: ${a.message}`
+      `[design-token-panel] Failed to parse inline config from #${i}: ${o.message}`
     );
   }
-  return P(e), e;
+  return _(e), e;
 }
-function C(n) {
+function T(n) {
   return n.__zudoDesignTokenPanelAdapter || (n.__zudoDesignTokenPanelAdapter = {}), n.__zudoDesignTokenPanelAdapter;
 }
-function S(n, o) {
-  const e = C(n);
-  let a = e[o];
-  return a || (a = { bound: !1, modulePromise: null }, e[o] = a), a;
+function V(n, a) {
+  const e = T(n);
+  let o = e[a];
+  return o || (o = { bound: !1, modulePromise: null }, e[a] = o), o;
 }
-function T(n) {
+function v(n) {
   try {
     return window.localStorage.getItem(n) === "1";
   } catch {
     return !1;
   }
 }
-function v(n, o) {
+function D(n, a, e) {
   try {
-    const e = window.localStorage;
-    return e.getItem(o) !== null || e.getItem(n) !== null;
+    const o = window.localStorage;
+    return o.getItem(e) !== null || o.getItem(a) !== null || o.getItem(n) !== null;
   } catch {
     return !1;
   }
 }
-async function i(n) {
-  return n.modulePromise === null && (n.modulePromise = import("@takazudo/zdtp").then((o) => {
+async function l(n) {
+  return n.modulePromise === null && (n.modulePromise = import("@takazudo/zdtp").then((a) => {
     try {
-      const e = u(), a = o.__panelConfigForTest();
-      e !== a && console.warn(
+      const e = u(), o = a.__panelConfigForTest();
+      e !== o && console.warn(
         "[design-token-panel] Singleton-sharing check failed: the host adapter and the panel module observed different PanelConfig singletons. This indicates the package's `config/panel-config` module is no longer code-split into a single shared chunk. The panel may behave correctly today, but storage keys / namespaces / branding could diverge between the two surfaces in future bundles."
       );
     } catch (e) {
@@ -58,17 +58,17 @@ async function i(n) {
         "[design-token-panel] Singleton-sharing check could not run (likely an older dist without the __panelConfigForTest accessor): " + e.message
       );
     }
-    return o;
+    return a;
   })), n.modulePromise;
 }
-function D(n, o, e, a, t) {
-  const s = n[o] ?? {};
+function K(n, a, e, o, t) {
+  const s = n[a] ?? {};
   s.showDesignPanel = async () => {
-    c(t, !0), await i(e), a.open();
+    c(t, !0), await l(e), o.open();
   }, s.hideDesignPanel = async () => {
-    await i(e), a.close();
+    await l(e), o.close();
   }, s.toggleDesignPanel = async () => {
-    await i(e), a.toggle();
+    await l(e), o.toggle();
     let r = !1;
     try {
       r = window.localStorage.getItem(d(t)) === "1";
@@ -76,13 +76,13 @@ function D(n, o, e, a, t) {
     }
     r && c(t, !0);
   }, s.enableAutoload = async () => {
-    (await i(e)).enableAutoload(t);
+    (await l(e)).enableAutoload(t);
   }, s.disableAutoload = async () => {
     if (e.modulePromise !== null) {
-      (await i(e)).disableAutoload(t);
+      (await l(e)).disableAutoload(t);
       return;
     }
-    k(t), I(!1, t);
+    E(t), C(!1, t);
     try {
       window.localStorage.setItem(g(t), "0");
     } catch {
@@ -91,12 +91,12 @@ function D(n, o, e, a, t) {
       window.localStorage.removeItem(d(t));
     } catch {
     }
-  }, n[o] = s;
+  }, n[a] = s;
 }
 (function() {
-  const o = E(), e = o.legacyIdRenameMap ? o : { ...o, legacyIdRenameMap: { ...b } }, a = h(e), t = u(), s = window, r = S(s, t.storagePrefix);
-  if (D(s, t.consoleNamespace, r, a, t), r.bound) return;
+  const a = S(), e = a.legacyIdRenameMap ? a : { ...a, legacyIdRenameMap: { ...A } }, o = w(e), t = u(), s = window, r = V(s, t.storagePrefix);
+  if (K(s, t.consoleNamespace, r, o, t), r.bound) return;
   r.bound = !0;
-  const f = g(t), p = w(t), m = y(t);
-  (T(f) || v(p, m) || _(t) || A(t)) && i(r);
+  const f = g(t), m = y(t), p = P(t), h = b(t);
+  (v(f) || D(m, p, h) || k(t) || I(t)) && l(r);
 })();

package/dist/astro/index.js

@@ -1,4 +1,4 @@
-import { s as t } from "../panel-config-3tBEHjvZ.js";
+import { s as t } from "../panel-config-CipeKMTz.js";
 import { c as d } from "../color-schemes-CgzOBqGO.js";
 import { F as r, G as m, a as g, S as z } from "../manifest-DCReQE0k.js";
 const e = {

package/dist/{autoload-state-B1MWY_Pp.js → autoload-state-DF7TsTgY.js}

@@ -1,4 +1,4 @@
-import { g as a, j as o } from "./panel-config-3tBEHjvZ.js";
+import { g as a, k as o } from "./panel-config-CipeKMTz.js";
 function n(e = a()) {
   return `${e.storagePrefix}-elpath-enabled`;
 }

package/dist/bin/server.js

@@ -1,20 +1,20 @@
 #!/usr/bin/env node
-import { realpathSync as H } from "node:fs";
-import { createServer as C } from "node:http";
-import { resolve as d } from "node:path";
-import { l as x, c as N } from "../load-routing-DtNTKoLW.js";
-function g(t, e) {
-  return typeof t != "string" || t.length === 0 || e.length === 0 ? !1 : e.includes(t);
+import { realpathSync as E } from "node:fs";
+import { createServer as H } from "node:http";
+import { resolve as p } from "node:path";
+import { l as $, c as x } from "../load-routing-LJ72261l.js";
+function g(o, t) {
+  return typeof o != "string" || o.length === 0 || t.length === 0 ? !1 : t.includes(o);
 }
-function w(t) {
+function w(o) {
   return {
-    "Access-Control-Allow-Origin": t,
+    "Access-Control-Allow-Origin": o,
     "Access-Control-Allow-Methods": "POST, OPTIONS",
     "Access-Control-Allow-Headers": "content-type",
     "Access-Control-Max-Age": "600"
   };
 }
-const k = 24681, b = "127.0.0.1", $ = `Usage: zdtp-server [options]
+const k = 24681, b = "127.0.0.1", N = `Usage: zdtp-server [options]
 
 Run a small Node http server that wraps the design-token apply handler.
 
@@ -39,8 +39,8 @@ Examples:
     --routing ./my.routing.json \\
     --allow-origin http://localhost:34434
 `;
-function v(t) {
-  const e = {
+function v(o) {
+  const t = {
     root: null,
     writeRoot: null,
     routing: null,
@@ -50,144 +50,148 @@ function v(t) {
     quiet: !1,
     help: !1
   };
-  let o = 0;
-  for (; o < t.length; ) {
-    const n = t[o];
+  let e = 0;
+  for (; e < o.length; ) {
+    const n = o[e];
     switch (n) {
       case "--help":
       case "-h":
-        e.help = !0, o += 1;
+        t.help = !0, e += 1;
         break;
       case "--quiet":
-        e.quiet = !0, o += 1;
+        t.quiet = !0, e += 1;
         break;
       case "--root":
-        e.root = c(t, o, "--root"), o += 2;
+        t.root = c(o, e, "--root"), e += 2;
         break;
       case "--write-root":
-        e.writeRoot = c(t, o, "--write-root"), o += 2;
+        t.writeRoot = c(o, e, "--write-root"), e += 2;
         break;
       case "--routing":
-        e.routing = c(t, o, "--routing"), o += 2;
+        t.routing = c(o, e, "--routing"), e += 2;
         break;
       case "--host":
-        e.host = c(t, o, "--host"), o += 2;
+        t.host = c(o, e, "--host"), e += 2;
         break;
       case "--port": {
-        const s = c(t, o, "--port"), r = Number(s);
+        const s = c(o, e, "--port"), r = Number(s);
         if (!Number.isInteger(r) || r < 0 || r > 65535)
           throw new Error(`--port must be an integer in 0..65535 (got ${JSON.stringify(s)})`);
-        e.port = r, o += 2;
+        t.port = r, e += 2;
         break;
       }
       case "--allow-origin": {
-        const s = c(t, o, "--allow-origin");
-        e.allowOrigins.push(s), o += 2;
+        const s = c(o, e, "--allow-origin");
+        t.allowOrigins.push(s), e += 2;
         break;
       }
       default:
         throw new Error(`Unknown option: ${n}`);
     }
   }
-  if (e.help) return e;
-  if (!e.writeRoot)
+  if (t.help) return t;
+  if (!t.writeRoot)
     throw new Error("--write-root is required (the only directory the bin will write into)");
-  if (!e.routing)
+  if (!t.routing)
     throw new Error("--routing is required (path to the routing JSON file)");
-  return e;
+  return t;
 }
-function c(t, e, o) {
-  const n = t[e + 1];
+function c(o, t, e) {
+  const n = o[t + 1];
   if (typeof n != "string" || n.startsWith("--"))
-    throw new Error(`${o} requires a value`);
+    throw new Error(`${e} requires a value`);
   return n;
 }
 const y = "/apply", D = "/healthz";
-function L(t) {
-  const e = d(t.root ?? process.cwd()), o = d(e, t.writeRoot), n = d(e, t.routing);
+function L(o) {
+  const t = p(o.root ?? process.cwd()), e = p(t, o.writeRoot), n = p(t, o.routing);
   return {
-    rootDir: e,
-    writeRoot: o,
+    rootDir: t,
+    writeRoot: e,
     routingPath: n,
-    port: t.port,
-    host: t.host,
-    allowOrigins: t.allowOrigins,
-    quiet: t.quiet
+    port: o.port,
+    host: o.host,
+    allowOrigins: o.allowOrigins,
+    quiet: o.quiet
   };
 }
-function a(t, e, o) {
-  const n = JSON.stringify(o);
-  t.statusCode = e, t.setHeader("Content-Type", "application/json"), t.setHeader("Content-Length", Buffer.byteLength(n).toString()), t.end(n);
+function a(o, t, e) {
+  const n = JSON.stringify(e);
+  o.statusCode = t, o.setHeader("Content-Type", "application/json"), o.setHeader("Content-Length", Buffer.byteLength(n).toString()), o.end(n);
 }
 const O = 1048576;
-function U(t) {
-  return new Promise((e, o) => {
+function j(o) {
+  return new Promise((t, e) => {
     const n = [];
     let s = 0;
-    t.on("data", (r) => {
+    o.on("data", (r) => {
       if (s += r.byteLength, s > O) {
-        e(413), t.destroy();
+        t(413), o.destroy();
         return;
       }
       n.push(r);
-    }), t.on("end", () => e(Buffer.concat(n).toString("utf-8"))), t.on("error", o);
+    }), o.on("end", () => t(Buffer.concat(n).toString("utf-8"))), o.on("error", e);
   });
 }
-function I(t) {
-  const e = new Headers();
-  for (const [o, n] of Object.entries(t.headers))
+function U(o) {
+  const t = new Headers();
+  for (const [e, n] of Object.entries(o.headers))
     if (Array.isArray(n))
-      for (const s of n) e.append(o, s);
-    else typeof n == "string" && e.set(o, n);
-  return e;
+      for (const s of n) t.append(e, s);
+    else typeof n == "string" && t.set(e, n);
+  return t;
 }
-async function j(t, e, o) {
-  t.statusCode = e.status, e.headers.forEach((s, r) => {
-    t.setHeader(r, s);
+async function I(o, t, e) {
+  o.statusCode = t.status, t.headers.forEach((s, r) => {
+    o.setHeader(r, s);
   });
-  for (const [s, r] of Object.entries(o))
-    t.setHeader(s, r);
-  const n = await e.text();
-  t.end(n);
+  for (const [s, r] of Object.entries(e))
+    o.setHeader(s, r);
+  const n = await t.text();
+  o.end(n);
 }
-function q(t, e) {
-  if (!t)
+function V(o, t) {
+  if (!o)
     try {
-      const o = JSON.parse(e);
-      if (!o.ok || !Array.isArray(o.updated)) return;
-      const n = o.updated.reduce(
+      const e = JSON.parse(t);
+      if (!e.ok || !Array.isArray(e.updated)) return;
+      const n = e.updated.reduce(
         (i, l) => i + (Array.isArray(l.changed) ? l.changed.length : 0),
         0
-      ), s = o.updated.length, r = o.updated.filter((i) => Array.isArray(i.changed) && i.changed.length > 0).map((i) => i.file);
+      ), s = e.updated.length, r = e.updated.filter((i) => Array.isArray(i.changed) && i.changed.length > 0).map((i) => i.file);
       console.log(
         `[design-token-panel] applied ${n} tokens to ${s} files (changed: ${r.length > 0 ? r.join(", ") : "none"})`
+      ), Array.isArray(e.unknownCssVars) && e.unknownCssVars.length > 0 && console.log(
+        `[design-token-panel] unknown: ${e.unknownCssVars.length} cssVar(s) not found (${e.unknownCssVars.join(", ")})`
+      ), Array.isArray(e.unknownOutsideBlockCssVars) && e.unknownOutsideBlockCssVars.length > 0 && console.log(
+        `[design-token-panel] outside scanned block: ${e.unknownOutsideBlockCssVars.length} of those cssVar(s) are declared in the file but outside the scanned :root/@theme block(s), so they were not rewritable (${e.unknownOutsideBlockCssVars.join(", ")})`
       );
     } catch {
     }
 }
-function F(t) {
-  const { applyHandler: e, config: o } = t;
+function B(o) {
+  const { applyHandler: t, config: e } = o;
   return async function(s, r) {
     const i = s.url ?? "/", l = (s.method ?? "GET").toUpperCase(), u = typeof s.headers.origin == "string" ? s.headers.origin : null;
     try {
       if (i === D && l === "GET") {
         a(r, 200, {
           ok: !0,
-          writeRoot: o.writeRoot,
-          routing: o.routingPath,
-          port: o.port
+          writeRoot: e.writeRoot,
+          routing: e.routingPath,
+          port: e.port
         });
         return;
       }
       if (i === y) {
         if (l === "OPTIONS") {
-          if (!g(u, o.allowOrigins)) {
+          if (!g(u, e.allowOrigins)) {
             a(r, 403, { ok: !1, error: "Origin not allowed" });
             return;
           }
           const S = w(u);
-          for (const [P, E] of Object.entries(S))
-            r.setHeader(P, E);
+          for (const [C, P] of Object.entries(S))
+            r.setHeader(C, P);
           r.statusCode = 204, r.end();
           return;
         }
@@ -195,16 +199,16 @@ function F(t) {
           r.setHeader("Allow", "POST, OPTIONS"), a(r, 405, { ok: !1, error: "Method not allowed" });
           return;
         }
-        const p = s.headers["content-type"];
-        if (typeof p != "string" || !p.toLowerCase().includes("application/json")) {
+        const d = s.headers["content-type"];
+        if (typeof d != "string" || !d.toLowerCase().includes("application/json")) {
           a(r, 415, { ok: !1, error: "Content-Type must be application/json" });
           return;
         }
-        if (!g(u, o.allowOrigins)) {
+        if (!g(u, e.allowOrigins)) {
           a(r, 403, { ok: !1, error: "Origin not allowed" });
           return;
         }
-        const f = await U(s);
+        const f = await j(s);
         if (f === 413) {
           a(r, 413, {
             ok: !1,
@@ -213,71 +217,71 @@ function F(t) {
           });
           return;
         }
-        const m = f, A = new Request(`http://localhost${y}`, {
+        const A = f, m = new Request(`http://localhost${y}`, {
           method: "POST",
-          headers: I(s),
-          body: m
-        }), h = await e(A), R = await h.clone().text(), T = w(u);
-        await j(r, h, T), q(o.quiet, R);
+          headers: U(s),
+          body: A
+        }), h = await t(m), R = await h.clone().text(), T = w(u);
+        await I(r, h, T), V(e.quiet, R);
         return;
       }
       a(r, 404, { ok: !1, error: "Not found" });
-    } catch (p) {
-      console.error("[design-token-panel] Unhandled error:", p), r.headersSent ? r.end() : a(r, 500, { ok: !1, error: "Internal server error" });
+    } catch (d) {
+      console.error("[design-token-panel] Unhandled error:", d), r.headersSent ? r.end() : a(r, 500, { ok: !1, error: "Internal server error" });
     }
   };
 }
-function _(t, e) {
-  t.on("error", (n) => {
-    n.code === "EADDRINUSE" && (console.error(`[design-token-panel] port ${e} already in use`), process.exit(1)), console.error("[design-token-panel] Server error:", n), process.exit(1);
+function q(o, t) {
+  o.on("error", (n) => {
+    n.code === "EADDRINUSE" && (console.error(`[design-token-panel] port ${t} already in use`), process.exit(1)), console.error("[design-token-panel] Server error:", n), process.exit(1);
   });
-  const o = (n) => {
-    t.close(() => {
+  const e = (n) => {
+    o.close(() => {
       process.exit(0);
     }), setTimeout(() => {
       console.error(`[design-token-panel] force-exiting after ${n}`), process.exit(0);
     }, 5e3).unref();
   };
-  process.on("SIGINT", o), process.on("SIGTERM", o);
+  process.on("SIGINT", e), process.on("SIGTERM", e);
 }
-function B() {
-  let t;
+function F() {
+  let o;
   try {
-    t = v(process.argv.slice(2));
+    o = v(process.argv.slice(2));
   } catch (r) {
     console.error(`[design-token-panel] ${r.message}`), console.error(""), console.error("Run --help for usage."), process.exit(1);
   }
-  t.help && (process.stdout.write($), process.exit(0));
-  const e = L(t);
-  let o;
+  o.help && (process.stdout.write(N), process.exit(0));
+  const t = L(o);
+  let e;
   try {
-    o = x(e.routingPath);
+    e = $(t.routingPath);
   } catch (r) {
     console.error(`[design-token-panel] Failed to load routing: ${r.message}`), process.exit(1);
   }
-  const n = N({
-    rootDir: e.rootDir,
-    writeRoot: e.writeRoot,
-    routing: o
-  }), s = C(F({ applyHandler: n, config: e }));
-  _(s, e.port), s.listen(e.port, e.host, () => {
-    if (!e.quiet) {
-      const r = s.address(), i = typeof r == "object" && r ? r.port : e.port;
+  const n = x({
+    rootDir: t.rootDir,
+    writeRoot: t.writeRoot,
+    routing: e
+  }), s = H(B({ applyHandler: n, config: t }));
+  q(s, t.port), s.listen(t.port, t.host, () => {
+    if (!t.quiet) {
+      const r = s.address(), i = typeof r == "object" && r ? r.port : t.port;
       console.log(
-        `[design-token-panel] listening on http://${e.host}:${i} (writeRoot: ${e.writeRoot})`
-      ), e.allowOrigins.length === 0 && console.log(
+        `[design-token-panel] listening on http://${t.host}:${i} (writeRoot: ${t.writeRoot})`
+      ), t.allowOrigins.length === 0 && console.log(
         "[design-token-panel] WARNING: no --allow-origin set; browser POST /apply will be rejected."
       );
     }
   });
 }
-const G = (() => {
+const _ = (() => {
   if (typeof process.argv[1] != "string") return !1;
   try {
-    const t = H(process.argv[1]), e = new URL(`file://${d(t)}`).href, o = import.meta.url;
-    return e === o;
+    const o = E(process.argv[1]), t = new URL(`file://${p(o)}`).href, e = import.meta.url;
+    return t === e;
   } catch {
     return !1;
   }
 })();
-G && B();
+_ && F();

package/dist/config/cluster-config.d.ts

@@ -21,6 +21,8 @@
  * `panelConfig.colorCluster`.
  */
 import type { ColorScheme } from './color-schemes';
+import type { SemanticValue } from '../tokens/tier-model';
+export type { SemanticValue } from '../tokens/tier-model';
 /**
  * Base-role keys that a cluster may declare. Subset is allowed (a cluster may
  * ship zero base roles when its design system doesn't expose them as tokens).
@@ -76,8 +78,16 @@ export interface ColorClusterDataConfig {
      * `--brand-p{n}`, `--demo-palette-{n}`.
      */
     paletteCssVarTemplate: string;
-    /** Semantic token name → default palette index. */
-    semanticDefaults: Record<string, number>;
+    /**
+     * Semantic token name → default mapping. Historically always a palette
+     * index (`number`); widened to `SemanticValue` (#459) so a default can also
+     * be a literal color or a cross-tab ramp reference. `resolveColorClusterFromTab`
+     * now derives the `{ literal }` / best-effort `{ ref }` variants too (#463)
+     * for a `semantic: true` tier; actually resolving a `{ ref }` against the
+     * ramp tier it names (rendering + apply) is still downstream work
+     * (#467/#469).
+     */
+    semanticDefaults: Record<string, SemanticValue>;
     /** Semantic token name → CSS custom-property name. */
     semanticCssNames: Record<string, string>;
     /** Fallback indices used when a scheme doesn't declare a base role. */
@@ -104,23 +114,36 @@ import type { TabConfig } from '../tokens/tier-model';
 /**
  * Derive a `ColorClusterDataConfig` from a color `TabConfig`.
  *
- * - Palette items: the first tier whose items all have `kind: 'color'`.
- *   Each item's `cssVar` becomes a palette slot; `paletteCssVarTemplate` is
- *   synthesised as `"{item.cssVar}"` with `{n}` replaced by the slot index.
- *   Because item cssVars are explicit (e.g. `--zfb-palette-0`) rather
- *   than template-based, we derive the template from the first item by
- *   replacing the terminal digit sequence with `{n}`.
+ * - Palette items: the first tier whose items all have `kind: 'color'` and
+ *   are not `semantic: true`. Each item's `cssVar` becomes a palette slot;
+ *   `paletteCssVarTemplate` is synthesised as `"{item.cssVar}"` with `{n}`
+ *   replaced by the slot index. Because item cssVars are explicit (e.g.
+ *   `--zfb-palette-0`) rather than template-based, we derive the template
+ *   from the first item by replacing the terminal digit sequence with `{n}`.
  *
- * - Semantic items: the first tier with `referencesTier` set pointing at the
- *   palette tier. Each item's `id` → `cssVar` mapping becomes `semanticCssNames`;
- *   the item's `default` (a palette item id) is looked up to produce the index
- *   for `semanticDefaults`.
+ * - Semantic items: either the first tier with `referencesTier` set pointing
+ *   at the palette tier (legacy shape), or a tier explicitly marked
+ *   `semantic: true` (#461) — the latter may have no palette sibling at all.
+ *   Each item's `id` → `cssVar` mapping becomes `semanticCssNames`; the
+ *   item's `default` is resolved to a `SemanticValue` by
+ *   `deriveSemanticValue` (palette index / literal / ramp-ref — see there).
+ *
+ * - A tab with a semantic tier but NO palette tier still produces a usable
+ *   cluster: `paletteSize` is `0` (the palette-driven UI has nothing to
+ *   render) but `semanticDefaults`/`semanticCssNames` are populated from the
+ *   semantic tier so the Semantic Tokens section isn't left empty (#463).
  *
  * - Metadata comes from `tab.colorExtras` (required on a color tab).
  *
+ * `tabs` is the panel config's full tabs array, used to resolve a semantic
+ * tier's cross-tab `{ ref }` mappings against a ramp tier living in ANOTHER
+ * tab (typically the grouped Palette tab). It defaults to `[tab]` so an
+ * existing single-argument call still works — intra-tab refs resolve, and a
+ * cross-tab ramp declaration falls back to its best-effort shape (#467).
+ *
  * Returns `undefined` when the tab has no `colorExtras` (not a color tab).
  */
-export declare function resolveColorClusterFromTab(tab: TabConfig): ColorClusterDataConfig | undefined;
+export declare function resolveColorClusterFromTab(tab: TabConfig, tabs?: readonly TabConfig[]): ColorClusterDataConfig | undefined;
 /**
  * Find the primary color tab (id 'color') in the host's tabs array and
  * derive its `ColorClusterDataConfig`. Returns `undefined` when no color tab