basalt-ui 1.40.2 → 1.41.0

package/dist/cli/index.js

@@ -7,6 +7,7 @@ import {
   readFileSync,
   rmdirSync,
   statSync,
+  realpathSync,
   unlinkSync,
   writeFileSync
 } from "node:fs";
@@ -233,6 +234,8 @@ 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");
 }
@@ -308,6 +311,91 @@ 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);
+}
+function migrateBlockToAgentsMd(cwd, manifest, opts = {}) {
+  const legacyHash = manifest.files[LEGACY_BLOCK_HOST];
+  if (legacyHash !== void 0) {
+    manifest.files[AGENTS_MD] ??= legacyHash;
+    delete manifest.files[LEGACY_BLOCK_HOST];
+  }
+  const none = { pending: false, deletedHost: false, problem: null };
+  const legacyAbs = resolve(cwd, LEGACY_BLOCK_HOST);
+  const agentsAbs = resolve(cwd, AGENTS_MD);
+  const legacy = readIfExists(legacyAbs);
+  if (legacy === null) return none;
+  try {
+    if (sameFile(legacyAbs, agentsAbs)) return none;
+  } catch (error) {
+    const why = error.code ?? error.message;
+    return { ...none, problem: `cannot tell whether ${LEGACY_BLOCK_HOST} is ${AGENTS_MD} (${why})` };
+  }
+  const legacyScan = scanBlock(legacy);
+  const { region } = legacyScan;
+  if (legacyScan.problem !== null) {
+    return { ...none, problem: `${LEGACY_BLOCK_HOST}: ${legacyScan.problem}` };
+  }
+  if (region === null) return none;
+  const agents = readIfExists(agentsAbs) ?? "";
+  const agentsScan = scanBlock(agents);
+  if (agentsScan.problem !== null)
+    return { ...none, problem: `${AGENTS_MD}: ${agentsScan.problem}` };
+  const legacyBlock = legacy.slice(region.start, region.end);
+  if (agentsScan.region !== null && normalizeForLedger(agents.slice(agentsScan.region.start, agentsScan.region.end)) !== normalizeForLedger(legacyBlock)) {
+    return {
+      ...none,
+      problem: `${LEGACY_BLOCK_HOST} and ${AGENTS_MD} each carry a basalt block and they differ \u2014 delete the stale block from ${LEGACY_BLOCK_HOST} (or the one in ${AGENTS_MD}, if ${LEGACY_BLOCK_HOST}'s is the one you want kept), then re-run.`
+    };
+  }
+  const before = legacy.slice(0, region.start).trimEnd();
+  const after = legacy.slice(region.end).trimStart();
+  const remainder = before === "" || after === "" ? `${before}${after}` : `${before}
+
+${after}`;
+  const deletedHost = remainder.split(/\r?\n/).every((l) => l.trim() === "" || isAgentsImportLine(l));
+  if (opts.dryRun === true) return { pending: true, deletedHost, problem: null };
+  if (agentsScan.region === null) writeFileEnsuringDir(agentsAbs, applyBlock(agents, legacyBlock));
+  if (deletedHost) unlinkSync(legacyAbs);
+  else writeFileSync(legacyAbs, `${remainder.trimEnd()}
+`);
+  return { pending: true, deletedHost, problem: null };
+}
+function blockMigrationProblem(cwd) {
+  const { problem } = migrateBlockToAgentsMd(cwd, { version: 1, files: {} }, { dryRun: true });
+  return problem === null ? null : `${problem.replace(/\.$/, "")}. Nothing else was reconciled \u2014 resolve this by hand, then re-run.`;
+}
 function hasDependency(cwd, pkgName) {
   try {
     const pkg = JSON.parse(readFileSync(resolve(cwd, "package.json"), "utf8"));
@@ -397,15 +485,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();
     }
@@ -498,7 +586,7 @@ pre-commit:
   if (peers.hasQuery && placement.relocatedQueryClient === null) scaffolds.push(queryClient);
   if (peers.hasRouter && peers.hasQuery) scaffolds.push(rootRoute);
   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 = [];
@@ -558,6 +646,14 @@ Retired but locally edited, so left in place \u2014 your agent still loads them.
 ` + pruned.drifted.map((dest) => `  \xB7 ${dest}`).join("\n")
   );
 }
+function reportBlockMigration(migration, command) {
+  if (!migration.pending) return;
+  const tail = migration.deletedHost ? `${LEGACY_BLOCK_HOST} held nothing else and was deleted.` : `the rest of ${LEGACY_BLOCK_HOST} is yours; while it exists Claude Code loads it INSTEAD of ${AGENTS_MD} unless it imports @${AGENTS_MD} \u2014 move your content over and delete it.`;
+  console.log(
+    `
+basalt-ui ${command}: moved the basalt block from ${LEGACY_BLOCK_HOST} to ${AGENTS_MD} \u2014 ${tail}`
+  );
+}
 function pruneRetiredManagedFiles(cwd, manifest, files, opts = {}) {
   const result = { removed: [], drifted: [] };
   for (const dest of retiredManagedDests(manifest, files)) {
@@ -944,6 +1040,8 @@ function run(argv, cwd = process.cwd()) {
   }
 }
 export {
+  AGENTS_MD,
+  LEGACY_BLOCK_HOST,
   MANIFEST_PATH,
   OXLINT_FILES,
   OXLINT_NO_BIN,
@@ -954,6 +1052,7 @@ export {
   SKIP,
   basaltBinCommand,
   basaltPresetEntry,
+  blockMigrationProblem,
   checkTheme,
   classify,
   conflictingProfileFlags,
@@ -966,11 +1065,15 @@ export {
   fontsCss,
   guardHook,
   hasBasaltKey,
+  hasManagedBlock,
+  importsAgentsMd,
   init,
   inspectLefthookGate,
+  isAgentsImportLine,
   isStringArray,
   managedFiles,
   mergeOxlintExtends,
+  migrateBlockToAgentsMd,
   namesShipped,
   normalizeColorFunctions,
   normalizeForLedger,
@@ -989,6 +1092,7 @@ export {
   reconcileRoots,
   relativePosix,
   renderContext,
+  reportBlockMigration,
   reportPrune,
   resolveGuardConfig,
   resolvePeerFlags,
@@ -997,6 +1101,8 @@ export {
   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;AA8C7D,yGAAyG;AACzG,wBAAgB,IAAI,CAAC,GAAG,GAAE,MAAsB,EAAE,aAAa,GAAE,aAAkB,GAAG,MAAM,CAuL3F"}

package/dist/cli/init.js

@@ -3,9 +3,11 @@ import { resolve } from "node:path";
 import { deriveSpacing } from "../tokens/index.js";
 import {
   MANIFEST_PATH,
+  blockMigrationProblem,
   findBasaltInstall,
   managedFiles,
   mergeOxlintExtends,
+  migrateBlockToAgentsMd,
   normalizeForLedger,
   patchPackageJson,
   placementNotices,
@@ -13,6 +15,7 @@ import {
   readManifest,
   reconcileRoots,
   renderContext,
+  reportBlockMigration,
   reportPrune,
   resolvePeerFlags,
   resolvePlacement,
@@ -31,6 +34,11 @@ const KEPT_FILE_COST = {
   "DESIGN.md": "the design brief Claude reads is yours, not the seeded one."
 };
 function init(cwd = process.cwd(), scaffoldFlags = {}) {
+  const blockProblem = blockMigrationProblem(cwd);
+  if (blockProblem !== null) {
+    console.error(`\u2716 basalt-ui init: ${blockProblem}`);
+    return 1;
+  }
   const install = findBasaltInstall(cwd);
   if (install.dir === null) {
     console.error(
@@ -50,6 +58,7 @@ function init(cwd = process.cwd(), scaffoldFlags = {}) {
   const peers = resolvePeerFlags(cwd, scaffoldFlags);
   const placement = resolvePlacement(cwd);
   const files = managedFiles(peers, placement);
+  const migration = migrateBlockToAgentsMd(cwd, manifest);
   const writtenFiles = [];
   const keptFiles = [];
   const missingSources = [];
@@ -79,6 +88,7 @@ function init(cwd = process.cwd(), scaffoldFlags = {}) {
     `basalt-ui init: ${writtenFiles.length} written, ${keptFiles.length} kept, manifest at ${MANIFEST_PATH}`
   );
   reportPrune(pruned);
+  reportBlockMigration(migration, "init");
   if (missingSources.length > 0) {
     console.log(
       `basalt-ui init: ${missingSources.length} shipped asset(s) not present, skipped: ${missingSources.join(", ")}`

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":"AAmDA,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,CAsN1F"}

package/dist/cli/sync.js

@@ -10,8 +10,12 @@ import {
   diffSummary,
   findBasaltInstall,
   inspectLefthookGate,
+  AGENTS_MD,
+  blockMigrationProblem,
   isStringArray,
+  LEGACY_BLOCK_HOST,
   managedFiles,
+  migrateBlockToAgentsMd,
   normalizeForLedger,
   noteRelocation,
   OXLINT_FILES,
@@ -25,6 +29,7 @@ import {
   reconcileRoots,
   relativePosix,
   renderContext,
+  reportBlockMigration,
   reportPrune,
   resolvePeerFlags,
   resolvePlacement,
@@ -72,12 +77,18 @@ function sync(opts = {}, invocationCwd = process.cwd()) {
     );
     return 1;
   }
+  const blockProblem = blockMigrationProblem(cwd);
+  if (blockProblem !== null) {
+    console.error(`\u2716 basalt-ui sync: ${blockProblem}`);
+    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);
+  const migration = migrateBlockToAgentsMd(cwd, manifest, { dryRun: opts.check === true });
   let updated = 0;
   let created = 0;
   let recreated = 0;
@@ -155,10 +166,15 @@ function sync(opts = {}, invocationCwd = process.cwd()) {
         `basalt-ui sync --check: ${retired.length} retired rule/skill file(s) still present: ${retired.join(", ")} \u2014 run \`basalt-ui sync\`.`
       );
     }
