basalt-ui 1.40.3 → 2.0.0

package/dist/cli/index.js

@@ -7,6 +7,7 @@ import {
   readFileSync,
   rmdirSync,
   statSync,
+  realpathSync,
   unlinkSync,
   writeFileSync
 } from "node:fs";
@@ -33,9 +34,7 @@ const GUARD_PASSTHROUGH = {
   rawHtmlLayout: true,
   inlineSpacing: true,
   inlineDisplay: true,
-  rawVisxAxis: true,
   rawMotionValue: true,
-  chartMissingAriaLabel: true,
   rawFormControl: true,
   sub16InputFont: true,
   severity: true
@@ -107,7 +106,7 @@ function readBasaltConfig(cwd) {
     return {};
   }
 }
-const SCANNABLE_EXT = /\.(?:tsx?|jsx|astro|vue|css|html?|webmanifest)$/;
+const SCANNABLE_EXT = /\.(?:tsx?|jsx|[cm][jt]s|astro|vue|css|html?|webmanifest)$/;
 function walkSourceFiles(dir, out = []) {
   let entries;
   try {
@@ -233,12 +232,17 @@ function waiverHintFor(relPath, profile) {
 const BLOCK_BEGIN_PREFIX = "<!-- basalt:begin";
 const BLOCK_END = "<!-- basalt:end -->";
 const MANIFEST_PATH = ".basalt/manifest.json";
+const AGENTS_MD = "AGENTS.md";
+const LEGACY_BLOCK_HOST = "CLAUDE.md";
 function sha256(text) {
   return createHash("sha256").update(text, "utf8").digest("hex");
 }
 function readIfExists(abs) {
-  if (!existsSync(abs)) return null;
-  return readFileSync(abs, "utf8");
+  try {
+    return readFileSync(abs, "utf8");
+  } catch {
+    return null;
+  }
 }
 function readSource(pkgRoot, source) {
   return readIfExists(resolve(pkgRoot, source));
@@ -308,6 +312,45 @@ function applyBlock(host, block) {
 ${block.trim()}
 `;
 }
+function sameFile(a, b) {
+  try {
+    return realpathSync(a) === realpathSync(b);
+  } catch (error) {
+    if (error.code === "ENOENT") return false;
+    throw error;
+  }
+}
+function hasManagedBlock(host) {
+  return host !== null && host.includes(BLOCK_BEGIN_PREFIX);
+}
+function scanBlock(host) {
+  const begin = hasManagedBlock(host);
+  if (!begin && !host.includes(BLOCK_END)) return { region: null, problem: null };
+  const bad = (problem) => ({ region: null, problem });
+  if (!begin) return bad(`\`${BLOCK_END}\` with no \`${BLOCK_BEGIN_PREFIX}\``);
+  let region;
+  try {
+    region = findBlockRegion(host);
+  } catch (error) {
+    return bad(error.message);
+  }
+  if (region === null) return bad(`\`${BLOCK_BEGIN_PREFIX}\` has no matching \`${BLOCK_END}\``);
+  if (host.indexOf(BLOCK_END) < region.start || host.indexOf(BLOCK_END, region.end) !== -1) {
+    return bad(`an extra or misplaced \`${BLOCK_END}\` outside the basalt block`);
+  }
+  return { region, problem: null };
+}
+function isAgentsImportLine(line) {
+  return line.trim() === `@${AGENTS_MD}`;
+}
+function importsAgentsMd(text) {
+  return text.split(/\r?\n/).some(isAgentsImportLine);
+}
+const ROUTER_SEED_DESTS = {
+  nav: "src/lib/nav.tsx",
+  root: "src/routes/__root.tsx",
+  main: "src/main.tsx"
+};
 function hasDependency(cwd, pkgName) {
   try {
     const pkg = JSON.parse(readFileSync(resolve(cwd, "package.json"), "utf8"));
@@ -318,16 +361,9 @@ function hasDependency(cwd, pkgName) {
     return false;
   }
 }
-function resolvePeerFlags(cwd, flags) {
-  return {
-    hasRouter: flags.withRouter === true || hasDependency(cwd, "@tanstack/react-router"),
-    hasQuery: flags.withQuery === true || hasDependency(cwd, "@tanstack/react-query")
-  };
-}
 const ROOT_PLACEMENT = {
   isPackageRepoRoot: true,
-  repoRoot: "",
-  relocatedQueryClient: null
+  repoRoot: ""
 };
 function findRepoRoot(dir) {
   let current = dir;
@@ -346,45 +382,14 @@ function oxlintBinResolves(dir) {
     if (d === root || dirname(d) === d) return false;
   }
 }
-function findFileNamed(dir, filename) {
-  let entries;
-  try {
-    entries = readdirSync(dir);
-  } catch {
-    return null;
-  }
-  for (const name of entries) {
-    if (name === "node_modules" || name === ".git" || name === "dist") continue;
-    const abs = resolve(dir, name);
-    let isDir;
-    try {
-      isDir = statSync(abs).isDirectory();
-    } catch {
-      continue;
-    }
-    if (isDir) {
-      const found = findFileNamed(abs, filename);
-      if (found !== null) return found;
-    } else if (name === filename) {
-      return abs;
-    }
-  }
-  return null;
-}
-function findRelocatedQueryClient(cwd) {
-  const seedAbs = resolve(cwd, "src/query-client.ts");
-  const found = findFileNamed(resolve(cwd, "src"), "query-client.ts");
-  return found !== null && found !== seedAbs ? found : null;
-}
 function resolvePlacement(cwd) {
   const repoRoot = findRepoRoot(cwd);
   return {
     isPackageRepoRoot: repoRoot === cwd,
-    repoRoot,
-    relocatedQueryClient: findRelocatedQueryClient(cwd)
+    repoRoot
   };
 }
-function managedFiles(peers, placement = ROOT_PLACEMENT) {
+function managedFiles(placement = ROOT_PLACEMENT) {
   const rules = RULE_NAMES.map((name) => ({
     dest: `.claude/rules/basalt-${name}.md`,
     mode: "managed",
@@ -397,15 +402,15 @@ function managedFiles(peers, placement = ROOT_PLACEMENT) {
     source: `agent/skills/${name}/SKILL.md`,
     render: (ctx) => readSource(ctx.pkgRoot, `agent/skills/${name}/SKILL.md`)
   }));
-  const claudeBlock = {
-    dest: "CLAUDE.md",
+  const agentsBlock = {
+    dest: AGENTS_MD,
     mode: "managed",
     markers: true,
-    source: "agent/templates/CLAUDE-block.md.tpl",
+    source: "agent/templates/AGENTS-block.md.tpl",
     // With markers, render() returns the fully-rendered region INCLUDING its begin/end markers.
-    // The writer splices it into the consumer's host CLAUDE.md at apply time.
+    // The writer splices it into the consumer's host AGENTS.md at apply time.
     render: (ctx) => {
-      const tpl = readSource(ctx.pkgRoot, "agent/templates/CLAUDE-block.md.tpl");
+      const tpl = readSource(ctx.pkgRoot, "agent/templates/AGENTS-block.md.tpl");
       if (tpl === null) return null;
       return fillTemplate(tpl, ctx.vars).trim();
     }
@@ -474,18 +479,8 @@ pre-commit:
 }
 `
   };
-  const queryClient = {
-    dest: "src/query-client.ts",
-    mode: "seed",
-    source: "agent/templates/query-client.ts.tpl",
-    render: (ctx) => {
-      const tpl = readSource(ctx.pkgRoot, "agent/templates/query-client.ts.tpl");
-      if (tpl === null) return null;
-      return fillTemplate(tpl, ctx.vars);
-    }
-  };
   const rootRoute = {
-    dest: "src/routes/__root.tsx",
+    dest: ROUTER_SEED_DESTS.root,
     mode: "seed",
     source: "agent/templates/__root.tpl",
     render: (ctx) => {
@@ -494,11 +489,21 @@ pre-commit:
       return fillTemplate(tpl, ctx.vars);
     }
   };
-  const scaffolds = [];
-  if (peers.hasQuery && placement.relocatedQueryClient === null) scaffolds.push(queryClient);
-  if (peers.hasRouter && peers.hasQuery) scaffolds.push(rootRoute);
+  const navModule = {
+    dest: ROUTER_SEED_DESTS.nav,
+    mode: "seed",
+    source: "agent/templates/nav.tpl",
+    render: (ctx) => readSource(ctx.pkgRoot, "agent/templates/nav.tpl")
+  };
+  const mainEntry = {
+    dest: ROUTER_SEED_DESTS.main,
+    mode: "seed",
+    source: "agent/templates/main.tpl",
+    render: (ctx) => readSource(ctx.pkgRoot, "agent/templates/main.tpl")
+  };
+  const scaffolds = [navModule, rootRoute, mainEntry];
   const rootTooling = placement.isPackageRepoRoot ? [lefthook, ci] : [];
-  return [...rules, ...skills, claudeBlock, design, oxfmt, ...rootTooling, oxlintrc, ...scaffolds];
+  return [...rules, ...skills, agentsBlock, design, oxfmt, ...rootTooling, oxlintrc, ...scaffolds];
 }
 function placementNotices(cwd, placement) {
   const out = [];
@@ -512,11 +517,6 @@ function placementNotices(cwd, placement) {
       `skipped .github/workflows/check.yml ${notRoot} \u2014 GitHub Actions only reads .github/ at the repo root; copy the steps from ${asset("configs/check.yml")} into your root CI workflow instead, and give each one \`working-directory: ${pkg}\` \u2014 the same relocation \`root:\` performs for lefthook, and needed for the same reason.`
     );
   }
-  if (placement.relocatedQueryClient !== null) {
-    out.push(
-      `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.`
-    );
-  }
   return out;
 }
 function readManifest(cwd) {
@@ -749,7 +749,7 @@ function stripJsonc(text) {
 }
 function parseJsonc(text) {
   try {
-    return JSON.parse(stripJsonc(text));
+    return JSON.parse(stripJsonc(text.replace(/^\uFEFF/, "")));
   } catch {
     return null;
   }
@@ -802,6 +802,7 @@ function inspectLefthookGate(repoRoot) {
   const wired = lefthookDumpRunLines(dump).some((run2) => /\bcheck-theme\b/.test(run2));
   return wired ? { kind: "wired", file } : { kind: "absent", file };
 }
+const ONLY_EXPORT_COMPONENTS = "react/only-export-components";
 function mergeOxlintExtends(cwd, presetPath) {
   const abs = resolve(cwd, ".oxlintrc.json");
   const raw = readIfExists(abs);
@@ -815,6 +816,13 @@ function mergeOxlintExtends(cwd, presetPath) {
   for (const [key, value] of Object.entries(cfg)) {
     merged[key] = key === "extends" ? [presetPath, ...existing] : value;
   }
+  const rules = merged["rules"];
+  if (rules !== void 0 && ONLY_EXPORT_COMPONENTS in rules) {
+    const [level, options] = [rules[ONLY_EXPORT_COMPONENTS]].flat();
+    const opts = typeof options === "object" && options !== null ? options : {};
+    const allowExportNames = [.../* @__PURE__ */ new Set([...opts.allowExportNames ?? [], "Route"])];
+    rules[ONLY_EXPORT_COMPONENTS] = [level, { ...opts, allowExportNames }];
+  }
   const indent = /\n([ \t]+)"/.exec(raw)?.[1] ?? "  ";
   writeFileSync(abs, JSON.stringify(merged, null, indent) + (raw.endsWith("\n") ? "\n" : ""));
   return "added";
@@ -915,9 +923,7 @@ function run(argv, cwd = process.cwd()) {
   switch (cmd) {
     case "init":
       return init(cwd, {
-        withRouter: flags.includes("--with-router"),
-        withQuery: flags.includes("--with-query"),
-        mergeLint: flags.includes("--merge-lint")
+        noMergeLint: flags.includes("--no-merge-lint")
       });
     case "sync":
       return sync(
@@ -944,10 +950,13 @@ function run(argv, cwd = process.cwd()) {
   }
 }
 export {
+  AGENTS_MD,
+  LEGACY_BLOCK_HOST,
   MANIFEST_PATH,
   OXLINT_FILES,
   OXLINT_NO_BIN,
   ROOT_PLACEMENT,
+  ROUTER_SEED_DESTS,
   RULE_NAMES,
   SERIES_MODULE_HINT_RE,
   SKILL_NAMES,
@@ -966,8 +975,11 @@ export {
   fontsCss,
   guardHook,
   hasBasaltKey,
+  hasManagedBlock,
+  importsAgentsMd,
   init,
   inspectLefthookGate,
+  isAgentsImportLine,
   isStringArray,
   managedFiles,
   mergeOxlintExtends,
@@ -991,12 +1003,13 @@ export {
   renderContext,
   reportPrune,
   resolveGuardConfig,
-  resolvePeerFlags,
   resolvePlacement,
   resolveProjectDir,
   retiredManagedDests,
   rootsNotices,
   run,
+  sameFile,
+  scanBlock,
   scannableFiles,
   sha256,
   shippedAssetPath,

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

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

package/dist/cli/init.js

@@ -1,8 +1,11 @@
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
-import { deriveSpacing } from "../tokens/index.js";
+import { deriveSpacing } from "../tokens/core.js";
 import {
   MANIFEST_PATH,
+  declaredProfile,
+  readBasaltConfig,
+  ROUTER_SEED_DESTS,
   findBasaltInstall,
   managedFiles,
   mergeOxlintExtends,
@@ -14,7 +17,6 @@ import {
   reconcileRoots,
   renderContext,
   reportPrune,
-  resolvePeerFlags,
   resolvePlacement,
   rootsNotices,
   sha256,
@@ -22,14 +24,22 @@ import {
   writeFileEnsuringDir,
   writeUnit
 } from "./index.js";
+import { seedTsconfigExtends } from "./doctor-upgrade.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.",
+  "src/main.tsx": "change it to match node_modules/basalt-ui/agent/templates/main.tpl: import 'basalt-ui/styles.css'; `const router = createBasaltRouter({ routeTree })`; declare `interface Register { router: typeof router }` in module '@tanstack/react-router'; render `<BasaltProvider router={router} />`. Without them the seeded src/lib/nav.tsx fails tsc.",
   ".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 oxlintrcCost(merge) {
+  if (merge === "added" || merge === "already") {
+    return "now extends the shipped preset: the basalt/* design rules and the jsx-a11y / import / promise / unicorn plugins are on.";
+  }
+  const why = merge === null ? "init ran with --no-merge-lint" : "init could not splice the extends in";
+  return `the shipped oxlint preset (the basalt/* rules, jsx-a11y, import, promise, unicorn) is NOT active: ${why}, nothing else turns it on, and every gate stays green without it. Add the \`extends\` by hand.`;
+}
 function init(cwd = process.cwd(), scaffoldFlags = {}) {
   const install = findBasaltInstall(cwd);
   if (install.dir === null) {
@@ -46,10 +56,26 @@ function init(cwd = process.cwd(), scaffoldFlags = {}) {
     pkg["scripts"] = { ...scripts, "lint:basalt": lintScript };
     return true;
   });
+  let buildNote = null;
+  patchPackageJson(cwd, (pkg) => {
+    const scripts = pkg["scripts"] ?? {};
+    const build = scripts["build"];
+    if (typeof build !== "string" || !/\btsc\b/.test(build) || build.startsWith("vite build")) {
+      return false;
+    }
+    if (build !== "tsc -b && vite build") {
+      buildNote = `"build" (${build}) left as is: run \`vite build\` before \`tsc\` (vite generates routeTree.gen.ts).`;
+      return false;
+    }
+    pkg["scripts"] = { ...scripts, build: "vite build && tsc -b" };
+    buildNote = 'rewrote "build" to `vite build && tsc -b` (vite generates routeTree.gen.ts).';
+    return true;
+  });
   const manifest = readManifest(cwd);
-  const peers = resolvePeerFlags(cwd, scaffoldFlags);
   const placement = resolvePlacement(cwd);
-  const files = managedFiles(peers, placement);
+  const tokensOnly = declaredProfile(readBasaltConfig(cwd), []) === "tokens-only";
+  const routerSeeds = Object.values(ROUTER_SEED_DESTS);
+  const files = managedFiles(placement).filter((f) => !(tokensOnly && routerSeeds.includes(f.dest)));
   const writtenFiles = [];
   const keptFiles = [];
   const missingSources = [];
@@ -70,7 +96,7 @@ function init(cwd = process.cwd(), scaffoldFlags = {}) {
     writtenFiles.push(file.dest);
   }
   const pruned = pruneRetiredManagedFiles(cwd, manifest, files);
-  const mergeLint = scaffoldFlags.mergeLint === true ? mergeOxlintExtends(cwd, ctx.vars.OXLINT_PRESET_PATH) : null;
+  const mergeLint = scaffoldFlags.noMergeLint === true ? null : mergeOxlintExtends(cwd, ctx.vars.OXLINT_PRESET_PATH);
   manifest.basaltVersion = ctx.vars.BASALT_VERSION;
   manifest.spacingScale = { ...deriveSpacing(0).scale };
   writeFileEnsuringDir(resolve(cwd, MANIFEST_PATH), `${JSON.stringify(manifest, null, 2)}
@@ -88,20 +114,20 @@ function init(cwd = process.cwd(), scaffoldFlags = {}) {
     console.log(`
 Kept (already present \u2014 basalt did not touch them):`);
     for (const dest of keptFiles) {
-      const cost = KEPT_FILE_COST[dest];
+      const cost = dest === ".oxlintrc.json" ? oxlintrcCost(mergeLint) : 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 mergeMessage = {
+    added: `spliced "${ctx.vars.OXLINT_PRESET_PATH}" into the existing .oxlintrc.json extends`,
+    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.`
+  };
+  const mergeLine = mergeLint === null ? void 0 : mergeMessage[mergeLint];
+  if (mergeLine !== void 0) console.log(`basalt-ui init: oxlint \u2014 ${mergeLine}`);
+  const tsconfigLine = tokensOnly ? null : seedTsconfigExtends(cwd);
+  if (tsconfigLine !== null) console.log(`basalt-ui init: ${tsconfigLine}`);
+  if (buildNote !== null) console.log(`basalt-ui init: ${buildNote}`);
   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}`);
@@ -111,16 +137,6 @@ Kept (already present \u2014 basalt did not touch them):`);
   for (const line of placementNotices(cwd, placement)) {
     console.log(`basalt-ui init: ${line}`);
   }
-  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:

package/dist/cli/sync.d.ts

@@ -7,24 +7,11 @@ export type SyncOptions = {
     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.
+ * The sentence `sync` and `doctor` both print when the cwd carries no install but an ancestor does
+ * (a package under a configured repo); one text, so neither prescribes a second `init`.
  */
 export declare function parentInstallAdvice(cwd: string, parent: string, verb: string): string;
+/** The nearest ANCESTOR of `dir` (exclusive) carrying a basalt manifest, or null. */
 export declare function findManifestAbove(dir: string): string | null;
 /**
  * Reconcile managed files with the shipped versions via a sha256 three-way compare.
@@ -33,11 +20,8 @@ export declare function findManifestAbove(dir: string): string | null;
  *   (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.
+ * Runs against `resolveProjectDir(cwd)` and REFUSES rather than scaffolding when that project has no
+ * manifest: `sync` refreshes, `init` scaffolds.
  */
 export declare function sync(opts?: SyncOptions, invocationCwd?: string): number;
 //# sourceMappingURL=sync.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/cli/sync.ts"],"names":[],"mappings":"AA8CA,gGAAgG;AAChG,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAGjE;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,CAoM1F"}
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/cli/sync.ts"],"names":[],"mappings":"AAwCA,gGAAgG;AAChG,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAGjE;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;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAKrF;AAED,qFAAqF;AACrF,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQ5D;AAED;;;;;;;;;GASG;AACH,wBAAgB,IAAI,CAAC,IAAI,GAAE,WAAgB,EAAE,aAAa,GAAE,MAAsB,GAAG,MAAM,CA0L1F"}

package/dist/cli/sync.js

@@ -1,6 +1,6 @@
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
-import { deriveSpacing } from "../tokens/index.js";
+import { deriveSpacing } from "../tokens/core.js";
 import {
   MANIFEST_PATH,
   basaltPresetEntry,
@@ -26,7 +26,6 @@ import {
   relativePosix,
   renderContext,
   reportPrune,
-  resolvePeerFlags,
   resolvePlacement,
   resolveProjectDir,
   rootsNotices,
@@ -66,7 +65,7 @@ function sync(opts = {}, invocationCwd = process.cwd()) {
   }
   if (!existsSync(resolve(cwd, MANIFEST_PATH))) {
     const elsewhere = findManifestAbove(cwd);
-    const wouldWrite = managedFiles(resolvePeerFlags(cwd, {}), resolvePlacement(cwd)).length;
+    const wouldWrite = managedFiles(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")}`)
     );
@@ -75,9 +74,8 @@ function sync(opts = {}, invocationCwd = process.cwd()) {
   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);
+  const files = managedFiles(placement);
   let updated = 0;
   let created = 0;
   let recreated = 0;
@@ -157,8 +155,8 @@ function sync(opts = {}, invocationCwd = process.cwd()) {
     }
     if (staleForCheck > 0) {
       console.error(`basalt-ui sync --check: ${staleForCheck} managed file(s) out of date.`);
-      return 1;
     }
+    if (staleForCheck > 0) return 1;
     const n = placementSkips.length;
     const skips = n === 0 ? "" : ` (${n} permanent placement skip(s) \u2014 --verbose for detail)`;
     console.log(`\u2713 basalt-ui sync --check: all managed files current.${skips}`);

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

@@ -1,36 +1,15 @@
 /**
  * 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.
+ * survives a repo's formatter (`rgba(255,255,255,0.6)` and `rgba(255, 255, 255, 0.6)` are the same
+ * colour; `0.10` becomes `0.1`). FORMATTING ONLY: token values are untouched, and only a bare decimal
+ * literal is touched (never a `%`, a `var()` or a unit). Exported for tests.
  */
 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.
+ * tokens:css — emit the `--vx-*` stylesheet, optionally retargeted, for a static site that installs
+ * nothing (`bunx basalt-ui tokens:css --selector-attribute data-theme --out src/tokens.css`). Token
+ * VALUES come from `buildPaletteCss`, so the CLI and the API cannot disagree; the CLI adds only file
+ * framing for a committed artifact: the `@generated` header, a trailing newline, `rgba()` spacing.
  */
 export declare function tokensCss(flags: string[], cwd?: string): number;
 /**

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

@@ -1 +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"}
+{"version":3,"file":"tokens-css.d.ts","sourceRoot":"","sources":["../../src/cli/tokens-css.ts"],"names":[],"mappings":"AAkCA;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAK3D;AA4DD;;;;;GAKG;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/commands/ShortcutsHelp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ShortcutsHelp.d.ts","sourceRoot":"","sources":["../../src/commands/ShortcutsHelp.tsx"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAQlD,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG;IAC7C,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,kDAAkD;IAClD,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;CACtB,CAAA;AA8BD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,EAC5B,KAA4B,EAC5B,GAAG,EACH,SAAS,EACT,KAAK,GACN,EAAE,kBAAkB,sCAyDpB"}
+{"version":3,"file":"ShortcutsHelp.d.ts","sourceRoot":"","sources":["../../src/commands/ShortcutsHelp.tsx"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAUlD,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG;IAC7C,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,kDAAkD;IAClD,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;CACtB,CAAA;AA8BD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,EAC5B,KAA4B,EAC5B,GAAG,EACH,SAAS,EACT,KAAK,GACN,EAAE,kBAAkB,sCAsDpB"}

package/dist/commands/ShortcutsHelp.js

@@ -1,10 +1,12 @@
 import { jsx, jsxs } from "react/jsx-runtime";
-import { useEffect, useState } from "react";
+import { useSyncExternalStore } from "react";
 import { Box, Group, Kbd, Stack, Text, Title } from "@mantine/core";
 import { cx } from "../common/props.js";
 import { toShortcutList } from "./projectors.js";
 import { detectMac, parseShortcut } from "./shortcut-format.js";
 import { VX } from "../tokens/index.js";
+const subscribeNever = () => () => {
+};
 function ShortcutRow({
   label,
   shortcut,
@@ -22,10 +24,7 @@ function ShortcutsHelp({
   className,
   style
 }) {
-  const [isMac, setIsMac] = useState(false);
-  useEffect(() => {
-    setIsMac(detectMac());
-  }, []);
+  const isMac = useSyncExternalStore(subscribeNever, detectMac, () => false);
   const shortcuts = toShortcutList();
   if (shortcuts.length === 0) return null;
   const grouped = /* @__PURE__ */ new Map();