basalt-ui 1.28.0 → 1.29.1

package/dist/cli/init.d.ts

@@ -0,0 +1,4 @@
+import type { ScaffoldFlags } from './index.js';
+/** Scaffold all managed files into the consumer repo, then write the manifest. Idempotent. Returns 0. */
+export declare function init(cwd?: string, scaffoldFlags?: ScaffoldFlags): number;
+//# sourceMappingURL=init.d.ts.map

package/dist/cli/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/cli/init.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAmB,aAAa,EAAE,MAAM,SAAS,CAAA;AA4C7D,yGAAyG;AACzG,wBAAgB,IAAI,CAAC,GAAG,GAAE,MAAsB,EAAE,aAAa,GAAE,aAAkB,GAAG,MAAM,CAgM3F"}

package/dist/cli/init.js

@@ -0,0 +1,165 @@
+import { existsSync } from "node:fs";
+import { relative, resolve } from "node:path";
+import { deriveSpacing } from "../tokens/index.js";
+import {
+  MANIFEST_PATH,
+  findBasaltInstall,
+  managedFiles,
+  mergeOxlintExtends,
+  normalizeForLedger,
+  patchPackageJson,
+  pruneRetiredManagedFiles,
+  readManifest,
+  reconcileRoots,
+  relativePosix,
+  renderContext,
+  reportPrune,
+  resolvePeerFlags,
+  resolvePlacement,
+  rootsNotices,
+  sha256,
+  shippedAssetPath,
+  unitState,
+  writeFileEnsuringDir,
+  writeUnit
+} from "./index.js";
+import { readOxlintPresetPlugins } from "./sync.js";
+const KEPT_FILE_COST = {
+  ".oxlintrc.json": "the shipped oxlint preset (the basalt/* design rules AND the jsx-a11y / import / promise / unicorn plugins) is NOT active \u2014 nothing else turns it on, and every gate stays green without it. Re-run with `--merge-lint` to splice the extends in, or add it by hand.",
+  "lefthook.yml": "the pre-commit oxlint / oxfmt / check-theme jobs are not wired \u2014 add `extends: [<preset>]` to your own file.",
+  ".github/workflows/check.yml": "CI does not run check-theme or the sync drift gate \u2014 copy those steps into your own workflow.",
+  ".oxfmtrc.json": "your existing formatter config stands; basalt formats nothing on its own.",
+  "DESIGN.md": "the design brief Claude reads is yours, not the seeded one."
+};
+function init(cwd = process.cwd(), scaffoldFlags = {}) {
+  const install = findBasaltInstall(cwd);
+  if (install.dir === null) {
+    console.error(
+      `\u26A0 basalt-ui init: basalt-ui does not resolve from ${cwd} or any directory above it \u2014 the seeded \`extends\` paths and CI steps are being written against the repo root by assumption. Install basalt-ui here (or at the repo root) and re-run \`basalt-ui init\` so they resolve.`
+    );
+  }
+  const rootsState = reconcileRoots(cwd, { write: true });
+  const ctx = renderContext(cwd);
+  const lintScript = `oxlint . && ${ctx.vars.BASALT_BIN} check-theme`;
+  const seededLintScript = patchPackageJson(cwd, (pkg) => {
+    const scripts = pkg["scripts"] ?? {};
+    if (scripts["lint:basalt"] !== void 0) return false;
+    pkg["scripts"] = { ...scripts, "lint:basalt": lintScript };
+    return true;
+  });
+  const manifest = readManifest(cwd);
+  const peers = resolvePeerFlags(cwd, scaffoldFlags);
+  const placement = resolvePlacement(cwd);
+  const files = managedFiles(peers, placement);
+  const writtenFiles = [];
+  const keptFiles = [];
+  const missingSources = [];
+  for (const file of files) {
+    const state = unitState(file, cwd, ctx);
+    if (state.desired === null) {
+      missingSources.push(file.source);
+      continue;
+    }
+    const destExists = existsSync(resolve(cwd, file.dest));
+    if (!file.markers && destExists) {
+      manifest.files[file.dest] = sha256(normalizeForLedger(state.desired));
+      keptFiles.push(file.dest);
+      continue;
+    }
+    const hash = writeUnit(file, cwd, state.desired);
+    manifest.files[file.dest] = hash;
+    writtenFiles.push(file.dest);
+  }
+  const pruned = pruneRetiredManagedFiles(cwd, manifest, files);
+  const mergeLint = scaffoldFlags.mergeLint === true ? mergeOxlintExtends(cwd, ctx.vars.OXLINT_PRESET_PATH) : null;
+  manifest.basaltVersion = ctx.vars.BASALT_VERSION;
+  manifest.spacingScale = { ...deriveSpacing(0).scale };
+  writeFileEnsuringDir(resolve(cwd, MANIFEST_PATH), `${JSON.stringify(manifest, null, 2)}
+`);
+  console.log(
+    `basalt-ui init: ${writtenFiles.length} written, ${keptFiles.length} kept, manifest at ${MANIFEST_PATH}`
+  );
+  reportPrune(pruned);
+  if (missingSources.length > 0) {
+    console.log(
+      `basalt-ui init: ${missingSources.length} shipped asset(s) not present, skipped: ${missingSources.join(", ")}`
+    );
+  }
+  if (keptFiles.length > 0) {
+    console.log(`
+Kept (already present \u2014 basalt did not touch them):`);
+    for (const dest of keptFiles) {
+      const cost = KEPT_FILE_COST[dest];
+      console.log(cost === void 0 ? `  \xB7 ${dest}` : `  \xB7 ${dest} \u2014 ${cost}`);
+    }
+  }
+  if (mergeLint !== null) {
+    const mergeMessage = {
+      added: `spliced "${ctx.vars.OXLINT_PRESET_PATH}" into the existing .oxlintrc.json extends`,
+      already: ".oxlintrc.json already extends the shipped preset \u2014 nothing to do",
+      absent: "no existing .oxlintrc.json to merge into (the seeded one already extends the preset)",
+      unreadable: ".oxlintrc.json is not valid JSON \u2014 merge the extends entry by hand",
+      "has-comments": `.oxlintrc.json carries comments; rewriting it would delete them (usually the reason each rule is off). Add "extends": ["${ctx.vars.OXLINT_PRESET_PATH}"] as the first entry by hand.`
+    };
+    console.log(`basalt-ui init: --merge-lint \u2014 ${mergeMessage[mergeLint]}`);
+  }
+  const rootsMessages = rootsNotices(rootsState);
+  for (const line of rootsMessages.log) console.log(`basalt-ui init: ${line}`);
+  for (const line of rootsMessages.error) console.error(`\u26A0 basalt-ui init: ${line}`);
+  if (seededLintScript) {
+    console.log(`basalt-ui init: added the "lint:basalt" script (${lintScript}) to package.json.`);
+  }
+  if (!placement.isPackageRepoRoot) {
+    console.log(
+      `basalt-ui init: skipped lefthook.yml (this package is not the repo root \u2014 repo root detected at ${placement.repoRoot}) \u2014 lefthook only reads config at the repo root; extend ${ctx.vars.LEFTHOOK_PRESET_PATH} from your root lefthook.yml instead, and give its check-theme command \`env: { BASALT_CWD: ${relativePosix(placement.repoRoot, cwd)} }\` so the guard runs where your basalt config actually lives.`
+    );
+    console.log(
+      `basalt-ui init: skipped .github/workflows/check.yml (this package is not the repo root \u2014 repo root detected at ${placement.repoRoot}) \u2014 GitHub Actions only reads .github/ at the repo root; copy the steps from ${shippedAssetPath(install, placement.repoRoot, "configs/check.yml")} into your root CI workflow instead.`
+    );
+  }
+  if (placement.relocatedQueryClient !== null) {
+    console.log(
+      `basalt-ui init: skipped src/query-client.ts (found an existing query client at ${relative(cwd, placement.relocatedQueryClient)}) \u2014 import it from there instead of re-seeding at the original path.`
+    );
+  }
+  if (!peers.hasQuery) {
+    console.log(
+      "basalt-ui init: skipped src/query-client.ts (no @tanstack/react-query dependency detected) \u2014 install it, or re-run with --with-query, to scaffold it."
+    );
+  }
+  if (!peers.hasRouter || !peers.hasQuery) {
+    console.log(
+      "basalt-ui init: skipped src/routes/__root.tsx (needs both @tanstack/react-router and @tanstack/react-query) \u2014 install both, or re-run with --with-router --with-query, to scaffold it."
+    );
+  }
+  console.log(
+    `
+Theme guard hook: add to .claude/settings.json \u2192 hooks.PreToolUse to catch violations before they land:
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [{ "type": "command", "command": "${ctx.vars.BASALT_BIN} guard-hook" }]
+      }
+    ]
+  }`
+  );
+  const presetPlugins = readOxlintPresetPlugins(ctx.pkgRoot);
+  if (presetPlugins.length > 0) {
+    console.log(
+      `
+Lint debt: adopting the shipped oxlint preset on an EXISTING app is not a no-op \u2014 it turns on ${presetPlugins.length} plugins (${presetPlugins.join(", ")}) plus the basalt/* design rules, on code never linted against them. Run \`oxlint .\` now and triage the count before your next commit; turn a rule off in your own .oxlintrc.json with a written reason rather than blanket-disabling a plugin.`
+    );
+  }
+  console.log(
+    "Activate the hooks: `lefthook install` \u2014 the seeded lefthook.yml is inert until the git hooks are written, and looks configured either way."
+  );
+  console.log(
+    `
+First run: run \`${ctx.vars.BASALT_BIN} check-theme\` next (or \`bun run lint:basalt\`), then tune the per-rule \`basalt.*\` config keys in package.json for anything that fires \u2014 do not mass-\`theme-allow\` findings. Then \`basalt-ui doctor\` to confirm the wiring actually took.`
+  );
+  return 0;
+}
+export {
+  init
+};

