@motion-proto/live-tokens 0.47.0 → 0.48.0

package/dist-plugin/migrateData/index.d.cts

@@ -0,0 +1,60 @@
+export { r as readLiveTokensConfig, a as resolveDataDirs } from '../dataPaths-DBN0RPuT.cjs';
+
+interface LegacyRename {
+    from: string;
+    to: string;
+}
+
+interface MigrateDataOptions {
+    /** The directory the three below sit under. Locates the pre-0.48
+     *  `manifests/` directory, which no config key names any more. */
+    dataDir: string;
+    colorsAndTypeDir: string;
+    componentConfigsDir: string;
+    themesDir: string;
+    /** The retired `manifestsDir` config key, when the consumer set it. */
+    legacyManifestsDir?: string;
+    /** The installed package's `src/live-tokens/data`. Its files are read-only:
+     *  they resolve names the consumer has no local copy of, and are never
+     *  deleted even when their content matches a theme. */
+    packageDataDir?: string;
+    /** Plan only, write nothing. */
+    check?: boolean;
+}
+interface MigrateDataResult {
+    status: 'clean' | 'planned' | 'healed';
+    /** Directories moved to the 0.48 layout, old → new, in the order they ran. */
+    renames: LegacyRename[];
+    /** The theme production resolves to after the heal, and how it was decided. */
+    production: {
+        slug: string;
+        how: 'all-default' | 'matched' | 'recovered';
+    } | null;
+    /** Path of the theme written to record an unmatched production state. */
+    recoveredThemePath: string | null;
+    /** Buffers filled because the live state differed from the open theme. */
+    workingWritten: string[];
+    /** Buffers left as they were: the new server already owns them. */
+    workingKept: string[];
+    /** Materialised copies removed. */
+    deletedFiles: string[];
+    /** Retired per-layer pointer files removed. */
+    deletedPointers: string[];
+    /** Named files matching no theme. Yours, so they stay. */
+    keptUserFiles: string[];
+    /** Files in the themes directory that are not themes. Read past, never
+     *  rewritten. */
+    notThemes: string[];
+    /** One sentence per reference a theme named that resolved to nothing. The
+     *  theme carries the shipped default there now. */
+    droppedRefs: string[];
+    /** A local `colors-and-type/default.json` whose content differs from the copy
+     *  the package ships. It shadows the shipped default. Reported only. */
+    shadowedDefaults: string[];
+    /** Themes rewritten from the pre-v3 by-reference form, so step 3 cannot
+     *  delete a file they still name. */
+    upgradedThemes: string[];
+}
+declare function migrateData(opts: MigrateDataOptions): MigrateDataResult;
+
+export { type MigrateDataOptions, type MigrateDataResult, migrateData };

package/dist-plugin/migrateData/index.d.ts

@@ -0,0 +1,60 @@
+export { r as readLiveTokensConfig, a as resolveDataDirs } from '../dataPaths-DBN0RPuT.js';
+
+interface LegacyRename {
+    from: string;
+    to: string;
+}
+
+interface MigrateDataOptions {
+    /** The directory the three below sit under. Locates the pre-0.48
+     *  `manifests/` directory, which no config key names any more. */
+    dataDir: string;
+    colorsAndTypeDir: string;
+    componentConfigsDir: string;
+    themesDir: string;
+    /** The retired `manifestsDir` config key, when the consumer set it. */
+    legacyManifestsDir?: string;
+    /** The installed package's `src/live-tokens/data`. Its files are read-only:
+     *  they resolve names the consumer has no local copy of, and are never
+     *  deleted even when their content matches a theme. */
+    packageDataDir?: string;
+    /** Plan only, write nothing. */
+    check?: boolean;
+}
+interface MigrateDataResult {
+    status: 'clean' | 'planned' | 'healed';
+    /** Directories moved to the 0.48 layout, old → new, in the order they ran. */
+    renames: LegacyRename[];
+    /** The theme production resolves to after the heal, and how it was decided. */
+    production: {
+        slug: string;
+        how: 'all-default' | 'matched' | 'recovered';
+    } | null;
+    /** Path of the theme written to record an unmatched production state. */
+    recoveredThemePath: string | null;
+    /** Buffers filled because the live state differed from the open theme. */
+    workingWritten: string[];
+    /** Buffers left as they were: the new server already owns them. */
+    workingKept: string[];
+    /** Materialised copies removed. */
+    deletedFiles: string[];
+    /** Retired per-layer pointer files removed. */
+    deletedPointers: string[];
+    /** Named files matching no theme. Yours, so they stay. */
+    keptUserFiles: string[];
+    /** Files in the themes directory that are not themes. Read past, never
+     *  rewritten. */
+    notThemes: string[];
+    /** One sentence per reference a theme named that resolved to nothing. The
+     *  theme carries the shipped default there now. */
+    droppedRefs: string[];
+    /** A local `colors-and-type/default.json` whose content differs from the copy
+     *  the package ships. It shadows the shipped default. Reported only. */
+    shadowedDefaults: string[];
+    /** Themes rewritten from the pre-v3 by-reference form, so step 3 cannot
+     *  delete a file they still name. */
+    upgradedThemes: string[];
+}
+declare function migrateData(opts: MigrateDataOptions): MigrateDataResult;
+
+export { type MigrateDataOptions, type MigrateDataResult, migrateData };