+    if (migration.pending) {
+      console.error(
+        `basalt-ui sync --check: the basalt block is still in ${LEGACY_BLOCK_HOST} \u2014 it now lives in ${AGENTS_MD}. Run \`basalt-ui sync\` to move it.`
+      );
+    }
     if (staleForCheck > 0) {
       console.error(`basalt-ui sync --check: ${staleForCheck} managed file(s) out of date.`);
-      return 1;
     }
+    if (staleForCheck > 0 || migration.pending) 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}`);
@@ -172,6 +188,7 @@ function sync(opts = {}, invocationCwd = process.cwd()) {
     `basalt-ui sync: ${updated} updated, ${created} created, ${recreated} recreated, ${skippedDrift} skipped (drift), ${pruned.removed.length} retired.`
   );
   reportPrune(pruned);
+  reportBlockMigration(migration, "sync");
   if (driftLines.length > 0) {
     console.log("Locally-edited files were skipped (run with --force to overwrite):");
     for (const l of driftLines) console.log(l);

package/dist/commands/shortcut-format.d.ts

@@ -9,7 +9,7 @@
  * parseShortcut('Mod+S', false)  // ['Ctrl', 'S']
  *
  * // Single display string for Spotlight description:
- * formatShortcutDisplay('Mod+S', true)   // '⌘ S' on mac
+ * formatShortcutDisplay('Mod+S', true)   // '⌘S' on mac
  * formatShortcutDisplay('Mod+S', false)  // 'Ctrl+S' on windows
  */
 /**
@@ -22,16 +22,20 @@ export declare function detectMac(): boolean;
  * Convert a shortcut string to a list of Kbd-friendly tokens.
  * 'Mod+S' → ['⌘', 'S'] (mac) or ['Ctrl', 'S'] (other).
  * 'Shift+Mod+P' → ['⇧', '⌘', 'P'] (mac) or ['Shift', 'Ctrl', 'P'] (other).
+ * Named keys read as glyphs on mac and Title-case words elsewhere:
+ * 'Mod+Backspace' → ['⌘', '⌫'] (mac) or ['Ctrl', 'Backspace'] (other).
  * isMac is the post-mount platform flag; defaults false on SSR / first render.
  *
  * @example
  * parseShortcut('Mod+S', true)         // ['⌘', 'S']
  * parseShortcut('Shift+Mod+P', false)  // ['Shift', 'Ctrl', 'P']
+ * parseShortcut('ArrowLeft', true)     // ['←']
  */
 export declare function parseShortcut(shortcut: string, isMac: boolean): string[];
 /**
  * Format a shortcut string for inline display (e.g. Spotlight action description).
- * Returns a compact string like '⌘ S' (mac) or 'Ctrl+S' (windows).
+ * Returns a compact string like '⌘S' / '⌘⌫' (mac, glyphs with no separator) or 'Ctrl+S' /
+ * 'Ctrl+Backspace' (elsewhere, Title-case words joined with '+').
  *
  * isMac is the post-mount platform flag. Pass false on SSR / first client render.
  *
@@ -40,9 +44,10 @@ export declare function parseShortcut(shortcut: string, isMac: boolean): string[
  * always-on and produces the same tokens via parseShortcut.
  *
  * @example
- * formatShortcutDisplay('Mod+S', true)         // '⌘ S'
+ * formatShortcutDisplay('Mod+S', true)          // '⌘S'
+ * formatShortcutDisplay('Mod+Backspace', true)  // '⌘⌫'
  * formatShortcutDisplay('Mod+S', false)         // 'Ctrl+S'
- * formatShortcutDisplay('Shift+Mod+P', true)    // '⇧ ⌘ P'
+ * formatShortcutDisplay('Shift+Mod+P', true)    // '⇧⌘P'
  */
 export declare function formatShortcutDisplay(shortcut: string, isMac: boolean): string;
 //# sourceMappingURL=shortcut-format.d.ts.map

package/dist/commands/shortcut-format.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shortcut-format.d.ts","sourceRoot":"","sources":["../../src/commands/shortcut-format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH;;;;GAIG;AACH,wBAAgB,SAAS,IAAI,OAAO,CAMnC;AAID;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAiBxE;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAI9E"}
+{"version":3,"file":"shortcut-format.d.ts","sourceRoot":"","sources":["../../src/commands/shortcut-format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH;;;;GAIG;AACH,wBAAgB,SAAS,IAAI,OAAO,CAMnC;AAmCD;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAqBxE;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAG9E"}

package/dist/commands/shortcut-format.js

@@ -4,9 +4,36 @@ function detectMac() {
   if (uadPlatform !== void 0) return /mac|iphone|ipad/i.test(uadPlatform);
   return /Mac|iPhone|iPad/.test(navigator.userAgent);
 }
+const NAMED_KEYS = {
+  backspace: ["\u232B", "Backspace"],
+  delete: ["\u2326", "Delete"],
+  del: ["\u2326", "Delete"],
+  arrowleft: ["\u2190", "Left"],
+  arrowright: ["\u2192", "Right"],
+  arrowup: ["\u2191", "Up"],
+  arrowdown: ["\u2193", "Down"],
+  left: ["\u2190", "Left"],
+  right: ["\u2192", "Right"],
+  up: ["\u2191", "Up"],
+  down: ["\u2193", "Down"],
+  escape: ["\u238B", "Esc"],
+  esc: ["\u238B", "Esc"],
+  enter: ["\u21A9", "Enter"],
+  return: ["\u21A9", "Enter"],
+  tab: ["\u21E5", "Tab"],
+  space: ["\u2423", "Space"],
+  home: ["\u2196", "Home"],
+  end: ["\u2198", "End"],
+  pageup: ["\u21DE", "PgUp"],
+  pagedown: ["\u21DF", "PgDn"]
+};
+function plainKey(key) {
+  return key.length === 1 ? key.toUpperCase() : key.charAt(0).toUpperCase() + key.slice(1);
+}
 function parseShortcut(shortcut, isMac) {
   return shortcut.split("+").map((key) => {
-    switch (key.toLowerCase()) {
+    const lower = key.toLowerCase();
+    switch (lower) {
       case "mod":
         return isMac ? "\u2318" : "Ctrl";
       case "shift":
@@ -16,15 +43,18 @@ function parseShortcut(shortcut, isMac) {
       case "meta":
         return isMac ? "\u2318" : "Meta";
       case "ctrl":
-        return isMac ? "^" : "Ctrl";
-      default:
-        return key.toUpperCase();
+        return isMac ? "\u2303" : "Ctrl";
+      default: {
+        const named = NAMED_KEYS[lower];
+        if (named !== void 0) return isMac ? named[0] : named[1];
+        return plainKey(key);
+      }
     }
   });
 }
 function formatShortcutDisplay(shortcut, isMac) {
   const tokens = parseShortcut(shortcut, isMac);
-  return isMac ? tokens.join(" ") : tokens.join("+");
+  return tokens.join(isMac ? "" : "+");
 }
 export {
   detectMac,

package/dist/content/copy-action.d.ts

@@ -6,7 +6,7 @@
  *
  * The check + tooltip are the entire success signal — no notification (docs/CONTENT-SPEC.md §7).
  * `color="teal"` resolves through the bridged Mantine family, so it stays on the token layer in
- * both schemes (see the package CLAUDE.md on `cssVariablesResolver`).
+ * both schemes (see the package MAINTAINING.md on `cssVariablesResolver`).
  *
  * Not part of the public surface — reach it through `CodeBlock` / `HeadingAnchor`.
  */

package/dist/content/glyphs.d.ts

@@ -4,7 +4,7 @@
  * hand-drawn ones that drift apart.
  *
  * Inline SVG rather than an icon dep: the framework takes icons as `ReactNode` from the consumer
- * (see the package CLAUDE.md) and ships none, but these are internal chrome of a shipped component,
+ * (see the package MAINTAINING.md) and ships none, but these are internal chrome of a shipped component,
  * not a consumer-facing slot. `currentColor` + `1em`-agnostic sizing keeps them steerable from CSS
  * — the heading anchor sizes its glyph as an optical ratio of whatever step the heading lands on
  * (docs/DESIGN-SPEC.md §3), while the code-block chrome pins a fixed 14px.

package/dist/data/virtual-list.d.ts

@@ -103,7 +103,7 @@ export type BasaltVirtualListHandle = {
     /**
      * The underlying `@tanstack/react-virtual` instance — the full escape hatch. Returns the RAW
      * `@tanstack/react-virtual` `Virtualizer`, so a future major of that library reaching this shape
-     * ships here as a plain `feat:` under the no-majors doctrine (`../../CLAUDE.md` "Commit type
+     * ships here as a plain `feat:` under the no-majors doctrine (root `AGENTS.md` "Commit type
      * discipline"), not a silent break.
      */
     getVirtualizer: () => Virtualizer<HTMLDivElement, Element>;

package/dist/theme/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/theme/index.ts"],"names":[],"mappings":"AAiEA,OAAO,KAAK,EACV,oBAAoB,EAGpB,oBAAoB,EAErB,MAAM,eAAe,CAAA;AAStB,OAAO,KAAK,EAAe,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAE/E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAGpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAQlD;;;;;GAKG;AACH,YAAY,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAIlD,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAMvD,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAA;AAgBnE,OAAO,QAAQ,eAAe,CAAC;IAC7B,UAAU,iBAAiB;QACzB,YAAY,CAAC,EAAE,YAAY,CAAA;QAC3B,WAAW,CAAC,EAAE,iBAAiB,CAAA;QAC/B,YAAY,CAAC,EAAE,YAAY,CAAA;QAC3B,aAAa,CAAC,EAAE,WAAW,CAAA;KAC5B;CACF;AAgiCD;+EAC+E;AAC/E,eAAO,MAAM,SAAS,EAAE,oBAAuD,CAAA;AAyT/E;;8FAE8F;AAC9F,eAAO,MAAM,oBAAoB,EAAE,oBACc,CAAA;AAEjD,kEAAkE;AAClE,MAAM,MAAM,wBAAwB,GAAG;IACrC;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAA;IAE9B;;;;;;;;;;;;;;;;OAgBG;IACH,KAAK,CAAC,EAAE,iBAAiB,CAAA;IAEzB;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;CAC7B,CAAA;AA0BD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,CAAC,EAAE,IAAI,CAAC,oBAAoB,EAAE,aAAa,CAAC,EACrD,OAAO,CAAC,EAAE,wBAAwB,GACjC,oBAAoB,CAmCtB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/theme/index.ts"],"names":[],"mappings":"AAiEA,OAAO,KAAK,EACV,oBAAoB,EAGpB,oBAAoB,EAErB,MAAM,eAAe,CAAA;AAStB,OAAO,KAAK,EAAe,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAE/E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAGpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAQlD;;;;;GAKG;AACH,YAAY,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAIlD,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAMvD,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAA;AAgBnE,OAAO,QAAQ,eAAe,CAAC;IAC7B,UAAU,iBAAiB;QACzB,YAAY,CAAC,EAAE,YAAY,CAAA;QAC3B,WAAW,CAAC,EAAE,iBAAiB,CAAA;QAC/B,YAAY,CAAC,EAAE,YAAY,CAAA;QAC3B,aAAa,CAAC,EAAE,WAAW,CAAA;KAC5B;CACF;AAuiCD;+EAC+E;AAC/E,eAAO,MAAM,SAAS,EAAE,oBAAuD,CAAA;AAkU/E;;8FAE8F;AAC9F,eAAO,MAAM,oBAAoB,EAAE,oBACc,CAAA;AAEjD,kEAAkE;AAClE,MAAM,MAAM,wBAAwB,GAAG;IACrC;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAA;IAE9B;;;;;;;;;;;;;;;;OAgBG;IACH,KAAK,CAAC,EAAE,iBAAiB,CAAA;IAEzB;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;CAC7B,CAAA;AA0BD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,CAAC,EAAE,IAAI,CAAC,oBAAoB,EAAE,aAAa,CAAC,EACrD,OAAO,CAAC,EAAE,wBAAwB,GACjC,oBAAoB,CAmCtB"}

package/dist/theme/index.js

@@ -156,13 +156,17 @@ const basaltVariantColorResolver = (input) => {
     const isDefaultColor = input.color === void 0 || input.color === input.theme.primaryColor;
     return isDefaultColor ? { ...resolved, hover: `color-mix(in srgb, var(--vx-ink) 6%, transparent)` } : resolved;
   }
+  if (input.variant === "outline") {
+    return { ...resolved, color: `color-mix(in srgb, ${resolved.color} 70%, var(--vx-ink))` };
+  }
   if (input.variant !== "light") return resolved;
   const ink = `var(--mantine-color-${colorName}-light-color)`;
   return {
     ...resolved,
     background: `color-mix(in srgb, ${ink} 13%, transparent)`,
     hover: `color-mix(in srgb, ${ink} 20%, transparent)`,
-    color: ink,
+    // Same pull toward ink as `outline`: the saturated tone text sat at 3.2–4.4:1 on its own tint.
+    color: `color-mix(in srgb, ${ink} 70%, var(--vx-ink))`,
     border: "none"
   };
 };
@@ -1003,6 +1007,12 @@ function buildCssVariablesResolver(data) {
       // secondary / muted text
       "--mantine-color-text": `var(--vx-ink, ${INK.ink.light})`,
       // primary body/heading text
+      // Field errors: Mantine's own error red measures 1.98:1 (dark) / 4.37:1 (light). The solid status red
+      // pulled toward ink clears AA on every text surface in both schemes.
+      "--mantine-color-error": "color-mix(in srgb, var(--vx-bad-solid) 85%, var(--vx-ink))",
+      // Links: Mantine reads the accent FILL shade (4.38:1 on the light page, under WCAG AA); the hover
+      // accent is the next step darker and clears 4.5:1 on every light text surface.
+      "--mantine-color-anchor": "var(--vx-accent-hover)",
       // `--app-shell-border-color` is set by `components.AppShell.extend({ vars })` above — this
       // entry was dead (an element-level declaration always beats an inherited `:root` value).
       // THE strict-surface lever. Mantine components do NOT chain border/surface colors through
@@ -1031,6 +1041,9 @@ function buildCssVariablesResolver(data) {
       "--mantine-color-default-border": "transparent",
       "--mantine-color-dimmed": `var(--vx-neutral, ${NEUTRAL.neutral.dark})`,
       "--mantine-color-text": `var(--vx-ink, ${INK.ink.dark})`,
+      // Field errors: Mantine's own error red measures 1.98:1 (dark) / 4.37:1 (light). The solid status red
+      // pulled toward ink clears AA on every text surface in both schemes.
+      "--mantine-color-error": "color-mix(in srgb, var(--vx-bad-solid) 85%, var(--vx-ink))",
       // See the light block above — `--app-shell-border-color` is set by `AppShell.extend` now.
       // Dark components read `--mantine-color-dark-4` (border) raw. `buildDarkTuple` already sets
       // dark-4, but to a slightly lighter step than the hairline token, so layout borders read

package/dist/theme/segmented-control.module.css

@@ -13,6 +13,14 @@
   font-weight: 600;
 }
 
+/*
+ * Inactive labels read ink2, not Mantine's gray-7 (4.0:1 on the light track): the active segment is
+ * told apart by the raised pill and weight 600, so the inactive text can stay at full AA contrast.
+ */
+.label:not([data-active], [data-disabled]) {
+  color: var(--vx-ink2);
+}
+
 /*
  * Mantine's own `.control` ships `flex: 1` with no `min-width` override, so its initial value
  * (`auto`) floors every option at its min-content width — a `fullWidth` track therefore still

package/dist/tokens/derive.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"derive.d.ts","sourceRoot":"","sources":["../../src/tokens/derive.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AAExC,MAAM,MAAM,YAAY,GAAG;IACzB;;;;;;;;OAQG;IACH,MAAM,EAAE,MAAM,CAAA;IACd,sEAAsE;IACtE,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,CAAA;IAC/C;kGAC8F;IAC9F,UAAU,EAAE,MAAM,CAAA;IAClB;mDAC+C;IAC/C,SAAS,EAAE,MAAM,CAAA;IACjB;;;;;;OAMG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;;;;;OAMG;IACH,gBAAgB,EAAE,MAAM,CAAA;CACzB,CAAA;AAED,8FAA8F;AAC9F,eAAO,MAAM,qBAAqB,EAAE,YAOnC,CAAA;AAID;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,YAAY,CAEjF;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAEnE;AAuHD,MAAM,MAAM,UAAU,GAClB,MAAM,GACN,KAAK,GACL,MAAM,GACN,OAAO,GACP,QAAQ,GACR,QAAQ,GACR,MAAM,GACN,MAAM,GACN,OAAO,GACP,MAAM,GACN,QAAQ,GACR,QAAQ,CAAA;AA6DZ,MAAM,MAAM,UAAU,GAClB,IAAI,GACJ,OAAO,GACP,YAAY,GACZ,UAAU,GACV,QAAQ,GACR,OAAO,GACP,QAAQ,GACR,UAAU,CAAA;AA2Bd,MAAM,MAAM,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAA;AAQvD,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,CAAA;AAS/C;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,6FAA6F;IAC7F,UAAU,EAAE,MAAM,CAAA;IAClB,0EAA0E;IAC1E,eAAe,EAAE,MAAM,CAAA;IACvB,6EAA6E;IAC7E,iBAAiB,EAAE,MAAM,CAAA;IACzB,4EAA4E;IAC5E,gBAAgB,EAAE,MAAM,CAAA;CACzB,CAAA;AAED;8BAC8B;AAC9B,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,EAAE,SAAS,CAAA;IACjB,WAAW,EAAE,SAAS,CAAA;IACtB,UAAU,EAAE,SAAS,CAAA;IACrB,eAAe,EAAE,SAAS,CAAA;IAC1B,QAAQ,EAAE,SAAS,CAAA;IACnB,IAAI,EAAE,MAAM,CAAC,UAAU,EAAE,SAAS,CAAC,CAAA;IACnC,OAAO,EAAE,MAAM,CAAC,UAAU,EAAE,SAAS,CAAC,CAAA;IACtC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;IAC9B,MAAM,EAAE,MAAM,CAAC,SAAS,EAAE,SAAS,CAAC,CAAA;CACrC,CAAA;AAED;;8DAE8D;AAC9D,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,cAAc,CAQjE;AAED,gGAAgG;AAChG,wBAAgB,eAAe,CAC7B,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,QAAQ,GAAG,SAAS,CAAC,EAChD,MAAM,EAAE,YAAY,GACnB,cAAc,CA+GhB"}
+{"version":3,"file":"derive.d.ts","sourceRoot":"","sources":["../../src/tokens/derive.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AAExC,MAAM,MAAM,YAAY,GAAG;IACzB;;;;;;;;OAQG;IACH,MAAM,EAAE,MAAM,CAAA;IACd,sEAAsE;IACtE,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,CAAA;IAC/C;kGAC8F;IAC9F,UAAU,EAAE,MAAM,CAAA;IAClB;mDAC+C;IAC/C,SAAS,EAAE,MAAM,CAAA;IACjB;;;;;;OAMG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;;;;;OAMG;IACH,gBAAgB,EAAE,MAAM,CAAA;CACzB,CAAA;AAED,8FAA8F;AAC9F,eAAO,MAAM,qBAAqB,EAAE,YAOnC,CAAA;AAID;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,YAAY,CAEjF;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAEnE;AAuHD,MAAM,MAAM,UAAU,GAClB,MAAM,GACN,KAAK,GACL,MAAM,GACN,OAAO,GACP,QAAQ,GACR,QAAQ,GACR,MAAM,GACN,MAAM,GACN,OAAO,GACP,MAAM,GACN,QAAQ,GACR,QAAQ,CAAA;AA6DZ,MAAM,MAAM,UAAU,GAClB,IAAI,GACJ,OAAO,GACP,YAAY,GACZ,UAAU,GACV,QAAQ,GACR,OAAO,GACP,QAAQ,GACR,UAAU,CAAA;AA2Bd,MAAM,MAAM,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAA;AAUvD,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,CAAA;AAS/C;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,6FAA6F;IAC7F,UAAU,EAAE,MAAM,CAAA;IAClB,0EAA0E;IAC1E,eAAe,EAAE,MAAM,CAAA;IACvB,6EAA6E;IAC7E,iBAAiB,EAAE,MAAM,CAAA;IACzB,4EAA4E;IAC5E,gBAAgB,EAAE,MAAM,CAAA;CACzB,CAAA;AAED;8BAC8B;AAC9B,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,EAAE,SAAS,CAAA;IACjB,WAAW,EAAE,SAAS,CAAA;IACtB,UAAU,EAAE,SAAS,CAAA;IACrB,eAAe,EAAE,SAAS,CAAA;IAC1B,QAAQ,EAAE,SAAS,CAAA;IACnB,IAAI,EAAE,MAAM,CAAC,UAAU,EAAE,SAAS,CAAC,CAAA;IACnC,OAAO,EAAE,MAAM,CAAC,UAAU,EAAE,SAAS,CAAC,CAAA;IACtC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;IAC9B,MAAM,EAAE,MAAM,CAAC,SAAS,EAAE,SAAS,CAAC,CAAA;CACrC,CAAA;AAED;;8DAE8D;AAC9D,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,cAAc,CAQjE;AAED,gGAAgG;AAChG,wBAAgB,eAAe,CAC7B,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,QAAQ,GAAG,SAAS,CAAC,EAChD,MAAM,EAAE,YAAY,GACnB,cAAc,CA+GhB"}

package/dist/tokens/derive.js

@@ -127,7 +127,9 @@ const SURFACE_TONE = {
   }
 };
 const INK_TONE = {
-  light: { ink: 15.16, ink2: 27.09, muted: 34.88, faint: 48.44 },
+  // light `faint` is tone 44.5 so tertiary text clears WCAG AA (4.5:1) on every text surface
+  // (bg / panel / subtle / field); 48.44 landed at 4.23–4.31:1 on bg and subtle.
+  light: { ink: 15.16, ink2: 27.09, muted: 34.88, faint: 44.5 },
   dark: { ink: 90.94, ink2: 88.12, muted: 84.91, faint: 66.24 }
 };
 const STATUS_HUE = { good: 151.975, warn: 76.64, bad: 29.905 };

package/dist/tokens.css

@@ -291,7 +291,7 @@ html[data-mantine-color-scheme='light'] {
   --vx-ink: #262629;
   --vx-ink2: #404043;
   --vx-muted: #525255;
-  --vx-faint: #737376;
+  --vx-faint: #69696c;
   --vx-accent: #4374a6;
   --vx-accent-hover: #3c6895;
   --vx-accent-fill: #4374a6;

package/llms.txt

@@ -1,4 +1,4 @@
-# basalt-ui v1.40.2
+# basalt-ui v1.41.0
 # Opinionated framework for Mantine-based React apps — theme, app shell, visx charts, toolchain presets
 #
 # basalt-ui is an opinionated framework for Mantine-based React apps.
@@ -19,7 +19,7 @@
 # ./tokens.css subpath. Guide: docs/FRAMEWORK-FREE.md in the repo.
 
 Package: basalt-ui
-Version: 1.40.2
+Version: 1.41.0
 
 ## basalt-ui
 Import: import { ... } from 'basalt-ui'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "basalt-ui",
-  "version": "1.40.2",
+  "version": "1.41.0",
   "description": "Opinionated framework for Mantine-based React apps — theme, app shell, visx charts, toolchain presets",
   "keywords": [
     "charts",

package/src/agent/foreign.ts

@@ -97,8 +97,9 @@ export type PartRenderContext<TPart = ForeignPart> = {
 export type PartRenderer<TPart = ForeignPart> = (ctx: PartRenderContext<TPart>) => ReactNode
 
 /**
- * Canonical const-generic factory (`packages/basalt-ui/CLAUDE.md`, "Canonical token-factory
- * contract") — identity passthrough, exact-keyed return, no builder, no config bag. Mirrors
+ * Canonical const-generic factory (`packages/basalt-ui/MAINTAINING.md` § "Token system — the
+ * derived palette", "Series color is consumer data") — identity passthrough, exact-keyed return,
+ * no builder, no config bag. Mirrors
  * `defineSeries` (`tokens/index.ts:648-650`) and `defineNotifications`
  * (`notifications/define-notifications.ts:112-115`).
  *

package/src/charts/index.ts

@@ -166,8 +166,8 @@ export {
 } from './sparklines'
 
 // ── Re-exported visx primitives ──────────────────────────────────────────
-// Bespoke charts (genuinely unique compositions per CLAUDE.md) need raw
-// visx primitives. Re-exporting them keeps the dependency declared in one
+// Bespoke charts (genuinely unique compositions, per `agent/rules/basalt-charts.md` "Adding a
+// chart") need raw visx primitives. Re-exporting them keeps the dependency declared in one
 // place and preserves the rule that consumers only import from `basalt-ui/charts`.
 export { Group } from '@visx/group'
 export { GridRows, GridColumns } from '@visx/grid'

package/src/charts/primitives/HoverOverlay.tsx

@@ -66,7 +66,8 @@ export function HoverOverlay({
         'aria-orientation': 'horizontal' as const,
         'aria-valuemin': 0,
         ...(valueMax !== undefined && { 'aria-valuemax': valueMax }),
-        ...(valueNow !== undefined && { 'aria-valuenow': valueNow }),
+        // `aria-valuenow` is required on a slider: 0 (the first point) until the cursor lands on one.
+        'aria-valuenow': valueNow ?? 0,
         ...(valueText !== undefined && { 'aria-valuetext': valueText }),
         onKeyDown,
         ...(onBlur !== undefined && { onBlur }),