package/dist/cli/sync.d.ts

@@ -0,0 +1,43 @@
+/** The oxlint plugins the shipped preset switches on — read from the preset, never restated. */
+export declare function readOxlintPresetPlugins(pkgRoot: string): string[];
+export type SyncOptions = {
+    force?: boolean;
+    check?: boolean;
+    /** The raw flag list, read for `--tokens-only` / `--framework` exactly as check-theme reads it. */
+    flags?: readonly string[];
+};
+/**
+ * The nearest ANCESTOR of `dir` (exclusive) carrying a basalt manifest, or null.
+ *
+ * `resolveProjectDir` resolves to exactly one directory — `BASALT_CWD` when set, else the
+ * invocation cwd — and never walks. The shape that produced this function is the one that resolver
+ * doesn't cover: a consumer standing in `apps/dashboard`, the package that actually depends on
+ * basalt-ui, whose install lives at the repo root above it. With nothing walking up, `sync` read
+ * "no manifest here" as "nothing scaffolded yet" and wrote a complete second consumer beside the
+ * real one.
+ */
+/**
+ * The sentence `sync` prints when the cwd carries no install but an ancestor does.
+ *
+ * Shared with `doctor` deliberately. The two commands already share `resolveProjectDir`, but not
+ * the ADVICE: `sync` named the parent install (1.22.0's "stop scaffolding a second consumer" fix)
+ * while `doctor`, in the same directory, kept prescribing `basalt-ui init` — so following doctor
+ * literally performed the exact mistake that fix exists to prevent. One function, one sentence.
+ */
+export declare function parentInstallAdvice(cwd: string, parent: string, verb: string): string;
+export declare function findManifestAbove(dir: string): string | null;
+/**
+ * Reconcile managed files with the shipped versions via a sha256 three-way compare.
+ *
+ * - `--check` makes NO writes; exits non-zero if any managed file is out-of-date or locally drifted
+ *   (a CI freshness gate), exit 0 when all current.
+ * - `--force` overwrites locally-drifted files instead of skipping them.
+ *
+ * Runs against `resolveProjectDir(cwd)`, exactly as `check-theme` and `doctor` do — and then
+ * REFUSES rather than scaffolding when the resolved project has no manifest. See
+ * {@link findManifestAbove} for the failure that bought this: `sync` is the drift refresh and
+ * `init` is the scaffold, so placing twenty files on a cwd that was never a consumer is a decision
+ * `sync` does not get to make silently.
+ */
+export declare function sync(opts?: SyncOptions, invocationCwd?: string): number;
+//# sourceMappingURL=sync.d.ts.map