package/dist-plugin/migrateData/index.js

@@ -0,0 +1,348 @@
+import {
+  THEME_SCHEMA_VERSION,
+  applyLegacyRenames,
+  detectLegacyLayout,
+  isColorsAndTypeShaped,
+  nextAvailableName,
+  normalizeTheme,
+  planLegacyRenames,
+  versionedFileResourceServer
+} from "../chunk-6OZFXIQI.js";
+import {
+  readLiveTokensConfig,
+  resolveDataDirs
+} from "../chunk-D3ZVKOR4.js";
+
+// vite-plugin/migrateData/migrateData.ts
+import fs from "fs";
+import path from "path";
+var RECOVERED_SLUG = "recovered-production";
+var RECOVERED_NAME = "Recovered production";
+var MARKER_KEYS = ["_fileName", "_source"];
+var VOLATILE_KEYS = [...MARKER_KEYS, "updatedAt"];
+function isObject(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function sortDeep(value) {
+  if (Array.isArray(value)) return value.map(sortDeep);
+  if (!isObject(value)) return value;
+  const out = {};
+  for (const key of Object.keys(value).sort()) out[key] = sortDeep(value[key]);
+  return out;
+}
+function comparable(value) {
+  if (!isObject(value)) return JSON.stringify(sortDeep(value));
+  const stable = {};
+  for (const key of Object.keys(value).sort()) {
+    if (VOLATILE_KEYS.includes(key)) continue;
+    stable[key] = sortDeep(value[key]);
+  }
+  return JSON.stringify(stable);
+}
+function sameContent(a, b) {
+  return comparable(a) === comparable(b);
+}
+function stripMarkers(value) {
+  const out = {};
+  for (const [key, v] of Object.entries(value)) {
+    if (!MARKER_KEYS.includes(key)) out[key] = v;
+  }
+  return out;
+}
+function readPointerName(file, key) {
+  if (!fs.existsSync(file)) return null;
+  try {
+    const name = JSON.parse(fs.readFileSync(file, "utf-8"))[key];
+    return typeof name === "string" && name ? name : null;
+  } catch {
+    return null;
+  }
+}
+function localNamedFiles(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir).filter((f) => f.endsWith(".json") && !f.startsWith("_")).map((f) => f.slice(0, -".json".length)).filter((name) => name !== "default");
+}
+function componentNames(componentConfigsDir) {
+  if (!fs.existsSync(componentConfigsDir)) return [];
+  return fs.readdirSync(componentConfigsDir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name).sort();
+}
+function shippedNames(packageDataDir, subdir) {
+  try {
+    const pkgRoot = path.resolve(packageDataDir, "..", "..", "..");
+    const pkg = JSON.parse(fs.readFileSync(path.join(pkgRoot, "package.json"), "utf-8"));
+    const files = Array.isArray(pkg.files) ? pkg.files : [];
+    const prefix = `src/live-tokens/data/${subdir}/`;
+    return files.filter((f) => f.startsWith(prefix) && /^[^/]+\.json$/.test(f.slice(prefix.length))).map((f) => path.basename(f, ".json"));
+  } catch {
+    return [];
+  }
+}
+function migrateData(opts) {
+  const { componentConfigsDir, check = false } = opts;
+  const packageDataDir = opts.packageDataDir;
+  const layoutInput = {
+    dataDir: opts.dataDir,
+    colorsAndTypeDir: opts.colorsAndTypeDir,
+    themesDir: opts.themesDir,
+    configuredManifestsDir: opts.legacyManifestsDir
+  };
+  const legacyLayout = detectLegacyLayout(layoutInput);
+  const renames = legacyLayout ? planLegacyRenames(legacyLayout, layoutInput) : [];
+  if (legacyLayout && !check) applyLegacyRenames(renames);
+  const planningLegacy = legacyLayout !== null && check;
+  const colorsAndTypeDir = planningLegacy ? opts.themesDir : opts.colorsAndTypeDir;
+  const themesDir = planningLegacy ? legacyLayout.manifestsDir : opts.themesDir;
+  const reported = (p) => {
+    if (!planningLegacy) return p;
+    for (const { from, to } of renames) {
+      if (p.startsWith(from + path.sep)) return path.join(to, p.slice(from.length + 1));
+    }
+    return p;
+  };
+  const colorsRes = versionedFileResourceServer({
+    dir: colorsAndTypeDir,
+    packageDir: packageDataDir ? path.join(packageDataDir, "colors-and-type") : void 0,
+    packageOwnedNames: packageDataDir ? shippedNames(packageDataDir, "colors-and-type") : void 0
+  });
+  const themesRes = versionedFileResourceServer({
+    dir: themesDir,
+    packageDir: packageDataDir ? path.join(packageDataDir, "themes") : void 0
+  });
+  const componentResources = /* @__PURE__ */ new Map();
+  const compRes = (comp) => {
+    let r = componentResources.get(comp);
+    if (!r) {
+      r = versionedFileResourceServer({
+        dir: path.join(componentConfigsDir, comp),
+        packageDir: packageDataDir ? path.join(packageDataDir, "component-configs", comp) : void 0,
+        packageOwnedNames: packageDataDir ? shippedNames(packageDataDir, `component-configs/${comp}`) : void 0
+      });
+      componentResources.set(comp, r);
+    }
+    return r;
+  };
+  const comps = componentNames(componentConfigsDir);
+  const legacyPointers = [];
+  for (const dir of [colorsAndTypeDir, ...comps.map((c) => path.join(componentConfigsDir, c))]) {
+    for (const name of ["_active.json", "_production.json"]) {
+      const p = path.join(dir, name);
+      if (fs.existsSync(p)) legacyPointers.push(p);
+    }
+  }
+  const empty = {
+    status: "clean",
+    renames,
+    production: null,
+    recoveredThemePath: null,
+    workingWritten: [],
+    workingKept: [],
+    deletedFiles: [],
+    deletedPointers: [],
+    keptUserFiles: [],
+    notThemes: [],
+    droppedRefs: [],
+    shadowedDefaults: [],
+    upgradedThemes: []
+  };
+  if (legacyPointers.length === 0) {
+    if (!legacyLayout) return empty;
+    return { ...empty, status: check ? "planned" : "healed" };
+  }
+  const resolvers = {
+    readColorsAndType: (name) => colorsRes.readJson(name),
+    readComponentConfig: (comp, name) => compRes(comp).readJson(name),
+    normalizeColorsAndType: (colorsAndType) => colorsAndType
+  };
+  const upgradedThemes = [];
+  const notThemes = [];
+  const droppedRefs = [];
+  const themes = [];
+  for (const slug of themesRes.listNames()) {
+    let raw;
+    try {
+      raw = themesRes.readJson(slug);
+    } catch {
+      continue;
+    }
+    if (!raw) continue;
+    if (isColorsAndTypeShaped(raw)) {
+      notThemes.push(themesRes.filePath(slug));
+      continue;
+    }
+    const { theme, migrated, dropped } = normalizeTheme(raw, resolvers);
+    themes.push({ slug, theme });
+    for (const ref of dropped) {
+      droppedRefs.push(
+        `theme "${slug}": the reference ${ref} resolved to nothing, so it carries the shipped default instead`
+      );
+    }
+    if (migrated && fs.existsSync(themesRes.filePath(slug))) {
+      upgradedThemes.push(themesRes.filePath(slug));
+      if (!check) fs.writeFileSync(themesRes.filePath(slug), JSON.stringify(theme, null, 2));
+    }
+  }
+  const themeBySlug = new Map(themes.map((t) => [t.slug, t.theme]));
+  const resolveName = (res, dir, file, key) => {
+    const name = readPointerName(path.join(dir, file), key);
+    if (!name || res.existingPath(name) === null) return "default";
+    return name;
+  };
+  const readPointed = (res, name) => {
+    try {
+      return res.readJson(name);
+    } catch (err) {
+      const file = res.existingPath(name) ?? res.filePath(name);
+      throw new Error(
+        `${file} will not parse (${err instanceof Error ? err.message : String(err)}), and a retired pointer names it. Fix or delete the file, then run the migration again.`
+      );
+    }
+  };
+  const defaultConfig = (comp) => compRes(comp).readJson("default");
+  const themeConfigFor = (theme, comp) => {
+    const embedded = theme.componentConfigs[comp];
+    return embedded ? { ...embedded, component: comp } : defaultConfig(comp);
+  };
+  const prodColorsName = resolveName(colorsRes, colorsAndTypeDir, "_production.json", "productionFile");
+  const prodConfigNames = new Map(
+    comps.map((comp) => [
+      comp,
+      resolveName(compRes(comp), path.join(componentConfigsDir, comp), "_production.json", "productionFile")
+    ])
+  );
+  const prodColors = readPointed(colorsRes, prodColorsName);
+  const prodConfigs = new Map(
+    comps.map((comp) => [comp, readPointed(compRes(comp), prodConfigNames.get(comp))])
+  );
+  const allDefault = prodColorsName === "default" && [...prodConfigNames.values()].every((n) => n === "default");
+  const matchesPointedProduction = (theme) => sameContent(theme.colorsAndType, prodColors) && comps.every((comp) => sameContent(themeConfigFor(theme, comp), prodConfigs.get(comp)));
+  let production;
+  let recoveredTheme = null;
+  let recoveredThemePath = null;
+  if (allDefault) {
+    production = { slug: "default", how: "all-default" };
+  } else {
+    const match = themes.find((t) => matchesPointedProduction(t.theme));
+    if (match) {
+      production = { slug: match.slug, how: "matched" };
+    } else {
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      const componentConfigs = {};
+      for (const comp of comps) {
+        const pointed = prodConfigs.get(comp);
+        if (!isObject(pointed)) continue;
+        if (sameContent(pointed, defaultConfig(comp))) continue;
+        componentConfigs[comp] = stripMarkers(pointed);
+      }
+      recoveredTheme = {
+        name: RECOVERED_NAME,
+        createdAt: now,
+        updatedAt: now,
+        schemaVersion: THEME_SCHEMA_VERSION,
+        colorsAndType: isObject(prodColors) ? stripMarkers(prodColors) : null,
+        componentConfigs
+      };
+      const slug = nextAvailableName((n) => themesRes.existingPath(n) !== null, RECOVERED_SLUG);
+      recoveredThemePath = themesRes.filePath(slug);
+      production = { slug, how: "recovered" };
+    }
+  }
+  const activeThemeSlug = themesRes.getActiveName();
+  const activeTheme = themeBySlug.get(activeThemeSlug) ?? null;
+  const workingWritten = [];
+  const workingKept = [];
+  const planWorking = (res, live, saved) => {
+    if (!isObject(live) || sameContent(live, saved)) return;
+    if (res.hasWorking()) {
+      workingKept.push(res.workingPath);
+      return;
+    }
+    workingWritten.push(res.workingPath);
+    if (!check) res.writeWorking(stripMarkers(live));
+  };
+  const activeColorsName = resolveName(colorsRes, colorsAndTypeDir, "_active.json", "activeFile");
+  planWorking(
+    colorsRes,
+    readPointed(colorsRes, activeColorsName),
+    activeTheme?.colorsAndType ?? colorsRes.readJson("default")
+  );
+  for (const comp of comps) {
+    const activeName = resolveName(
+      compRes(comp),
+      path.join(componentConfigsDir, comp),
+      "_active.json",
+      "activeFile"
+    );
+    planWorking(
+      compRes(comp),
+      readPointed(compRes(comp), activeName),
+      activeTheme ? themeConfigFor(activeTheme, comp) : defaultConfig(comp)
+    );
+  }
+  const deletedFiles = [];
+  const keptUserFiles = [];
+  const sweep = (res, dir, savedCopies) => {
+    for (const name of localNamedFiles(dir)) {
+      if (res.isPackageFile(name)) continue;
+      let content;
+      try {
+        content = res.readJson(name);
+      } catch {
+        keptUserFiles.push(res.filePath(name));
+        continue;
+      }
+      const matched = themes.some((t) => sameContent(savedCopies(t.theme), content));
+      if (!matched) {
+        keptUserFiles.push(res.filePath(name));
+        continue;
+      }
+      deletedFiles.push(res.filePath(name));
+      if (!check) fs.unlinkSync(res.filePath(name));
+    }
+  };
+  sweep(colorsRes, colorsAndTypeDir, (theme) => theme.colorsAndType);
+  for (const comp of comps) {
+    sweep(compRes(comp), path.join(componentConfigsDir, comp), (theme) => themeConfigFor(theme, comp));
+  }
+  const shadowedDefaults = [];
+  const localDefault = path.join(colorsAndTypeDir, "default.json");
+  const packageDefault = packageDataDir ? path.join(packageDataDir, "colors-and-type", "default.json") : null;
+  if (packageDefault && fs.existsSync(localDefault) && fs.existsSync(packageDefault) && path.resolve(localDefault) !== path.resolve(packageDefault)) {
+    try {
+      const local = JSON.parse(fs.readFileSync(localDefault, "utf-8"));
+      const shipped = JSON.parse(fs.readFileSync(packageDefault, "utf-8"));
+      if (!sameContent(local, shipped)) shadowedDefaults.push(localDefault);
+    } catch {
+    }
+  }
+  if (!check) {
+    for (const p of legacyPointers) fs.unlinkSync(p);
+  }
+  if (!check) {
+    if (recoveredTheme && recoveredThemePath) {
+      themesRes.ensureDir();
+      fs.writeFileSync(recoveredThemePath, JSON.stringify(recoveredTheme, null, 2));
+    }
+    themesRes.ensureDir();
+    themesRes.setProductionName(production.slug);
+  }
+  return {
+    status: check ? "planned" : "healed",
+    renames,
+    production,
+    recoveredThemePath: recoveredThemePath && reported(recoveredThemePath),
+    workingWritten: workingWritten.map(reported),
+    workingKept: workingKept.map(reported),
+    deletedFiles: deletedFiles.map(reported),
+    deletedPointers: legacyPointers.map(reported),
+    keptUserFiles: keptUserFiles.map(reported),
+    notThemes: notThemes.map(reported),
+    droppedRefs,
+    shadowedDefaults: shadowedDefaults.map(reported),
+    upgradedThemes: upgradedThemes.map(reported)
+  };
+}
+export {
+  migrateData,
+  readLiveTokensConfig,
+  resolveDataDirs
+};