package/dist/cli/sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/cli/sync.ts"],"names":[],"mappings":"AA2CA,gGAAgG;AAChG,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CASjE;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,mGAAmG;IACnG,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAC1B,CAAA;AAED;;;;;;;;;GASG;AACH;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAKrF;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQ5D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,IAAI,CAAC,IAAI,GAAE,WAAgB,EAAE,aAAa,GAAE,MAAsB,GAAG,MAAM,CAqN1F"}

package/dist/cli/sync.js

@@ -0,0 +1,206 @@
+import { existsSync } from "node:fs";
+import { relative, resolve } from "node:path";
+import { deriveSpacing } from "../tokens/index.js";
+import {
+  MANIFEST_PATH,
+  basaltPresetEntry,
+  classify,
+  conflictingProfileFlags,
+  declaredProfile,
+  diffSummary,
+  findBasaltInstall,
+  inspectLefthookGate,
+  isStringArray,
+  managedFiles,
+  normalizeForLedger,
+  parseJsonc,
+  pruneRetiredManagedFiles,
+  readBasaltConfig,
+  readIfExists,
+  readManifest,
+  readSource,
+  reconcileRoots,
+  relativePosix,
+  renderContext,
+  reportPrune,
+  resolvePeerFlags,
+  resolvePlacement,
+  resolveProjectDir,
+  rootsNotices,
+  sha256,
+  shippedAssetPath,
+  unitState,
+  writeFileEnsuringDir,
+  writeUnit
+} from "./index.js";
+function readOxlintPresetPlugins(pkgRoot) {
+  const raw = readSource(pkgRoot, "configs/oxlint.json");
+  if (raw === null) return [];
+  try {
+    const plugins = JSON.parse(raw).plugins;
+    return isStringArray(plugins) ? plugins : [];
+  } catch {
+    return [];
+  }
+}
+function parentInstallAdvice(cwd, parent, verb) {
+  return `This repo's install is at ${relativePosix(cwd, parent)} (${parent}) \u2014 run ${verb} there, or set BASALT_CWD to it.`;
+}
+function findManifestAbove(dir) {
+  let current = resolve(dir, "..");
+  for (; ; ) {
+    if (existsSync(resolve(current, MANIFEST_PATH))) return current;
+    const parent = resolve(current, "..");
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+function sync(opts = {}, invocationCwd = process.cwd()) {
+  const syncFlags = opts.flags ?? [];
+  if (conflictingProfileFlags(syncFlags)) {
+    console.error("basalt-ui sync: --tokens-only and --framework are alternatives \u2014 pass one.");
+    return 1;
+  }
+  const project = resolveProjectDir(invocationCwd);
+  const cwd = project.dir;
+  if (project.relocatedFrom !== null) {
+    console.log(`basalt-ui sync: BASALT_CWD relocated from ${project.relocatedFrom} to ${cwd}.`);
+  }
+  if (declaredProfile(readBasaltConfig(cwd), syncFlags) === "tokens-only") {
+    console.log(
+      `basalt-ui sync: ${MANIFEST_PATH}: n/a \u2014 a tokens-only consumer has no scaffold to reconcile. The token layer is refreshed by re-running \`basalt-ui tokens:css\`, and \`tokens:css --check\` is its drift gate. Pass --framework to force the full profile.`
+    );
+    return 0;
+  }
+  if (!existsSync(resolve(cwd, MANIFEST_PATH))) {
+    const elsewhere = findManifestAbove(cwd);
+    const wouldWrite = managedFiles(resolvePeerFlags(cwd, {}), resolvePlacement(cwd)).length;
+    console.error(
+      `\u2716 basalt-ui sync: no ${MANIFEST_PATH} at ${cwd} \u2014 refusing to scaffold. \`sync\` refreshes an EXISTING basalt install; creating one is \`basalt-ui init\`'s decision, and continuing here would write ${wouldWrite} managed file(s) into this directory.` + (elsewhere === null ? " No manifest exists at any ancestor either \u2014 run `basalt-ui init` here if this package really is meant to be a consumer." : ` ${parentInstallAdvice(cwd, elsewhere, "sync")}`)
+    );
+    return 1;
+  }
+  const rootsState = reconcileRoots(cwd, { write: opts.check !== true });
+  const ctx = renderContext(cwd);
+  const manifest = readManifest(cwd);
+  const peers = resolvePeerFlags(cwd, {});
+  const placement = resolvePlacement(cwd);
+  const files = managedFiles(peers, placement);
+  let updated = 0;
+  let created = 0;
+  let recreated = 0;
+  let skippedDrift = 0;
+  let staleForCheck = 0;
+  const driftLines = [];
+  const missingSources = [];
+  for (const file of files) {
+    const state = unitState(file, cwd, ctx);
+    if (state.desired === null) {
+      missingSources.push(file.source);
+      continue;
+    }
+    const tracked = manifest.files[file.dest] !== void 0;
+    if (file.mode === "seed") {
+      if (state.current === null && !opts.check) {
+        manifest.files[file.dest] = writeUnit(file, cwd, state.desired);
+        if (tracked) recreated++;
+        else created++;
+      }
+      continue;
+    }
+    const kind = classify(state, manifest.files[file.dest]);
+    if (kind === "current") {
+      manifest.files[file.dest] = sha256(normalizeForLedger(state.desired));
+      continue;
+    }
+    if (kind === "drifted" && !opts.force) {
+      driftLines.push(diffSummary(file, state));
+      staleForCheck++;
+      skippedDrift++;
+      continue;
+    }
+    staleForCheck++;
+    if (opts.check) continue;
+    manifest.files[file.dest] = writeUnit(file, cwd, state.desired);
+    if (kind !== "missing") updated++;
+    else if (tracked) recreated++;
+    else created++;
+  }
+  const pruned = pruneRetiredManagedFiles(cwd, manifest, files, {
+    dryRun: opts.check === true,
+    force: opts.force === true
+  });
+  staleForCheck += pruned.removed.length + pruned.drifted.length;
+  if (!placement.isPackageRepoRoot) {
+    console.log(
+      `basalt-ui sync: skipped lefthook.yml (this package is not the repo root \u2014 repo root detected at ${placement.repoRoot}) \u2014 lefthook only reads config at the repo root; extend node_modules/basalt-ui/configs/lefthook.yml from your root lefthook.yml instead.`
+    );
+    console.log(
+      `basalt-ui sync: skipped .github/workflows/check.yml (this package is not the repo root \u2014 repo root detected at ${placement.repoRoot}) \u2014 GitHub Actions only reads .github/ at the repo root; extend node_modules/basalt-ui/configs/check.yml from your root CI workflow instead.`
+    );
+  }
+  if (placement.relocatedQueryClient !== null) {
+    console.log(
+      `basalt-ui sync: skipped src/query-client.ts (found an existing query client at ${relative(cwd, placement.relocatedQueryClient)}) \u2014 import it from there instead of re-seeding at the original path.`
+    );
+  }
+  const rootsMessages = rootsNotices(rootsState);
+  for (const line of rootsMessages.log) console.log(`basalt-ui sync: ${line}`);
+  for (const line of rootsMessages.error) console.error(`\u26A0 basalt-ui sync: ${line}`);
+  const install = findBasaltInstall(cwd);
+  const lefthookGate = inspectLefthookGate(placement.repoRoot);
+  if (lefthookGate.kind === "absent") {
+    console.error(
+      `\u26A0 basalt-ui sync: ${lefthookGate.file}: \`lefthook dump\` resolves the merged config and no pre-commit command runs check-theme \u2014 there is no pre-commit gate. Add "extends: [${shippedAssetPath(install, placement.repoRoot, "configs/lefthook.yml")}]".`
+    );
+  }
+  const oxlintrcRaw = readIfExists(resolve(cwd, ".oxlintrc.json"));
+  const oxlintEntry = oxlintrcRaw === null ? null : basaltPresetEntry(parseJsonc(oxlintrcRaw)?.["extends"]);
+  if (oxlintEntry !== null && !existsSync(resolve(cwd, oxlintEntry))) {
+    console.error(
+      `\u26A0 basalt-ui sync: .oxlintrc.json extends "${oxlintEntry}", which does not exist \u2014 oxlint refuses to start on a missing extends target (\`NotFound\`). Repoint it at "${shippedAssetPath(install, cwd, "configs/oxlint.json")}".`
+    );
+  }
+  if (opts.check) {
+    if (driftLines.length > 0) {
+      console.error("basalt-ui sync --check: locally-drifted managed files:");
+      for (const l of driftLines) console.error(l);
+    }
+    const retired = [...pruned.removed, ...pruned.drifted];
+    if (retired.length > 0) {
+      console.error(
+        `basalt-ui sync --check: ${retired.length} retired rule/skill file(s) still present: ${retired.join(", ")} \u2014 run \`basalt-ui sync\`.`
+      );
+    }
+    if (staleForCheck > 0) {
+      console.error(`basalt-ui sync --check: ${staleForCheck} managed file(s) out of date.`);
+      return 1;
+    }
+    console.log("\u2713 basalt-ui sync --check: all managed files current.");
+    return 0;
+  }
+  manifest.basaltVersion = ctx.vars.BASALT_VERSION;
+  manifest.spacingScale = { ...deriveSpacing(0).scale };
+  writeFileEnsuringDir(resolve(cwd, MANIFEST_PATH), `${JSON.stringify(manifest, null, 2)}
+`);
+  console.log(
+    `basalt-ui sync: ${updated} updated, ${created} created, ${recreated} recreated, ${skippedDrift} skipped (drift), ${pruned.removed.length} retired.`
+  );
+  reportPrune(pruned);
+  if (driftLines.length > 0) {
+    console.log("Locally-edited files were skipped (run with --force to overwrite):");
+    for (const l of driftLines) console.log(l);
+  }
+  if (missingSources.length > 0) {
+    console.log(
+      `basalt-ui sync: ${missingSources.length} shipped asset(s) not present, skipped: ${missingSources.join(", ")}`
+    );
+  }
+  return 0;
+}
+export {
+  findManifestAbove,
+  parentInstallAdvice,
+  readOxlintPresetPlugins,
+  sync
+};

package/dist/cli/tokens-css.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Space- and number-normalize the argument list of a legacy color function so the emitted file
+ * survives a normal repo's formatter.
+ *
+ * This is FORMATTING ONLY and deliberately the CLI's single deviation from "print exactly what
+ * `buildPaletteCss` returned": `rgba(255,255,255,0.6)` and `rgba(255, 255, 255, 0.6)` are the same
+ * colour, the shipped palette emits the first form on the dark side and the second on the light
+ * side, and a consumer committing the output ate a lint-ignore entry for the difference. The token
+ * VALUES are untouched — nothing here can change what basalt's tokens are.
+ *
+ * Trailing zeros go the same way and for the same reason: prettier rewrites `0.10` → `0.1`, so the
+ * two `rgba(28, 25, 23, 0.10)` alphas in the light shadow tokens were the whole reason the one
+ * framework-free consumer still could not lint its committed sheet — `--fix` and `tokens:css
+ * --check` disagreed forever, and the lint-ignore entry survived two releases. Only a bare decimal
+ * literal is touched (never a `%`, a `var()` or a unit), and `0.10`/`0.1` are the same number.
+ *
+ * Exported for tests, so the expectation can be computed rather than restated.
+ */
+export declare function normalizeColorFunctions(css: string): string;
+/**
+ * tokens:css — emit the `--vx-*` stylesheet, optionally retargeted.
+ *
+ * The escape hatch from installing anything: a static site runs this once (`bunx basalt-ui
+ * tokens:css --selector-attribute data-theme --out src/tokens.css`) and consumes basalt's token
+ * system as plain CSS, with no package in its dependency tree at all. `basalt-ui/tokens.css` is the
+ * same artifact for a consumer that does install; this command exists for the ones that shouldn't
+ * have to just to change a selector.
+ *
+ * It parses flags and calls `buildPaletteCss` for the token VALUES — the CLI and the API must not
+ * be able to disagree about what basalt's tokens are. What it adds is strictly file framing for an
+ * artifact a consumer COMMITS: the `@generated` header (the guard's skip marker), a trailing
+ * newline, and `rgba()` argument spacing. All three were reported by the one framework-free
+ * consumer as the reasons the output could not simply be committed.
+ */
+export declare function tokensCss(flags: string[], cwd?: string): number;
+/**
+ * fonts:css — emit the shipped `--basalt-font-*` stacks as plain CSS.
+ *
+ * The typeface half of the framework-free route, which had no supported path at all: `tokens.css`
+ * emits no font vars, `styles.css` is the one place the defaults live and a framework-free consumer
+ * is told not to import it, and `buildFontsCss` returns `''` unless the caller already knows the
+ * stacks. The one non-Mantine consumer lost its font identity entirely and hardcoded the stacks —
+ * which the theme guard then flagged as `raw-font-family`.
+ *
+ * The declarations are READ from the shipped stylesheet rather than restated here, so this command
+ * and `basalt-ui/styles.css` can never name different typefaces. Note the fonts themselves are
+ * `@fontsource-variable/*` packages: without them the stacks fall through to their own system
+ * fallbacks, which is the intended framework-free behaviour.
+ */
+export declare function fontsCss(flags: string[], cwd?: string): number;
+//# sourceMappingURL=tokens-css.d.ts.map

package/dist/cli/tokens-css.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens-css.d.ts","sourceRoot":"","sources":["../../src/cli/tokens-css.ts"],"names":[],"mappings":"AAkCA;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAK3D;AA4DD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,GAAG,GAAE,MAAsB,GAAG,MAAM,CA4E9E;AAgBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,GAAG,GAAE,MAAsB,GAAG,MAAM,CAa7E"}

package/dist/cli/tokens-css.js

@@ -0,0 +1,165 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { GENERATED_HEADER_LINE } from "../guard/index.js";
+import { buildPaletteCss } from "../tokens/index.js";
+import { packageRoot, readFrameworkVersion, readIfExists, readSource } from "./index.js";
+function flagValue(flags, name) {
+  const i = flags.indexOf(name);
+  if (i === -1) return void 0;
+  const value = flags[i + 1];
+  return value === void 0 || value.startsWith("--") ? void 0 : value;
+}
+function generatedHeader(version, command, flags) {
+  const shown = flags.filter((f) => f !== "--check");
+  const invocation = shown.length === 0 ? command : `${command} ${shown.join(" ")}`;
+  return `${GENERATED_HEADER_LINE}
+/* basalt-ui ${version} \u2014 \`basalt-ui ${invocation}\` */
+`;
+}
+function normalizeColorFunctions(css) {
+  return css.replace(/\b(rgba?|hsla?)\(([^()]*)\)/g, (_match, fn, args) => {
+    const parts = args.split(",").map((part) => normalizeCssNumber(part.trim()));
+    return `${fn}(${parts.join(", ")})`;
+  });
+}
+function normalizeCssNumber(arg) {
+  if (!/^\d+\.\d+$/.test(arg)) return arg;
+  return arg.replace(/\.?0+$/, "");
+}
+const SCHEME_CLASS_SENTINEL = "data-basalt-scheme-class";
+function emitGeneratedCss(content, flags, cwd, command) {
+  const out = flagValue(flags, "--out");
+  const check = flags.includes("--check");
+  if (out === void 0) {
+    if (check) {
+      console.error(
+        `${command}: --check needs --out <path> \u2014 there is nothing to compare stdout to.`
+      );
+      return 1;
+    }
+    process.stdout.write(content);
+    return 0;
+  }
+  const target = isAbsolute(out) ? out : resolve(cwd, out);
+  const shown = relative(cwd, target) || target;
+  if (check) {
+    const onDisk = readIfExists(target);
+    if (onDisk === null) {
+      console.error(
+        `\u2716 ${command} --check: ${shown} does not exist \u2014 run without --check to write it.`
+      );
+      return 1;
+    }
+    if (onDisk === content) {
+      console.log(`\u2713 ${command} --check: ${shown} is up to date.`);
+      return 0;
+    }
+    const diskLines = onDisk.split("\n");
+    const wantLines = content.split("\n");
+    console.error(
+      `\u2716 ${command} --check: ${shown} differs from what \`basalt-ui ${command}\` emits today (on disk ${diskLines.length} lines, emitted ${wantLines.length}) \u2014 re-run the same command without --check and commit the result. A basalt-ui release moves the \`@generated\` header line, so this is byte-exact \u2014 expect a no-op commit on every upgrade that ships a committed generated sheet.`
+    );
+    return 1;
+  }
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, content);
+  console.log(`wrote ${content.split("\n").length} lines \u2192 ${shown}`);
+  return 0;
+}
+function tokensCss(flags, cwd = process.cwd()) {
+  const attribute = flagValue(flags, "--selector-attribute");
+  const schemeClass = flagValue(flags, "--selector-class");
+  const lightClass = flagValue(flags, "--light-class");
+  const darkValue = flagValue(flags, "--dark-value");
+  const lightValue = flagValue(flags, "--light-value");
+  const defaultScheme = flagValue(flags, "--default-scheme");
+  const only = flagValue(flags, "--only");
+  if (defaultScheme !== void 0 && !["dark", "light", "none"].includes(defaultScheme)) {
+    console.error(
+      `tokens:css: --default-scheme must be dark, light or none (got '${defaultScheme}')`
+    );
+    return 1;
+  }
+  if (only !== void 0 && !["core", "all"].includes(only)) {
+    console.error(`tokens:css: --only must be core or all (got '${only}')`);
+    return 1;
+  }
+  if (schemeClass !== void 0 && attribute !== void 0) {
+    console.error(
+      "tokens:css: --selector-class and --selector-attribute are alternatives \u2014 pass one."
+    );
+    return 1;
+  }
+  if (schemeClass !== void 0 && /[^\w-]/.test(schemeClass)) {
+    console.error(
+      `tokens:css: --selector-class must be a plain CSS class name (got '${schemeClass}')`
+    );
+    return 1;
+  }
+  if (lightClass !== void 0 && /[^\w-]/.test(lightClass)) {
+    console.error(`tokens:css: --light-class must be a plain CSS class name (got '${lightClass}')`);
+    return 1;
+  }
+  const resolvedDarkValue = schemeClass !== void 0 ? schemeClass : darkValue;
+  const resolvedLightValue = schemeClass !== void 0 ? lightClass ?? "light" : lightValue;
+  const resolvedAttribute = schemeClass !== void 0 ? SCHEME_CLASS_SENTINEL : attribute;
+  const scheme = {
+    ...resolvedAttribute === void 0 ? {} : { attribute: resolvedAttribute },
+    ...resolvedDarkValue === void 0 ? {} : { darkValue: resolvedDarkValue },
+    ...resolvedLightValue === void 0 ? {} : { lightValue: resolvedLightValue }
+  };
+  let css = buildPaletteCss({
+    ...Object.keys(scheme).length === 0 ? {} : { scheme },
+    ...defaultScheme === void 0 ? {} : { defaultScheme },
+    ...flags.includes("--media-fallback") ? { mediaFallback: true } : {},
+    ...only === void 0 ? {} : { only },
+    // The tokens-only consumer is exactly the one who writes these names by hand, so they are also
+    // the one who wants the deprecated camelCase aliases gone — and this command is their only
+    // entry point. Without the flag the CLI and the API could disagree about what basalt's tokens
+    // are, which is the one thing this command is documented never to allow.
+    ...flags.includes("--no-legacy-aliases") ? { legacyAliases: false } : {}
+  });
+  if (schemeClass !== void 0) {
+    css = css.replace(
+      new RegExp(`\\[${SCHEME_CLASS_SENTINEL}='([\\w-]+)'\\]`, "g"),
+      (_match, value) => `.${value}`
+    );
+  }
+  const version = readFrameworkVersion(packageRoot());
+  const content = `${generatedHeader(version, "tokens:css", flags)}${normalizeColorFunctions(css)}
+`;
+  return emitGeneratedCss(content, flags, cwd, "tokens:css");
+}
+function readShippedFontDecls(pkgRoot) {
+  const css = readSource(pkgRoot, "dist/styles.css") ?? readSource(pkgRoot, "src/styles.css");
+  if (css === null) return [];
+  const decls = [];
+  for (const match of css.matchAll(/(--basalt-font[\w-]*)\s*:\s*([^;]+);/g)) {
+    decls.push({
+      name: match[1],
+      value: match[2].replace(/\s+/g, " ").trim()
+    });
+  }
+  return decls;
+}
+function fontsCss(flags, cwd = process.cwd()) {
+  const pkgRoot = packageRoot();
+  const decls = readShippedFontDecls(pkgRoot);
+  if (decls.length === 0) {
+    console.error(
+      "fonts:css: could not read the shipped font stacks from styles.css \u2014 this is a packaging bug in basalt-ui, not a config error."
+    );
+    return 1;
+  }
+  const body = `:root {
+${decls.map((d) => `  ${d.name}: ${d.value};`).join("\n")}
+}
+`;
+  const header = generatedHeader(readFrameworkVersion(pkgRoot), "fonts:css", flags);
+  return emitGeneratedCss(`${header}${body}`, flags, cwd, "fonts:css");
+}
+export {
+  fontsCss,
+  normalizeColorFunctions,
+  tokensCss
+};

package/dist/commands/define-commands.js

@@ -1,4 +1,4 @@
-import { isDev } from "../utils/is-dev.js";
+import { isDev } from "../common/is-dev.js";
 let activeCommands = {};
 function defineCommands(spec) {
   activeCommands = spec;

package/dist/commands/define-overlays.js

@@ -1,6 +1,6 @@
 import { useEffect } from "react";
 import { missingLayer } from "../common/errors.js";
-import { isDev } from "../utils/is-dev.js";
+import { isDev } from "../common/is-dev.js";
 let modalsPromise;
 function loadModals() {
   modalsPromise ??= import("@mantine/modals").then((m) => m.modals).catch(() => void 0);