package/dist-plugin/themeTypes-DMHZOnUn.d.cts

@@ -0,0 +1,211 @@
+interface CurveAnchor {
+    x: number;
+    y: number;
+    inDx: number;
+    inDy: number;
+    outDx: number;
+    outDy: number;
+}
+
+interface Oklch {
+    l: number;
+    c: number;
+    h: number;
+}
+
+type HarmonyMode = 'complementary' | 'split-complementary' | 'triadic' | 'tetradic' | 'compound' | 'square' | 'analogous' | 'monochromatic' | 'custom';
+interface HarmonyAxis {
+    /** Hue in [0, 360). Always present, bound or not. */
+    hue: number;
+    /** Bound family label (member of HARMONY_ELIGIBLE), or null when the axis is empty. */
+    family: string | null;
+}
+
+type GradientStyle = 'linear' | 'radial' | 'conic';
+interface GradientStop {
+    position: number;
+    paletteLabel: string;
+}
+interface PaletteConfig {
+    /** Numeric OKLCH intent — the single stored basis. Unclamped: the store holds
+     *  what the user meant; gamut clamping is projection-only (derivation output,
+     *  swatch/canvas painting, hex/CSS serialization). */
+    baseColor: Oklch;
+    lightnessCurve: CurveAnchor[];
+    saturationCurve: CurveAnchor[];
+    scaleCurves: Record<string, {
+        lightness: CurveAnchor[];
+        saturation: CurveAnchor[];
+    }>;
+    curveOffset: Record<string, number>;
+    overrides: Record<string, Oklch>;
+    snappedScales: string[];
+    emptyMode?: 'solid' | 'gradient';
+    gradientStyle?: GradientStyle;
+    gradientAngle?: number;
+    gradientReverse?: boolean;
+    gradientStops?: GradientStop[];
+    gradientSize?: 'page' | 'window';
+    anchorToBase?: boolean;
+    /**
+     * Where the base color sits in the ramp while `anchorToBase` is on: the
+     * PALETTE_STEPS index whose curve anchors are pinned to the base color
+     * (lightness = base L, saturation = multiplier 100). `displacedL` /
+     * `displacedS` remember the y of a pre-existing anchor (endpoint or
+     * user-authored) the placement overwrote at that x, so moving the
+     * placement or toggling off restores it instead of deleting it.
+     * `priorLightnessEndpoints` / `priorSaturationEndpoints` remember the two
+     * endpoints exactly as they stood before the curve's first-ever placement
+     * (a smoothed reshape, not algebraically invertible the way a later
+     * scaled-handle re-placement is), so a clear can still restore the true
+     * original regardless of how many times the anchor has since moved.
+     */
+    anchorPlacement?: {
+        step: number;
+        displacedL?: number;
+        displacedS?: number;
+        priorLightnessEndpoints?: [CurveAnchor, CurveAnchor];
+        priorSaturationEndpoints?: [CurveAnchor, CurveAnchor];
+    };
+    /**
+     * Set to true by importers when they overlay `cssVariables[--color-{ns}-*]`
+     * without owning the typed-state curves. The storage-layer reconciler uses
+     * it as an opt-in switch: snap `baseColor` to the imported
+     * `--color-{ns}-500` anchor and clear the flag. Editor-authored themes
+     * never set this, so the reconciler is a strict no-op for them.
+     *
+     * Persists on disk for first-load reconciliation. After reconcile strips
+     * the palette-derived keys from `cssVariables`, subsequent reconciles find
+     * no anchor and become idempotent no-ops regardless of the flag's value.
+     */
+    _imported?: boolean;
+}
+type FontSourceKind = 'google' | 'typekit' | 'css-url' | 'font-face';
+interface FontFamily {
+    id: string;
+    name: string;
+    cssName: string;
+    weights?: number[];
+    italics?: boolean;
+}
+interface FontSource {
+    id: string;
+    kind: FontSourceKind;
+    url?: string;
+    cssText?: string;
+    families: FontFamily[];
+    label?: string;
+}
+type SystemCascadePreset = 'system-ui-sans' | 'system-ui-serif' | 'system-ui-mono';
+type GenericFamily = 'sans-serif' | 'serif' | 'monospace' | 'cursive' | 'fantasy';
+type FontStackVariable = '--font-display' | '--font-sans' | '--font-serif' | '--font-mono';
+type FontStackSlot = {
+    kind: 'project';
+    familyId: string;
+} | {
+    kind: 'system';
+    preset: SystemCascadePreset;
+} | {
+    kind: 'generic';
+    value: GenericFamily;
+};
+interface FontStack {
+    variable: FontStackVariable;
+    slots: FontStackSlot[];
+}
+/** On-disk shape of one `--gradient-N` library token. Structural mirror of the
+ *  store's `GradientToken` (like `AliasDiskValue`'s inline gradient shape) so
+ *  the file schema stays independent of store types. The rendered strings in
+ *  `cssVariables` are a projection of these for production CSS; this field is
+ *  the editable basis. */
+interface GradientDiskToken {
+    variable: string;
+    type: 'linear' | 'radial' | 'solid' | 'none';
+    angle: number;
+    radius?: number;
+    centerX?: number;
+    aspectX?: number;
+    aspectY?: number;
+    stops: {
+        position: number;
+        color: string;
+        opacity?: number;
+    }[];
+}
+/**
+ * Where a live read resolved from: the unsaved `_working` buffer, the open
+ * theme's embedded copy, or the shipped default. It says which layer answered,
+ * never whether the content was edited — applying a theme fills the buffer for
+ * every layer it carries.
+ */
+type LiveSource = 'working' | 'theme' | 'default';
+interface ColorsAndType {
+    name: string;
+    createdAt: string;
+    updatedAt: string;
+    editorConfigs: Record<string, PaletteConfig>;
+    cssVariables: Record<string, string>;
+    fontSources?: FontSource[];
+    fontStacks?: FontStack[];
+    /** Absent on files saved before gradients round-tripped; the loader keeps
+     *  the stock defaults then, which match what those files rendered. */
+    gradients?: GradientDiskToken[];
+    /** Four fixed harmony axes, each owning a hue with an optional bound family. */
+    harmonyAxes?: HarmonyAxis[];
+    /**
+     * Server-attached marker naming the open theme — the document this content
+     * belongs to, not a colors-and-type file. Set by `themeFileApi`'s GET
+     * handlers; read by `themeInit` to seed `openThemeSlug`. Not persisted.
+     */
+    _fileName?: string;
+    /** Server-attached marker: which of the three live layers answered. */
+    _source?: LiveSource;
+    /**
+     * Migration stamp. Absent on legacy files, treated as 0; the loader runs
+     * any registered theme migrations whose `fromVersion >= file.schemaVersion`.
+     * Save paths stamp the current value so resaved files skip past
+     * migrations.
+     */
+    schemaVersion?: number;
+}
+/** On-disk shape of a single alias entry. Plain strings carry the bulk of
+ *  aliases (token refs like `--surface-canvas-low` or literal CSS like `4px`);
+ *  the gradient object shape is the structured payload for component-owned
+ *  gradients that can't compress to a single string. */
+type AliasDiskValue = string | {
+    kind: 'gradient';
+    value: {
+        type: 'linear' | 'radial' | 'solid' | 'none';
+        angle: number;
+        radius?: number;
+        centerX?: number;
+        aspectX?: number;
+        aspectY?: number;
+        stops: {
+            position: number;
+            color: string;
+            opacity?: number;
+        }[];
+    };
+};
+interface ComponentConfig {
+    name: string;
+    component: string;
+    createdAt: string;
+    updatedAt: string;
+    aliases: Record<string, AliasDiskValue>;
+    config?: Record<string, unknown>;
+    /**
+     * Server-attached marker. Same role as `ColorsAndType._fileName`: the open
+     * theme, not a config file. Set by the component-configs GET handlers.
+     */
+    _fileName?: string;
+    /** Server-attached marker: which of the three live layers answered. */
+    _source?: LiveSource;
+    /**
+     * Migration stamp. Absent on legacy files, treated as 0. See `ColorsAndType.schemaVersion`.
+     */
+    schemaVersion?: number;
+}
+
+export type { AliasDiskValue as A, ColorsAndType as C, FontSource as F, GradientDiskToken as G, HarmonyMode as H, Oklch as O, ComponentConfig as a, FontStack as b };